From 1a7b025aeec0472d108e97dae4de1cb1a71724c4 Mon Sep 17 00:00:00 2001 From: admin123 Date: Mon, 25 May 2026 16:41:45 +0800 Subject: [PATCH] docs: add unified dist distribution plan --- .../2026-05-25-unified-dist-distribution.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-25-unified-dist-distribution.md diff --git a/docs/superpowers/plans/2026-05-25-unified-dist-distribution.md b/docs/superpowers/plans/2026-05-25-unified-dist-distribution.md new file mode 100644 index 0000000..404cd77 --- /dev/null +++ b/docs/superpowers/plans/2026-05-25-unified-dist-distribution.md @@ -0,0 +1,188 @@ +# Unified Dist Distribution Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make first-time install, Git-based install, ZIP-based install, and later updates all use the same unpacked extension directory named `dist/`. + +**Architecture:** Standardize the extension output path through one shared build-path helper, then make ZIP packaging wrap that exact `dist/` directory, and finally update all teammate-facing docs to reference only that path. The release pipeline keeps its existing behavior, but the user-facing artifact shape becomes stable and singular. + +**Tech Stack:** TypeScript, Node.js ESM scripts, Chrome MV3 extension packaging, Vitest + +--- + +## File Map + +- Create: `scripts/build-output-path.mjs` + - Single source of truth for the unpacked extension output path. +- Modify: `scripts/build.mjs` + - Write release builds to `dist/`. +- Modify: `scripts/package-release.mjs` + - Package the shared `dist/` output instead of any alternate directory. +- Modify: `scripts/package-release-archive.mjs` + - Ensure ZIP output preserves a top-level `dist/` folder. +- Modify: `tests/package-release-archive.test.ts` + - Verify ZIP layout unpacks as `dist/...`. +- Create: `tests/build-output-path.test.ts` + - Verify the shared helper resolves `dist/`. +- Modify: `playwright.config.js` + - Load the extension from `dist/`. +- Modify: `e2e-tests/extension-load.spec.js` + - Verify files under `dist/`. +- Modify: `README.md` + - Remove `dist-release` references and describe `dist/` as the only unpacked directory. +- Modify: `docs/internal-extension-distribution.md` + - Align the release flow language with `dist/`. +- Modify: `docs/【给同事】从Git下载使用说明.md` + - Instruct coworkers to load `dist/`. +- Modify: `.gitignore` + - Remove obsolete `dist-release/` ignore entry if no longer needed. +- Delete tracked directory: `dist-release/` + - Remove the confusing second unpacked extension directory from the repo. + +### Task 1: Lock the single output path in tests + +**Files:** +- Create: `tests/build-output-path.test.ts` +- Modify: `tests/package-release-archive.test.ts` + +- [ ] **Step 1: Write the failing helper test** + +Create a small test asserting both development and release builds resolve to: + +```ts +path.join("/repo", "dist") +``` + +- [ ] **Step 2: Write the failing ZIP layout assertion** + +Update the archive test so it expects: + +```ts +"dist/hello.txt" +``` + +not a flat file list or any alternate top-level folder. + +- [ ] **Step 3: Run focused tests** + +Run: + +```bash +npm test -- tests/build-output-path.test.ts tests/package-release-archive.test.ts +``` + +Expected: FAIL until the shared path helper and ZIP layout are implemented. + +### Task 2: Standardize build and package scripts + +**Files:** +- Create: `scripts/build-output-path.mjs` +- Modify: `scripts/build.mjs` +- Modify: `scripts/package-release.mjs` +- Modify: `scripts/package-release-archive.mjs` + +- [ ] **Step 1: Implement the shared output-path helper** + +Add `resolveExtensionBuildDir(projectRoot, buildTarget)` and return `dist/` for both release and development flows. + +- [ ] **Step 2: Update the build script** + +Replace any hard-coded directory switching logic so the release build writes into `dist/`. + +- [ ] **Step 3: Update the package script** + +Point ZIP packaging at the same `dist/` directory. + +- [ ] **Step 4: Keep ZIP layout stable** + +Ensure the archive helper stores files under a top-level `dist/` directory inside the ZIP. + +- [ ] **Step 5: Verify** + +Run: + +```bash +npm test -- tests/build-output-path.test.ts tests/package-release-archive.test.ts +npm run build:release +npm run package:internal +``` + +Expected: PASS, and the ZIP should unpack as `dist/...`. + +### Task 3: Remove `dist-release` from tooling and docs + +**Files:** +- Modify: `playwright.config.js` +- Modify: `e2e-tests/extension-load.spec.js` +- Modify: `README.md` +- Modify: `docs/internal-extension-distribution.md` +- Modify: `docs/【给同事】从Git下载使用说明.md` +- Modify: `.gitignore` +- Delete tracked directory: `dist-release/` + +- [ ] **Step 1: Update tool references** + +Point Playwright and debug paths at `dist/`. + +- [ ] **Step 2: Update teammate docs** + +Make every install/update instruction reference only `dist/`. + +- [ ] **Step 3: Remove the obsolete tracked directory** + +Delete the committed `dist-release/` tree so future contributors cannot mistake it for the live extension directory. + +- [ ] **Step 4: Verify references** + +Run: + +```bash +rg -n "dist-release" README.md docs package.json scripts e2e-tests playwright.config.js src tests .gitignore +``` + +Expected: no remaining user-facing `dist-release` references. + +### Task 4: Final verification + +**Files:** +- Modify any of the above only if fixes are required + +- [ ] **Step 1: Run targeted tests** + +Run: + +```bash +npm test -- tests/build-output-path.test.ts tests/package-release-archive.test.ts tests/manifest.test.ts +``` + +Expected: PASS. + +- [ ] **Step 2: Rebuild and inspect the artifact** + +Run: + +```bash +npm run build:release +npm run package:internal +unzip -l release/star-chart-search-enhancer-internal.zip | sed -n '1,20p' +``` + +Expected: the archive contents start with `dist/...`. + +- [ ] **Step 3: Full verification** + +Run: + +```bash +npm test +``` + +Expected: PASS, or if unrelated pre-existing failures remain, capture them explicitly before completion. + +- [ ] **Step 4: Commit** + +```bash +git add scripts/build-output-path.mjs scripts/build.mjs scripts/package-release.mjs scripts/package-release-archive.mjs tests/build-output-path.test.ts tests/package-release-archive.test.ts README.md docs/internal-extension-distribution.md docs/【给同事】从Git下载使用说明.md playwright.config.js e2e-tests/extension-load.spec.js .gitignore +git commit -m "chore: unify extension distribution around dist" +``` +