@vndv/pi-codegraph 0.1.0 → 0.1.2

package/README.md

@@ -1,42 +1,65 @@
 # pi-codegraph
+### CodeGraph tools for pi
 
-Pi package that adds CodeGraph tools to Pi Agent.
+Install · Usage · How it works
 
-## Requirements
+Ask pi structural questions about your codebase without falling back to slow grep/read loops.
 
-Node.js 22 LTS is recommended. CodeGraph blocks Node.js 25 because of a V8 WASM JIT bug in tree-sitter grammar compilation.
+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.
 
-Pi provides the package extension runtime and core libraries. This package declares `@earendil-works/pi-coding-agent` and `typebox` as peer dependencies, as required by Pi package loading.
+---
 
-CodeGraph must already be installed and available on `PATH`:
+## Quick start
 
 ```bash
 npm install -g @colbymchenry/codegraph
+cd /path/to/project
+codegraph init -i
+pi install npm:@vndv/pi-codegraph@0.1.1
+pi
 ```
 
-Projects must be indexed before Pi can query them:
+Then ask:
 
-```bash
-cd /path/to/project
-codegraph init -i
+```text
+Use CodeGraph. Show project structure and main entry points.
 ```
 
+---
+
+## What's included
+
+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 |
+
+---
+
 ## Install
 
-From GitHub:
+From npm:
 
 ```bash
-pi install https://github.com/vndv/pi-codegraph
+pi install npm:@vndv/pi-codegraph@0.1.1
 ```
 
-From npm:
+From GitHub:
 
 ```bash
-pi install npm:@vndv/pi-codegraph@0.1.0
+pi install https://github.com/vndv/pi-codegraph
 ```
 
-This works only after `@vndv/pi-codegraph@0.1.0` has been published to npm. If npm returns `404 Not Found`, use the GitHub or local development install until the first npm publish is complete.
-
 Local development install:
 
 ```bash
@@ -45,62 +68,141 @@ cd pi-codegraph
 pi install "$(pwd)"
 ```
 
-Verify Pi sees the package:
+Then `/reload` in pi, or restart pi.
+
+Verify pi sees the package:
 
 ```bash
 pi list
 ```
 
-## Uninstall
+---
 
-Remove the package using the same source shown by `pi list`:
+## Requirements
+
+Node.js 22 LTS is recommended. CodeGraph blocks Node.js 25 because that Node line has a V8 WASM JIT issue that can crash while compiling tree-sitter grammars.
+
+CodeGraph must be installed and available on `PATH`:
 
 ```bash
-pi remove https://github.com/vndv/pi-codegraph
+npm install -g @colbymchenry/codegraph
 ```
 
-If you installed from npm or a local path, remove that exact entry instead:
+Each project must be indexed before pi can query it:
 
 ```bash
-pi remove npm:@vndv/pi-codegraph@0.1.0
-pi remove /path/to/pi-codegraph
+cd /path/to/project
+codegraph init -i
 ```
 
-Then start Pi inside an indexed project:
+This package declares `@earendil-works/pi-coding-agent` and `typebox` as peer dependencies because pi provides the extension runtime.
+
+---
+
+## Usage
+
+### 1. Start pi inside an indexed project
 
 ```bash
 cd /path/to/project
 pi
 ```
 
-Example prompt:
+### 2. Ask structural questions
+
+Good prompts:
 
 ```text
