@aroman22/codegraph-vba 1.3.3

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

@@ -0,0 +1,41 @@
+/**
+ * The marker-fenced agent-instructions block the installer writes into each
+ * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md).
+ *
+ * History: pre-#529 the installer wrote a full usage playbook here, which
+ * duplicated the MCP `initialize` instructions for the main agent — so it
+ * was removed and `mcp/server-instructions.ts` became the single source of
+ * truth. A much smaller block returned for #704, because the MCP
+ * instructions cannot reach two audiences that the instructions FILE does
+ * reach:
+ *
+ *  - **Task-tool subagents** — they receive the project instructions file
+ *    in their context but NOT the MCP initialize instructions. They hold
+ *    the codegraph MCP tools only as deferred names and rarely think to
+ *    load them: measured on a forced-delegation flow question (excalidraw,
+ *    sonnet, high effort), subagents loaded + used codegraph in ~1 of 9
+ *    runs without this block, and consistently with it — including runs
+ *    with zero Read/grep fallback.
+ *  - **Non-MCP harnesses** — agents with no MCP client at all can still
+ *    run the `codegraph explore` CLI, which prints the same output as the
+ *    MCP tool.
+ *
+ * Keep this block SHORT. The main agent reads it every turn on top of the
+ * server instructions — the #529 duplication-cost argument still bounds
+ * its size. Command names and the two surfaces, nothing more.
+ */
+/** Markers used by the marker-based section write/removal. */
+export declare const CODEGRAPH_SECTION_START = "<!-- CODEGRAPH_START -->";
+export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
+/**
+ * The full block, markers included, exactly as written to disk.
+ *
+ * The wording is deliberately CONDITIONAL ("in repositories indexed by…"):
+ * a global install writes this into a user-scope file (~/.claude/CLAUDE.md,
+ * ~/.codex/AGENTS.md) that applies to every project the user opens —
+ * including unindexed ones, where an unconditional "this repository is
+ * indexed" claim would send subagents into failing codegraph calls (the
+ * noise the unindexed-session policy exists to prevent).
+ */
+export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` prints the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- 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,62 @@
+/**
+ * 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 (`mark-dirty` / `sync-if-dirty`) that a
+ * pre-0.8 install wrote. Exported for direct unit-testing; reused by both
+ * `install` (an upgrade self-heals) and `uninstall`.
+ */
+export declare function cleanupLegacyHooks(loc: Location): WriteResult['files'][number];
+/**
+ * Remove the front-load `UserPromptSubmit` hook this installer writes (see
+ * writePromptHookEntry). Used by `uninstall`, and by `install` when the user
+ * opts out, so the choice round-trips.
+ */
+export declare function removePromptHookEntry(loc: Location): WriteResult['files'][number];
+export declare function writePermissionsEntry(loc: Location): WriteResult['files'][number];
+/**
+ * Write the front-load `UserPromptSubmit` hook into Claude `settings.json` —
+ * a `command` hook that runs `codegraph prompt-hook`, which injects
+ * codegraph_explore context for structural prompts so the agent reliably uses
+ * the graph. Idempotent: if our command is already wired under UserPromptSubmit
+ * the file is left byte-for-byte untouched and reported `unchanged`. Sibling
+ * hooks (the user's own, or other events) are preserved. Opt-in — the installer
+ * only calls this when the user accepts the prompt (default-yes).
+ */
+export declare function writePromptHookEntry(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,38 @@
+/**
+ * opencode target.
+ *
+ *   - MCP server entry to `~/.config/opencode/opencode.jsonc` (global,
+ *     XDG-style on EVERY platform, Windows included — see below) 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.
+ *
+ *     opencode resolves its config dir with the `xdg-basedir` package
+ *     (sst/opencode `packages/core/src/global.ts`): `XDG_CONFIG_HOME`
+ *     if set, else `~/.config` — unconditionally, on all platforms. It
+ *     never reads `%APPDATA%`; that layout belonged to the discontinued
+ *     Go fork. We previously wrote there on Windows, so opencode never
+ *     saw the entry (#535) — install/uninstall now also sweep a stale
+ *     codegraph entry out of the legacy `%APPDATA%/opencode` location.
+ *   - 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,101 @@
+/**
+ * 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.
+ *
+ * One server-scoped wildcard rather than a per-tool list. By default only
+ * `codegraph_explore` is even LISTED to the agent (see DEFAULT_MCP_TOOLS in
+ * mcp/tools.ts), so in practice explore is the only tool this auto-approves —
+ * but the wildcard means that if a user re-enables another tool via
+ * CODEGRAPH_MCP_TOOLS, it's already pre-approved (no permission prompt, no
+ * hand-editing settings.json), and future tools are covered too. Claude only
+ * honors globs after a literal `mcp__<server>__` prefix, so this exact string
+ * is the way to allow-all for one server; a bare `mcp__codegraph` or `*` is
+ * ignored. The allowlist gates PROMPTING, not visibility, so a superset here
+ * never makes a hidden tool appear.
+ */
+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';
+/**
+ * Upsert the CodeGraph instructions block into an agent instructions
+ * file (CLAUDE.md / AGENTS.md / GEMINI.md). The one write shared by
+ * every target: self-heals a stale pre-#529 long block (markers match →
+ * replaced by the current short one), appends after existing user
+ * content otherwise, and reports `unchanged` on byte-equal re-runs so
+ * install stays idempotent. See `instructions-template.ts` for why this
+ * block exists (#704: subagents + non-MCP harnesses never see the MCP
+ * initialize instructions).
+ */
+export declare function upsertInstructionsEntry(file: string): {
+    path: string;
+    action: 'created' | 'updated' | '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,108 @@
+/**
+ * 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;
+    /**
+     * Front-load prompt hook (Claude `UserPromptSubmit`) that injects
+     * codegraph_explore context for structural prompts. `true` installs it,
+     * `false` removes any prior install (so opt-out round-trips), `undefined`
+     * leaves it untouched. Targets without a prompt-hook concept ignore it.
+     */
+    promptHook?: 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