suaveplan/openspec/changes/complete-installer/tasks.md

# Tasks: complete-installer

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Error codes

- [ ] 1.1 Extend `src/error-codes.ts` `defineCodes("INSTALLER", [...])` tuple
      with every code listed in `design.md` §"Error codes" (existing nine,
      seven upgrade codes from the superseded change, eighteen new codes).
- [ ] 1.2 Update `src/error-codes.md` to enumerate every code with one-line
      semantic description.
- [ ] 1.3 Rewrite `src/error-codes.spec-conformance.test.ts` to assert every
      code value is present, frozen, and `INSTALLER.`-prefixed
      (`MODIFIED: registry contains every complete-installer code`).

## 2. State + lockfile + journal (`src/state/`)

- [ ] 2.1 `src/state/state.types.ts` — `InstallerState`, `InstalledPlugin`,
      `FileHash`, named option / report types.
- [ ] 2.2 `src/state/state.schemas.ts` — Zod schemas validating the on-disk
      shape.
- [ ] 2.3 `src/state/state-file.ts` — `loadState`, `writeState` (atomic
      write → fsync → rename), `updatePlugin`, `removePlugin`. Throws
      `INSTALLER.STATE_INVALID` on schema failure.
- [ ] 2.4 `src/state/state-file.spec-conformance.test.ts` covering atomic
      write and load-validation paths.
- [ ] 2.5 `src/state/hash-tree.ts` — `hashTree(fs, dir)` via BLAKE3
      (`@suaveplan/crypto-hash`).
- [ ] 2.6 `src/state/journal.ts` — append-only newline-JSON journal with
      `beginTxn`, `stage`, `commit`, `abort`, `replay`. Throws
      `INSTALLER.JOURNAL_REPLAY_FAILED` on malformed lines.
- [ ] 2.7 `src/state/journal.spec-conformance.test.ts`.
- [ ] 2.8 `src/state/lockfile.ts` — `loadLockfile`, `writeLockfile`
      (deterministic sorted keys, integrity digest). Throws
      `INSTALLER.LOCKFILE_INVALID` / `INSTALLER.LOCKFILE_WRITE_FAILED`.
- [ ] 2.9 `src/state/lockfile.spec-conformance.test.ts` (byte-identical
      round-trip).
- [ ] 2.10 Sibling `.md` for every new file.

## 3. Registry sources (`src/registry/`)

- [ ] 3.1 `src/registry/registry.types.ts` — `RegistrySource` interface,
      `ResolvedPlugin`, `SearchHit`, `SearchOptions`.
- [ ] 3.2 `src/registry/registry.schemas.ts` — Zod boundary schemas.
- [ ] 3.3 `src/registry/verdaccio/verdaccio.ts` — default source, reuses
      `discoverPlugins`; adds `search` + version listing over HTTP.
- [ ] 3.4 `src/registry/oci/oci.ts` — OCI tarball pull, `OCI_TOKEN`.
- [ ] 3.5 `src/registry/git/git.ts` — `git clone --depth 1`.
- [ ] 3.6 `src/registry/local-tarball/local-tarball.ts` — tar-extract.
- [ ] 3.7 `src/registry/index.ts` — explicit named re-exports.
- [ ] 3.8 `*.spec-conformance.test.ts` per source (4 files).
- [ ] 3.9 `src/testing/fixtures/registry/verdaccio-container.ts` —
      testcontainers Verdaccio fixture + fixture plugin catalogue.
- [ ] 3.10 Sibling `.md` for every new file.

## 4. Plugin host extensions (`src/host/hooks/`, `src/host/upgrade/`)

- [ ] 4.1 `src/host/hooks/hooks.ts` — invoke `preInstall`/`postInstall`/
      `preUpgrade`/`postUpgrade`/`preUninstall`/`postUninstall` with OTel
      spans + rollback-on-throw.
- [ ] 4.2 `src/host/hooks/hooks.spec-conformance.test.ts`.
- [ ] 4.3 Extend `InstallerPlugin` interface in
      `src/types/installer.types.ts` with `capabilities`, `dependsOn`,
      and the six new hook fields.
- [ ] 4.4 `src/host/upgrade/upgrade.ts` — full pipeline per spec.
- [ ] 4.5 `src/host/upgrade/preflight.ts` — lockfile + dirty-tree gates.
- [ ] 4.6 `src/host/upgrade/diff.ts` + `materialise` helpers.
- [ ] 4.7 `src/host/upgrade/migrations.ts` + `migrations.types.ts` —
      `MigrationContext`, `MigrationTable`, `loadMigrationTable`,
      `selectMigrations` (BFS), `runMigrations` (transactional).
- [ ] 4.8 Upgrade `*.spec-conformance.test.ts` files (`upgrade`,
      `preflight`, `dirty-tree`, `apply-diff`, `migrations`).
- [ ] 4.9 Sibling `.md` for every new file.

## 5. Installer class + commands (`src/installer/`)

