@colbymchenry/codegraph 0.9.6 → 0.9.8

package/dist/installer/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * CodeGraph Interactive Installer
+ *
+ * Multi-target: writes MCP server config + instructions for the
+ * agents the user picks (Claude Code, Cursor, Codex CLI, opencode,
+ * Hermes Agent, Gemini CLI, Antigravity IDE).
+ * Defaults to the Claude-only behavior for backwards compatibility
+ * when no targets are explicitly chosen and nothing else is detected.
+ *
+ * Uses @clack/prompts for the interactive UI; `runInstallerWithOptions`
+ * is the non-interactive entry point used by the `--target` /
+ * `--print-config` CLI flags.
+ */
+import type { AgentTarget, Location, TargetId } from './targets/types';
+export { writeMcpConfig, writePermissions, hasMcpConfig, hasPermissions, } from './config-writer';
+export type { InstallLocation } from './config-writer';
+export interface RunInstallerOptions {
+    /** Comma-separated target list, or `auto` / `all` / `none`. */
+    target?: string;
+    /** Skip the location prompt; use this value directly. */
+    location?: Location;
+    /** Skip the auto-allow prompt; use this value directly. */
+    autoAllow?: boolean;
+    /**
+     * Skip every confirm and use defaults: location=global,
+     * autoAllow=true, target=auto. For scripting / CI.
+     */
+    yes?: boolean;
+}
+/**
+ * Interactive entry point — preserves the historical UX (`codegraph
+ * install` with no args goes through the prompts), but now starts
+ * the targets multi-select pre-populated with detected agents.
+ */
+export declare function runInstaller(): Promise<void>;
+export declare function runInstallerWithOptions(opts: RunInstallerOptions): Promise<void>;
+export interface RunUninstallerOptions {
+    /**
+     * Comma-separated target list, or `auto` / `all` / `none`. Defaults
+     * to `all` — uninstall sweeps every known agent and reports which
+     * ones it actually touched, so the user doesn't have to know where
+     * they configured it.
+     */
+    target?: string;
+    /** Skip the location prompt; use this value directly. */
+    location?: Location;
+    /** Non-interactive: location=global, target=all, no prompts. */
+    yes?: boolean;
+}
+export type UninstallStatus = 'removed' | 'not-configured' | 'unsupported';
+/**
+ * Per-target outcome of an uninstall sweep. `removed` means we deleted
+ * at least one thing; `not-configured` means the agent had no codegraph
+ * config at this location (nothing to do); `unsupported` means the
+ * agent has no config concept for this location (e.g. Codex is
+ * global-only, so a `local` uninstall skips it).
+ */
+export interface UninstallReport {
+    id: TargetId;
+    displayName: string;
+    status: UninstallStatus;
+    /** Absolute paths we actually edited/removed (action === 'removed'). */
+    removedPaths: string[];
+    /** Verbatim notes from the target (rare for uninstall). */
+    notes: string[];
+}
+/**
+ * Pure uninstall sweep — no prompts, no I/O beyond the targets' own
+ * file edits. Exposed (and unit-tested) separately from the clack UI in
+ * `runUninstaller` so the aggregation logic can be asserted directly.
+ *
+ * Each target's `uninstall()` is already safe to call when nothing was
+ * installed (it returns `not-found` actions), so this is safe to run
+ * across every target unconditionally.
+ */
+export declare function uninstallTargets(targets: readonly AgentTarget[], location: Location): UninstallReport[];
+/**
+ * Interactive uninstaller — the inverse of `runInstallerWithOptions`.
+ * Asks global-vs-local first (unless `--location`/`--yes` is given),
+ * then sweeps every agent target (or the `--target` subset) and prints
+ * one block per agent so the user sees exactly which providers it hit.
+ *
+ * Removes only what install wrote (MCP server entry, instructions
+ * block, permissions) — never the `.codegraph/` index, which `codegraph
+ * uninit` owns.
+ */
+export declare function runUninstaller(opts: RunUninstallerOptions): Promise<void>;
+/**
+ * When the live file watcher will be disabled for this project (e.g. WSL2
+ * /mnt drives, or CODEGRAPH_NO_WATCH), the index would silently go stale.
+ * Explain that, and offer to keep it fresh automatically via git hooks
+ * (commit / pull / checkout) instead of manual `codegraph sync`.
+ *
+ * No-op on environments where the watcher runs normally, so it's safe to
+ * call unconditionally after init.
+ */
+export declare function offerWatchFallback(clack: typeof import('@clack/prompts'), projectPath: string, opts?: {
+    yes?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/installer/instructions-template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Marker constants for the legacy agent-instructions block.
+ *
+ * Codegraph used to write a `## CodeGraph` usage guide into each
+ * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md /
+ * codegraph.mdc / Kiro steering doc). That duplicated the guidance the
+ * MCP server already emits in its `initialize` response — every agent
+ * read the same playbook twice each turn (issue #529). The installer no
+ * longer writes an instructions file; the MCP server instructions in
+ * `mcp/server-instructions.ts` are the single source of truth.
+ *
+ * These markers are retained so install (self-heal on upgrade) and
+ * uninstall can find and strip the block a previous install wrote.
+ */
+/** Markers used by the marker-based section removal. */
+export declare const CODEGRAPH_SECTION_START = "<!-- CODEGRAPH_START -->";
+export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
+//# sourceMappingURL=instructions-template.d.ts.map

package/dist/installer/targets/antigravity.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Google Antigravity IDE target. Antigravity is Google's VS Code-derived
+ * multi-agent IDE; the Gemini CLI is in the process of consolidating with
+ * it under a single agent platform. Antigravity reads MCP server
+ * definitions from a separate config file from the CLI.
+ *
+ * ## Config path: unified vs legacy
+ *
+ * Antigravity recently migrated to a **unified** MCP config path shared
+ * across all Antigravity tools:
+ *
+ *   - **Unified** (post-migration, current): `~/.gemini/config/mcp_config.json`
+ *     — signalled by the `~/.gemini/config/.migrated` marker file.
+ *   - **Legacy** (pre-migration): `~/.gemini/antigravity/mcp_config.json`
+ *     — what the github-mcp-server install guide still documents.
+ *
+ * We detect the marker at install time and write to the right path. On
+ * uninstall we sweep BOTH — so a user who installed on the legacy path,
+ * was then auto-migrated by Antigravity, and re-ran `codegraph install`
+ * doesn't end up with stale codegraph entries in two files.
+ *
+ * ## Entry shape: no `type: stdio` field
+ *
+ * Antigravity rejects MCP entries that carry the `type: "stdio"` field
+ * the rest of our targets use — the working entries it manages itself
+ * (e.g. `code-review-graph`) omit it, and dropping it was load-bearing
+ * to get codegraph to appear in the Customizations UI. We build the
+ * entry locally instead of routing through `getMcpServerConfig()`.
+ *
+ * ## macOS GUI app PATH resolution
+ *
+ * Antigravity is a GUI Electron app. macOS gives Dock/Finder-launched
+ * apps a stripped PATH (`/usr/bin:/bin:/usr/sbin:/sbin`) — nvm-managed
+ * tools live outside that, so a bare `codegraph` command fails to spawn
+ * even when `which codegraph` resolves in the user's shell. We resolve
+ * `codegraph` to its absolute path on macOS at install time. (Linux GUI
+ * apps inherit user PATH; Windows uses `PATH` env directly — both are
+ * fine with the bare command.)
+ *
+ * ## Shared instructions (no GEMINI.md from here)
+ *
+ * The IDE shares `~/.gemini/GEMINI.md` with Gemini CLI for instructions
+ * — written by the `./gemini.ts` target. We deliberately don't touch it
+ * here so uninstalling Antigravity without uninstalling Gemini CLI
+ * leaves CLI instructions intact. Users who install only Antigravity
+ * still get a working MCP integration; the prefer-codegraph-over-grep
+ * guidance just won't be present unless they also install the gemini
+ * target.
+ *
+ * ## Location
+ *
+ * `supportsLocation('local')` returns false — Antigravity has no
+ * project-scoped config concept as of 2026-05.
+ */
+import { AgentTarget } from './types';
+export declare const antigravityTarget: AgentTarget;
+//# sourceMappingURL=antigravity.d.ts.map

package/dist/installer/targets/claude.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Claude Code target. Writes:
+ *
+ *   - MCP server entry to `~/.claude.json` (global = user scope, loads
+ *     in every project) or `./.mcp.json` (local = project scope, the
+ *     file Claude Code actually reads for a single project). See the
+ *     scope table at https://code.claude.com/docs/en/mcp.
+ *   - Permissions to `~/.claude/settings.json` (global) or
+ *     `./.claude/settings.json` (local), gated on `autoAllow`.
+ *   - Instructions to `~/.claude/CLAUDE.md` (global) or
+ *     `./.claude/CLAUDE.md` (local).
+ *
+ * Earlier versions wrote the local MCP entry to `./.claude.json` — a
+ * file Claude Code never reads — so the server silently never loaded
+ * until the user manually renamed it to `.mcp.json` (issue #207). We
+ * now write `./.mcp.json` and migrate any stale `./.claude.json` entry
+ * out of the way on install and uninstall.
+ */
+import { AgentTarget, Location, WriteResult } from './types';
+/**
+ * Per-file write helpers, exported so the legacy `config-writer.ts`
+ * shim can call only the named operation (writeMcpConfig writes ONLY
+ * the MCP entry, etc.) instead of `claudeTarget.install()` which
+ * writes all three files. Without this split the shims silently
+ * cause side effects callers don't expect.
+ */
+export declare function writeMcpEntry(loc: Location): WriteResult['files'][number];
+/**
+ * Remove stale codegraph auto-sync hooks from Claude `settings.json`.
+ *
+ * Surgical at the individual-command level: only entries matching
+ * `isLegacyCodegraphHookCommand` are dropped, so a sibling hook sharing
+ * a matcher group (or the Stop event) with ours survives. We prune a
+ * matcher group only once its `hooks` array is empty, an event only
+ * once it has no groups left, and `hooks` itself only once every event
+ * is gone — and none of that runs unless we actually removed a
+ * codegraph command, so a settings.json with no legacy hooks is left
+ * byte-for-byte untouched and reported `unchanged`.
+ *
+ * Exported so it can be unit-tested directly and reused by both
+ * `install` (an upgrade self-heals) and `uninstall`.
+ */
+export declare function cleanupLegacyHooks(loc: Location): WriteResult['files'][number];
+export declare function writePermissionsEntry(loc: Location): WriteResult['files'][number];
+/**
+ * Strip the marker-delimited CodeGraph block from CLAUDE.md if a prior
+ * install wrote one. Codegraph no longer maintains an instructions file
+ * (issue #529) — the MCP server's `initialize` instructions are the
+ * single source of truth — so both install (self-heal on upgrade) and
+ * uninstall call this. `removeMarkedSection` returns `not-found`/`kept`
+ * when there's nothing to strip; the install caller drops those from
+ * the report so a fresh install stays quiet.
+ */
+export declare function removeInstructionsEntry(loc: Location): WriteResult['files'][number];
+export declare const claudeTarget: AgentTarget;
+//# sourceMappingURL=claude.d.ts.map

package/dist/installer/targets/codex.d.ts

@@ -0,0 +1,18 @@
+/**
+ * OpenAI Codex CLI target.
+ *
+ *   - MCP server entry to `~/.codex/config.toml` as the dotted-key
+ *     table `[mcp_servers.codegraph]`. TOML — not JSON — handled by
+ *     the narrow serializer in `./toml.ts`.
+ *   - Instructions to `~/.codex/AGENTS.md`.
+ *
+ * Codex CLI as of 2026-05 has no project-local config concept —
+ * everything lives under `~/.codex/`. `supportsLocation('local')`
+ * returns false; the orchestrator skips Codex when the user picks
+ * the local install location.
+ *
+ * No permissions concept.
+ */
+import { AgentTarget } from './types';
+export declare const codexTarget: AgentTarget;
+//# sourceMappingURL=codex.d.ts.map

package/dist/installer/targets/cursor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cursor target.
+ *
+ *   - MCP server entry to `~/.cursor/mcp.json` (global) or
+ *     `./.cursor/mcp.json` (local). Same `{mcpServers: {...}}` shape
+ *     as Claude.
+ *   - Instructions to `./.cursor/rules/codegraph.mdc` (project-local
+ *     ONLY). Cursor's rules system is a project-scoped surface;
+ *     global cursor rules aren't a stable convention as of 2026-05.
+ *     For `--location=global`, only mcp.json is written.
+ *
+ * ## Why we hardcode `--path` for Cursor
+ *
+ * Cursor launches MCP-server subprocesses with a working directory
+ * that ISN'T the workspace root AND doesn't pass `rootUri` /
+ * `workspaceFolders` in the MCP initialize call. The codegraph MCP
+ * server's `process.cwd()` fallback therefore misses the workspace's
+ * `.codegraph/` and reports "not initialized" on every tool call.
+ *
+ * So we inject `--path` into the args ourselves:
+ *
+ *   - `local`  install: absolute path (we know it at install time).
+ *   - `global` install: `${workspaceFolder}` — Cursor expands this to
+ *     the open workspace's root, giving us per-workspace behavior
+ *     from a single global config.
+ *
+ * Codex and Claude do not need this — they launch MCP servers with
+ * `cwd = workspace` and pass `rootUri`, respectively.
+ *
+ * No permissions concept — Cursor doesn't have an auto-allow list
+ * the installer can populate. `autoAllow` is silently ignored.
+ */
+import { AgentTarget } from './types';
+export declare const cursorTarget: AgentTarget;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/installer/targets/gemini.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Gemini CLI target (also covers the rebranded "Antigravity CLI" —
+ * Google is in the middle of unifying its CLI tools under
+ * Antigravity, and the new CLI continues to read `~/.gemini/settings.json`
+ * + project-local `.gemini/settings.json`). Writes:
+ *
+ *   - MCP server entry to `~/.gemini/settings.json` (global) or
+ *     `./.gemini/settings.json` (local) under the standard
+ *     `mcpServers.codegraph` key. Same shape as Claude / Cursor.
+ *   - Instructions to `~/.gemini/GEMINI.md` (global) or `./GEMINI.md`
+ *     (local — Gemini reads the project root file directly, not
+ *     under `.gemini/`).
+ *
+ * No permissions concept — Gemini CLI gates tool invocations through
+ * the `trust` field per server, not an external allowlist. We leave
+ * `trust` unset so the user controls confirmation prompts.
+ *
+ * The Antigravity IDE shares `~/.gemini/GEMINI.md` for instructions
+ * but uses a separate MCP config file (`~/.gemini/antigravity/mcp_config.json`)
+ * — see `./antigravity.ts`. Both targets writing to GEMINI.md is
+ * safe: the marker-based section replacement makes the second write
+ * a byte-identical no-op.
+ */
+import { AgentTarget } from './types';
+export declare const geminiTarget: AgentTarget;
+//# sourceMappingURL=gemini.d.ts.map

package/dist/installer/targets/hermes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hermes Agent target.
+ *
+ * Hermes reads MCP servers from `$HERMES_HOME/config.yaml` under the
+ * top-level `mcp_servers` key, and exposes discovered MCP tools through
+ * dynamic toolsets named `mcp-<server>`. We add:
+ *
+ *   mcp_servers.codegraph -> `codegraph serve --mcp`
+ *   platform_toolsets.cli -> `mcp-codegraph`
+ *
+ * The second entry matters because Hermes CLI profiles often enable an
+ * explicit `platform_toolsets.cli` list. Without `mcp-codegraph` in that
+ * list, the MCP server can be configured and connected but its tools may
+ * still be filtered out of normal CLI sessions.
+ */
+import { AgentTarget } from './types';
+export declare const hermesTarget: AgentTarget;
+//# sourceMappingURL=hermes.d.ts.map

package/dist/installer/targets/kiro.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Kiro CLI / IDE target. Writes:
+ *
+ *   - MCP server entry to `~/.kiro/settings/mcp.json` (global) or
+ *     `./.kiro/settings/mcp.json` (local). Standard `mcpServers.codegraph`
+ *     shape, same as Claude / Cursor / Gemini.
+ *   - Instructions to `~/.kiro/steering/codegraph.md` (global) or
+ *     `./.kiro/steering/codegraph.md` (local). Kiro's "steering" system
+ *     loads every `*.md` file in the steering dir as agent context, so
+ *     a dedicated `codegraph.md` is the natural surface — we own the
+ *     whole file outright (no marker-based merging needed) and delete
+ *     it on uninstall.
+ *
+ * No permissions concept — Kiro gates tool invocations through its own
+ * UI prompts rather than an external allowlist. `autoAllow` is silently
+ * ignored.
+ *
+ * Paths are identical on macOS / Linux / Windows because Kiro resolves
+ * its config root from `os.homedir()` on all three (Windows `~` →
+ * `%USERPROFILE%\.kiro`).
+ *
+ * Docs: https://kiro.dev/docs/cli/mcp/
+ *       https://kiro.dev/docs/cli/steering/
+ */
+import { AgentTarget } from './types';
+export declare const kiroTarget: AgentTarget;
+//# sourceMappingURL=kiro.d.ts.map

package/dist/installer/targets/opencode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * opencode target.
+ *
+ *   - MCP server entry to `~/.config/opencode/opencode.jsonc` (global,
+ *     XDG-style; `%APPDATA%/opencode/opencode.jsonc` on Windows) or
+ *     `./opencode.jsonc` (local). Falls back to `opencode.json` when a
+ *     `.json` file already exists; defaults new installs to `.jsonc`
+ *     because that's what opencode itself creates on first run.
+ *   - Instructions to `~/.config/opencode/AGENTS.md` (global) or
+ *     `./AGENTS.md` (local). opencode reads AGENTS.md for agent
+ *     instructions — same convention Codex CLI uses.
+ *   - No permissions concept.
+ *
+ * Config shape uses opencode's wrapper:
+ *   {
+ *     "$schema": "https://opencode.ai/config.json",
+ *     "mcp": { "codegraph": { "type": "local", "command": [...], "enabled": true } }
+ *   }
+ *
+ * The shape differs from Claude/Cursor — opencode uses `mcp.<name>`
+ * (not `mcpServers`), takes `command` as a string array combining
+ * binary + args, and includes an explicit `enabled` flag.
+ *
+ * Reads + writes go through `jsonc-parser` so any `//` and `/* *\/`
+ * comments the user has added to their `.jsonc` survive idempotent
+ * re-runs.
+ */
+import { AgentTarget } from './types';
+export declare const opencodeTarget: AgentTarget;
+//# sourceMappingURL=opencode.d.ts.map

package/dist/installer/targets/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Registry of all known agent targets.
+ *
+ * Adding a new target = create `targets/<id>.ts` exporting an
+ * `AgentTarget`, then add it to the array below. Order here is the
+ * order they appear in the multiselect prompt, in `--target=all`,
+ * and in `--print-config`'s help listing — keep it stable.
+ */
+import { AgentTarget, Location, TargetId } from './types';
+export declare const ALL_TARGETS: readonly AgentTarget[];
+export declare function getTarget(id: string): AgentTarget | undefined;
+export declare function listTargetIds(): TargetId[];
+/**
+ * Run `detect()` for every target at the given location. Returns the
+ * full registry zipped with detection results — orchestrator uses
+ * this to seed the multiselect prompt with installed agents
+ * pre-checked.
+ */
+export declare function detectAll(loc: Location): Array<{
+    target: AgentTarget;
+    detection: ReturnType<AgentTarget['detect']>;
+}>;
+/**
+ * Resolve a `--target=` flag value to a list of `AgentTarget`
+ * instances. Accepts:
+ *
+ *   - `auto` — return all targets whose `detect().installed` is true,
+ *     or `['claude']` as a fallback if none detected (least-surprise
+ *     for existing users).
+ *   - `all` — every target in the registry.
+ *   - `none` — empty list (caller skips agent writes entirely).
+ *   - csv list — `'claude,cursor'` etc. Unknown ids throw.
+ */
+export declare function resolveTargetFlag(value: string, loc: Location): AgentTarget[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/installer/targets/shared.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Helpers shared across `AgentTarget` implementations.
+ *
+ * Lifted from the original `config-writer.ts` so each target can
+ * compose them without inheritance. Kept deliberately small — the
+ * targets are different enough (JSON vs TOML vs Markdown, varying
+ * idempotency markers) that a base class would force the awkward
+ * shape onto everyone.
+ */
+/**
+ * The MCP-server config block codegraph injects. Same shape across
+ * all JSON-shaped agent configs (Claude, Cursor, opencode), only the
+ * surrounding wrapper differs. Codex (TOML) builds its own block.
+ */
+export declare function getMcpServerConfig(): {
+    type: string;
+    command: string;
+    args: string[];
+};
+/**
+ * Permissions list for Claude `settings.json`. Other targets that
+ * have a permissions concept can compose this list directly. The
+ * permission strings follow Claude's `mcp__<server>__<tool>` format.
+ */
+export declare function getCodeGraphPermissions(): string[];
+/**
+ * Read a JSON file, returning `{}` when missing or unparseable.
+ *
+ * Unparseable files are backed up to `<path>.backup` BEFORE we return
+ * `{}` — so an idempotent re-run never silently deletes a user's
+ * existing config that happened to break JSON parse temporarily.
+ */
+export declare function readJsonFile(filePath: string): Record<string, any>;
+/**
+ * Write a file atomically: write to `<path>.tmp.<pid>`, then rename.
+ *
+ * Prevents corruption if the process crashes mid-write. The temp
+ * file is cleaned up on rename failure.
+ */
+export declare function atomicWriteFileSync(filePath: string, content: string): void;
+/**
+ * Atomic JSON write. Trailing newline matches the convention every
+ * existing target had — preserves diff-friendly file shape.
+ */
+export declare function writeJsonFile(filePath: string, data: Record<string, any>): void;
+/**
+ * Compare two JSON values for deep equality, ignoring key order.
+ *
+ * Used for idempotency: when the on-disk config already exactly
+ * matches what we'd write, return action=`unchanged` instead of
+ * re-writing (and emitting a confusing "Updated" log line).
+ */
+export declare function jsonDeepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Replace or append a marker-delimited section in a markdown-ish file.
+ *
+ * Used by Claude / Codex for the `<!-- CODEGRAPH_START --> ... <!--
+ * CODEGRAPH_END -->` block. Preserves all content outside the
+ * markers verbatim.
+ *
+ * Returns `created` when the file didn't exist; `updated` when
+ * markers were found and content swapped; `appended` when markers
+ * weren't found and section was added at end. `unchanged` when the
+ * existing block already matches `body`.
+ */
+export declare function replaceOrAppendMarkedSection(filePath: string, body: string, startMarker: string, endMarker: string): 'created' | 'updated' | 'appended' | 'unchanged';
+/**
+ * Inverse of `replaceOrAppendMarkedSection`. Strips the marker
+ * block from `filePath` if present. If the file becomes empty after
+ * removal, deletes the file entirely (matches the existing Claude
+ * uninstall behavior).
+ *
+ * Returns `removed` when content was stripped, `not-found` when
+ * the markers weren't present, `kept` when the file didn't exist.
+ */
+export declare function removeMarkedSection(filePath: string, startMarker: string, endMarker: string): 'removed' | 'not-found' | 'kept';
+//# sourceMappingURL=shared.d.ts.map

package/dist/installer/targets/toml.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny TOML helpers — just enough to inject / replace / remove a
+ * single dotted-key table block (`[mcp_servers.codegraph]`) inside an
+ * existing `~/.codex/config.toml`. We deliberately do NOT try to be a
+ * general TOML parser/serializer; that would mean pulling in a
+ * dependency (~50KB) for ~6 lines of output.
+ *
+ * Strategy: treat the file as text. Find the `[mcp_servers.codegraph]`
+ * header line, splice it (and the lines that follow it until the next
+ * `[...]` header or EOF) in or out. Everything outside that block is
+ * preserved verbatim, byte-for-byte.
+ *
+ * Limitations (acceptable for our narrow use):
+ *   - Only handles top-level table headers; not array-of-tables or
+ *     subtables nested inside `[mcp_servers]` itself (we always write
+ *     the full dotted key `[mcp_servers.codegraph]`).
+ *   - Doesn't validate sibling TOML — if the file is malformed
+ *     elsewhere, our injection won't fix it but won't make it worse.
+ *   - Quotes string values with double quotes; escapes `\` and `"`.
+ */
+/**
+ * Serialize a record into the body lines of a TOML table. Values
+ * supported: string, string[]. Other types throw — the codex MCP
+ * config only needs these two.
+ */
+export declare function serializeTomlTableBody(values: Record<string, string | string[]>): string;
+/**
+ * Build a full table block: header line + body. Suitable for direct
+ * insertion into a TOML file.
+ */
+export declare function buildTomlTable(header: string, values: Record<string, string | string[]>): string;
+/**
+ * Insert or replace a top-level dotted-key TOML table block in the
+ * given file content. Preserves all other content verbatim.
+ *
+ * Returns `'inserted'` when the table was newly added, `'replaced'`
+ * when an existing one was rewritten, `'unchanged'` when the
+ * existing block already matches `block` byte-for-byte.
+ */
+export declare function upsertTomlTable(fileContent: string, header: string, block: string): {
+    content: string;
+    action: 'inserted' | 'replaced' | 'unchanged';
+};
+/**
+ * Remove a top-level dotted-key TOML table block. Returns the
+ * possibly-empty new content + an action flag.
+ */
+export declare function removeTomlTable(fileContent: string, header: string): {
+    content: string;
+    action: 'removed' | 'not-found';
+};
+//# sourceMappingURL=toml.d.ts.map

package/dist/installer/targets/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Agent target abstraction for the installer.
+ *
+ * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
+ * implements this interface so the installer orchestrator can write the
+ * right MCP-server config + instructions file + permissions for that
+ * agent without baking client-specific paths into core code. Adding a
+ * new agent = one new file in `targets/` + one entry in `registry.ts`.
+ *
+ * Closes the Claude-locked installer issue (upstream #137). The
+ * runtime MCP server is already agent-agnostic; this brings the
+ * installer to the same surface.
+ */
+export type Location = 'global' | 'local';
+/**
+ * Stable string id used in the `--target` CLI flag and the registry
+ * lookup. New targets add a value here when they're added to the
+ * registry. Keep these short and lowercase.
+ */
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro';
+/**
+ * Result of `target.detect(location)`.
+ *
+ * `installed` is a best-effort heuristic that the agent's CLI / app /
+ * config dir is present on this system — used to default the
+ * multiselect prompt to "what's actually here." False positives are
+ * acceptable (we still write); false negatives just mean the user
+ * has to opt in manually.
+ *
+ * `alreadyConfigured` reports whether codegraph has already been
+ * wired into this target at this location — drives the
+ * "Updated"-vs-"Added" log line and lets `--check` exit 0/1.
+ */
+export interface DetectionResult {
+    installed: boolean;
+    alreadyConfigured: boolean;
+    /** Path inspected; surfaced in diagnostic / dry-run output. */
+    configPath?: string;
+}
+/**
+ * What `target.install(location)` actually changed on disk. The
+ * orchestrator renders one log line per file using `action`.
+ *
+ * `unchanged` means we touched the file but its contents were already
+ * what we'd write — used for byte-identical idempotent re-runs.
+ */
+export interface WriteResult {
+    files: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'unchanged' | 'removed' | 'not-found' | 'kept';
+    }>;
+    /**
+     * Optional one-line notes the orchestrator surfaces verbatim — e.g.
+     * "Restart Cursor to apply." Keep these short; multi-line goes in
+     * the README.
+     */
+    notes?: string[];
+}
+export interface InstallOptions {
+    /**
+     * Whether to write the agent's permissions / auto-allow surface
+     * (Claude `settings.json`, others where applicable). When the
+     * target has no permissions concept this option is a no-op.
+     */
+    autoAllow: boolean;
+}
+export interface AgentTarget {
+    /** Stable id; matches the `TargetId` union. */
+    readonly id: TargetId;
+    /** Human-readable name shown in clack prompts and log lines. */
+    readonly displayName: string;
+    /** Optional URL for "where do I learn more about this agent." */
+    readonly docsUrl?: string;
+    /**
+     * Whether this target supports the given install location.
+     *
+     * Some agents (Codex CLI as of 2026-05) have no project-local
+     * config concept — only a single `~/.codex/` dir. Returning false
+     * for an unsupported (target, location) pair lets the orchestrator
+     * skip cleanly with a clear message.
+     */
+    supportsLocation(loc: Location): boolean;
+    detect(loc: Location): DetectionResult;
+    install(loc: Location, opts: InstallOptions): WriteResult;
+    /**
+     * Inverse of install. Removes only what install would have written;
+     * preserves sibling MCP servers, sibling permissions, and unrelated
+     * markdown sections. Must be safe to call when nothing was ever
+     * installed (returns `not-found` actions).
+     */
+    uninstall(loc: Location): WriteResult;
+    /**
+     * Print the MCP-server snippet a user would paste manually for this
+     * target. Used by `codegraph install --print-config <id>` and by
+     * the README. Must NOT touch the filesystem.
+     */
+    printConfig(loc: Location): string;
+    /** Filesystem paths this target would write to at this location. */
+    describePaths(loc: Location): string[];
+}
+//# sourceMappingURL=types.d.ts.map