feat(installer): multi-target — Claude Code, Cursor, Codex CLI, opencode (#162)

* feat(installer): multi-target — Claude Code, Cursor, Codex CLI, opencode Closes the Claude-locked installer behind issue #137. The runtime MCP server was already agent-agnostic (stdio); only the installer was locked. After this refactor, `codegraph install` can write per-agent MCP config + instructions for any combination of supported agents. ## What ships Four agent targets, each implementing the new `AgentTarget` interface: - **Claude Code** — `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/CLAUDE.md` (or local equivalents). Behavior preserved from the original installer; existing installs upgrade in place. - **Cursor** — `~/.cursor/mcp.json` (g) or `./.cursor/mcp.json` (l) + project-local `./.cursor/rules/codegraph.mdc`. - **Codex CLI** — `~/.codex/config.toml` with `[mcp_servers.codegraph]` + `~/.codex/AGENTS.md`. Global only. Hand-rolled TOML serializer scoped to the table we own — siblings + array-of-tables preserved. - **opencode** — `~/.config/opencode/opencode.json` (XDG) or `./opencode.json`. Adding a 5th agent is a new file in `src/installer/targets/` plus one entry in `registry.ts`. ## CLI changes ``` codegraph install # interactive multi-select codegraph install --yes # auto-detect, install global codegraph install --target=cursor,claude --yes # explicit list codegraph install --target=auto --location=local # detected, project-local codegraph install --target=none # skip agent writes entirely codegraph install --print-config codex # dump snippet, no writes ``` ## Backwards compat Every export from the old `config-writer.ts` (`writeMcpConfig`, `writePermissions`, `writeClaudeMd`, `hasMcpConfig`, `hasPermissions`, `hasClaudeMdSection`) is preserved as a `@deprecated` shim that delegates to per-file helpers in `targets/claude.ts`. Existing Claude users see byte-identical on-disk layout — `detect()` reports `alreadyConfigured: true`, re-running is a no-op. ## Tests +47 new tests in `__tests__/installer-targets.test.ts`: - Parameterized contract test across all 4 targets × supported locations (install → unchanged on re-run, sibling preservation, uninstall reverses install, printConfig writes nothing). - Codex partial-state recovery, locked-block contract for the codegraph table, full TOML serializer suite. - Registry: getTarget, resolveTargetFlag (auto/all/none/csv). `__tests__/installer.test.ts` relaxed one assertion: the new code returns `unchanged` for byte-identical re-runs instead of `updated`; the surrounding-custom-content contract is unchanged. ## Uninstall behavior change `bin/uninstall.ts` now loops `ALL_TARGETS.uninstall('global')` on `npm uninstall -g`. A user who manually configured `~/.codex/config.toml` with our block will have only that block removed on package uninstall — we only touch the dotted-key table we own. Based on andreinknv/codegraph@c5165e4. Issue #137. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(scripts): add local-install.sh for hands-on branch testing Builds the current branch and `npm link`s it as the global `codegraph` binary. `--undo` unlinks and reinstalls the published version. Mirrors the style of scripts/release.sh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(installer): move agent picker to the first prompt Reorders runInstallerWithOptions so the multi-select for agents (Claude / Cursor / Codex / opencode) is step 1 — before the global-npm-install confirm and before the location prompt. Bare `npx @colbymchenry/codegraph` now opens with "Which agents should CodeGraph configure?", which is the answer most users want first. Side effects of the reorder: - Early exit if zero targets selected — skips global-install and location prompts entirely, exits with "nothing to do." - Multiselect labels drop the per-location "will skip" hint (location isn't known yet) and replace it with a static "global only" badge for targets like Codex that have no project-local config concept. - If every selected target is global-only, the location prompt is skipped and global is forced (no point asking). - Detection probes the user-provided location if known via flag, else 'global' as the most common default — labels are a hint about what's installed locally, not load-bearing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(installer): disambiguate "global" wording in install prompts Two prompts both said "global" but meant different things — users read them as duplicates. Renamed for clarity: - Step 2 (npm install -g): "Install codegraph globally?" → "Install the codegraph CLI on your PATH? (Required so agents can launch the MCP server)". Spinner messages match. - Step 3 (config location): "Where would you like to install?" with "Global"/"Local" → "Apply agent configs to all your projects, or just this one?" with "All projects" (~/.claude, ~/.cursor, etc.) / "Just this project" (./.claude, ./.cursor, etc.). - All-global-only fallback: "Using global install" → "Writing user-wide configs (selected agents have no project-local config)." Underlying `Location` values ('global' / 'local') unchanged; only the UI strings shift, so no test or flag breakage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(installer/cursor): inject --path so workspace-aware queries work Cursor launches MCP-server subprocesses with cwd != workspace root, AND does not pass rootUri or workspaceFolders in the MCP initialize call. The codegraph MCP server's process.cwd() fallback misses the workspace's .codegraph/ and reports "not initialized" on every tool call. Codex and Claude don't have this issue (Codex launches with cwd=workspace, Claude passes rootUri). Fix: inject `--path` into the args we write for Cursor. - local install (./.cursor/mcp.json): hardcode the absolute project path — known at install time. - global install (~/.cursor/mcp.json): use `${workspaceFolder}` so Cursor expands it per-workspace. One global config now drives every project the user opens, without per-project re-install. No test breakage — the parameterized contract tests check idempotency / sibling preservation, not the exact args content. File-header comment documents the rationale so the next person doesn't strip the arg as boilerplate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(init): auto-wire project-local agent surfaces Closes the global-Cursor UX gap: `~/.cursor/mcp.json` registers the MCP server, but Cursor's agent only learns to *prefer* codegraph over native grep when it sees `.cursor/rules/codegraph.mdc` — a project-local file that global install can't write. Previously the user had to re-run `codegraph install --target=cursor --location=local` for every new project. Now `codegraph init` does it automatically. ## What changed - New optional `AgentTarget.wireProjectSurfaces()` returning a WriteResult of project-local files to drop. Most targets omit it (their global config is complete). Cursor implements it to write the rules file. - New `wireProjectSurfacesForGlobalAgents()` orchestrator in installer/index.ts — iterates ALL_TARGETS, detects which are configured globally, calls their wireProjectSurfaces, returns what was written. - `codegraph init` calls the orchestrator in both branches: - Fresh init: write surfaces after CodeGraph.init succeeds. - Already-initialized re-init: write surfaces too, so re-running `init` is the documented recovery path for a project missing its rules file. ## Steady-state UX 1. Once, ever: `codegraph install` (writes global agent configs) 2. Per project: `codegraph init -i` (builds the index + auto-wires project-local agent surfaces — currently Cursor's rules file) No new tests — wireProjectSurfaces delegates to writeRulesEntry, which is already covered by the parameterized contract tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(installer): agent-agnostic instructions template The old template was inherited from the Claude-only era and prescribed "ALWAYS spawn an Explore agent" — a Claude Code-specific concept (subagents via the Task tool). When Cursor's agent read this it had no Explore agent to spawn, got confused, and fell back to native grep/read even for structural queries the codegraph MCP tools answer in one call. This rewrite: - Frames each tool by the question it answers (search vs callers vs impact vs context vs explore vs node vs files vs status). - Tells the agent explicitly to TRUST codegraph results and not re-verify them with grep — the over-grep-after-codegraph behavior was the main symptom we saw on Cursor. - Reframes "spawn Explore agent" as an OPTIONAL pattern for harnesses that support parallel subagents — Claude Code still gets the hint, Cursor / Codex / opencode just skip it. - Trims the "if not initialized" section to one prescriptive line. Same marker delimiters (``) so existing installs upgrade in place via the marker-based section swap. No test changes needed — the parameterized contract tests check marker placement + sibling preservation, not the literal body. Effective surfaces: ~/.claude/CLAUDE.md (Claude), .cursor/rules/ codegraph.mdc (Cursor, project-local), ~/.codex/AGENTS.md (Codex). Users get the new copy by re-running `codegraph install` for global writes, or `codegraph init` for Cursor's project rules. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): reflect multi-agent support at the top + accurate flow - Tagline now reads "Supercharge Claude Code, Cursor & Codex" instead of Claude-only — multi-agent support is what the PR is about, the README should say so above the fold. - New badge row (Claude Code / Cursor / Codex CLI / opencode) in the same shields.io style as the OS row. - Install-flow bullets reordered to match the actual prompt order (agent picker first, then PATH install, then location). - `codegraph init -i` step now mentions that init wires up project-local agent surfaces (Cursor rules file etc.) so global install works in every project without a re-run. - Agent-agnostic phrasing in the closing line ("your agent" not "Claude Code"). Headline-level brand decision left intentionally in this PR — the existing Claude-only positioning predates multi-agent support. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: andreinknv <andrei.nknv@outlook.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 19:26:09 -05:00
parent 7e617d819b
commit a447e1d430
19 changed files with 2265 additions and 532 deletions
@@ -0,0 +1,181 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import {
+  atomicWriteFileSync,
+  getMcpServerConfig,
+  removeMarkedSection,
+  replaceOrAppendMarkedSection,
+} from './shared';
+import {
+  CODEGRAPH_SECTION_END,
+  CODEGRAPH_SECTION_START,
+  INSTRUCTIONS_TEMPLATE,
+} from '../instructions-template';
+import { buildTomlTable, removeTomlTable, upsertTomlTable } from './toml';
+
+const TOML_HEADER = 'mcp_servers.codegraph';
+
+function configDir(): string {
+  return path.join(os.homedir(), '.codex');
+}
+function tomlConfigPath(): string {
+  return path.join(configDir(), 'config.toml');
+}
+function instructionsPath(): string {
+  return path.join(configDir(), 'AGENTS.md');
+}
+
+class CodexTarget implements AgentTarget {
+  readonly id = 'codex' as const;
+  readonly displayName = 'Codex CLI';
+  readonly docsUrl = 'https://github.com/openai/codex';
+
+  supportsLocation(loc: Location): boolean {
+    return loc === 'global';
+  }
+
+  detect(loc: Location): DetectionResult {
+    if (loc !== 'global') {
+      return { installed: false, alreadyConfigured: false };
+    }
+    const tomlPath = tomlConfigPath();
+    let alreadyConfigured = false;
+    if (fs.existsSync(tomlPath)) {
+      try {
+        const content = fs.readFileSync(tomlPath, 'utf-8');
+        alreadyConfigured = content.includes(`[${TOML_HEADER}]`);
+      } catch { /* ignore */ }
+    }
+    const installed = fs.existsSync(configDir());
+    return { installed, alreadyConfigured, configPath: tomlPath };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    if (loc !== 'global') {
+      return {
+        files: [],
+        notes: ['Codex CLI has no project-local config — re-run with --location=global to install.'],
+      };
+    }
+    const files: WriteResult['files'] = [];
+
+    files.push(writeMcpEntry());
+    files.push(writeInstructionsEntry());
+
+    return { files };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    if (loc !== 'global') return { files: [] };
+    const files: WriteResult['files'] = [];
+
+    const tomlPath = tomlConfigPath();
+    if (fs.existsSync(tomlPath)) {
+      const content = fs.readFileSync(tomlPath, 'utf-8');
+      const { content: nextContent, action } = removeTomlTable(content, TOML_HEADER);
+      if (action === 'removed') {
+        if (nextContent.trim() === '') {
+          try { fs.unlinkSync(tomlPath); } catch { /* ignore */ }
+        } else {
+          atomicWriteFileSync(tomlPath, nextContent.trimEnd() + '\n');
+        }
+        files.push({ path: tomlPath, action: 'removed' });
+      } else {
+        files.push({ path: tomlPath, action: 'not-found' });
+      }
+    } else {
+      files.push({ path: tomlPath, action: 'not-found' });
+    }
+
+    const instr = instructionsPath();
+    const instrAction = removeMarkedSection(instr, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
+    files.push({ path: instr, action: instrAction });
+
+    return { files };
+  }
+
+  printConfig(loc: Location): string {
+    if (loc !== 'global') {
+      return '# Codex CLI has no project-local config — use --location=global.\n';
+    }
+    const block = buildCodegraphBlock();
+    return `# Add to ${tomlConfigPath()}\n\n${block}\n`;
+  }
+
+  describePaths(loc: Location): string[] {
+    if (loc !== 'global') return [];
+    return [tomlConfigPath(), instructionsPath()];
+  }
+}
+
+function buildCodegraphBlock(): string {
+  const mcp = getMcpServerConfig();
+  return buildTomlTable(TOML_HEADER, {
+    command: mcp.command,
+    args: mcp.args,
+  });
+}
+
+function writeMcpEntry(): WriteResult['files'][number] {
+  const file = tomlConfigPath();
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const block = buildCodegraphBlock();
+  // Single read — `existing === ''` derives both "is the file empty
+  // or absent" and "what was its content," avoiding a TOCTOU window
+  // between two `fs.existsSync` calls.
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+  const created = existing.length === 0;
+  const { content: nextContent, action } = upsertTomlTable(existing, TOML_HEADER, block);
+
+  if (action === 'unchanged') {
+    return { path: file, action: 'unchanged' };
+  }
+  atomicWriteFileSync(file, nextContent);
+  return { path: file, action: created ? 'created' : 'updated' };
+}
+
+function writeInstructionsEntry(): WriteResult['files'][number] {
+  const file = instructionsPath();
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const action = replaceOrAppendMarkedSection(
+    file,
+    INSTRUCTIONS_TEMPLATE,
+    CODEGRAPH_SECTION_START,
+    CODEGRAPH_SECTION_END,
+  );
+  const mapped: 'created' | 'updated' | 'unchanged' =
+    action === 'created' ? 'created'
+      : action === 'unchanged' ? 'unchanged'
+        : 'updated';
+  return { path: file, action: mapped };
+}
+
+export const codexTarget: AgentTarget = new CodexTarget();