- [ ] 5.1 `src/installer/installer.ts` — `Installer` class wrapping
      `Host`, exposing every documented method. ≤300 lines: factor each
      command into its own file.
- [ ] 5.2 `src/installer/install.ts` — `install` orchestrator: resolve
      registry → discover plugin → resolve deps → host run → write state
      → write lockfile.
- [ ] 5.3 `src/installer/reinstall.ts` — force-reapply at recorded
      version. Throws `REINSTALL_NOT_INSTALLED`.
- [ ] 5.4 `src/installer/uninstall.ts` — gate dirty-tree, run hooks,
      delete recorded files transactionally, drop state + lockfile
      entry. Throws `UNINSTALL_NOT_INSTALLED`, `UNINSTALL_DIRTY_TREE`.
- [ ] 5.5 `src/installer/list.ts` — enumerate with drift status.
- [ ] 5.6 `src/installer/info.ts` — manifest + state + transitive
      dependency graph. Throws `INFO_NOT_INSTALLED`.
- [ ] 5.7 `src/installer/pin.ts` — set `pinned: true, resolved`.
- [ ] 5.8 `src/installer/unpin.ts` — clear `pinned` flag.
- [ ] 5.9 `src/installer/freeze.ts` — deterministic lockfile snapshot.
- [ ] 5.10 `src/installer/update.ts` — `--all` bulk upgrade with
      partial-failure aggregation. Throws `UPDATE_PARTIAL_FAILURE`.
- [ ] 5.11 `src/installer/search.ts` — delegate to active registry.
      Throws `REGISTRY_UNREACHABLE`.
- [ ] 5.12 `src/installer/doctor.ts` — every diagnostic check in
      parallel; `--fix` for journal rollback only.
- [ ] 5.13 `src/installer/dependency-graph.ts` — Tarjan cycle detect +
      topological sort. Throws `DEPENDENCY_CYCLE`,
      `DEPENDENCY_UNSATISFIED`.
- [ ] 5.14 Conformance tests:
      - [ ] 5.14.1 `src/installer/installer.spec-conformance.test.ts`
            (install, reinstall, uninstall, list, info, pin/unpin, freeze,
            update, search, dependency-cycle, OTel span, event-bus).
      - [ ] 5.14.2 `src/installer/doctor.spec-conformance.test.ts`.
- [ ] 5.15 OTel span instrumentation on every public method:
      `installer.<method>` with documented attributes + error recording.
- [ ] 5.16 Typed event-bus emission on every state-mutating method.
- [ ] 5.17 `src/installer/index.ts` — explicit named re-exports.
- [ ] 5.18 Sibling `.md` for every new file.

## 6. CLI bin (`src/bin/`)

- [ ] 6.1 Extend `src/bin/suaveplan-install.ts` to register every verb:
      `install`, `reinstall`, `upgrade`, `uninstall`, `list`, `info`,
      `doctor`, `pin`, `unpin`, `freeze`, `update`, `search`. Keep `add`
      as an alias of `install`.
- [ ] 6.2 Parse every documented global flag (`--dry-run`, `--force`,
      `--no-interactive`, `--answers <file>`, `--cwd <dir>`,
      `--registry <name>`, `--json`) and verb-specific flags from
      design.md.
- [ ] 6.3 `--json` output path: emit the report object verbatim.
- [ ] 6.4 `src/bin/suaveplan-install.spec-conformance.test.ts`
      asserting every verb forwards every flag (recording `Installer`
      stub).
- [ ] 6.5 Update `src/bin/suaveplan-install.md`.

## 7. Type / schema additions (`src/types/`, `src/schemas/`)

- [ ] 7.1 Extend `src/types/installer.types.ts` with `InstallerOptions`,
      `InstallReport`, `UpgradeReport`, `UninstallReport`,
      `InstalledPluginInfo`, `PluginInfoReport`, `DoctorReport`,
      `DoctorFinding`, `LockfileReport`, `UpdateReport`, `SearchHit`,
      `SearchOptions`, lifecycle hook signatures, dependency types.
- [ ] 7.2 Extend `src/schemas/` with Zod validators for every new
      report / option type.
- [ ] 7.3 No inline shapes anywhere (AGENTS.md §11).

## 8. Subpath exports + barrels

- [ ] 8.1 `package.json` `exports` map gains one subpath per new feature
      module: `./installer/installer`, `./installer/install`,
      `./installer/reinstall`, `./installer/uninstall`, `./installer/list`,
      `./installer/info`, `./installer/pin`, `./installer/unpin`,
      `./installer/freeze`, `./installer/update`, `./installer/search`,
      `./installer/doctor`, `./installer/dependency-graph`,
      `./state/state-file`, `./state/journal`, `./state/lockfile`,
      `./state/hash-tree`, `./registry`, `./registry/verdaccio`,
      `./registry/oci`, `./registry/git`, `./registry/local-tarball`,
      `./host/upgrade`, `./host/hooks`, `./migrations`.
- [ ] 8.2 Every `<feature>/index.ts` uses explicit named re-exports
      (AGENTS.md §6a — no `export *`).
