@isac322/pi-codegraph 0.2.0

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "node",
+      "args": ["./bin/codegraph-mcp.mjs"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isac322
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @isac322/pi-codegraph
+
+CodeGraph tools for Pi and OMP, with worktree-aware index lifecycle management.
+
+## Why this package
+
+The extension exposes CodeGraph's structural tools with native Pi metadata and rendering while keeping OMP on its native MCP path. Indexes are separated per worktree, stored centrally, synchronized automatically, identity-checked, and garbage-collected after worktrees disappear.
+
+## Install
+
+```sh
+pi install npm:@isac322/pi-codegraph
+```
+
+OMP loads the package-local `.mcp.json` and `omp.extensions` entry. Pi loads `pi.extensions` and starts the internal MCP facade at session start, never during extension discovery.
+
+The package installs `@colbymchenry/codegraph` as an optional dependency and falls back to a `codegraph` executable on `PATH`.
+
+## Tools
+
+- `codegraph_explore`: broad architecture and flow exploration
+- `codegraph_search`: symbol-name lookup
+- `codegraph_node`: one known symbol and its relationships
+- `codegraph_files`: indexed project structure
+- `codegraph_callers`: inbound calls
+- `codegraph_callees`: outbound calls
+- `codegraph_impact`: transitive change impact
+- `codegraph_status`: CodeGraph index health
+
+Pi adds compact call/result rendering and `/codegraph status|sync|doctor|gc`.
+
+## Worktrees
+
+Each worktree gets a distinct database. New indexes are stored under the configured central index store and exposed to CodeGraph through the worktree's `.codegraph` symlink. Existing real `.codegraph` directories remain in place and receive identity metadata.
+
+A project path is accepted only when it is inside an allowed root or resolves to a worktree with the same Git common directory as the session root. Repository and worktree identities are checked before an index is reused. Missing or replaced worktrees fail closed.
+
+## Configuration
+
+Global configuration is read from `~/.config/pi-codegraph/config.json`, or from `PI_CODEGRAPH_CONFIG`.
+
+```json
+{
+  "autoSync": true,
+  "autoGc": true,
+  "indexStore": "/home/me/.cache/pi-codegraph",
+  "workerIdleTimeoutMs": 300000,
+  "maxWorkers": 6,
+  "requestTimeoutMs": 30000,
+  "syncMinIntervalMs": 15000,
+  "maxOutputChars": 60000,
+  "allowedProjectRoots": ["/work/company"],
+  "promptInjection": true,
+  "codegraphExecutable": ""
+}
+```
+
+Environment overrides:
+
+- `PI_CODEGRAPH_AUTO_SYNC`
+- `PI_CODEGRAPH_AUTO_GC`
+- `PI_CODEGRAPH_INDEX_STORE`
+- `PI_CODEGRAPH_WORKER_IDLE_MS`
+- `PI_CODEGRAPH_MAX_WORKERS`
+- `PI_CODEGRAPH_REQUEST_TIMEOUT_MS`
+- `PI_CODEGRAPH_SYNC_MIN_INTERVAL_MS`
+- `PI_CODEGRAPH_MAX_OUTPUT_CHARS`
+- `PI_CODEGRAPH_ALLOWED_ROOTS`
+- `PI_CODEGRAPH_PROMPT_INJECTION`
+- `PI_CODEGRAPH_EXECUTABLE`
+
+`PI_CODEGRAPH_ALLOWED_ROOTS` uses the platform path delimiter.
+
+## Runtime behavior
+
+- Pi defers process startup until `session_start` and closes all resources on `session_shutdown`.
+- OMP uses one package-local MCP facade and project-scoped CodeGraph workers.
+- Workers are capped, evicted by least-recently-used idle order, and terminated after the idle timeout.
+- Tool cancellation and timeout propagate to the worker. Diagnostics are ANSI-stripped, size-limited, and redact common token and secret forms.
+- `codegraph_files` accepts absolute in-project paths and `~`, normalizing them to repo-relative POSIX prefixes.
+- Large results are bounded and retain both their beginning and end with an explicit truncation marker.
+
+## Security
+
+Pi checks project trust before initialization or tool execution. The MCP facade resolves real paths and restricts access to the active workspace, sibling worktrees of the same repository, and explicitly configured roots.
+
+## Pi package gallery
+
+The npm package declares the `pi-package` keyword and an explicit `pi.extensions` manifest. After npm publication, Pi's package gallery can index it at [pi.dev/packages](https://pi.dev/packages).
+
+Releases use npm trusted publishing from `.github/workflows/publish.yml`. Configure the npm trusted publisher for repository `isac322/pi-codegraph` and workflow `publish.yml`, then publish a GitHub Release.
+
+## License
+
+MIT

package/bin/codegraph-mcp.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { loadSettings } from "../lib/config.mjs";
+import { ProjectGuard, WorkspaceManager, annotateFilesResult, normalizeFilesPath, publicSettings, sanitizeDiagnostic, truncateText } from "../lib/codegraph.mjs";
+import { CodeGraphWorkerPool } from "../lib/worker-pool.mjs";
+import { codegraphTools, codegraphToolNames } from "../lib/tool-metadata.mjs";
+
+const settings = await loadSettings();
+const baseRoot = process.env.PI_CODEGRAPH_BASE_ROOT || process.cwd();
+const guard = await ProjectGuard.create(baseRoot, settings);
+const manager = new WorkspaceManager(settings);
+const pool = new CodeGraphWorkerPool(settings);
+const controllers = new Map();
+let buffer = "";
+let gcTimer;
+
+function write(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function response(id, result) {
+  write({ jsonrpc: "2.0", id, result });
+}
+
+function errorResponse(id, error, code = -32603) {
+  write({ jsonrpc: "2.0", id, error: { code, message: sanitizeDiagnostic(error?.message || error) } });
+}
+
+async function resolveIdentity(params = {}) {
+  return guard.resolve(params.projectPath || baseRoot);
+}
+
+function extractText(result) {
+  return (result?.content || []).filter((part) => part?.type === "text").map((part) => part.text).join("\n") || JSON.stringify(result);
+}
+
+async function callTool(params, signal) {
+  const name = params?.name;
+  if (!codegraphToolNames.includes(name)) throw new Error(`Unknown CodeGraph tool: ${name}`);
+  const supplied = { ...(params?.arguments || {}) };
+  const identity = await resolveIdentity(supplied);
+  await manager.prepare(identity, { signal });
+  delete supplied.projectPath;
+  const originalFilesPath = name === "codegraph_files" && typeof supplied.path === "string" ? supplied.path : undefined;
+  if (name === "codegraph_files") {
+    const normalized = normalizeFilesPath(originalFilesPath, identity.sourcePath);
+    if (normalized === undefined) delete supplied.path;
+    else supplied.path = normalized;
+  }
+  const result = await pool.call(identity.sourcePath, name, supplied, signal);
+  if (result?.isError) return result;
+  let text = extractText(result);
+  if (name === "codegraph_files") text = annotateFilesResult(text, originalFilesPath);
+  const limited = truncateText(text, settings.maxOutputChars);
+  return {
+    ...result,
+    content: [{ type: "text", text: limited.text }],
+    _meta: { projectPath: identity.sourcePath, truncated: limited.truncated },
+  };
+}
+
+async function handleRequest(message, signal) {
+  switch (message.method) {
+    case "initialize":
+      return {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "pi-codegraph", version: "0.2.0" },
+      };
+    case "tools/list":
+      return { tools: codegraphTools.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })) };
+    case "tools/call":
+      return callTool(message.params, signal);
+    case "codegraph/workspace/prepare": {
+      const identity = await resolveIdentity(message.params);
+      const result = await manager.prepare(identity, { signal });
+      await manager.gc(pool.activeProjects());
+      return result;
+    }
+    case "codegraph/workspace/status": {
+      const identity = await resolveIdentity(message.params);
+      return manager.status(identity);
+    }
+    case "codegraph/workspace/sync": {
+      const identity = await resolveIdentity(message.params);
+      return manager.prepare(identity, { signal, forceSync: true });
+    }
+    case "codegraph/workspace/doctor": {
+      const identity = await resolveIdentity(message.params);
+      return manager.doctor(identity);
+    }
+    case "codegraph/workspace/gc":
+      return manager.gc(pool.activeProjects(), Boolean(message.params?.force));
+    case "codegraph/settings":
+      return publicSettings(settings);
+    case "shutdown":
+      return null;
+    default:
+      throw Object.assign(new Error(`Method not found: ${message.method}`), { rpcCode: -32601 });
+  }
+}
+
+async function receive(message) {
+  if (message.method === "notifications/cancelled") {
+    controllers.get(message.params?.requestId)?.abort();
+    return;
+  }
+  if (message.id === undefined) return;
+  const controller = new AbortController();
+  controllers.set(message.id, controller);
+  try {
+    response(message.id, await handleRequest(message, controller.signal));
+  } catch (error) {
+    if (message.method === "tools/call") {
+      response(message.id, { content: [{ type: "text", text: sanitizeDiagnostic(error.message) }], isError: true });
+    } else {
+      errorResponse(message.id, error, error.rpcCode);
+    }
+  } finally {
+    controllers.delete(message.id);
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  buffer += chunk.toString("utf8");
+  let newline;
+  while ((newline = buffer.indexOf("\n")) !== -1) {
+    const line = buffer.slice(0, newline).trim();
+    buffer = buffer.slice(newline + 1);
+    if (!line) continue;
+    try { void receive(JSON.parse(line)); } catch { errorResponse(null, new Error("Invalid JSON"), -32700); }
+  }
+});
+
+async function shutdown() {
+  clearInterval(gcTimer);
+  for (const controller of controllers.values()) controller.abort();
+  await pool.close();
+}
+
+if (settings.autoGc) {
+  gcTimer = setInterval(() => { void manager.gc(pool.activeProjects()); }, 60 * 60_000);
+  gcTimer.unref?.();
+}
+process.on("SIGTERM", () => { void shutdown().finally(() => process.exit(0)); });
+process.on("SIGINT", () => { void shutdown().finally(() => process.exit(0)); });
+process.stdin.on("end", () => { void shutdown().finally(() => process.exit(0)); });

