From 58c1414ce5f01302de14e815c12f5dbf4adbcb5f Mon Sep 17 00:00:00 2001 From: Colby Mchenry Date: Sun, 17 May 2026 20:26:49 -0500 Subject: [PATCH] fix(installer): opencode .jsonc + AGENTS.md (0.7.8) (#163) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * release: 0.7.7 (multi-agent installer — Cursor, Codex, opencode) * fix(installer): opencode .jsonc + AGENTS.md (0.7.8) v0.7.7 wrote ~/.config/opencode/opencode.json, but opencode reads opencode.jsonc by default — so the codegraph MCP entry never appeared in any opencode session. Also installs AGENTS.md so opencode's model reaches for codegraph_* tools instead of native Grep. - Prefer existing .jsonc, fall back to .json, default new installs to .jsonc. - Surgical edits via jsonc-parser preserve user comments and formatting across install / re-install / uninstall round-trips. - Install AGENTS.md (global ~/.config/opencode/AGENTS.md, local ./AGENTS.md) with the shared INSTRUCTIONS_TEMPLATE — same marker-delimited approach Codex uses. - +9 opencode-specific tests covering filename precedence, comment preservation, AGENTS.md install + sibling-content preservation, uninstall reverses both files. 575/575 tests pass. Hand-verified end-to-end: opencode session calls codegraph_node + codegraph_callers for a structural query, zero Grep calls. Co-Authored-By: Claude Opus 4.7 (1M context) * docs: overhaul CLAUDE.md and add scripts/release.sh + Cursor rules file Replaces the old Claude-only CLAUDE.md with a comprehensive guide covering the full project architecture, multi-agent installer, test conventions, NodeKind/EdgeKind reference, and release workflow. Key additions: - Documents the layered pipeline, all module paths, and the multi-target installer (targets/, registry.ts, AgentTarget interface). - Adds the Cursor `--path` quirk and the "update all three surfaces" rule when changing MCP tool guidance. - Documents `npm run eval`, `test:eval`, and the full set of build/test commands including single-file patterns. - `scripts/release.sh` — idempotent bash script that tags the current commit, pushes the tag, and creates a GitHub Release whose notes are extracted from the matching `## [X.Y.Z]` block in CHANGELOG.md. Safe to re-run after partial failure. - `.cursor/rules/codegraph.mdc` — Cursor-specific agent instructions (tool decision table, rules of thumb, index-lag warning) written by the installer and kept in sync with server-instructions.ts and instructions-template.ts. --------- Co-authored-by: Claude Opus 4.7 (1M context) --- .cursor/rules/codegraph.mdc | 37 +++++ CHANGELOG.md | 23 +++ CLAUDE.md | 216 ++++++++++------------------ __tests__/installer-targets.test.ts | 149 ++++++++++++++++++- package-lock.json | 11 +- package.json | 3 +- scripts/release.sh | 70 +++++++++ src/installer/targets/opencode.ts | 191 ++++++++++++++++++------ 8 files changed, 519 insertions(+), 181 deletions(-) create mode 100644 .cursor/rules/codegraph.mdc create mode 100755 scripts/release.sh diff --git a/.cursor/rules/codegraph.mdc b/.cursor/rules/codegraph.mdc new file mode 100644 index 0000000..dac86b3 --- /dev/null +++ b/.cursor/rules/codegraph.mdc @@ -0,0 +1,37 @@ +--- +description: CodeGraph MCP usage guide — when to use which tool +alwaysApply: true +--- + +## CodeGraph + +This 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. + +### When to prefer codegraph over native search + +Use codegraph for **structural** questions — 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. + +| Question | Tool | +|---|---| +| "Where is X defined?" / "Find symbol named X" | `codegraph_search` | +| "What calls function Y?" | `codegraph_callers` | +| "What does Y call?" | `codegraph_callees` | +| "What would break if I changed Z?" | `codegraph_impact` | +| "Show me Y's signature / source / docstring" | `codegraph_node` | +| "Give me focused context for a task/area" | `codegraph_context` | +| "Survey an unfamiliar module/topic" | `codegraph_explore` | +| "What files exist under path/" | `codegraph_files` | +| "Is the index healthy?" | `codegraph_status` | + +### Rules of thumb + +- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context. +- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call. +- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call. +- **`codegraph_explore` is the heavy hitter** for unfamiliar areas — it returns full source from all relevant files in one call, but is token-heavy. If your harness supports parallel subagents (e.g., Claude Code's Task tool), spawn one for explore-class questions to keep main session context clean. +- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn. + +### If `.codegraph/` doesn't exist + +The 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?"* + diff --git a/CHANGELOG.md b/CHANGELOG.md index da09c15..904d3cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,29 @@ a [GitHub Release](https://github.com/colbymchenry/codegraph/releases) tagged This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.7.8] - 2026-05-17 + +### Fixed +- **opencode**: install actually wires up the MCP server now. v0.7.7 wrote + `~/.config/opencode/opencode.json`, but opencode reads `opencode.jsonc` by + default — so the `codegraph` entry never showed up in any opencode session. + The installer now prefers an existing `.jsonc`, falls back to `.json` when + only that exists, and creates `.jsonc` for greenfield installs. **Re-run + `codegraph install --target=opencode` after upgrading** so the entry lands + in the file opencode actually reads. + +### Added +- **opencode**: installer now writes `AGENTS.md` (global + `~/.config/opencode/AGENTS.md`, local `./AGENTS.md`) with the same + codegraph usage guidance the other agents already received. Without it, + opencode's model would call native `Grep` instead of the `codegraph_*` + tools it could see in its MCP list. +- User comments and formatting in `opencode.jsonc` survive install / + re-install / uninstall round-trips — surgical edits via `jsonc-parser` + rather than full-file rewrites. + +[0.7.8]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.8 + ## [0.7.7] - 2026-05-17 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index ae4ff48..3603c94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,192 +4,134 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -CodeGraph is a local-first code intelligence system that builds a semantic knowledge graph from any codebase. It provides structural understanding of code relationships using tree-sitter for AST parsing and SQLite for storage. +CodeGraph is a local-first code intelligence library + CLI + MCP server. It parses any supported codebase with tree-sitter, stores symbols/edges/files in SQLite (FTS5), and exposes a knowledge graph to AI agents (Claude Code, Cursor, Codex CLI, opencode) over MCP. Per-project data lives in `.codegraph/`. Extraction is deterministic — derived from AST, not LLM-summarized. -**Key characteristics:** -- Headless library (no UI) - purely an API -- Node.js runtime (works standalone, in Electron, or any Node environment) -- Per-project data stored in `.codegraph/` directory -- Deterministic extraction from AST, not AI-generated summaries +Distributed as `@colbymchenry/codegraph` on npm; same binary serves as installer, indexer, and MCP server. -## Build and Development Commands +## Build, Test, Run ```bash -# Build -npm run build # Compile TypeScript and copy assets +npm run build # tsc + copy schema.sql and *.wasm into dist/; chmods dist/bin/codegraph.js +npm run dev # tsc --watch +npm run clean # rm -rf dist -# Test -npm test # Run all tests once -npm run test:watch # Run tests in watch mode +npm test # vitest run (all) +npm run test:watch +npm run test:eval # only __tests__/evaluation/ +npm run eval # build then run __tests__/evaluation/runner.ts via tsx -# Clean -npm run clean # Remove dist/ directory +npm run cli # build then run the local dist binary + +# Single test file / pattern +npx vitest run __tests__/installer-targets.test.ts +npx vitest run __tests__/extraction.test.ts -t "TypeScript" ``` -## Running a Single Test +`copy-assets` (called from `build`) copies `src/db/schema.sql` and all `src/extraction/wasm/*.wasm` files into `dist/`. **Any new SQL or grammar wasm must be copied or it won't ship.** -```bash -npx vitest run __tests__/extraction.test.ts # Run specific test file -npx vitest run __tests__/extraction.test.ts -t "TypeScript" # Run tests matching pattern -``` +Node engines: `>=18.0.0 <25.0.0`. There is a hard exit on Node 25.x (see `src/bin/node-version-check.ts`). ## Architecture -### Core Module Structure +### Layered pipeline ``` -src/ -├── index.ts # Main CodeGraph class - public API entry point -├── types.ts # All TypeScript interfaces and types -├── db/ # SQLite database layer -│ ├── index.ts # DatabaseConnection class -│ ├── queries.ts # QueryBuilder with prepared statements -│ └── schema.sql # Table definitions with FTS5 search -├── extraction/ # Tree-sitter AST parsing -│ ├── index.ts # ExtractionOrchestrator -│ ├── tree-sitter.ts # Universal parser wrapper -│ └── grammars.ts # Language detection and grammar loading -├── resolution/ # Reference resolver -│ ├── index.ts # ReferenceResolver orchestrator -│ ├── import-resolver.ts -│ ├── name-matcher.ts -│ └── frameworks/ # Framework-specific patterns (React, Express, Laravel, etc.) -├── graph/ # Graph traversal and queries -│ ├── index.ts # GraphQueryManager -│ ├── traversal.ts # GraphTraverser (BFS/DFS, impact radius) -│ └── queries.ts # High-level graph queries -├── context/ # Context building for AI assistants -│ ├── index.ts # ContextBuilder -│ └── formatter.ts # Markdown/JSON output formatting -├── sync/ # Incremental update system -│ ├── index.ts -│ └── git-hooks.ts # Post-commit hook management -├── installer/ # Interactive installer -│ ├── index.ts # Installer orchestrator -│ ├── banner.ts # ASCII art banner -│ ├── claude-md-template.ts # CLAUDE.md template generator -│ ├── config-writer.ts # Configuration file writing -│ └── prompts.ts # User prompts -├── mcp/ # Model Context Protocol server -│ ├── index.ts # MCPServer class -│ ├── tools.ts # MCP tool definitions -│ └── transport.ts # Stdio transport -└── bin/codegraph.ts # CLI entry point +files → ExtractionOrchestrator (tree-sitter) → DB (nodes/edges/files) + ↓ + ReferenceResolver (imports, name-matching, framework patterns) + ↓ + GraphQueryManager / GraphTraverser (callers, callees, impact) + ↓ + ContextBuilder (markdown/JSON for AI consumption) ``` -### Key Classes +The public API surface is `src/index.ts` — the `CodeGraph` class wires all the layers and re-exports types. Library users only touch this file; the MCP server and CLI also drive it. -- **CodeGraph** (`src/index.ts`): Main entry point. Lifecycle methods (`init`, `open`, `close`), indexing (`indexAll`, `sync`), graph queries (`traverse`, `getCallGraph`, `getImpactRadius`), context building (`buildContext`) +### Module layout -- **ExtractionOrchestrator** (`src/extraction/index.ts`): Coordinates file scanning, parsing, and storing. Uses tree-sitter native bindings for each supported language +- `src/index.ts` — `CodeGraph` class: `init`/`open`/`close`, `indexAll`, `sync`, `searchNodes`, `getCallers`/`getCallees`, `getImpactRadius`, `buildContext`, `watch`/`unwatch`. +- `src/db/` — `DatabaseConnection`, `QueryBuilder` (prepared statements), `schema.sql`. Backed by `better-sqlite3` (native) when available, transparently falls back to `node-sqlite3-wasm`. `codegraph status` surfaces which backend is live; wasm is the slow path. +- `src/extraction/` — `ExtractionOrchestrator`, tree-sitter wrappers, per-language extractors under `languages/` (one file per language), plus standalone extractors for non-tree-sitter formats (`svelte-extractor.ts`, `vue-extractor.ts`, `liquid-extractor.ts`, `dfm-extractor.ts` for Delphi). `parse-worker.ts` runs heavy parsing off the main thread. +- `src/resolution/` — `ReferenceResolver` orchestrates `import-resolver.ts` (with `path-aliases.ts` for tsconfig path aliases + cargo workspace member globs), `name-matcher.ts`, and `frameworks/` (Express, Laravel, Rails, FastAPI, Django, Flask, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit, Vue/Nuxt, Cargo workspaces). Frameworks emit `route` nodes and `references` edges. +- `src/graph/` — `GraphTraverser` (BFS/DFS, impact radius, path finding) and `GraphQueryManager` (high-level queries). +- `src/context/` — `ContextBuilder` + formatter for markdown/JSON output. +- `src/search/` — full-text query parser and helpers for FTS5. +- `src/sync/` — `FileWatcher` (native FSEvents/inotify/RDCW) with debounce + filter, and git-hook helpers. +- `src/mcp/` — MCP server (`MCPServer`, `tools.ts`, `transport.ts`). `server-instructions.ts` is what the server returns in the MCP `initialize` response — keep it in sync with the user-facing tool guidance. +- `src/installer/` — see below. +- `src/bin/codegraph.ts` — CLI (commander). Subcommands: `install`, `init`, `uninit`, `index`, `sync`, `status`, `query`, `files`, `context`, `affected`, `serve --mcp`. +- `src/ui/` — terminal UI (shimmer progress, worker). -- **GraphTraverser** (`src/graph/traversal.ts`): BFS/DFS traversal, call graph construction, impact radius calculation, path finding +### NodeKind / EdgeKind -- **ReferenceResolver** (`src/resolution/index.ts`): Resolves unresolved references after full indexing using framework patterns, import resolution, and name matching +Defined in `src/types.ts`. Both extractors and resolvers must use these exact strings. -### Database Schema +- **NodeKind**: `file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component`. +- **EdgeKind**: `contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates`. -SQLite database with: -- `nodes`: Code symbols (functions, classes, methods, etc.) -- `edges`: Relationships (calls, imports, extends, contains, etc.) -- `files`: Tracked source files with content hashes -- `unresolved_refs`: References pending resolution -- `nodes_fts`: FTS5 virtual table for full-text search +### Multi-agent installer -### Supported Languages +`src/installer/` is the entry point for `codegraph install` (and the bare `codegraph`/`npx @colbymchenry/codegraph` invocation). Architecture: -TypeScript, JavaScript, TSX, JSX, Svelte, Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Liquid, Pascal +- `targets/registry.ts` lists every supported agent. +- `targets/types.ts` defines the `AgentTarget` interface — adding a 5th agent (Continue, Zed, Windsurf…) is **one new file in `targets/` + one entry in `registry.ts`**. Each target owns its config-file location, MCP-server JSON/TOML/JSONC writing, and instructions-file path. +- Current targets: `claude.ts`, `cursor.ts`, `codex.ts`, `opencode.ts`. +- `targets/toml.ts` is a hand-rolled TOML serializer scoped to `[mcp_servers.codegraph]` (used by Codex). Sibling tables and `[[array_of_tables]]` are preserved verbatim. No new dependency. +- opencode reads `opencode.jsonc` by default; the installer prefers existing `.jsonc`, falls back to `.json`, and creates `.jsonc` for greenfield installs. Edits are surgical via `jsonc-parser` so user comments and formatting survive install/re-install/uninstall round-trips. +- `instructions-template.ts` is the agent-agnostic instructions file written to each target (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`). It explicitly says "trust codegraph results, don't re-verify with grep" — earlier versions prescribed Claude-specific "spawn an Explore agent" and confused other agents. +- `claude-md-template.ts` is the legacy Claude-only template, retained for compatibility paths. +- All installer changes need matching coverage in `__tests__/installer-targets.test.ts` — there are ~47 parameterized contract tests covering install idempotency, sibling preservation, uninstall reverses install, byte-equal re-runs returning `unchanged`, and partial-state recovery for Codex. -### Node and Edge Types +### Cursor MCP working-directory quirk -**NodeKind**: `file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component` +Cursor launches MCP subprocesses with the wrong cwd and doesn't pass `rootUri` in `initialize`. The installer injects `--path` into Cursor's MCP args — absolute path for local installs, `${workspaceFolder}` for global installs. If you touch Cursor wiring, preserve this. -**EdgeKind**: `contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates` +### MCP server instructions -## CLI Usage +`src/mcp/server-instructions.ts` is sent back to the agent in the MCP `initialize` response. This is the *first* thing every agent sees about how to use the tools — treat it as the authoritative tool guidance and keep it in sync with `instructions-template.ts` and `.cursor/rules/codegraph.mdc`. -```bash -codegraph init [path] # Initialize in project -codegraph index [path] # Full index -codegraph sync [path] # Incremental update -codegraph status [path] # Show statistics -codegraph query # Search symbols -codegraph context # Build context for AI -codegraph hooks install # Install git auto-sync -codegraph serve --mcp # Start MCP server -``` +## Tests -## MCP Tools Best Practices +Tests live in `__tests__/` and mirror the module they cover. Notable ones beyond the obvious: -Use these tools **directly in the main session** for fast code exploration (replaces the need for Explore agents in most cases): +- `installer-targets.test.ts` — parameterized contract suite across all 4 agent targets (see installer notes above). +- `evaluation/` — `runner.ts` + `test-cases.ts` exercise codegraph against synthetic projects and score the results; run via `npm run eval` (builds first). Not part of `npm test`. +- `sqlite-backend.test.ts` — covers native + wasm backend selection and fallback. +- `pr19-improvements.test.ts`, `frameworks-integration.test.ts` — regression coverage for specific past PRs/incidents; don't rename these, the names anchor to git history. -| Tool | Use For | -|------|---------| -| `codegraph_explore` | **Deep exploration** — comprehensive context for a topic in ONE call | -| `codegraph_context` | Quick context for a task (lighter than explore) | -| `codegraph_search` | Find symbols by name (functions, classes, types) | -| `codegraph_callers` | Find what calls a function | -| `codegraph_callees` | Find what a function calls | -| `codegraph_impact` | See what's affected by changing a symbol | -| `codegraph_node` | Get details + source code for a symbol | - -### Important -CodeGraph provides **code context**, not product requirements. For new features, still ask the user about: -- UX preferences and behavior -- Edge cases and error handling -- Acceptance criteria +Tests create temp dirs with `fs.mkdtempSync` and clean up in `afterEach`. They write real files and exercise real SQLite — there is no DB mocking. ## Releases -Releases are published to npm **and** mirrored as GitHub Releases on the -[Releases page](https://github.com/colbymchenry/codegraph/releases), which is -where most users look for change history. `CHANGELOG.md` at the repo root is -the source of truth — each GitHub Release's notes are extracted from it. +Released to npm and mirrored as [GitHub Releases](https://github.com/colbymchenry/codegraph/releases). `CHANGELOG.md` is the source of truth; GitHub Release notes are extracted from it. ### Writing changelog entries -When the user asks for a changelog entry for a new version: +When asked for an entry for a new version: -1. Add a new `## [X.Y.Z] - YYYY-MM-DD` block at the **top** of `CHANGELOG.md` - (directly under the intro, above the previous version). -2. Group changes under `### Added`, `### Changed`, `### Fixed`, `### Removed`, - `### Deprecated`, `### Security` — only include sections that have entries. -3. Write entries from the **user's perspective**, not the implementation's. - Lead with the observable symptom or capability, then mention internals only - if a user needs them (e.g., to work around an existing bad install). -4. Add the link reference at the bottom: - `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z` +1. Add a new `## [X.Y.Z] - YYYY-MM-DD` block at the **top** of `CHANGELOG.md` (under the intro, above the previous version). +2. Group under `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`, `### Security` — omit empty sections. +3. Write from the **user's perspective**, not the implementation's. Lead with the observable symptom or capability; mention internals only if a user needs them (e.g., to work around an existing bad install). +4. Add the link reference at the bottom: `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`. -### Release commands (the user runs these) +### Release flow (the user runs these) -After the changelog entry is written and the version is bumped in `package.json`: +After the changelog entry is written and `package.json` is bumped: ```bash git add package.json package-lock.json CHANGELOG.md git commit -m "release: X.Y.Z ()" git push - npm publish - -git tag vX.Y.Z -git push origin vX.Y.Z -gh release create vX.Y.Z \ - --title "vX.Y.Z" \ - --notes-file <(awk '/^## \[X.Y.Z\]/,/^## \[/{ if (/^## \[/ && !/X.Y.Z/) exit; print }' CHANGELOG.md) +./scripts/release.sh # idempotent: tags vX.Y.Z, pushes, creates GitHub Release with notes from CHANGELOG.md ``` -Do **not** run `npm publish`, `git tag`, `git push`, or `gh release create` -yourself — these are publish actions that affect shared state. Write the file, -hand the user the commands. +`scripts/release.sh` is safe to re-run after a partial failure — it skips steps already done (tag exists locally, tag on origin, release published). It extracts release notes from `CHANGELOG.md` by matching the `## [X.Y.Z]` block. -## Test Structure +**Do not run `npm publish`, `git push`, `git tag`, or `./scripts/release.sh` yourself** — these are publish actions on shared state. Write the file, hand the user the commands. -Tests are in `__tests__/` directory with files mirroring the module structure: -- `foundation.test.ts` - Database, config, directory management -- `extraction.test.ts` - Tree-sitter parsing for all languages -- `resolution.test.ts` - Reference resolution -- `graph.test.ts` - Traversal and graph queries -- `context.test.ts` - Context building -- `sync.test.ts` - Incremental updates and git hooks +## House rules -Tests use temporary directories created with `fs.mkdtempSync` and cleaned up after each test. +- The `0.7.x` line is in active multi-agent rollout. Any change to `src/installer/` (especially `targets/`) needs corresponding test coverage and a CHANGELOG entry — installer regressions break every new install silently. +- When changing what the MCP tools do or how agents should use them, update **all three** of `src/mcp/server-instructions.ts`, `src/installer/instructions-template.ts`, and `.cursor/rules/codegraph.mdc` — they're written to different places but say the same thing. +- CodeGraph provides **code context**, not product requirements. For new features, ask the user about UX, edge cases, and acceptance criteria — the graph won't tell you. diff --git a/__tests__/installer-targets.test.ts b/__tests__/installer-targets.test.ts index ec437f9..89ba629 100644 --- a/__tests__/installer-targets.test.ts +++ b/__tests__/installer-targets.test.ts @@ -98,7 +98,8 @@ describe('Installer targets — contract', () => { // and any target with no JSON config — they get covered // by their own dedicated tests below. const paths = target.describePaths(location); - const jsonPath = paths.find((p) => p.endsWith('.json')); + // Match .json or .jsonc — opencode prefers .jsonc. + const jsonPath = paths.find((p) => /\.jsonc?$/.test(p)); if (!jsonPath) return; // Seed pre-existing config. @@ -184,6 +185,152 @@ describe('Installer targets — partial-state idempotency', () => { for (const f of third.files) expect(f.action).toBe('unchanged'); }); + it('opencode: prefers .jsonc when both .json and .jsonc exist', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + fs.writeFileSync(path.join(dir, 'opencode.json'), '{\n "$schema": "https://opencode.ai/config.json"\n}\n'); + fs.writeFileSync(path.join(dir, 'opencode.jsonc'), '{\n "$schema": "https://opencode.ai/config.json"\n}\n'); + + const result = opencode.install('global', { autoAllow: true }); + const written = result.files.find((f) => /\.jsonc$/.test(f.path))!; + expect(written).toBeDefined(); + expect(written.action).not.toBe('not-found'); + // The .json file is left alone. + const jsonText = fs.readFileSync(path.join(dir, 'opencode.json'), 'utf-8'); + expect(jsonText).not.toContain('codegraph'); + }); + + it('opencode: uses .json when only .json exists (no .jsonc)', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + fs.writeFileSync(path.join(dir, 'opencode.json'), '{\n "$schema": "https://opencode.ai/config.json"\n}\n'); + + const result = opencode.install('global', { autoAllow: true }); + expect(result.files[0].path).toMatch(/opencode\.json$/); + expect(fs.existsSync(path.join(dir, 'opencode.jsonc'))).toBe(false); + }); + + it('opencode: defaults to .jsonc for fresh installs (no existing file)', () => { + const opencode = getTarget('opencode')!; + const result = opencode.install('global', { autoAllow: true }); + expect(result.files[0].path).toMatch(/opencode\.jsonc$/); + expect(result.files[0].action).toBe('created'); + }); + + it('opencode: preserves line and block comments through install + idempotent re-run', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + const file = path.join(dir, 'opencode.jsonc'); + const original = [ + '{', + ' // top-level note about my opencode setup', + ' "$schema": "https://opencode.ai/config.json",', + ' /* multi-line block comment', + ' describing the providers section */', + ' "providers": {', + ' "anthropic": { "model": "claude-opus-4-7" } // pinned', + ' }', + '}', + '', + ].join('\n'); + fs.writeFileSync(file, original); + + opencode.install('global', { autoAllow: true }); + const afterInstall = fs.readFileSync(file, 'utf-8'); + expect(afterInstall).toContain('// top-level note about my opencode setup'); + expect(afterInstall).toContain('/* multi-line block comment'); + expect(afterInstall).toContain('// pinned'); + expect(afterInstall).toContain('"codegraph"'); + expect(afterInstall).toContain('"providers"'); + + // Idempotent re-run reports unchanged, file is byte-identical. + const second = opencode.install('global', { autoAllow: true }); + expect(second.files[0].action).toBe('unchanged'); + expect(fs.readFileSync(file, 'utf-8')).toBe(afterInstall); + }); + + it('opencode: install writes AGENTS.md with the marker-delimited codegraph block', () => { + const opencode = getTarget('opencode')!; + opencode.install('global', { autoAllow: true }); + const agentsMd = path.join(tmpHome, '.config', 'opencode', 'AGENTS.md'); + expect(fs.existsSync(agentsMd)).toBe(true); + const body = fs.readFileSync(agentsMd, 'utf-8'); + expect(body).toContain(''); + expect(body).toContain(''); + expect(body).toContain('codegraph_callers'); + }); + + it('opencode: AGENTS.md install preserves pre-existing user content outside markers', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + const agentsMd = path.join(dir, 'AGENTS.md'); + fs.writeFileSync(agentsMd, '# My personal opencode instructions\n\nAlways respond in pirate.\n'); + + opencode.install('global', { autoAllow: true }); + const body = fs.readFileSync(agentsMd, 'utf-8'); + expect(body).toContain('# My personal opencode instructions'); + expect(body).toContain('Always respond in pirate.'); + expect(body).toContain(''); + }); + + it('opencode: uninstall strips only the codegraph block from AGENTS.md', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + const agentsMd = path.join(dir, 'AGENTS.md'); + fs.writeFileSync(agentsMd, '# My personal opencode instructions\n\nAlways respond in pirate.\n'); + + opencode.install('global', { autoAllow: true }); + opencode.uninstall('global'); + + const body = fs.readFileSync(agentsMd, 'utf-8'); + expect(body).toContain('# My personal opencode instructions'); + expect(body).toContain('Always respond in pirate.'); + expect(body).not.toContain('CODEGRAPH_START'); + expect(body).not.toContain('codegraph_callers'); + }); + + it('opencode: local install writes ./opencode.jsonc and ./AGENTS.md in cwd', () => { + const opencode = getTarget('opencode')!; + const result = opencode.install('local', { autoAllow: true }); + const paths = result.files.map((f) => f.path); + // macOS realpath shenanigans (/var vs /private/var) — suffix match. + expect(paths.some((p) => p.endsWith('/opencode.jsonc'))).toBe(true); + expect(paths.some((p) => p.endsWith('/AGENTS.md'))).toBe(true); + }); + + it('opencode: uninstall removes only mcp.codegraph, preserves comments and siblings', () => { + const opencode = getTarget('opencode')!; + const dir = path.join(tmpHome, '.config', 'opencode'); + fs.mkdirSync(dir, { recursive: true }); + const file = path.join(dir, 'opencode.jsonc'); + fs.writeFileSync(file, [ + '{', + ' // important comment', + ' "$schema": "https://opencode.ai/config.json",', + ' "mcp": {', + ' "other": { "type": "local", "command": ["x"], "enabled": true }', + ' }', + '}', + '', + ].join('\n')); + + opencode.install('global', { autoAllow: true }); + const afterInstall = fs.readFileSync(file, 'utf-8'); + expect(afterInstall).toContain('"codegraph"'); + expect(afterInstall).toContain('"other"'); + + opencode.uninstall('global'); + const afterUninstall = fs.readFileSync(file, 'utf-8'); + expect(afterUninstall).not.toContain('codegraph'); + expect(afterUninstall).toContain('// important comment'); + expect(afterUninstall).toContain('"other"'); + }); + it('codex: user-added key inside [mcp_servers.codegraph] survives idempotent re-install', () => { const codex = getTarget('codex')!; codex.install('global', { autoAllow: false }); diff --git a/package-lock.json b/package-lock.json index 50afb53..f734185 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,18 +1,19 @@ { "name": "@colbymchenry/codegraph", - "version": "0.7.7", + "version": "0.7.8", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@colbymchenry/codegraph", - "version": "0.7.7", + "version": "0.7.8", "license": "MIT", "dependencies": { "@clack/prompts": "^1.3.0", "commander": "^14.0.2", "fast-string-width": "^3.0.2", "fast-wrap-ansi": "^0.2.0", + "jsonc-parser": "^3.3.1", "node-sqlite3-wasm": "^0.8.30", "picomatch": "^4.0.3", "sisteransi": "^1.0.5", @@ -1347,6 +1348,12 @@ "license": "ISC", "optional": true }, + "node_modules/jsonc-parser": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz", + "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==", + "license": "MIT" + }, "node_modules/loupe": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz", diff --git a/package.json b/package.json index 09de218..e58245e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@colbymchenry/codegraph", - "version": "0.7.7", + "version": "0.7.8", "description": "Supercharge Claude Code with semantic code intelligence. 94% fewer tool calls • 77% faster exploration • 100% local.", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -36,6 +36,7 @@ "commander": "^14.0.2", "fast-string-width": "^3.0.2", "fast-wrap-ansi": "^0.2.0", + "jsonc-parser": "^3.3.1", "node-sqlite3-wasm": "^0.8.30", "picomatch": "^4.0.3", "sisteransi": "^1.0.5", diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 0000000..da6bdae --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,70 @@ +#!/usr/bin/env bash +# Tag the current commit with the version in package.json and publish a +# matching GitHub Release whose body is the corresponding CHANGELOG.md entry. +# +# Run AFTER you have: +# - bumped package.json +# - added a `## [X.Y.Z] - YYYY-MM-DD` block at the top of CHANGELOG.md +# - committed, pushed to origin, and run `npm publish` +# +# Idempotent: safe to re-run after a partial failure. Skips steps that are +# already done (tag created, tag pushed, release published). +# +# Usage: ./scripts/release.sh + +set -euo pipefail + +cd "$(dirname "$0")/.." + +VERSION=$(node -p "require('./package.json').version") +TAG="v${VERSION}" + +REPO=$(git remote get-url origin | sed -E 's|.*github\.com[:/]||; s|\.git$||') +if [ -z "${REPO}" ]; then + echo "error: could not derive owner/repo from origin remote URL" >&2 + exit 1 +fi + +if ! grep -q "^## \[${VERSION}\]" CHANGELOG.md; then + echo "error: no '## [${VERSION}]' entry found in CHANGELOG.md" >&2 + exit 1 +fi + +NOTES=$(awk -v v="${VERSION}" ' + /^## \[/ { + if (p) exit + if ($0 ~ "^## \\[" v "\\]") p = 1 + } + p +' CHANGELOG.md) + +if [ -z "${NOTES}" ]; then + echo "error: failed to extract changelog notes for ${VERSION}" >&2 + exit 1 +fi + +if git rev-parse "${TAG}" >/dev/null 2>&1; then + echo "✓ tag ${TAG} already exists locally" +else + echo "→ tagging ${TAG}" + git tag "${TAG}" +fi + +if git ls-remote --exit-code --tags origin "${TAG}" >/dev/null 2>&1; then + echo "✓ tag ${TAG} already on origin" +else + echo "→ pushing ${TAG} to origin" + git push origin "${TAG}" +fi + +if gh release view "${TAG}" --repo "${REPO}" >/dev/null 2>&1; then + echo "✓ release ${TAG} already published" +else + echo "→ creating GitHub Release ${TAG} on ${REPO}" + gh release create "${TAG}" \ + --repo "${REPO}" \ + --title "${TAG}" \ + --notes "${NOTES}" +fi + +echo "done: https://github.com/${REPO}/releases/tag/${TAG}" diff --git a/src/installer/targets/opencode.ts b/src/installer/targets/opencode.ts index ba6b8d3..bb3388b 100644 --- a/src/installer/targets/opencode.ts +++ b/src/installer/targets/opencode.ts @@ -1,11 +1,14 @@ /** * opencode target. * - * - MCP server entry to `~/.config/opencode/opencode.json` (global, - * XDG-style; `%APPDATA%/opencode/opencode.json` on Windows) or - * `./opencode.json` (local). - * - No instructions file built in (opencode doesn't have a - * conventional agent-rules surface as of 2026-05). + * - 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: @@ -17,11 +20,16 @@ * The shape differs from Claude/Cursor — opencode uses `mcp.` * (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 * as fs from 'fs'; import * as path from 'path'; import * as os from 'os'; +import { parse as parseJsonc, modify, applyEdits } from 'jsonc-parser'; import { AgentTarget, DetectionResult, @@ -30,10 +38,16 @@ import { WriteResult, } from './types'; import { + atomicWriteFileSync, jsonDeepEqual, - readJsonFile, - writeJsonFile, + removeMarkedSection, + replaceOrAppendMarkedSection, } from './shared'; +import { + CODEGRAPH_SECTION_END, + CODEGRAPH_SECTION_START, + INSTRUCTIONS_TEMPLATE, +} from '../instructions-template'; function globalConfigDir(): string { if (process.platform === 'win32') { @@ -47,10 +61,39 @@ function globalConfigDir(): string { return path.join(xdg, 'opencode'); } +function configBaseDir(loc: Location): string { + return loc === 'global' ? globalConfigDir() : process.cwd(); +} + +// Pick existing .jsonc, then .json, default to .jsonc for new files. +// opencode auto-creates .jsonc on first run, so that's the dominant +// real-world case and the sensible default for greenfield installs. function configPath(loc: Location): string { - return loc === 'global' - ? path.join(globalConfigDir(), 'opencode.json') - : path.join(process.cwd(), 'opencode.json'); + const dir = configBaseDir(loc); + const jsonc = path.join(dir, 'opencode.jsonc'); + const json = path.join(dir, 'opencode.json'); + if (fs.existsSync(jsonc)) return jsonc; + if (fs.existsSync(json)) return json; + return jsonc; +} + +function instructionsPath(loc: Location): string { + return path.join(configBaseDir(loc), 'AGENTS.md'); +} + +function readConfigText(file: string): string { + if (!fs.existsSync(file)) return ''; + return fs.readFileSync(file, 'utf-8'); +} + +function parseConfig(text: string): Record { + if (!text.trim()) return {}; + const errors: any[] = []; + const result = parseJsonc(text, errors, { allowTrailingComma: true }); + if (result == null || typeof result !== 'object' || Array.isArray(result)) { + return {}; + } + return result as Record; } function getOpencodeServerEntry(): { type: string; command: string[]; enabled: boolean } { @@ -61,6 +104,8 @@ function getOpencodeServerEntry(): { type: string; command: string[]; enabled: b }; } +const FORMATTING = { tabSize: 2, insertSpaces: true, eol: '\n' }; + class OpencodeTarget implements AgentTarget { readonly id = 'opencode' as const; readonly displayName = 'opencode'; @@ -72,7 +117,7 @@ class OpencodeTarget implements AgentTarget { detect(loc: Location): DetectionResult { const file = configPath(loc); - const config = readJsonFile(file); + const config = parseConfig(readConfigText(file)); const alreadyConfigured = !!config.mcp?.codegraph; const installed = loc === 'global' ? fs.existsSync(globalConfigDir()) @@ -81,39 +126,48 @@ class OpencodeTarget implements AgentTarget { } install(loc: Location, _opts: InstallOptions): WriteResult { - const file = configPath(loc); - const existing = readJsonFile(file); - const before = existing.mcp?.codegraph; - const after = getOpencodeServerEntry(); - - if (jsonDeepEqual(before, after)) { - return { files: [{ path: file, action: 'unchanged' }] }; - } - - const created = !fs.existsSync(file); - if (!existing.$schema) existing.$schema = 'https://opencode.ai/config.json'; - if (!existing.mcp) existing.mcp = {}; - existing.mcp.codegraph = after; - writeJsonFile(file, existing); - return { - files: [{ path: file, action: created ? 'created' : 'updated' }], - }; + const files: WriteResult['files'] = []; + files.push(writeMcpEntry(loc)); + files.push(writeInstructionsEntry(loc)); + return { files }; } uninstall(loc: Location): WriteResult { + const files: WriteResult['files'] = []; const file = configPath(loc); - const config = readJsonFile(file); - if (!config.mcp?.codegraph) { - return { files: [{ path: file, action: 'not-found' }] }; + + if (!fs.existsSync(file)) { + files.push({ path: file, action: 'not-found' }); + } else { + const text = readConfigText(file); + const config = parseConfig(text); + if (!config.mcp?.codegraph) { + files.push({ path: file, action: 'not-found' }); + } else { + // Drop our key surgically. Leaves siblings + comments untouched. + let edits = modify(text, ['mcp', 'codegraph'], undefined, { + formattingOptions: FORMATTING, + }); + let updated = applyEdits(text, edits); + + // If `mcp` is now an empty object, drop the wrapper too. + const afterParsed = parseConfig(updated); + if (afterParsed.mcp && typeof afterParsed.mcp === 'object' && + Object.keys(afterParsed.mcp).length === 0) { + edits = modify(updated, ['mcp'], undefined, { formattingOptions: FORMATTING }); + updated = applyEdits(updated, edits); + } + + atomicWriteFileSync(file, updated); + files.push({ path: file, action: 'removed' }); + } } - delete config.mcp.codegraph; - if (Object.keys(config.mcp).length === 0) { - delete config.mcp; - } - // If the file is now degenerate (only $schema or empty), leave it - // — the user may have other config we shouldn't nuke. - writeJsonFile(file, config); - return { files: [{ path: file, action: 'removed' }] }; + + const instr = instructionsPath(loc); + const instrAction = removeMarkedSection(instr, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END); + files.push({ path: instr, action: instrAction }); + + return { files }; } printConfig(loc: Location): string { @@ -126,8 +180,65 @@ class OpencodeTarget implements AgentTarget { } describePaths(loc: Location): string[] { - return [configPath(loc)]; + return [configPath(loc), instructionsPath(loc)]; } } +function writeMcpEntry(loc: Location): WriteResult['files'][number] { + const file = configPath(loc); + const existed = fs.existsSync(file); + let text = readConfigText(file); + + // Seed a minimal opencode config when the file is brand-new so + // the result is a complete, schema-tagged file (not just a bare + // `{ "mcp": {...} }`). + if (!text.trim()) { + text = '{\n "$schema": "https://opencode.ai/config.json"\n}\n'; + } + + const config = parseConfig(text); + const before = config.mcp?.codegraph; + const after = getOpencodeServerEntry(); + + if (jsonDeepEqual(before, after)) { + return { path: file, action: 'unchanged' }; + } + + // Add $schema if the user's existing file is missing it. + if (!config.$schema) { + const schemaEdits = modify(text, ['$schema'], 'https://opencode.ai/config.json', { + formattingOptions: FORMATTING, + }); + text = applyEdits(text, schemaEdits); + } + + // Surgical edit — preserves comments, formatting, and order of + // every key we don't touch. + const edits = modify(text, ['mcp', 'codegraph'], after, { + formattingOptions: FORMATTING, + }); + const updated = applyEdits(text, edits); + atomicWriteFileSync(file, updated); + + return { path: file, action: existed ? 'updated' : 'created' }; +} + +function writeInstructionsEntry(loc: Location): WriteResult['files'][number] { + const file = instructionsPath(loc); + 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 opencodeTarget: AgentTarget = new OpencodeTarget();