@saluzi/codegraph 0.1.0

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

@@ -0,0 +1,122 @@
+/**
+ * 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'
+/**
+ * Result of `target.detect(location)`.
+ *
+ * `installed` is a best-effort heuristic that the agent's CLI / app /
+ * config dir is present on this system — used to default the
+ * multiselect prompt to "what's actually here." False positives are
+ * acceptable (we still write); false negatives just mean the user
+ * has to opt in manually.
+ *
+ * `alreadyConfigured` reports whether codegraph has already been
+ * wired into this target at this location — drives the
+ * "Updated"-vs-"Added" log line and lets `--check` exit 0/1.
+ */
+export interface DetectionResult {
+  installed: boolean
+  alreadyConfigured: boolean
+  /** Path inspected; surfaced in diagnostic / dry-run output. */
+  configPath?: string
+}
+/**
+ * What `target.install(location)` actually changed on disk. The
+ * orchestrator renders one log line per file using `action`.
+ *
+ * `unchanged` means we touched the file but its contents were already
+ * what we'd write — used for byte-identical idempotent re-runs.
+ */
+export interface WriteResult {
+  files: Array<{
+    path: string
+    action:
+      | 'created'
+      | 'updated'
+      | 'unchanged'
+      | 'removed'
+      | 'not-found'
+      | 'kept'
+  }>
+  /**
+   * Optional one-line notes the orchestrator surfaces verbatim — e.g.
+   * "Restart Cursor to apply." Keep these short; multi-line goes in
+   * the README.
+   */
+  notes?: string[]
+}
+export interface InstallOptions {
+  /**
+   * Whether to write the agent's permissions / auto-allow surface
+   * (Claude `settings.json`, others where applicable). When the
+   * target has no permissions concept this option is a no-op.
+   */
+  autoAllow: boolean
+}
+export interface AgentTarget {
+  /** Stable id; matches the `TargetId` union. */
+  readonly id: TargetId
+  /** Human-readable name shown in clack prompts and log lines. */
+  readonly displayName: string
+  /** Optional URL for "where do I learn more about this agent." */
+  readonly docsUrl?: string
+  /**
+   * Whether this target supports the given install location.
+   *
+   * Some agents (Codex CLI as of 2026-05) have no project-local
+   * config concept — only a single `~/.codex/` dir. Returning false
+   * for an unsupported (target, location) pair lets the orchestrator
+   * skip cleanly with a clear message.
+   */
+  supportsLocation(loc: Location): boolean
+  detect(loc: Location): DetectionResult
+  install(loc: Location, opts: InstallOptions): WriteResult
+  /**
+   * Inverse of install. Removes only what install would have written;
+   * preserves sibling MCP servers, sibling permissions, and unrelated
+   * markdown sections. Must be safe to call when nothing was ever
+   * installed (returns `not-found` actions).
+   */
+  uninstall(loc: Location): WriteResult
+  /**
+   * Print the MCP-server snippet a user would paste manually for this
+   * target. Used by `codegraph install --print-config <id>` and by
+   * the README. Must NOT touch the filesystem.
+   */
+  printConfig(loc: Location): string
+  /** Filesystem paths this target would write to at this location. */
+  describePaths(loc: Location): string[]
+  /**
+   * Optional. Write any project-local surfaces this target needs in
+   * order to work fully when its MCP config is configured globally.
+   * Called by `codegraph init` to bootstrap new projects without
+   * forcing the user to re-run `codegraph install` per project.
+   *
+   * Most targets need nothing here — their global config is complete.
+   * Cursor is the notable exception: its rules system
+   * (`.cursor/rules/*.mdc`) is project-scoped only, and is what makes
+   * Cursor's agent prefer codegraph over its built-in grep.
+   *
+   * Must be idempotent. Targets that have nothing project-local omit
+   * the method entirely.
+   */
+  wireProjectSurfaces?(): WriteResult
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * CodeGraph MCP Server
+ *
+ * Model Context Protocol server that exposes CodeGraph functionality
+ * as tools for AI assistants like Claude.
+ *
+ * @module mcp
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from 'codegraph';
+ *
+ * const server = new MCPServer('/path/to/project');
+ * await server.start();
+ * ```
+ */
+/**
+ * MCP Server for CodeGraph
+ *
+ * Implements the Model Context Protocol to expose CodeGraph
+ * functionality as tools that can be called by AI assistants.
+ */
+export declare class MCPServer {
+  private transport
+  private cg
+  private toolHandler
+  private projectPath
+  private initPromise
+  private clientSupportsRoots
+  private rootsAttempted
+  private originalPpid
+  private hostPpid
+  private ppidWatchdog
+  private stopped
+  constructor(projectPath?: string)
+  /**
+   * Start the MCP server
+   *
+   * Note: CodeGraph initialization is deferred until the initialize request
+   * is received, which includes the rootUri from the client.
+   */
+  start(): Promise<void>
+  /**
+   * Try to initialize CodeGraph for the default project.
+   *
+   * Walks up parent directories to find the nearest .codegraph/ folder,
+   * similar to how git finds .git/ directories.
+   *
+   * If initialization fails, the error is recorded but the server continues
+   * to work — cross-project queries and retries on subsequent tool calls
+   * are still possible.
+   */
+  private tryInitializeDefault
+  /**
+   * Retry initialization of the default project if it previously failed.
+   * Called lazily on tool calls that need the default project.
+   * Re-walks parent directories each time so it picks up projects
+   * initialized after the MCP server started.
+   *
+   * Awaits any in-flight background init (kicked off by handleInitialize) so
+   * we never open the SQLite file twice concurrently.
+   */
+  private retryInitIfNeeded
+  /**
+   * Resolve the project root via the MCP `roots/list` request and initialize
+   * from the first root the client reports. Falls back to the process cwd if
+   * the client returns no usable root or doesn't answer in time. See issue #196.
+   */
+  private initFromRoots
+  /**
+   * Start file watching on the active CodeGraph instance.
+   * Logs sync activity to stderr for diagnostics.
+   */
+  private startWatching
+  /**
+   * Stop the server
+   */
+  stop(): void
+  /**
+   * Handle incoming JSON-RPC messages
+   */
+  private handleMessage
+  /**
+   * Handle initialize request
+   */
+  private handleInitialize
+  /**
+   * Handle tools/list request
+   */
+  private handleToolsList
+  /**
+   * Handle tools/call request
+   */
+  private handleToolsCall
+}
+export { StdioTransport } from './transport'
+export { tools, ToolHandler } from './tools'
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/server-instructions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
+ * SDK, …) surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the codegraph toolset
+ * before it sees individual tool descriptions.
+ *
+ * Goals when editing this:
+ *   - Tool selection by intent (which tool for which question)
+ *   - Common chains (refactor planning = X then Y)
+ *   - Anti-patterns (don't grep when codegraph_search is faster)
+ *
+ * Keep it tight. The agent reads this every session — long instructions
+ * burn tokens. Reference only tools that exist on `main`; gate any
+ * conditional tools behind feature checks if/when they ship.
+ */
+export declare const SERVER_INSTRUCTIONS =
+  '# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don\'t delegate exploration\n\nFor "how does X work", architecture, trace, or where-is-X questions,\nanswer DIRECTLY using 2-3 codegraph calls: `codegraph_context` first,\nthen ONE `codegraph_explore` for the source of the symbols it surfaces.\nCodegraph IS the pre-built search index \u2014 so delegating the lookup to a\nseparate file-reading sub-task/agent, or running your own grep + read\nloop, repeats work codegraph already did and costs more for the same\nanswer. Reach for raw Read/Grep only to confirm a specific detail\ncodegraph didn\'t cover. A direct codegraph answer is typically a handful\nof calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **"What is the symbol named X?"** \u2192 `codegraph_search`\n- **"What\'s the deal with this task / feature / area?"** \u2192 `codegraph_context` (PRIMARY \u2014 composes search + node + callers + callees in one call)\n- **"What calls this?"** \u2192 `codegraph_callers`\n- **"What does this call?"** \u2192 `codegraph_callees`\n- **"What would changing this break?"** \u2192 `codegraph_impact`\n- **"Show me this symbol\'s source / signature / docstring."** \u2192 `codegraph_node`\n- **"Show me several related symbols\' source / survey an area."** \u2192 `codegraph_explore` (ONE capped call; prefer over many codegraph_node/Read)\n- **"What\'s in directory X?"** \u2192 `codegraph_files`\n- **"Is the index ready / what\'s its size?"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Onboarding**: `codegraph_context` first. If still unclear, `codegraph_explore` for breadth, then `codegraph_node` on specific symbols.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Don\'t grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don\'t chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one round-trip.\n- **Don\'t loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use `codegraph_node` for a single symbol.\n- **Don\'t query the index immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync. Wait for the next turn.\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that\'s still the TypeScript compiler / test suite / linter\'s job. Codegraph supplements those with structural context they don\'t have.\n'
+//# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/tools.d.ts

@@ -0,0 +1,269 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools exposed by the CodeGraph MCP server.
+ */
+import CodeGraph from '../index'
+/**
+ * Calculate the recommended number of codegraph_explore calls based on project size.
+ * Larger codebases need more exploration calls to cover their surface area,
+ * but smaller ones should use fewer to avoid unnecessary overhead.
+ */
+export declare function getExploreBudget(fileCount: number): number
+/**
+ * Adaptive output budget for `codegraph_explore`, scaled to project size.
+ *
+ * Smaller codebases get a tighter total cap, fewer default files, smaller
+ * per-file cap, and tighter clustering — so a focused query on a 100-file
+ * project doesn't dump a whole file's worth of source into the agent's
+ * context. Larger codebases keep the generous defaults because the
+ * agent's native discovery cost (grep + find + many Reads) genuinely
+ * dwarfs a fat explore call at that scale.
+ *
+ * Meta-text (relationships map, "additional relevant files" list,
+ * completeness signal, budget note) is gated off for tiny projects
+ * where one rich call is the whole story and the extra prose is just
+ * overhead.
+ *
+ * Tier breakpoints mirror `getExploreBudget` so a project sits in the
+ * same tier across both knobs.
+ */
+export interface ExploreOutputBudget {
+  /** Hard cap on total output characters. */
+  maxOutputChars: number
+  /** Default `maxFiles` when the caller didn't specify one. */
+  defaultMaxFiles: number
+  /** Cap on contiguous source returned per file (across all its clusters). */
+  maxCharsPerFile: number
+  /** Cluster gap threshold in lines — tighter clustering on small projects. */
+  gapThreshold: number
+  /** Max symbols listed in the per-file header (`#### path — sym(kind), ...`). */
+  maxSymbolsInFileHeader: number
+  /** Max edges shown per relationship kind in the Relationships section. */
+  maxEdgesPerRelationshipKind: number
+  /** Include the "Relationships" section. */
+  includeRelationships: boolean
+  /** Include the "Additional relevant files (not shown)" trailing list. */
+  includeAdditionalFiles: boolean
+  /** Include the "Complete source code is included above…" reminder. */
+  includeCompletenessSignal: boolean
+  /** Include the explore-budget reminder at the end. */
+  includeBudgetNote: boolean
+}
+export declare function getExploreOutputBudget(
+  fileCount: number,
+): ExploreOutputBudget
+/**
+ * MCP Tool definition
+ */
+export interface ToolDefinition {
+  name: string
+  description: string
+  inputSchema: {
+    type: 'object'
+    properties: Record<string, PropertySchema>
+    required?: string[]
+  }
+}
+interface PropertySchema {
+  type: string
+  description: string
+  enum?: string[]
+  default?: unknown
+}
+/**
+ * Tool execution result
+ */
+export interface ToolResult {
+  content: Array<{
+    type: 'text'
+    text: string
+  }>
+  isError?: boolean
+}
+/**
+ * All CodeGraph MCP tools
+ *
+ * Designed for minimal context usage - use codegraph_context as the primary tool,
+ * and only use other tools for targeted follow-up queries.
+ *
+ * All tools support cross-project queries via the optional `projectPath` parameter.
+ */
+export declare const tools: ToolDefinition[]
+/**
+ * Tool handler that executes tools against a CodeGraph instance
+ *
+ * Supports cross-project queries via the projectPath parameter.
+ * Other projects are opened on-demand and cached for performance.
+ */
+export declare class ToolHandler {
+  private cg
+  private projectCache
+  private defaultProjectHint
+  constructor(cg: CodeGraph | null)
+  /**
+   * Update the default CodeGraph instance (e.g. after lazy initialization)
+   */
+  setDefaultCodeGraph(cg: CodeGraph): void
+  /**
+   * Record the directory the server tried to resolve the default project from.
+   * Used only to make the "no default project" error actionable.
+   */
+  setDefaultProjectHint(searchedPath: string): void
+  /**
+   * Whether a default CodeGraph instance is available
+   */
+  hasDefaultCodeGraph(): boolean
+  /**
+   * Get tool definitions with dynamic descriptions based on project size.
+   * The codegraph_explore tool description includes a budget recommendation
+   * scaled to the number of indexed files.
+   */
+  getTools(): ToolDefinition[]
+  /**
+   * Get CodeGraph instance for a project
+   *
+   * If projectPath is provided, opens that project's CodeGraph (cached).
+   * Otherwise returns the default CodeGraph instance.
+   *
+   * Walks up parent directories to find the nearest .codegraph/ folder,
+   * similar to how git finds .git/ directories.
+   */
+  private getCodeGraph
+  /**
+   * Close all cached project connections
+   */
+  closeAll(): void
+  /**
+   * Validate that a value is a non-empty string within length bounds.
+   *
+   * The `maxLength` cap protects against MCP clients that ship huge
+   * payloads (10MB+ query strings either by accident or maliciously).
+   * Without this, a single oversized input can pin the FTS5 index or
+   * exhaust memory before any real work runs.
+   */
+  private validateString
+  /**
+   * Validate an optional path-like string input. Returns the value if
+   * valid (or undefined), or a ToolResult with the error.
+   */
+  private validateOptionalPath
+  /**
+   * Execute a tool by name
+   */
+  execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult>
+  /**
+   * Handle codegraph_search
+   */
+  private handleSearch
+  /**
+   * Handle codegraph_context
+   */
+  private handleContext
+  /**
+   * Heuristic to detect if a query looks like a feature request
+   */
+  private looksLikeFeatureRequest
+  /**
+   * Handle codegraph_callers
+   */
+  private handleCallers
+  /**
+   * Handle codegraph_callees
+   */
+  private handleCallees
+  /**
+   * Handle codegraph_impact
+   */
+  private handleImpact
+  /**
+   * Handle codegraph_explore — deep exploration in a single call
+   *
+   * Strategy: find relevant symbols via graph traversal, group by file,
+   * then read contiguous file sections covering all symbols per file.
+   * This replaces multiple codegraph_node + Read calls.
+   *
+   * Output size is adaptive to project file count via
+   * `getExploreOutputBudget` — see #185 for why a fixed 35k cap was a
+   * tax on small projects while earning its keep on large ones.
+   */
+  private handleExplore
+  /**
+   * Handle codegraph_node
+   */
+  private handleNode
+  /**
+   * Handle codegraph_status
+   */
+  private handleStatus
+  /**
+   * Handle codegraph_files - get project file structure from the index
+   */
+  private handleFiles
+  /**
+   * Convert glob pattern to regex
+   */
+  private globToRegex
+  /**
+   * Format files as a flat list
+   */
+  private formatFilesFlat
+  /**
+   * Format files grouped by language
+   */
+  private formatFilesGrouped
+  /**
+   * Format files as a tree structure
+   */
+  private formatFilesTree
+  /**
+   * Find a symbol by name, handling disambiguation when multiple matches exist.
+   * Returns the best match and a note about alternatives if any.
+   */
+  /**
+   * Check if a node matches a symbol query.
+   *
+   * Accepts simple names (`run`) and three flavors of qualifier:
+   *   - dotted     `Session.request`         (TS/JS/Python)
+   *   - colon-pair `stage_apply::run`        (Rust, C++, Ruby)
+   *   - slash      `configurator/stage_apply` (path-ish)
+   *
+   * Multi-level qualifiers compose: `crate::configurator::stage_apply::run`
+   * works. Rust path prefixes (`crate`, `super`, `self`) are stripped so
+   * the canonical `crate::module::symbol` form resolves.
+   *
+   * Resolution order, last part must always equal `node.name`:
+   *   1. Suffix-match against `qualifiedName` (handles class-scoped methods
+   *      where the extractor builds the qualified name from the AST stack)
+   *   2. File-path containment (handles file-derived modules in Rust/
+   *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
+   */
+  private matchesSymbol
+  private findSymbol
+  /**
+   * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
+   * results across all matching symbols (e.g., multiple classes with an `execute` method).
+   */
+  private findAllSymbols
+  /**
+   * Truncate output if it exceeds the maximum length
+   */
+  private truncateOutput
+  private formatSearchResults
+  private formatNodeList
+  private formatImpact
+  /**
+   * Build a compact structural outline of a container symbol from its
+   * indexed children (methods, fields, properties, …) — name, kind,
+   * line number, and signature — so the agent gets the shape of a class
+   * without the full source of every method. Returns '' when the container
+   * has no indexed children, so the caller can fall back to full source.
+   */
+  private buildContainerOutline
+  private formatNodeDetails
+  private formatTaskContext
+  private textResult
+  private errorResult
+}
+export {}
+//# sourceMappingURL=tools.d.ts.map

