feat(installer): extract a shared opencode-family implementation and add a codev target

[quickbeard]

Closes #1274.

What

Adds a codev installer target for codev-code (repo) — a fork of opencode that keeps opencode's config format but renames the on-disk app identity.

Why

CodeGraph's opencode target writes to ~/.config/opencode/opencode.jsonc (or ./opencode.jsonc locally). The codev fork reads only ~/.config/codev/codev.jsonc / ./codev.jsonc, so a CodeGraph install is invisible to it — and detect() checks for ~/.config/opencode, so on a machine with only codev installed, --target=auto never even offers it. We maintain the fork and hit this directly: CodeGraph simply doesn't work with it today, and manual config editing is the only workaround.

Everything except the paths is already compatible. We verified against the fork's source that it keeps opencode's config shape byte-for-byte: the same mcp.<name> wrapper with { "type": "local", "command": [...], "enabled": true }, the same https://opencode.ai/config.json $schema (the fork stamps that URL into fresh configs itself), the same XDG-only dir resolution via xdg-basedir on every platform, .jsonc preferred over .json, and the same global + project AGENTS.md instructions convention.

How

The opencode target's mechanics apply to the fork verbatim, so rather than copy the file, this PR:

• targets/opencode-family.ts (new) — the previous opencode.ts implementation, unchanged in behavior, parameterized by a small spec: { id, displayName, docsUrl, appName, sweepLegacyWindowsAppData }. appName drives both the config dir and the config file base name.
• targets/opencode.ts — now a thin spec over the factory (appName: 'opencode', sweepLegacyWindowsAppData: true). Behavior is identical, including the opencode config path on Windows uses %APPDATA% instead of ~/.config/opencode/ #535 legacy %APPDATA% sweep.
• targets/codev.ts (new) — the codev spec (appName: 'codev'), following the "one new file + one registry entry" architecture. The %APPDATA% sweep is off: the pre-opencode config path on Windows uses %APPDATA% instead of ~/.config/opencode/ #535 misplacement is opencode install history the fork never had, so the codev target must never touch %APPDATA%.
• Registry + TargetId union entries, the install/uninstall location-prompt hints, and a CHANGELOG entry under [Unreleased].
• Deliberately not added to the README / site-docs agent lists — we'd rather not advertise a niche fork in your marketing surfaces; happy to add it if you'd prefer the lists stay exhaustive.

Tests

