Package Extension

Produces ai-engineer-coach-<version>.vsix at the repo root, suitable for code --install-extension.

Prerequisites

• Node.js (matches engines.vscode of ^1.120.0 from package.json; any recent LTS works).
• npm ci to install dependencies — do not use npm install for a packaging build, since the lockfile is the source of truth.
• vsce is invoked through npx; no global install needed.

Steps

npm ci
npm run package

npm run package runs scripts/package-readme-swap.mjs, which:

1. Renames the GitHub-facing README.md to README.github.md.
2. Copies README.extension.md into README.md (this is the README the Marketplace shows).
3. Runs vsce package --allow-missing-repository --no-dependencies, which itself triggers the vscode:prepublish script → npm run build → node esbuild.mjs to bundle into dist/extension.js.
4. Restores the original README.md regardless of build success.

The --no-dependencies flag is required because runtime dependencies are bundled into dist/extension.js by esbuild; node_modules/ is excluded via .vscodeignore.

Output

• ai-engineer-coach-<version>.vsix at the repo root.
• dist/extension.js (the bundled entry point).

Install locally to smoke-test:

code --install-extension ai-engineer-coach-*.vsix

Then AI Engineer Coach: Open Dashboard from the command palette.

Size budgets

scripts/check-bundle-size.mjs enforces:

• dist/extension.js ≤ 2 MB
• Any *.vsix at the repo root ≤ 5 MB

Run it after packaging:

npm run check-size

Troubleshooting

• README.github.md left behind — the swap script aborted before its finally could rename the file back. Manually mv README.github.md README.md before re-running.
• vsce: command not found — npx vsce should resolve through node_modules/.bin/; run npm ci if it doesn't, since vsce is a transitive dev dependency.
• Missing publisher name — the publisher field in package.json is required; do not remove it when bumping the version.
• Bundle over budget — usually a new dependency that wasn't tree-shaken. Check npm run analyze:data-inventory and the esbuild output, then either drop the dep or split it into a dynamic import.
• Spellcheck or lint fails first — npm run check (typecheck + lint + spellcheck + knip + test) is what CI runs; fix those before packaging if the goal is a release.

Versioning

Bump version in package.json, add a CHANGELOG.md entry, then commit before packaging so the .vsix filename matches the released tag. Do not amend the commit after building — it's fine to ship a .vsix whose embedded git SHA differs from the tag.

Anti-patterns

• Don't run vsce package directly — you'll ship README.md (the GitHub one with screenshots and badges) instead of README.extension.md.
• Don't commit the .vsix; it's listed in .gitignore style via convention. Attach it to a GitHub Release instead.
• Don't disable --no-dependencies "to be safe" — it will bloat the package past the 5 MB budget and double-ship code that's already bundled.