# 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"
```