docs: add unified dist distribution plan
This commit is contained in:
parent
b3b916c6bc
commit
1a7b025aee
188
docs/superpowers/plans/2026-05-25-unified-dist-distribution.md
Normal file
188
docs/superpowers/plans/2026-05-25-unified-dist-distribution.md
Normal file
@ -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"
|
||||||
|
```
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user