@saluzi/codegraph 0.1.0

package/dist/installer/claude-md-template.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Backwards-compat re-export shim.
+ *
+ * The instructions template moved to `instructions-template.ts` so it
+ * can be shared across all agent targets (Claude Code, Cursor, Codex
+ * CLI, opencode). This file is preserved purely so existing imports
+ * (`@colbymchenry/codegraph` consumers, downstream tooling) keep
+ * working unchanged. New code should import from
+ * `./instructions-template` directly.
+ *
+ * @deprecated Import from `./instructions-template` instead.
+ */
+export {
+  CODEGRAPH_SECTION_START,
+  CODEGRAPH_SECTION_END,
+  CLAUDE_MD_TEMPLATE,
+  INSTRUCTIONS_TEMPLATE,
+} from './instructions-template'
+//# sourceMappingURL=claude-md-template.d.ts.map

package/dist/installer/config-writer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Backwards-compat shim — original Claude-only writer functions.
+ *
+ * The installer now uses the multi-target architecture in
+ * `./targets/`. This file is preserved so existing imports (the test
+ * suite, downstream tooling) keep working unchanged. Each function
+ * delegates to the Claude target. New code should import the target
+ * registry from `./targets/registry` directly.
+ *
+ * @deprecated Use `targets/registry.ts` and the `AgentTarget`
+ *   abstraction instead.
+ */
+export type InstallLocation = 'global' | 'local'
+/**
+ * Each shim calls ONLY the named per-file helper — writeMcpConfig
+ * writes only the MCP JSON, writePermissions only settings.json,
+ * writeClaudeMd only CLAUDE.md. The full multi-file install lives
+ * in `claudeTarget.install()` which the new orchestrator uses.
+ */
+export declare function writeMcpConfig(location: InstallLocation): void
+export declare function writePermissions(location: InstallLocation): void
+export declare function writeClaudeMd(location: InstallLocation): {
+  created: boolean
+  updated: boolean
+}
+export declare function hasMcpConfig(location: InstallLocation): boolean
+export declare function hasPermissions(location: InstallLocation): boolean
+export declare function hasClaudeMdSection(location: InstallLocation): boolean
+//# sourceMappingURL=config-writer.d.ts.map

package/dist/installer/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * CodeGraph Interactive Installer
+ *
+ * Multi-target: writes MCP server config + instructions for the
+ * agents the user picks (Claude Code, Cursor, Codex CLI, opencode,
+ * Hermes Agent).
+ * 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,
+  WriteResult,
+} from './targets/types'
+export {
+  writeMcpConfig,
+  writePermissions,
+  writeClaudeMd,
+  hasMcpConfig,
+  hasPermissions,
+  hasClaudeMdSection,
+} 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>
+/**
+ * For every target that has a global config and exposes
+ * `wireProjectSurfaces`, write its project-local surfaces (e.g.
+ * Cursor's `.cursor/rules/codegraph.mdc`). Idempotent — runs
+ * silently when there's nothing to write.
+ *
+ * Called by `codegraph init` so that a user who ran
+ * `codegraph install` once globally doesn't have to re-run it per
+ * project to get full agent support.
+ *
+ * Returns the list of `(target, file)` pairs that were created or
+ * updated — caller decides how to surface them.
+ */
+export declare function wireProjectSurfacesForGlobalAgents(): Array<{
+  target: AgentTarget
+  file: WriteResult['files'][number]
+}>
+/**
+ * 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,30 @@
+/**
+ * Agent-instructions template — the markdown body each agent target
+ * writes into its conventional instructions file (CLAUDE.md /
+ * AGENTS.md / codegraph.mdc / etc.).
+ *
+ * The body content is identical across agents because the codegraph
+ * usage advice is agent-agnostic — only the destination filename and
+ * any optional frontmatter (Cursor `.mdc`) varies per target.
+ *
+ * The legacy `claude-md-template.ts` re-exports these names for
+ * backwards compatibility with downstream importers.
+ */
+/** Markers used by the marker-based section replacement. */
+export declare const CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->'
+export declare const CODEGRAPH_SECTION_END = '<!-- CODEGRAPH_END -->'
+/**
+ * The full marker-delimited block written into each agent's
+ * instructions file. Includes the start/end markers so the section
+ * can be detected and replaced on re-install.
+ */
+export declare const INSTRUCTIONS_TEMPLATE =
+  '<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X\'s signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |\n| "What calls function Y?" | `codegraph_callers` |\n| "What does Y call?" | `codegraph_callees` |\n| "What would break if I changed Z?" | `codegraph_impact` |\n| "Show me Y\'s signature / source / docstring" | `codegraph_node` |\n| "Give me focused context for a task/area" | `codegraph_context` |\n| "See several related symbols\' source at once" | `codegraph_explore` |\n| "What files exist under path/" | `codegraph_files` |\n| "Is the index healthy?" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don\'t delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that\'s slower, less accurate, and wastes context.\n- **Don\'t grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don\'t chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don\'t loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols\' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag**: the file watcher debounces ~500ms behind writes; don\'t re-query immediately after editing a file in the same turn.\n\n### If `.codegraph/` doesn\'t exist\n\nThe MCP server returns "not initialized." Ask the user: *"I notice this project doesn\'t have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*\n<!-- CODEGRAPH_END -->'
+/**
+ * Backwards-compat alias. Existing downstream code may import
+ * `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
+ * `claude-md-template.ts`.
+ */
+export declare const CLAUDE_MD_TEMPLATE =
+  '<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X\'s signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |\n| "What calls function Y?" | `codegraph_callers` |\n| "What does Y call?" | `codegraph_callees` |\n| "What would break if I changed Z?" | `codegraph_impact` |\n| "Show me Y\'s signature / source / docstring" | `codegraph_node` |\n| "Give me focused context for a task/area" | `codegraph_context` |\n| "See several related symbols\' source at once" | `codegraph_explore` |\n| "What files exist under path/" | `codegraph_files` |\n| "Is the index healthy?" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don\'t delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that\'s slower, less accurate, and wastes context.\n- **Don\'t grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don\'t chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don\'t loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols\' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag**: the file watcher debounces ~500ms behind writes; don\'t re-query immediately after editing a file in the same turn.\n\n### If `.codegraph/` doesn\'t exist\n\nThe MCP server returns "not initialized." Ask the user: *"I notice this project doesn\'t have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*\n<!-- CODEGRAPH_END -->'
+//# sourceMappingURL=instructions-template.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * 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]
+export declare function writeInstructionsEntry(
+  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/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/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,38 @@
+/**
+ * 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,92 @@
+/**
+ * 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,64 @@
+/**
+ * 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