-Use CodeGraph. Show project structure and main entry points.
+Use CodeGraph. Explain how authentication reaches the request handler.
+Use CodeGraph. What calls PlanBoostSession?
+Use CodeGraph. What would break if I change UserRepository?
+Use CodeGraph. Show files under internal/services and important symbols.
 ```
 
-## Tools
+### 3. Prefer the right tool
+
+Use `codegraph_context` for broad "how does this work?" questions.
+
+Use `codegraph_node` when you already know the symbol name.
+
+Use `codegraph_trace` for "how does X reach Y?" flow questions.
 
-This package registers:
+Use `codegraph_search` for declarations and symbols, not arbitrary text or constant values.
 
-- `codegraph_search`
-- `codegraph_context`
-- `codegraph_callers`
-- `codegraph_callees`
-- `codegraph_impact`
-- `codegraph_explore`
-- `codegraph_node`
-- `codegraph_status`
-- `codegraph_files`
-- `codegraph_trace`
+---
 
-Each tool proxies to:
+## How it works
+
+pi extensions are not MCP configuration files. This package registers native pi tools, and each tool proxies one request to CodeGraph's MCP server internally:
 
 ```bash
 codegraph serve --mcp --path <project>
 ```
 
-For broad code questions, Pi should prefer `codegraph_context`. For known symbols, use `codegraph_node`. Use `codegraph_search` for declaration/symbol lookup, not literal constants or arbitrary text.
+The flow is:
+
+```text
+pi agent
+  -> pi-codegraph extension tool
+  -> local CodeGraph MCP process
+  -> .codegraph/codegraph.db in the current project
+  -> structured result back to pi
+```
+
+That means another developer only needs the npm package, the `codegraph` CLI, and an initialized `.codegraph` index in their project. They do not need to edit pi MCP config.
+
+---
+
+## Uninstall
+
+Remove the package using the same source shown by `pi list`:
+
+```bash
+pi remove npm:@vndv/pi-codegraph@0.1.1
+```
+
+If you installed from GitHub or a local path, remove that exact entry instead:
+
+```bash
+pi remove https://github.com/vndv/pi-codegraph
+pi remove /path/to/pi-codegraph
+```
+
+Then `/reload` in pi, or restart pi.
+
+---
+
+## Troubleshooting
+
+### `codegraph_*` tools are missing
+
+Check that pi installed the package:
+
+```bash
+pi list
+```
+
+Then reload or restart pi.
+
+### CodeGraph says the project is not initialized
+
+Run:
+
+```bash
+cd /path/to/project
+codegraph init -i
+```
+
+### Node.js version is unsupported
+
+Use Node.js 22 LTS:
+
+```bash
+nvm install 22
+nvm use 22
+```
+
+---
 
 ## Development
 
@@ -109,34 +211,64 @@ npm ci
 npm run ci
 ```
 
-## Release
+Install the local checkout into pi:
+
+```bash
+pi install /Users/vndv/Documents/programming/open-source/pi-codegraph
+```
 
-Run the full local package check before publishing:
+Before opening a pull request:
 
 ```bash
 npm run ci
-npm pack --dry-run
 ```
 
-First npm publish:
+---
+
+## Release
+
+The package is published to npm as `@vndv/pi-codegraph`.
+
+Releases are automated with Changesets. Any package update, including README changes shipped to npm, needs a changeset so the release workflow can bump the version and deploy a new npm package.
+
+For every user-facing change, add a changeset in the feature branch:
+
+```bash
+npx changeset
+```
+
+Choose the bump type:
+
+- `patch` for fixes and docs that affect package users
+- `minor` for new tools or behavior
+- `major` for breaking changes
+
+After the PR is merged to `main`, the release workflow opens or updates a `chore: version packages` pull request. That PR contains the version bump and changelog update.
+
+Merge the version PR to publish to npm automatically.
+
+The workflow runs:
 
 ```bash
-npm login
-npm publish --access public
+npm run version-packages
+npm run publish-packages
 ```
 
-Future releases use Changesets:
+`publish-packages` runs `npm publish --access public --provenance`.
+
+The workflow uses npm trusted publishing through GitHub Actions OIDC.
+
+Local release commands are still available when needed:
 
 ```bash
-npx changeset
+npm run ci
 npm run local-release
 ```
 
-GitHub publishing is also supported:
+GitHub Actions needs npm trusted publishing configured for `.github/workflows/publish.yml`.
+
+---
 
