# 8. Installer modularization + secret-leak defense

**Status:** Accepted · 2026-04-27 (v8.0.0)

> **Phase numbers below are the eight-phase ones.** [ADR-0014](./0014-six-phase-consolidation.md) renumbered the contract in v19.0.0 (the producer/consumer phase docs it names were renumbered). The decision this ADR records is unchanged; only the labels moved, and they are left as written because an ADR records what was decided.

> **Amended v10.7.0:** the `_adapters.mjs` module and its third-party adapter dispatch were removed when the pipeline narrowed to Claude Code + Copilot CLI (see ADR 0007). `install/` now ships **8** modules, not 9; the module list below records the v8.0.0 decision as it shipped at the time.

> **Amendment, 2026-09-13 ([ADR-0012](./0012-macos-only.md), macOS only).** Linux
> and Windows support was removed. `package.json` declares `os: ["darwin"]`,
> every workflow runs on a macOS runner, and `test.yml`'s matrix is macOS ×
> Node 20/22 with no Ubuntu leg and no Windows job. Where the body below
> describes an Ubuntu/macOS/Windows matrix or an Ubuntu `act` lane, read it as
> the record of what was decided then.

## Context

Two pressures collided during the v7.x line:

1. **Installer monolith.** `install.js` reached 1246 LOC by v7.9.1. It mixed flag parsing, three platform installers (Claude / Copilot / six third-party adapters), telemetry, a dev-only file exclusion list, and a 200-line static generator for `copilot-instructions.md`. Reasoning about install behaviour required holding the whole file in your head; reviewers asked for documentation we could not produce because every change touched untyped, intertwined sections.

2. **Secret leaks at deploy time.** During the v7.9.1 production deploy of the project website, a `vercel deploy --token=vcp_...` invocation failed. The Vercel CLI printed the failed argv verbatim in its retry hint. That leaked the deploy token into the conversation transcript and forced a token rotation. A second incident in the same release window - `git -c user.email=...` overriding the repo-local config - pushed seven commits with the wrong author identity, which Vercel's contributor gate then blocked. Both classes of failure share a root cause: privileged values flowed through argv when the codebase had no audited boundary between provider tools and the orchestration layer.

We needed an architectural answer that prevented both classes of failure from recurring without expanding scope into "rewrite everything as TypeScript" - the project's zero-dependency philosophy (ADR-4) is a hard constraint.

## Decision

### 1. `install.js` becomes a 24-line shim; logic moves under `install/`

The monolith splits into focused modules under `install/`:

```
install/
  index.mjs                  - entry point, flag parsing, dispatcher
  claude.mjs                 - Claude Code installer
  copilot.mjs                - Copilot CLI installer
  _adapters.mjs              - third-party adapter dispatch
  _common.mjs                - shared FS helpers (copyDir, ensureDir, ...)
  _platform-filter.mjs       - --platform=ios|android filter
  _telemetry.mjs             - opt-in install telemetry
  _copilot-instructions.mjs  - generator for ~/.copilot/copilot-instructions.md
  _dev-only-files.mjs        - single source of truth for excluded files
```

`install.js` keeps its bin entry contract (24 lines, just `import { runInstall } from './install/index.mjs'; await runInstall(process.argv)`). Existing invocations - `npx ... install --all`, the `package.json` `./install` export, every smoke test that runs `node install.js` - continue working without API changes. The package.json `files` array adds `install/**/*` so npm publish ships the new modules.

### 2. Install layout is now a regression gate

`pipeline/scripts/smoke-install-layout.sh` (35 assertions) runs the live installer into a temp HOME and proves:

- All 9 expected modules exist under `install/`.
- `install.js` is under 50 lines and imports `install/index.mjs`.
- `--claude`, `--copilot`, `--all` produce the same on-disk tree the v7.x monolith produced (file counts, hook registration, multi-agent skill pruning).
- Cross-target file count parity for shared scripts and agents.

Future refactors must keep this smoke green. Drift is detected before it ships, not after.

### 3. Provider tools wrap CLIs that leak credentials

`pipeline/lib/vercel-deploy.sh` is the safe wrapper around the Vercel CLI. Three properties hold for every invocation:

