star-chart-search-enhancer/docs/superpowers/plans/2026-05-25-unified-dist-distribution.md

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:

path.join("/repo", "dist")

• Step 2: Write the failing ZIP layout assertion

Update the archive test so it expects:

"dist/hello.txt"

not a flat file list or any alternate top-level folder.

• Step 3: Run focused tests

Run:

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:

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:

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:

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:

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:

npm test

Expected: PASS, or if unrelated pre-existing failures remain, capture them explicitly before completion.

• Step 4: Commit

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"