- [ ] 8.3 Package-root `src/index.ts` re-exports the `Installer` class
      plus every named report type for the top-level surface.

## 9. Testing fixtures (`src/testing/fixtures/`)

- [ ] 9.1 `src/testing/fixtures/plugins/base-plugin.ts` — simple plugin
      no dependencies, exercises the install / uninstall path.
- [ ] 9.2 `src/testing/fixtures/plugins/dependent-plugin.ts` —
      depends on `base-plugin`, exercises topological resolution.
- [ ] 9.3 `src/testing/fixtures/plugins/cyclic-a-plugin.ts` +
      `cyclic-b-plugin.ts` — exercise `DEPENDENCY_CYCLE`.
- [ ] 9.4 `src/testing/fixtures/plugins/upgrade-fixture-plugin.ts` —
      `1.0.0` and `2.0.0` variants with one migration script.
- [ ] 9.5 `src/testing/fixtures/plugins/hooks-fixture-plugin.ts` —
      every lifecycle hook implemented for hook-order tests.

## 10. Docs

- [ ] 10.1 Every new implementation `.ts` has a sibling `.md` meeting
      AGENTS.md §4 (≥200 words, Purpose / Features / Basic / Advanced /
      API Reference / Implementation Notes, both examples compile).
- [ ] 10.2 Update root `packages/tooling/installer/README.md` to
      enumerate every verb, link to per-module docs in the **Modules**
      section, and show a quickstart for `install`, `upgrade`,
      `uninstall`, `doctor`, `search`.
- [ ] 10.3 No `TODO`, `FIXME`, `@deprecated`, marketing language, or
      stub-doc placeholders anywhere (AGENTS.md §2b).

## 11. Dependent sweep + impact

- [ ] 11.1 Add empty `upgrade.ts` `MigrationTable` export to
      `@suaveplan/install-agent-skills` and wire it through the
      manifest so the migration-loader path runs even with zero
      migrations.
- [ ] 11.2 Add optional `preInstall` and `postUninstall` hooks to
      `@suaveplan/install-agent-skills` so hooks-fixture path is
      exercised by a real consumer.
- [ ] 11.3 Extend `install-agent-skills` conformance harness with
      `upgradePlugin`, `uninstallPlugin`, `reinstallPlugin` helpers
      mirroring `runPlugin`.
- [ ] 11.4 `bunx turbo test --filter=...@suaveplan/installer` green.

## 12. Pre-archive gates (AGENTS.md §13)

- [ ] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/installer`
      green.
- [ ] 12.2 `bunx turbo test:coverage --filter=@suaveplan/installer`
      100% istanbul on every new module.
- [ ] 12.3 `bun run check` (biome) green.
- [ ] 12.4 Banned-pattern scan (`@deprecated|TODO|FIXME|ts-ignore|
      ts-expect-error|.skip|.only`) zero output in new files.
- [ ] 12.5 Test-runner-import scan (`from "vitest"` / `from "bun:test"`)
      zero output in new files (AGENTS.md §7).
- [ ] 12.6 Barrel-shape scan (no `export *` in feature `index.ts` files)
      zero output (AGENTS.md §6a).
- [ ] 12.7 Missing `.md` scan zero output.
- [ ] 12.8 Subpath export count matches feature-module count.
- [ ] 12.9 Bare-version scan zero output (`catalog:` / `workspace:^`).
- [ ] 12.10 File-size scan: every `*.ts` ≤ 300 lines, every `*.test.ts`
      ≤ 500 lines.
- [ ] 12.11 `bunx turbo build --filter=@suaveplan/installer` green.

## 13. Root-doc refresh + markdownlint (AGENTS.md §13b)

- [ ] 13.1 `bun scripts/folder-reorg/generate-manifest.ts` to refresh
      `MANIFEST.md`.
- [ ] 13.2 `bun scripts/generate-missing.ts` to refresh `MISSING.yml`.
- [ ] 13.3 Update `STATUS.md` installer row (already Completed; refresh
      surface description).
- [ ] 13.4 Update `SUMMARY.md` installer paragraph to enumerate every
      verb + library surface.
- [ ] 13.5 `bunx markdownlint-cli2 --fix` against touched markdown,
      resolve any unfixable violations by hand.

## 14. Archive (AGENTS.md §14)

- [ ] 14.1 Fold `specs/installer/spec.md` delta into
      `openspec/specs/installer/spec.md` (modified `INSTALLER-09`
      replaces the existing one verbatim; every ADDED requirement
      appends).
- [ ] 14.2 Delete the superseded folder
      `openspec/changes/_superseded-narrow-deferrals-2026-05-17/add-installer-upgrade/`
      since its content is now subsumed.
- [ ] 14.3 Move `openspec/changes/complete-installer/` →
      `openspec/archive/<yyyy-mm-dd>-complete-installer/`.
- [ ] 14.4 `openspec validate complete-installer --strict` green prior
      to archive.