-1. Add `NPM_TOKEN` repository secret in GitHub.
-2. Update the package version with Changesets or by editing `package.json`.
-3. Commit and push to `main`.
-4. Create a GitHub release for the version tag.
+## License
 
-The publish workflow runs `npm publish --provenance`.
+MIT

package/extensions/codegraph.ts

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { Static } from "typebox";
@@ -134,6 +136,8 @@ type ToolName = (typeof ToolDefinitions)[number]["name"];
 type ToolParams = Record<string, unknown> & { projectPath?: string };
 type JsonRpcRequest = (method: string, params: Record<string, unknown>) => Promise<any>;
 
+const MaxDiagnosticLength = 1000;
+
 export const codegraphToolNames = ToolDefinitions.map((tool) => tool.name);
 
 export async function withCodeGraphMcp<T>(
@@ -141,7 +145,7 @@ export async function withCodeGraphMcp<T>(
   signal: AbortSignal | undefined,
   fn: (request: JsonRpcRequest) => Promise<T>,
 ): Promise<T> {
-  const cwd = projectPath || process.cwd();
+  const cwd = await resolveProjectCwd(projectPath);
   const child = spawn("codegraph", ["serve", "--mcp", "--path", cwd], {
     cwd,
     env: process.env,
@@ -151,6 +155,39 @@ export async function withCodeGraphMcp<T>(
   return runJsonRpcSession(child, cwd, signal, fn);
 }
 
+export async function resolveProjectCwd(projectPath: string | undefined): Promise<string> {
+  const cwd = projectPath || process.cwd();
+
+  if (!path.isAbsolute(cwd)) {
+    throw new Error("CodeGraph projectPath must be an absolute path.");
+  }
+
+  let info;
+  try {
+    info = await stat(cwd);
+  } catch {
+    throw new Error("CodeGraph projectPath does not exist or is not accessible.");
+  }
+
+  if (!info.isDirectory()) {
+    throw new Error("CodeGraph projectPath must point to a directory.");
+  }
+
+  return cwd;
+}
+
+export function sanitizeDiagnostic(value: string): string {
+  const withoutAnsi = value.replace(/\u001b\[[0-9;]*m/g, "");
+  const redacted = withoutAnsi
+    .replace(/\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|APIKEY|AUTH)[A-Z0-9_]*=)\S+/gi, "$1[redacted]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+    .replace(/--(?:token|secret|password|api-key|apikey|otp)(?:=|\s+)\S+/gi, "--[redacted]");
+
+  return redacted.length > MaxDiagnosticLength
+    ? `${redacted.slice(0, MaxDiagnosticLength)}...`
+    : redacted;
+}
+
 async function runJsonRpcSession<T>(
   child: ChildProcessWithoutNullStreams,
   cwd: string,
@@ -211,7 +248,8 @@ async function runJsonRpcSession<T>(
 
   child.on("exit", (code) => {
     if (pending.size === 0) return;
-    const msg = stderr.trim() || `CodeGraph MCP process exited with code ${code}`;
+    const diagnostic = sanitizeDiagnostic(stderr.trim());
+    const msg = diagnostic || `CodeGraph MCP process exited with code ${code}`;
     for (const entry of pending.values()) entry.reject(new Error(msg));
     pending.clear();
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vndv/pi-codegraph",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CodeGraph tools for Pi Agent.",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,7 @@
   "homepage": "https://github.com/vndv/pi-codegraph#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vndv/pi-codegraph.git"
+    "url": "https://github.com/vndv/pi-codegraph"
   },
   "bugs": {
     "url": "https://github.com/vndv/pi-codegraph/issues"
@@ -37,10 +37,12 @@
   "scripts": {
     "ci": "npm run typecheck && npm test && npm pack --dry-run",
     "local-release": "changeset version && changeset publish",
+    "publish-packages": "npm publish --access public --provenance",
     "prepack": "npm run typecheck && npm test",
     "prepublishOnly": "npm run ci",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts"
   },
   "engines": {
     "node": ">=22.19.0 <25"