@vndv/pi-codegraph 0.1.7 → 0.1.9

package/README.md

@@ -8,7 +8,7 @@
 
 Ask pi structural questions about your codebase without falling back to slow grep/read loops.
 
-An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph](https://github.com/colbymchenry/codegraph) tools. CodeGraph indexes your project with tree-sitter, then pi can query symbols, callers, callees, dependency impact, files, and call paths through native extension tools.
+An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph](https://github.com/colbymchenry/codegraph) tools. CodeGraph indexes your project with tree-sitter, then pi can query symbols, callers, callees, dependency impact, files, and relationships through native extension tools.
 
 ---
 
@@ -18,7 +18,7 @@ An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph]
 npm install -g @colbymchenry/codegraph
 cd /path/to/project
 codegraph init -i
-pi install npm:@vndv/pi-codegraph@0.1.7
+pi install npm:@vndv/pi-codegraph@0.1.9
 pi
 ```
 
@@ -36,13 +36,11 @@ Extension tools only. There is no MCP setup for pi users to maintain.
 
 | Tool | Description |
 | --- | --- |
-| `codegraph_context` | Broad task context: entry points, related symbols, callers, callees, and key code |
 | `codegraph_search` | Symbol search by name |
 | `codegraph_node` | One symbol's signature, location, source, callers, and callees |
 | `codegraph_files` | Indexed file tree |
 | `codegraph_callers` | Functions or methods that call a symbol |
 | `codegraph_callees` | Functions or methods called by a symbol |
-| `codegraph_trace` | Static call path from one symbol to another |
 | `codegraph_impact` | Impact radius for changing a symbol |
 | `codegraph_explore` | Source for several related symbols grouped by file |
 | `codegraph_status` | Index health and pending sync status |
@@ -54,7 +52,7 @@ Extension tools only. There is no MCP setup for pi users to maintain.
 From npm:
 
 ```bash
-pi install npm:@vndv/pi-codegraph@0.1.7
+pi install npm:@vndv/pi-codegraph@0.1.9
 ```
 
 From GitHub:
@@ -126,12 +124,10 @@ Use CodeGraph. Show files under internal/services and important symbols.
 
 ### 3. Prefer the right tool
 
-Use `codegraph_context` for broad "how does this work?" questions.
+Use `codegraph_explore` for broad "how does this work?" or "how does X reach Y?" questions.
 
 Use `codegraph_node` when you already know the symbol name.
 
-Use `codegraph_trace` for "how does X reach Y?" flow questions.
-
 Use `codegraph_search` for declarations and symbols, not arbitrary text or constant values.
 
 ---
@@ -163,7 +159,7 @@ That means another developer only needs the npm package, the `codegraph` CLI, an
 Remove the package using the same source shown by `pi list`:
 
 ```bash