package/extensions/omp.mjs

@@ -0,0 +1,14 @@
+import { loadSettings } from "../lib/config.mjs";
+import { workspaceSummary } from "../lib/codegraph.mjs";
+import { buildCodeGraphPrompt } from "../lib/prompt.mjs";
+
+export default async function ompCodeGraphExtension(omp) {
+  const settings = await loadSettings();
+  if (!settings.promptInjection || typeof omp?.on !== "function") return;
+  omp.on("before_agent_start", async (event, ctx) => {
+    const cwd = ctx?.cwd || process.cwd();
+    const status = await workspaceSummary(cwd);
+    const guidance = buildCodeGraphPrompt({ runtime: "omp", cwd, status });
+    return { systemPrompt: event.systemPrompt ? `${event.systemPrompt}\n\n${guidance}` : guidance };
+  });
+}

package/extensions/pi.mjs

@@ -0,0 +1,127 @@
+import { Text } from "@earendil-works/pi-tui";
+import { loadSettings } from "../lib/config.mjs";
+import { workspaceSummary } from "../lib/codegraph.mjs";
+import { buildCodeGraphPrompt } from "../lib/prompt.mjs";
+import { PiCodeGraphClient } from "../lib/pi-mcp-client.mjs";
+import { codegraphTools, summarizeToolText, toolCallLabel } from "../lib/tool-metadata.mjs";
+
+function textContent(result) {
+  return (result?.content || []).filter((item) => item?.type === "text").map((item) => item.text).join("\n");
+}
+
+async function trusted(ctx) {
+  if (typeof ctx?.isProjectTrusted !== "function") return true;
+  return Boolean(await ctx.isProjectTrusted());
+}
+
+export default async function piCodeGraphExtension(pi) {
+  const settings = await loadSettings();
+  let sessionCwd = process.cwd();
+  let client;
+
+  const getClient = async (cwd, ctx) => {
+    if (!(await trusted(ctx))) throw new Error("CodeGraph is disabled until this project is trusted.");
+    if (!client || sessionCwd !== cwd) {
+      await client?.close();
+      sessionCwd = cwd;
+      client = new PiCodeGraphClient(settings, cwd);
+    }
+    return client;
+  };
+
+  for (const tool of codegraphTools) {
+    pi.registerTool({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      promptSnippet: tool.promptSnippet,
+      promptGuidelines: tool.promptGuidelines,
+      parameters: tool.inputSchema,
+      async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        const cwd = ctx?.cwd || sessionCwd || process.cwd();
+        const activeClient = await getClient(cwd, ctx);
+        const args = { ...(params || {}), projectPath: params?.projectPath || cwd };
+        const result = await activeClient.callTool(tool.name, args, signal);
+        const text = textContent(result);
+        if (result?.isError) throw new Error(text || `${tool.label} failed`);
+        const summary = summarizeToolText(text);
+        return {
+          content: result?.content?.length ? result.content : [{ type: "text", text: JSON.stringify(result) }],
+          details: { toolName: tool.name, projectPath: args.projectPath, ...summary },
+        };
+      },
+      renderCall(args, theme) {
+        return new Text(theme.fg("toolTitle", theme.bold(`${tool.label} `)) + theme.fg("muted", toolCallLabel(tool.name, args)), 0, 0);
+      },
+      renderResult(result, { expanded }, theme) {
+        const details = result.details || {};
+        const text = textContent(result);
+        if (!text) return new Text(theme.fg("dim", "No output"), 0, 0);
+        if (expanded) return new Text(text, 0, 0);
+        const lines = text.split("\n");
+        const preview = lines.slice(0, 6).join("\n");
+        const suffix = lines.length > 6 ? `\n${theme.fg("dim", `... ${lines.length - 6} more lines`)}` : "";
+        const marker = details.truncated ? theme.fg("warning", " [truncated]") : "";
+        return new Text(`${preview}${suffix}${marker}`, 0, 0);
+      },
+    });
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionCwd = ctx.cwd || process.cwd();
+    if (!(await trusted(ctx))) return;
+    ctx.ui?.setStatus?.("codegraph", "CodeGraph indexing");
+    try {
+      const activeClient = await getClient(sessionCwd, ctx);
+      await activeClient.request("codegraph/workspace/prepare", { projectPath: sessionCwd });
+    } catch (error) {
+      ctx.ui?.notify?.(`CodeGraph initialization failed: ${error.message}`, "warning");
+    } finally {
+      ctx.ui?.setStatus?.("codegraph", undefined);
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!settings.promptInjection || !(await trusted(ctx))) return;
+    const cwd = ctx.cwd || sessionCwd || process.cwd();
+    const status = await workspaceSummary(cwd);
+    const guidance = buildCodeGraphPrompt({ runtime: "pi", cwd, status });
+    return { systemPrompt: event.systemPrompt ? `${event.systemPrompt}\n\n${guidance}` : guidance };
+  });
+
+  pi.on("session_shutdown", async () => {
+    await client?.close();
+    client = undefined;
+  });
+
+  pi.registerCommand("codegraph", {
+    description: "CodeGraph status, sync, doctor, or gc",
+    handler: async (input, ctx) => {
+      if (!(await trusted(ctx))) {
+        ctx.ui?.notify?.("Trust this project before using CodeGraph.", "error");
+        return;
+      }
+      const action = String(input || "status").trim().split(/\s+/)[0] || "status";
+      const methods = {
+        status: "codegraph/workspace/status",
+        sync: "codegraph/workspace/sync",
+        doctor: "codegraph/workspace/doctor",
+        gc: "codegraph/workspace/gc",
+      };
+      if (!methods[action]) {
+        ctx.ui?.notify?.("Usage: /codegraph [status|sync|doctor|gc]", "error");
+        return;
+      }
+      ctx.ui?.setStatus?.("codegraph", `CodeGraph ${action}`);
+      try {
+        const activeClient = await getClient(ctx.cwd || sessionCwd, ctx);
+        const result = await activeClient.request(methods[action], { projectPath: ctx.cwd || sessionCwd, force: action === "gc" });
+        ctx.ui?.notify?.(JSON.stringify(result, null, 2), "info");
+      } catch (error) {
+        ctx.ui?.notify?.(`CodeGraph ${action} failed: ${error.message}`, "error");
+      } finally {
+        ctx.ui?.setStatus?.("codegraph", undefined);
+      }
+    },
+  });
+}