package/dist/mcp/transport.d.ts

@@ -0,0 +1,117 @@
+/**
+ * MCP Stdio Transport
+ *
+ * Handles JSON-RPC 2.0 communication over stdin/stdout for MCP protocol.
+ */
+/**
+ * JSON-RPC 2.0 Request
+ */
+export interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: string | number
+  method: string
+  params?: unknown
+}
+/**
+ * JSON-RPC 2.0 Response
+ */
+export interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: string | number | null
+  result?: unknown
+  error?: JsonRpcError
+}
+/**
+ * JSON-RPC 2.0 Error
+ */
+export interface JsonRpcError {
+  code: number
+  message: string
+  data?: unknown
+}
+/**
+ * JSON-RPC 2.0 Notification (no id, no response expected)
+ */
+export interface JsonRpcNotification {
+  jsonrpc: '2.0'
+  method: string
+  params?: unknown
+}
+export declare const ErrorCodes: {
+  readonly ParseError: -32700
+  readonly InvalidRequest: -32600
+  readonly MethodNotFound: -32601
+  readonly InvalidParams: -32602
+  readonly InternalError: -32603
+}
+export type MessageHandler = (
+  message: JsonRpcRequest | JsonRpcNotification,
+) => Promise<void>
+/**
+ * Stdio Transport for MCP
+ *
+ * Reads JSON-RPC messages from stdin and writes responses to stdout.
+ */
+export declare class StdioTransport {
+  private rl
+  private messageHandler
+  private pending
+  private nextRequestId
+  /**
+   * Start listening for messages on stdin
+   */
+  start(handler: MessageHandler): void
+  /**
+   * Stop listening
+   */
+  stop(): void
+  /**
+   * Send a server-initiated request to the client and await its response.
+   *
+   * MCP is bidirectional: the server can ask the client questions too. We use
+   * this for `roots/list` — the spec-blessed way to learn the workspace root
+   * when the client didn't pass one in `initialize` (see issue #196). Rejects
+   * on timeout so callers can fall back rather than hang forever.
+   */
+  request(
+    method: string,
+    params?: unknown,
+    timeoutMs?: number,
+  ): Promise<unknown>
+  /**
+   * Send a response
+   */
+  send(response: JsonRpcResponse): void
+  /**
+   * Send a notification (no id)
+   */
+  notify(method: string, params?: unknown): void
+  /**
+   * Send a success response
+   */
+  sendResult(id: string | number, result: unknown): void
+  /**
+   * Send an error response
+   */
+  sendError(
+    id: string | number | null,
+    code: number,
+    message: string,
+    data?: unknown,
+  ): void
+  /**
+   * Handle an incoming line of JSON
+   */
+  private handleLine
+  /**
+   * Resolve (or reject) the pending server-initiated request matching this
+   * response's id. Unknown ids are ignored — the client may echo something we
+   * never sent, or a request may have already timed out.
+   */
+  private handleResponse
+  /**
+   * Check if message is a valid JSON-RPC 2.0 message
+   */
+  private isValidMessage
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/resolution/frameworks/cargo-workspace.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cargo Workspace Resolver Helper
+ *
+ * Parses a project's root Cargo.toml and member crate manifests to
+ * build a crate-name -> member-directory map. Used by the Rust
+ * resolver to resolve `use crate_name::...` references that point
+ * into workspace member crates.
+ */
+import { ResolutionContext } from '../types'
+/**
+ * Build a map from crate-name aliases to workspace member directory paths.
+ * Example: "mytool-core" and "mytool_core" -> "crates/mytool-core"
+ *
+ * Supports glob members (e.g. `members = ["crates/*"]`) via picomatch
+ * when the context exposes `listDirectories`.
+ */
+export declare function getCargoWorkspaceCrateMap(
+  context: ResolutionContext,
+): Map<string, string>
+//# sourceMappingURL=cargo-workspace.d.ts.map