• The parameterized contract suite (install/idempotency/sibling-preservation/uninstall/printConfig) picks the new target up automatically from the registry; the two mcp-vs-mcpServers shape checks now cover both family members.
• New codev-specific tests pin: the global paths (~/.config/codev/codev.jsonc + AGENTS.md), .jsonc-over-.json preference, .json fallback, local ./codev.jsonc, fork independence (installing/uninstalling one never touches the other's files), and that detection and install ignore %APPDATA%/codev entirely.
• __tests__/installer-targets.test.ts: 172/172 pass. Full npm test: 2008 pass (three unrelated worker-exit flakes under parallel run; those files pass individually).

End-to-end verification

Against a scratch $HOME with the built dist/:

1. codegraph install --target=auto --yes with only a ~/.config/codev dir present → detects codev, writes codev.jsonc + AGENTS.md.
2. The real codev binary pointed at that config: codev mcp list → ✓ codegraph connected.
3. codegraph uninstall --target=codev --yes → config back to the bare $schema file, AGENTS.md block gone.

Notes for review

• Left the codegraph install/uninstall command descriptions in src/bin/codegraph.ts untouched — they list only 5 of the 8 existing agents already, so updating them felt like separate cleanup.
• Happy to rename opencode-family.ts or restructure the spec if you'd prefer a different shape for downstream-fork targets.

[colbymchenry]

CodeGraph review

@quickbeard — 1 business rule at risk on this change.

Overall risk: 🟡 Low

This PR introduces a new codev installer target by extracting shared logic into an Opencode‑family implementation and updates the uninstall prompts to reference the new paths. The installer now supports the codev target alongside existing ones, and the changelog documents the new feature. No concrete breakages are evident, but the new shared code lacks direct test coverage.

Worth double-checking

• OpencodeFamilyTarget implementation — Confirm that the shared OpencodeFamilyTarget correctly resolves config and instruction paths for the new codev target and does not interfere with existing opencode behavior.
• Uninstall prompt UI — Verify that the updated uninstall prompt hints now include the codev paths and that the displayed text matches the diff.
• Runtime compatibility (rule r5) — The new OpencodeFamilyTarget class has no direct unit tests; ensure that this lack of coverage does not affect runtime stability.

Business rules (1 at risk · 3 honored · 1 not applicable)

Status	Rule	Note
⚠️ At risk	Runtime compatibility and releases	New shared implementation (OpencodeFamilyTarget) lacks direct unit tests, posing a potential runtime compatibility risk.

QA checklist — 2 things to verify in the running product

• cli — Run codegraph install --target=codev (global) and verify that ~/.config/codev/codev.jsonc is created with a proper $schema and mcp.codegraph entry, and that ~/.config/codev/AGENTS.md contains the CodeGraph block. (Ensures the new codev target writes the expected configuration files without affecting other targets.)
• cli — Run codegraph uninstall --target=codev (global) and confirm that the previously created codev.jsonc and AGENTS.md entries are removed, and that no leftover files remain. (Validates that the uninstall flow correctly cleans up the new target's artifacts.)

Blast radius: 10 files affected beyond the diff · 138 symbols · 1 test file selected

Tests to run:

• __tests__/installer-targets.test.ts

---

Full report

[quickbeard]

Thanks for the review — addressed the at-risk rule in dfdf889.

Runtime compatibility (r5) — OpencodeFamilyTarget direct tests

Added a dedicated "opencode-family factory contract" suite (6 tests) that instantiates the factory with a synthetic spec (appName: 'sampleapp') belonging to neither registered target, so every asserted path can only come from the spec. It pins:

• Spec identity passthrough (id / displayName / docsUrl).
• Path derivation from appName: global ~/.config/<app>/<app>.jsonc + AGENTS.md, local ./<app>.jsonc, and printConfig.
• The existing-.json-over-new-.jsonc preference.
• XDG_CONFIG_HOME resolution.
• The load-bearing one: %APPDATA% handling follows the sweepLegacyWindowsAppData flag rather than the app name — with the sweep disabled, a planted %APPDATA%/<app> entry is invisible to detect/install/uninstall and survives byte-identical; with it enabled, the same state is detected and healed.

That's the contract the next fork target relies on.

Worth noting the class wasn't uncovered before this: both opencode and codev are instances of it, so the parameterized contract suite plus their target-specific tests (172 before, 178 now, all passing) already ran every code path through its two instantiations — what was missing was a test of the parameterization itself, which this adds.

QA checklist

Both items were executed against the built dist/ before the PR went up:

• install --target=codev (global, scratch $HOME) produced codev.jsonc with the $schema + mcp.codegraph entry and the AGENTS.md block, and the real codev binary loaded it (codev mcp list → ✓ codegraph connected).
• uninstall --target=codev removed the entry (config back to the bare $schema file) and the AGENTS.md block, no leftovers.

Uninstall prompt hints

Confirmed the rendered text matches the diff — ~/.config/codev in the global hint, ./codev.jsonc in the local one.

[colbymchenry]

CodeGraph review

Overall risk: 🟡 Low

This PR introduces a new codev installer target by extracting the opencode logic into a shared family implementation and updating the uninstall prompt hints. The change also adds codev to the target registry and updates type definitions. No concrete breakages are evident, but the new target’s behavior should be verified.

Worth double-checking

• Installer target registration — Confirm that codevTarget is correctly exported and included in ALL_TARGETS (src/installer/targets/registry.ts) and that the updated TargetId union (src/installer/targets/types.ts) compiles without affecting existing logic.
• Uninstall prompt hints — Verify the hint strings in runUninstaller (src/installer/index.ts) now list the new codev paths and that the formatting matches other entries.
• Legacy Windows sweep flag — Ensure sweepLegacyWindowsAppData: false for the codev spec prevents any accidental writes to %APPDATA% (opencode-family.ts: legacyWindowsConfigDir logic).

Business rules (3 honored · 2 not applicable)

No rules violated or at risk.

QA checklist — 3 things to verify in the running product

• cli — Run codegraph install --target=codev --location=global and verify that ~/.config/codev/codev.jsonc contains a mcp.codegraph entry and that ~/.config/opencode remains untouched. (Validates that the new codev target writes to its own config directory without interfering with the existing opencode target.)
• cli — Run codegraph uninstall --target=codev --location=global and confirm that the codev.jsonc file is removed (or the codegraph entry is removed) and no residual AGENTS.md block remains. (Ensures the uninstall path correctly cleans up the codev configuration and does not leave stale markers.)
• cli — Execute codegraph install --target=codev --location=local in a temporary project and check that ./codev.jsonc is created with the correct schema and MCP entry. (Checks that the local‑install path works for the new target.)

Blast radius: 10 files affected beyond the diff · 138 symbols · 1 test file selected

Tests to run:

• __tests__/installer-targets.test.ts

---

Full report

[quickbeard]

Confirmed resolved on the current tip (dfdf889). The at-risk r5 finding (no direct tests for the shared OpencodeFamilyTarget) is covered by the new "opencode-family factory contract" suite that drives the factory through a synthetic appName: 'sampleapp' spec (belonging to neither registered target), pinning spec-identity passthrough, appName-derived path resolution, the .json-over-.jsonc preference, XDG_CONFIG_HOME handling, and the sweepLegacyWindowsAppData flag behavior. The follow-up review now reports no rules violated or at risk.

Re-verified locally:

• npx vitest run __tests__/installer-targets.test.ts → 178/178 pass
• npx tsc --noEmit → clean (the codev TargetId union compiles)

The QA-checklist items (install/uninstall --target=codev global + local) were also executed against the built dist/, including loading the config with the real codev binary (codev mcp list → ✓ codegraph connected).