star-chart-search-enhancer/docs/superpowers/plans/2026-05-25-cos-extension-update.md

COS Extension Update 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: Point the popup update flow at the real COS release bucket and keep the generated release manifest, docs, and tests aligned with that COS-based distribution path.

Architecture: Reuse the existing update-check flow already in src/shared/update-check.ts, src/popup/index.ts, src/popup/view.ts, and src/background/index.ts. The only behavior change is the source of truth: the popup should fetch a stable COS-hosted latest.json, while scripts/write-latest-manifest.mjs should keep generating versioned asset URLs under the COS release folder. Everything else stays manual and user-driven.

Tech Stack: TypeScript, Chrome MV3, Vitest, Node.js ESM scripts, Tencent COS public HTTPS URLs

---

Task 1: Lock the popup manifest URL to COS

Files:

• Modify: src/shared/update-config.ts

• Test: tests/update-config.test.ts

• Step 1: Write the failing URL test

Add a small test that asserts UPDATE_MANIFEST_URL points at the stable COS-hosted latest.json URL for this bucket:

expect(UPDATE_MANIFEST_URL).toBe(
  "https://wksgx-1343191620.cos.ap-nanjing.myqcloud.com/star-chart-search-enhancer/latest.json"
);

• Step 2: Run the focused test

Run:

npm test -- tests/update-config.test.ts

Expected: FAIL because the current constant still uses the placeholder example URL.

• Step 3: Update the constant

Replace the placeholder string in src/shared/update-config.ts with the COS latest.json URL above.

• Step 4: Verify

Run:

npm test -- tests/update-config.test.ts tests/popup-entry.test.ts

Expected: PASS.

Task 2: Generate release assets from the COS base

Files:

• Modify: scripts/write-latest-manifest.mjs

• Modify: release/latest.json

• Test: tests/update-check.test.ts

• Step 1: Write a manifest generation regression test

Add or extend a test that proves the generated manifest uses the COS release base for assets, not example.com. Use the COS base:

https://wksgx-1343191620.cos.ap-nanjing.myqcloud.com/star-chart-search-enhancer/releases/0.2.0421.2

Assert that zipUrl and guideUrl are derived from that base.

• Step 2: Run the focused test

Run:

npm test -- tests/update-check.test.ts

Expected: FAIL until the generator default points at COS.

• Step 3: Update the generator default

Change publicBaseUrl in scripts/write-latest-manifest.mjs to default to the COS release base for this bucket and region, while keeping UPDATE_PUBLIC_BASE_URL as the override path for future releases.

• Step 4: Regenerate the tracked manifest

Run:

npm run write:latest

Then confirm release/latest.json contains the COS URLs.

• Step 5: Verify

Run:

npm test -- tests/update-check.test.ts tests/popup-entry.test.ts tests/background-index.test.ts

Expected: PASS.

Task 3: Update distribution docs and verify COS access

Files:

• Modify: docs/internal-extension-distribution.md

• Modify: README.md

• Step 1: Update the release instructions

Document the stable manifest URL, the versioned asset base, and the upload flow to COS. Keep the user-facing manual install steps unchanged.

• Step 2: Add the COS verification command

Document a curl -I check for the public latest.json URL and the uploaded ZIP/PDF so a failed COS ACL is caught before release.

• Step 3: Run the final verification

Run:

npm test
npm run build:release

Expected: PASS, and the generated release bundle should still open the popup update card correctly.