thedotmack-claude-mem/plans/10-build-artifact-hygiene-EXECUTION.md

# plan-10 EXECUTION — Wave 0: Runtime Dependency Closure + Clean-Room CI Smoke

> **Master:** #2783 · **Anchor child:** #2730 (`Cannot find module 'zod/v3'`) · **Design doc:** `plans/10-build-artifact-hygiene.md`
> **Format:** make-plan phased plan, executable with `/do`. Each phase has What-to-implement / Doc references / Verification / Anti-pattern guards.
> **Scope of THIS plan:** the runtime-dependency-completeness slice of plan-10 (the thing that blocks every other Wave). The broader plan-10 children (#2584 better-auth bloat, #2570 bundle-size canary, #2538 typecheck-red, #2537 CLAUDE.md tarball leak) are **separate slices** — see "Deferred plan-10 scope" at the end.

---

## Phase 0 — Documentation Discovery (facts, decisions, allowed APIs)

This phase is **already complete** (4 discovery subagents, read-only). Consolidated below. A `/do` Implementation subagent must READ these files before touching anything; do not re-derive.

### Ground truth (file:line)

**Dependency declaration**
- Root `package.json:125-147` — 21 runtime deps incl. `zod@^4.4.3` (line 145).
- `plugin/package.json` — the **runtime manifest** the worker/Stop-hook install resolves; **27 deps** incl. `zod@^4.3.6`. **It is generated** by `scripts/build-hooks.js:202-249` (zod at line 209). **Never hand-edit `plugin/package.json`** — edit the generator.
- Version skew: root `^4.4.3` vs plugin `^4.3.6` (`build-hooks.js:209`).

**Why zod is required at runtime (not bundled)**
- `scripts/build-hooks.js:274-292` worker `external` array includes `'zod'` (line 277). Also external in server-beta (`:343`) and context-generator (`:448`). esbuild `external: ['zod']` matches all subpaths.
- The `require("zod/v3")` / `zod/v4` / `zod/v4-mini` literals are **transitive** (from bundled `@modelcontextprotocol/sdk` / `@anthropic-ai/claude-agent-sdk`); no first-party source imports `zod/v3`. They appear in the built bundle `plugin/scripts/worker-service.cjs` (~line 950, minified).
- The MCP bundle (`build-hooks.js:421-428`) intentionally **bundles** zod and has a guard failing the build if `require('zod...')` leaks — because Claude Desktop launches it with no plugin `node_modules`. **Do not break that guard.**

**How node_modules is materialized**
- Install: `src/npx-cli/install/setup-runtime.ts:370` → `bun install --ignore-scripts` in the cache dir (`~/.claude/plugins/cache/thedotmack/claude-mem/<version>/plugin`, `paths.ts:47-49`). **No lockfile, no `--frozen-lockfile`** → unpinned, resolution-time-dependent.
- Marketplace fallback: `install.ts:598` → `npm install --omit=dev --ignore-scripts` (`npm-install-helper.ts:53-69`).
- Post-install guard `verifyCriticalModules` (`setup-runtime.ts:221-236`): checks only `existsSync(node_modules/<dep>)` (lines 227-228). **Does not** assert subpath resolution or version.

**Why it RECURS on auto-update**
- claude-mem has no self-updater. Claude Code refreshes plugin files; the Setup hook `plugin/scripts/version-check.js:60-66` only **prints a hint** (`run: npx claude-mem@latest install`). No `bun install` runs against the new manifest → stale/missing `node_modules/zod` persists until a manual reinstall.

**Publish surface**
- Root `package.json:43-58` `files` allowlist ships `plugin/package.json` but **no `node_modules`, no lockfile**.
- `.npmignore` **excludes** `plugin/node_modules/` and **`plugin/bun.lock`**.
- `prepublishOnly` (`package.json:113`): `npm run build && node scripts/check-postinstall-allowlist.js` — existing precedent for a CI-time dependency guard.

**CI / test harness**
- `.github/workflows/ci.yml` — PR gate, job `build` (lines 9-47): checkout → setup-node 20 → setup-bun → `npm install --no-audit --no-fund` (line 30) → `npm run typecheck` → `npm run build` → `bun test`. Comment at `ci.yml:25-28` documents that the lockfile is gitignored so `npm ci`/cache can't be used. Second job `server-runtime-e2e-docker` (49-78) does **not** gate `build`.
- `.github/workflows/npm-publish.yml` — tag-triggered (`v*`, lines 3-6). Single `publish` job (8-21): `npm install --ignore-scripts` (17) → `npm run build` (18) → `npm publish` (19), `NODE_AUTH_TOKEN` (20-21). **No `needs:`.**
- Test runner: **`bun test`** (`package.json:104`); config `bunfig.toml` (`[test] smol=true`). Convention example: `tests/json-utils.test.ts` (imports from `bun:test`, temp-dir setup/teardown). No `npm pack` / clean-room test exists anywhere.

### Decision gate — ✅ RESOLVED 2026-06-04: **Approach A (ship `plugin/bun.lock`)** confirmed by maintainer.

`/do` should implement **Approach A** below and must NOT re-prompt. Approach B is retained only as documentation of the rejected alternative.

The repo **deliberately gitignores lockfiles** (`.gitignore:19-20`, `ci.yml:25-28`). Two ways to make the runtime closure deterministic:

- **Approach A (CHOSEN): commit & ship a `plugin/bun.lock`, install with `--frozen-lockfile`.** Carries the full transitive closure; matches the master's "enforce a boundary on what we ship" and the requested goal. Cost: reverses the gitignore policy *scoped to the plugin lockfile only*.
- **Approach B (fallback): exact-pin versions in the generated `plugin/package.json`** (no `^`), no lockfile. Respects the no-lockfile policy; deterministic for top-level deps (enough for the literal zod/v3 bug) but does **not** pin transitive deps. Weaker "full closure" guarantee.

**This plan implements Approach A.** If the maintainer rejects reversing the lockfile policy, switch Phase 1 to Approach B (the generator edit at `build-hooks.js:209` becomes exact-version emission and Phases 2-5 are unchanged). **Do not proceed past Phase 1 design without this confirmed.**

### Allowed APIs / tools (cite when used)
- `bun install --frozen-lockfile --ignore-scripts` (Bun CLI) — pinned install.
- `bun install` in `plugin/` to (re)generate `plugin/bun.lock`.
- `require.resolve(specifier, { paths })` (Node) — subpath resolution assertion.
- `npm pack` + `npm install <tarball> --prefix <tmp>` (npm CLI) — clean-room install.
- `bun test`, `bun:test` (`describe/it/expect`) — repo test convention.

### Anti-patterns to avoid (from discovery)
- ❌ Editing `plugin/package.json` directly — it is regenerated by `build-hooks.js:202-249`.
- ❌ Removing `'zod'` from the worker `external` list to "just bundle it" — diverges from the architecture, bloats `worker-service.cjs` against `WORKER_SERVICE_MAX_BYTES` (`build-hooks.js:322-329`), and doesn't generalize to other missing runtime deps. (Noted as a rejected alternative, not the fix.)
- ❌ Breaking the MCP no-external-zod guard (`build-hooks.js:421-428`).
- ❌ Using `npm ci` in CI (no lockfile for the root; and the plugin lockfile is bun's).
- ❌ Adding a `process.exit(1)` or a blocking reinstall on a hook path (`version-check.js`) — CLAUDE.md forbids it; auto-reinstall-on-update is out of scope (see Deferred).

---

## Phase 1 — Ship a deterministic runtime dependency closure (Approach A)

**What to implement**
1. Make the generated plugin manifest version-consistent: in `scripts/build-hooks.js:209`, align the generated `zod` range with root (`package.json:145` → `^4.4.3`). Keep all 27 deps; only fix the skew. Copy the existing generator object shape (lines 202-249) — do not restructure it.
2. Generate the lockfile as a build artifact: after `build-hooks.js` writes `plugin/package.json`, run `bun install` in `plugin/` to produce `plugin/bun.lock`. Add a build step (new script `scripts/gen-plugin-lockfile.cjs` invoked from the `build` script in `package.json:65`, AFTER `build-hooks.js`) — or extend `build-hooks.js` to shell out to `bun install --cwd plugin`. Follow the existing `execSync` pattern used in `scripts/sync-marketplace.cjs:138-162`.
3. Commit & ship the lockfile:
   - `.gitignore:19-20` — narrow the ignore so `plugin/bun.lock` is **tracked** (keep ignoring root `bun.lock`/`package-lock.json` if desired; un-ignore the plugin one).
   - `.npmignore` — **remove** the `plugin/bun.lock` exclusion.
   - `package.json:43-58` `files` — **add** `plugin/bun.lock` to the allowlist.
4. Install from the lockfile: `src/npx-cli/install/setup-runtime.ts:370` — change `bun install --ignore-scripts` → `bun install --frozen-lockfile --ignore-scripts`. Keep `--ignore-scripts`. (`copyPluginToCache` at `install.ts:574-581` already copies the whole `plugin/` tree recursively, so the committed `plugin/bun.lock` is carried into the cache dir automatically — verify, don't add new copy logic.)

**Documentation references**
- Generator object + zod line: `scripts/build-hooks.js:202-249` (zod `:209`).
- `execSync` install pattern to copy: `scripts/sync-marketplace.cjs:138-162`.
- Install command to edit: `src/npx-cli/install/setup-runtime.ts:370`.
- Recursive plugin copy (confirm lockfile is carried): `src/npx-cli/commands/install.ts:574-581`.
- Allowlist/ignore files: `package.json:43-58`, `.npmignore`, `.gitignore:19-20`.

**Verification checklist**
- [ ] `npm run build` produces a tracked `plugin/bun.lock` containing zod@4.4.x and all 27 deps.
- [ ] `git status` shows `plugin/bun.lock` as tracked (not ignored): `git check-ignore plugin/bun.lock` returns nothing.
- [ ] `npm pack` tarball contains `plugin/bun.lock` and `plugin/package.json`: `tar -tzf $(npm pack --silent) | grep -E 'plugin/(bun.lock|package.json)'`.
- [ ] In a temp copy of `plugin/`, `bun install --frozen-lockfile --ignore-scripts` succeeds with **no** "lockfile had changes" error (proves manifest⇄lockfile are in sync).
- [ ] After install, `require.resolve('zod/v3', { paths: ['<tmp>/node_modules'] })` resolves.
- [ ] Generated `plugin/package.json` zod range equals root (`grep '"zod"' plugin/package.json package.json`).

**Anti-pattern guards**
- ❌ Do not hand-edit `plugin/package.json` (regenerated).
- ❌ Do not drop `--ignore-scripts` (postinstall-hang lesson, `plans/04`).
- ❌ Do not commit the root `node_modules` or a root lockfile to "fix" this — scope is the plugin runtime closure.
- ❌ Do not change the worker `external` list.

---

## Phase 2 — Make a broken install fail LOUD at install time

**What to implement**
Strengthen `verifyCriticalModules` (`src/npx-cli/install/setup-runtime.ts:221-236`) so it asserts the dependency is actually **importable**, not merely a directory. For each critical dep, resolve it with `require.resolve(dep, { paths: [<cacheDir>/node_modules] })`; and for zod specifically, also assert the **subpaths the worker requires** resolve: `zod/v3`, `zod/v4`, `zod/v4-mini`. On failure, throw the existing loud install error (copy the error-emission pattern already used in that function / the installer error taxonomy from `plans/04`). The point: a partial/stale install fails `npx claude-mem install` immediately instead of surfacing later as a Stop-hook `Cannot find module`.

**Documentation references**
- Function to extend: `src/npx-cli/install/setup-runtime.ts:221-236` (current dir-existence check at 227-228).
- Exact subpaths to assert: derived from `plugin/scripts/worker-service.cjs` (`require("zod/v3"|"zod/v4"|"zod/v4-mini")`) — see Phase 0.
- Installer error-emission style: reuse the same throw/log this file already uses; cross-ref `plans/04-installer-transparency.md` taxonomy.

**Verification checklist**
- [ ] New unit test (`tests/cli/verify-critical-modules.test.ts`, `bun:test`, copy shape from `tests/json-utils.test.ts`): given a temp `node_modules` with `zod` present but `zod/v3` export missing/removed, `verifyCriticalModules` THROWS; given a complete zod v4, it passes.
- [ ] `bun test tests/cli/` green.
- [ ] Manual: delete `node_modules/zod/v3*` in a temp install → `verifyCriticalModules` fails with a clear message naming `zod/v3`.

**Anti-pattern guards**
- ❌ Do not assume `require.resolve` of the package root implies subpaths resolve — assert subpaths explicitly (that's the whole bug).
- ❌ Do not swallow the failure (no empty catch) — it must throw/exit non-zero on the install path (NOT a hook path).
- ❌ Do not hardcode a zod version; assert subpath resolution, which is version-agnostic.

---

## Phase 3 — Clean-room install + import smoke test (the regression backstop)

**What to implement**
A net-new script `scripts/smoke-clean-room.cjs` (model its `execSync`/temp-dir style on `scripts/sync-marketplace.cjs` + `tests/json-utils.test.ts` temp-dir handling) that, against a fresh temp dir:
1. **Plugin-runtime closure (the #2730 guard):** copy `plugin/` → tmp, `bun install --frozen-lockfile --ignore-scripts`, then assert `require.resolve` of `zod`, `zod/v3`, `zod/v4`, `zod/v4-mini` from `<tmp>/node_modules`; then spawn `bun <tmp>/scripts/worker-service.cjs` with a no-op/`--help`-style invocation and assert it does **not** print `Cannot find module`.
2. **npm-package completeness:** `npm pack`, install the tarball into a second temp dir (`npm install <tarball> --prefix <tmp2> --ignore-scripts`), then `node -e "require('<tmp2>/.../dist/npx-cli/index.js')"`-style load of the published `bin`/`main` entrypoints (`package.json:29-42`) to catch missing `dist` runtime deps.
3. Exit non-zero with a precise message on any missing module. Add an npm script `"smoke:clean-room": "node scripts/smoke-clean-room.cjs"` near the other scripts (`package.json:104-110`).

**Documentation references**
- Temp-dir + spawn conventions: `tests/json-utils.test.ts`, `scripts/sync-marketplace.cjs:138-173`.
- Published entrypoints to load: `package.json:29-42` (`bin`, `main`, `exports`).
- Subpaths to assert: Phase 0 (worker-service.cjs requires).
- Existing prepublish-guard precedent: `scripts/check-postinstall-allowlist.js`.

**Verification checklist**
- [ ] `npm run build && npm run smoke:clean-room` exits 0 on a healthy tree.
- [ ] Fault injection: temporarily remove `zod` from the generated manifest (or delete it from the tmp `node_modules`) → the script exits non-zero and names `zod/v3`. Revert.
- [ ] Script makes **no** network calls beyond the package installs and runs offline against the local registry cache where possible (note any unavoidable network in the script header).
- [ ] Runtime under ~2-3 min on CI (it does two installs).

**Anti-pattern guards**
- ❌ Do not run the smoke test against the repo's already-installed `node_modules` — it must use a fresh temp dir (the existing `tests/server/server-runtime-smoke.test.ts` runs in-tree and would NOT catch this class).
- ❌ Do not assert on minified symbol names inside `worker-service.cjs`; assert on module resolution + absence of `Cannot find module`.
- ❌ Do not leave temp dirs behind (clean up in a `finally`).

---

## Phase 4 — Wire into CI and gate publish

**What to implement**
1. **PR gate:** add a new job to `.github/workflows/ci.yml` (insert after the `build` job ends at line 47, before `server-runtime-e2e-docker:` at line 49). Copy the runner/setup boilerplate from the `build` job (lines 11-30: `runs-on: ubuntu-latest`, checkout@v4, setup-node@v4 node 20, setup-bun@v2, `npm install --no-audit --no-fund`). Steps: `npm run build` → `npm run smoke:clean-room`. Name it e.g. `clean-room-deps` ("clean-room dependency closure smoke").
2. **Frozen-lockfile drift check:** in the same job (or the `build` job), add a step that runs `bun install --frozen-lockfile --ignore-scripts` inside `plugin/` and fails if the lockfile is out of sync with the generated manifest (catches a contributor who changed deps but didn't regenerate the lockfile).
3. **Publish gate:** `.github/workflows/npm-publish.yml` is tag-triggered and independent of `ci.yml`, so the gate must live inside it. Insert `npm run smoke:clean-room` as a step **between** `npm run build` (line 18) and `npm publish` (line 19). (Alternatively split into a separate job and add `needs:` to `publish` — inline is simpler and sufficient.)

**Documentation references**
- PR-gate insertion point + boilerplate to copy: `.github/workflows/ci.yml:9-47`.
- Publish step to gate: `.github/workflows/npm-publish.yml:17-19`.
- Lockfile-is-gitignored caveat (now partially reversed for plugin): `ci.yml:25-28`.

**Verification checklist**
- [ ] `actionlint`/yaml parses (or GitHub "Actions" tab shows the new job on a draft PR).
- [ ] On a PR that intentionally breaks the closure (drop a dep in the generator), the `clean-room-deps` job FAILS.
- [ ] On a clean PR, `clean-room-deps` PASSES.
- [ ] The publish workflow contains the smoke step before `npm publish` (`grep -n 'smoke:clean-room' .github/workflows/npm-publish.yml`).
- [ ] The frozen-lockfile drift step fails when `plugin/package.json` is edited without regenerating `plugin/bun.lock`.

**Anti-pattern guards**
- ❌ Do not put the publish gate only in `ci.yml` — it does not run on tag pushes; the publish job would remain ungated.
- ❌ Do not add `cache: 'npm'` / `npm ci` (no root lockfile).
- ❌ Do not duplicate secrets handling; reuse the existing `NODE_AUTH_TOKEN`/`NPM_TOKEN` block.

---

## Phase 5 — Final verification

1. **Implementation matches docs:** re-read Phase 0 file:line anchors and confirm every edit landed where specified (`build-hooks.js:209`, `setup-runtime.ts:370`, `setup-runtime.ts:221-236`, `package.json files`, `.npmignore`, `.gitignore`, both workflow files, new script + npm script).
2. **Anti-pattern grep:**
   - `grep -n "bun install --ignore-scripts" src/npx-cli/install/setup-runtime.ts` → must now read `--frozen-lockfile --ignore-scripts`.
   - `grep -n "plugin/bun.lock" .npmignore` → must return nothing (un-excluded).
   - `git check-ignore plugin/bun.lock` → returns nothing (tracked).
   - confirm worker `external` still lists `'zod'` (`build-hooks.js:277`) and MCP guard intact (`:421-428`).
3. **Full suite:** `npm run typecheck && npm run build && bun test && npm run smoke:clean-room` all green.
4. **End-to-end repro of #2730:** in a throwaway dir, simulate the cache install path (`bun install --frozen-lockfile --ignore-scripts` against shipped `plugin/`), launch `worker-service.cjs` in a Stop-hook-style invocation, confirm **no** `Cannot find module 'zod/v3'`.
5. **Issue hygiene:** PR body `Closes #2783` (and references #2730). The clean-room job + frozen-lockfile drift check are the test-matrix cells this slice contributes to CI (per `plans/EXECUTION.md`).

---

## Deferred plan-10 scope (NOT this PR — separate slices)
- #2584 — `worker-service.cjs` bundles unused `better-auth` (~3.7MB); externalize/gate behind server runtime.
- #2570 — bundle-size canary in CI + cross-platform marketplace-sync.
- #2538 — fix the 24 typecheck-drift errors; make `npm run typecheck` a required gate.
- #2537 — `files`/`.npmignore` so maintainer `CLAUDE.md` files don't publish; assert tarball contents.

Each is its own `/make-plan` → `/do`. They share plan-10's "enforce a boundary on what we ship" architecture but ship independently after this Wave-0 slice unblocks the rest.

## Out-of-scope (other masters)
- Auto-**reinstall** of deps on update (vs. today's hint-only `version-check.js:65`) — lifecycle behavior, route to **plan-03 #2780**. This plan makes the install *deterministic and loud*; it does not change WHEN the install runs.
- Worker runtime crashes unrelated to dep resolution — **plan-03**.