1. Tokens flow through `VERCEL_TOKEN` env var. The wrapper refuses to deploy if `--token=` appears anywhere in argv - that pattern was the v7.9.1 leak.
2. Every stdout/stderr line is piped through a `redact_filter` sed pass that scrubs `--token=...`, `vcp_...`, `Bearer ...`, `"token":"..."`, and `"VERCEL_TOKEN":"..."` shapes.
3. Failed deploys exit with a clear marker line; the wrapper does not echo the original argv that the CLI printed in its retry hint.

`pipeline/scripts/smoke-vercel-deploy-redact.sh` (12 assertions) is the regression gate for the redact filter. Each known leak shape has a fixture that must NOT survive redaction.

### 4. Mode dispatch generator + drift smoke

`pipeline/scripts/gen-mode-dispatch.mjs` is the canonical source for the "Required: Phase Tracker Contract" section embedded in every mode dispatch file. `pipeline/scripts/smoke-mode-dispatch-drift.sh` (61 assertions) verifies each mode file declares the right phase list (4-phase for `dev*`, 8-phase for `local`/`autopilot`) and links `refs/tracker-contract.md`.

### 5. Cross-phase cohesion smoke

Schema validation proves each schema is well-formed. It does not prove that producer / consumer phase docs both reference the schema they hand off. `pipeline/scripts/smoke-cross-phase-cohesion.sh` (17 assertions) adds the cohesion gate: Phase 1 → Phase 2 (`analysis-output`), Phase 2 → Phase 3 (`planning-output`), Phase 4 → Phase 4 triage (`reviewer-output`), Phase 4 triage → Phase 6 (`triage-output`), and Phase 6 → Phase 7 (`agent-state`) hand-offs are documented on both sides.

### 6. CI matrix splits into full + lite workflows

`.github/workflows/test.yml` keeps the full matrix (Ubuntu/macOS/Windows × Node 20/22 + credential-store round-trips). `.github/workflows/ci-lite.yml` is the workflow_dispatch-only fast lane (Ubuntu + Node 22, no credential round-trips, ~3 minutes). The lite workflow is the one contributors run via `act` while billing is paused; the full matrix runs on demand for releases.

### 7. Recovery guide gains four new playbooks

`docs/recovery-guide.md` adds: worktree corruption, tracker state corruption, token rotation mid-pipeline, and failed-push force-with-lease decision tree. All four were learned from the v7.9.1 release window.

## Consequences

**What gets easier:**

- Reading the installer. Each module is < 300 LOC and has a single responsibility.
- Reviewing installer changes. A diff that touches `install/copilot.mjs` is bounded; reviewers do not need to skim 1246 lines of context.
- Auditing for credential exposure. Every Vercel call goes through one wrapper; future provider integrations follow the same pattern (next: deploy-to-Cloudflare wrapper, npm publish wrapper).
- Detecting doc drift. Smokes catch missing schema references before docs ship to users.

**What gets harder:**

- Adding a brand-new install target. The contributor must touch `install/index.mjs` (flag wiring), create `install/<target>.mjs` (installer), update `smoke-install-layout.sh` (assertion). That's three files instead of one - but the boundaries are sharp and a smoke fails loudly if anything is missed.
- Maintaining the static `_copilot-instructions.mjs` generator. The body still has to match the source-of-truth content in `pipeline/commands/multi-agent/`. Plan: in v9 we replace the static template with a generator that reads the actual phase files. For v8 the smoke `smoke-multi-repo-integration.sh` already greps the generator output for canonical strings, so drift is detected.

**What we explicitly chose not to do:**

- Migrate to TypeScript. The zero-dependency rule (ADR-4) still holds; TS would force a build step.
- Move the install layout assertions into a unit test. Bash + `find` is the right tool - the assertions check a real filesystem tree, not pure logic.
- Auto-rotate Vercel tokens on detected leak. Rotation is a user decision; the wrapper just makes leaks harder, never silently mints replacements.

## References

- `install/` directory split (this ADR)
- `pipeline/lib/vercel-deploy.sh` - secret-leak defense wrapper
- `pipeline/scripts/smoke-install-layout.sh`, `smoke-vercel-deploy-redact.sh`, `smoke-mode-dispatch-drift.sh`, `smoke-cross-phase-cohesion.sh` - regression gates
- `feedback_vercel_cli_token_leak.md`, `feedback_git_author_repo_local.md`, `feedback_explicit_consent_for_push.md` - incident retrospectives that drove this work