-pi remove npm:@vndv/pi-codegraph@0.1.7
+pi remove npm:@vndv/pi-codegraph@0.1.9
 ```
 
 If you installed from GitHub or a local path, remove that exact entry instead:

package/extensions/codegraph.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
@@ -34,17 +35,6 @@ const ToolDefinitions = [
       projectPath: OptionalProjectPath,
     }),
   },
-  {
-    name: "codegraph_context",
-    label: "CodeGraph Context",
-    description: "Primary tool for architecture, feature, bug-context, or how-does-X-work questions.",
-    parameters: Type.Object({
-      task: Type.String({ description: "Task, question, or code area to understand." }),
-      maxNodes: Type.Optional(Type.Number({ default: 20 })),
-      includeCode: Type.Optional(Type.Boolean({ default: true })),
-      projectPath: OptionalProjectPath,
-    }),
-  },
   {
     name: "codegraph_callers",
     label: "CodeGraph Callers",
@@ -120,16 +110,6 @@ const ToolDefinitions = [
       projectPath: OptionalProjectPath,
     }),
   },
-  {
-    name: "codegraph_trace",
-    label: "CodeGraph Trace",
-    description: "Trace the call path between two symbols.",
-    parameters: Type.Object({
-      from: Type.String(),
-      to: Type.String(),
-      projectPath: OptionalProjectPath,
-    }),
-  },
 ] as const;
 
 type ToolName = (typeof ToolDefinitions)[number]["name"];
@@ -140,7 +120,8 @@ type PendingJsonRpcRequests = Map<number, {
   reject: (error: Error) => void;
 }>;
 
-const MaxDiagnosticLength = 1000;
+export const MaxDiagnosticLength = 1000;
+export const SessionTimeoutMs = 20_000;
 
 export const codegraphToolNames = ToolDefinitions.map((tool) => tool.name);
 
@@ -156,11 +137,49 @@ export async function withCodeGraphMcp<T>(
     stdio: ["pipe", "pipe", "pipe"],
   });
 
-  return runJsonRpcSession(child, cwd, signal, fn);
+  const session = runJsonRpcSession(child, cwd, signal, fn);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const onAbortClearTimer = () => clearTimeout(timer);
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      if (!child.killed) child.kill();
+      reject(new Error(
+        "CodeGraph MCP session timed out after " + SessionTimeoutMs + "ms. " +
+        'Try running "codegraph unlock" in the project directory, then restart pi.'
+      ));
+    }, SessionTimeoutMs);
+    signal?.addEventListener("abort", onAbortClearTimer, { once: true });
+  });
+
+  session.catch(() => {});
+  timeout.catch(() => {});
+  return Promise.race([session, timeout]).finally(() => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbortClearTimer);
+  });
+}
+
+export function normalizeWindowsPath(inputPath: string): string {
+  let normalized = inputPath.trim();
+
+  if (process.platform !== "win32") return normalized;
+
+  const wslMatch = normalized.match(/^\/mnt\/([a-zA-Z])\/(.*)$/);
+  if (wslMatch) {
+    normalized = wslMatch[1].toUpperCase() + ":\\" + wslMatch[2].replace(/\//g, "\\");
+  }
+
+  const gitBashMatch = normalized.match(/^\/([a-zA-Z])\/(.*)$/);
+  if (gitBashMatch) {
+    normalized = gitBashMatch[1].toUpperCase() + ":\\" + gitBashMatch[2].replace(/\//g, "\\");
+  }
+
+  return normalized;
 }
 
 export async function resolveProjectCwd(projectPath: string | undefined): Promise<string> {
-  const cwd = projectPath || process.cwd();
+  const cwd = normalizeWindowsPath(projectPath || process.cwd());
 
   if (!path.isAbsolute(cwd)) {
     throw new Error("CodeGraph projectPath must be an absolute path.");
@@ -180,6 +199,34 @@ export async function resolveProjectCwd(projectPath: string | undefined): Promis
   return cwd;
 }
 
+export function normalizeFilesPath(inputPath?: string, projectCwd?: string): string | undefined {
+  if (typeof inputPath !== "string" || inputPath.trim() === "") return undefined;
+
+  const trimmed = inputPath.trim();
+  let expanded = trimmed;
+  if (expanded === "~" || expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+    expanded = path.join(os.homedir(), expanded.slice(1));
+  }
+
+  if (projectCwd && path.isAbsolute(expanded)) {
+    const relative = path.relative(projectCwd, expanded);
+    if (relative === "") return undefined;
+    if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+      return relative.split(path.sep).join("/");
+    }
+  }
+
+  return trimmed.split(path.sep).join("/");
+}
+
+const EmptyFilesMarker = "No files found matching the criteria.";
+
+export function annotateFilesResult(resultText: string, originalPath?: string): string {
+  if (!originalPath || !resultText.includes(EmptyFilesMarker)) return resultText;
+
+  return `${resultText}\n\nHint: codegraph_files interprets "path" as a root-relative POSIX prefix (e.g. "src/components"). The filter "${originalPath}" did not match any indexed path.`;
+}
+
 export function sanitizeDiagnostic(value: string): string {
   const withoutAnsi = value.replace(/\u001b\[[0-9;]*m/g, "");
   const redacted = withoutAnsi
@@ -332,17 +379,42 @@ async function initializeJsonRpcSession(
   sendNotification("initialized", {});
 }
 
+async function prepareToolArguments(
+  name: ToolName,
+  params: ToolParams,
+): Promise<{ args: ToolParams; originalFilesPath?: string }> {
+  if (name !== "codegraph_files") return { args: params };
+
+  const projectPath = typeof params.projectPath === "string" ? params.projectPath : undefined;
+  const projectCwd = await resolveProjectCwd(projectPath);
+  const originalFilesPath = typeof params.path === "string" ? params.path : undefined;
+  const normalizedPath = normalizeFilesPath(originalFilesPath, projectCwd);
+
+  const args: ToolParams = { ...params };
+  if (normalizedPath === undefined) {
+    delete args.path;
+  } else {
+    args.path = normalizedPath;
+  }
+
+  return { args, originalFilesPath };
+}
+
 export async function callCodeGraphTool(
   name: ToolName,
   params: ToolParams,
   signal?: AbortSignal,
 ): Promise<string> {
-  const projectPath = typeof params.projectPath === "string" ? params.projectPath : undefined;
-  const result = await withCodeGraphMcp(projectPath, signal, (request) =>
-    request("tools/call", {
-      name,
-      arguments: params || {},
-    })
+  const { args, originalFilesPath } = await prepareToolArguments(name, params);
+
+  const result = await withCodeGraphMcp(
+    typeof args.projectPath === "string" ? args.projectPath : undefined,
+    signal,
+    (request) =>
+      request("tools/call", {
+        name,
+        arguments: args,
+      }),
   );
 
   const text = (result?.content || [])
@@ -351,7 +423,8 @@ export async function callCodeGraphTool(
     .join("\n");
 
   if (result?.isError) throw new Error(text || "CodeGraph tool failed.");
-  return text || JSON.stringify(result);
+  const finalText = text || JSON.stringify(result);
+  return name === "codegraph_files" ? annotateFilesResult(finalText, originalFilesPath) : finalText;
 }
 
 export default function codegraphExtension(pi: ExtensionAPI): void {
@@ -359,8 +432,8 @@ export default function codegraphExtension(pi: ExtensionAPI): void {
     const guidance = [
       "CodeGraph tools are available as codegraph_* Pi tools.",
       "For architecture, flow, where-is-symbol, impact, and codebase navigation questions, use CodeGraph tools directly before grep/read.",
-      "Use codegraph_context first for broad questions, codegraph_search for symbol-name lookup, codegraph_files for project structure, codegraph_node for a known symbol, and codegraph_trace for call paths.",
-      "If codegraph_search returns no exact result, try codegraph_context or codegraph_files/codegraph_explore before falling back to grep/read; CodeGraph symbol search may miss literal constants or generated names that still exist in source text.",
+      "Use codegraph_explore first for broad questions, codegraph_search for symbol-name lookup, codegraph_files for project structure, codegraph_node for a known symbol, and codegraph_callers for impact/flow analysis.",
+      "If codegraph_search returns no exact result, try codegraph_explore or codegraph_files/codegraph_node before falling back to grep/read; CodeGraph symbol search may miss literal constants or generated names that still exist in source text.",
       "Only use grep/read after CodeGraph is insufficient or when the user asks for literal text matching.",
     ].join("\n");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vndv/pi-codegraph",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CodeGraph tools for Pi Agent.",
   "license": "MIT",
   "type": "module",
@@ -59,9 +59,9 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@colbymchenry/codegraph": "^0.9.7",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@types/node": "^25.9.1",
+    "@colbymchenry/codegraph": "^1.0.1",
+    "@earendil-works/pi-coding-agent": "^0.79.6",
+    "@types/node": "^26.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"
   }