@henryqw/pi-codegraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+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,57 @@
+# pi-codegraph
+
+Get a separate CodeGraph index when you start Pi in a new Git worktree. The package also supplies a lazy CodeGraph MCP server through **pi-mcp-adapter**, including the explore tool. It does not implement an MCP client or edit your MCP configuration.
+
+## Install
+
+Requirements: Pi 0.87.x, Node.js 22.19 or newer, Git, the `codegraph` CLI on `PATH`, and **pi-mcp-adapter 2.36.x or newer within 2.x installed and enabled in Pi**.
+
+```sh
+npm install -g @colbymchenry/codegraph
+pi install npm:pi-mcp-adapter
+pi install npm:@henryqw/pi-codegraph
+```
+
+Installing an npm peer dependency alone does not enable the adapter's Pi extension. Install both packages with Pi, then restart Pi or run `/reload`.
+
+Opt a repository in by building its first index in the **primary checkout**:
+
+```sh
+cd /path/to/primary-checkout
+codegraph init --yes
+```
+
+After that, launch `pi` in any linked worktree. The extension initializes when Pi starts, not when Git creates the worktree.
+
+## What happens
+
+- A missing worktree index is built only when the primary checkout already has `.codegraph/codegraph.db`.
+- Launching from a subdirectory still initializes the worktree root. Each worktree keeps its own `.codegraph`; databases are never copied or shared between branches.
+- Existing indexes are left alone. CodeGraph owns synchronization when its MCP server runs.
+- Non-Git directories and repositories without a primary index are not initialized. A first index always requires your explicit `codegraph init`.
+- Pi shows initialization or waiting status. Initialization has a ten-minute timeout; concurrent sessions wait up to five minutes for the same worktree's initializer.
+- The adapter server is `henryqw_pi-codegraph__codegraph`. It discovers tools lazily and exposes `codegraph_explore` directly without an extra package prefix. Other CodeGraph tools remain available through `mcp`. On a cold connection, CodeGraph may require an explicit `projectPath`; pass the worktree root when its tool schema requests it.
+
+The MCP definition uses the adapter's native `pi.mcp` package discovery. Install this **package**, not just its extension `.ts` file. Loading a single file with `pi -e` does not discover its MCP manifest. When using the whole local harness as a Pi package, its server is instead `henryqw_pi-harness__codegraph`; do not install both forms together.
+
+## Failures and limits
+
+At startup, the extension checks for a loaded adapter and runs `codegraph --version`, even when an index already exists. If either prerequisite is unavailable, Pi warns with the installation command for each missing prerequisite and skips setup without creating a lock. Headless sessions print the same warning to stderr. A broken or timed-out CLI check includes its failure details; if CodeGraph is already installed, check Pi's `PATH`. Restart Pi or run `/reload` after fixing the prerequisites.
+
+The `codegraph` executable must be available to both Pi and its MCP child process. The package never installs either prerequisite automatically.
+
+Initialization uses an exclusive `pi-codegraph-init.lock` directory inside the worktree's Git metadata. Failed or interrupted initialization keeps this lock so a partial database is not accepted on the next launch. Errors include the exact worktree and lock paths. To recover:
+
+1. Confirm no initializer is still running.
+2. Inspect the failed index and run `codegraph index` in that worktree.
+3. Only after indexing succeeds, remove the reported empty lock directory with `rmdir`, then run `/reload`.
+
+Do not remove an active lock. Existing indexes without an extension-owned lock are not health-checked. The lock coordinates this extension's sessions, not manual `codegraph init` commands or unrelated clients; avoid running those during initialization. A setup error does not remove files or change adapter configuration.
+
+Only Git worktree-root indexes and the default `.codegraph` directory are supported. An alternate `CODEGRAPH_DIR` is rejected. Nested monorepo indexes are not initialized automatically. The primary checkout must remain present and indexed for automatic opt-in detection.
+
+The extension does not add ignore rules, delete indexes, or prune worktrees. Add `.codegraph/` to your own ignore rules if needed. Pi Subagent and Pi Orchestrator conservatively treat ignored files as retained work: an indexed worker worktree may require manual cleanup. This package does not weaken those data-loss safeguards.
+
+## Existing MCP configuration
+
+If you already configured a `codegraph` server manually, remove that entry after confirming the package server works. Keeping both can expose duplicate servers/tools. The extension does not change your MCP configuration.

package/extensions/codegraph.ts

@@ -0,0 +1,113 @@
+import { mkdir, rmdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const LOCK_WAIT_MS = 5 * 60_000;
+const INIT_TIMEOUT_MS = 10 * 60_000;
+
+async function hasIndex(root: string): Promise<boolean> {
+	try {
+		return (await stat(join(root, ".codegraph", "codegraph.db"))).isFile();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function git(pi: ExtensionAPI, cwd: string, args: string[]): Promise<string> {
+	const result = await pi.exec("git", args, { cwd, timeout: 10_000 });
+	if (result.code !== 0 || result.killed) {
+		throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+	}
+	return result.stdout.replace(/\r?\n$/, "");
+}
+
+async function initialize(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	const prerequisites: string[] = [];
+	if (!pi.getAllTools().some((tool) => tool.name === "mcp")) {
+		prerequisites.push("Install and enable pi-mcp-adapter >=2.36.0: pi install npm:pi-mcp-adapter");
+	}
+	const version = await pi.exec("codegraph", ["--version"], { cwd: ctx.cwd, timeout: 10_000 });
+	if (version.code !== 0 || version.killed) {
+		const detail = version.killed ? "timed out or killed" : version.stderr.trim().slice(-1000) || `exit ${version.code}`;
+		prerequisites.push(`codegraph --version failed (${detail}). Install CodeGraph: npm install -g @colbymchenry/codegraph. If already installed, check that codegraph runs on Pi's PATH.`);
+	}
+	if (prerequisites.length) {
+		const message = `pi-codegraph: setup skipped.\n${prerequisites.join("\n")}\nThen restart Pi or /reload.`;
+		ctx.ui.setStatus("pi-codegraph", "CodeGraph: prerequisites missing");
+		if (ctx.hasUI) ctx.ui.notify(message, "warning");
+		else console.warn(message);
+		return;
+	}
+	ctx.ui.setStatus("pi-codegraph", undefined);
+	const rootResult = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: ctx.cwd, timeout: 10_000 });
+	if (rootResult.code !== 0 || rootResult.killed) {
+		if (!rootResult.killed && rootResult.stderr.includes("not a git repository")) return;
+		throw new Error(`Cannot locate Git worktree: ${rootResult.stderr.trim() || `exit ${rootResult.code}`}`);
+	}
+	const root = rootResult.stdout.replace(/\r?\n$/, "");
+	if (!root) throw new Error("Git returned an empty worktree root.");
+	if (process.env.CODEGRAPH_DIR && process.env.CODEGRAPH_DIR !== ".codegraph") {
+		throw new Error("pi-codegraph requires the default CODEGRAPH_DIR (.codegraph). Unset CODEGRAPH_DIR before launching Pi.");
+	}
+	const gitDir = await git(pi, root, ["rev-parse", "--absolute-git-dir"]);
+	if (!gitDir) throw new Error("Git returned an empty metadata directory.");
+	const lock = join(gitDir, "pi-codegraph-init.lock");
+	// Check the lock before the database: an in-progress/failed init can leave a partial DB.
+	const recovery = `Inspect CodeGraph in ${root}. If no initializer is running, run codegraph index in that directory, then remove ${lock} with rmdir and /reload.`;
+	const deadline = Date.now() + LOCK_WAIT_MS;
+	ctx.ui.setStatus("pi-codegraph", "CodeGraph: checking index…");
+	try {
+		while (true) {
+			try {
+				await mkdir(lock);
+				break;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+				if (Date.now() >= deadline) throw new Error(`Timed out waiting for CodeGraph initialization. ${recovery}`);
+				ctx.ui.setStatus("pi-codegraph", "CodeGraph: waiting for initialization…");
+				await delay(250);
+			}
+		}
+		let attempted = false;
+		let succeeded = false;
+		try {
+			if (await hasIndex(root)) return;
+			const worktrees = await git(pi, root, ["worktree", "list", "--porcelain", "-z"]);
+			const first = worktrees.split("\0", 1)[0];
+			if (!first?.startsWith("worktree ")) throw new Error("Git returned an invalid primary worktree.");
+			const primary = first.slice("worktree ".length);
+			if (!primary || primary === root || !(await hasIndex(primary))) return;
+			ctx.ui.setStatus("pi-codegraph", "CodeGraph: building worktree index…");
+			attempted = true;
+			const result = await pi.exec("codegraph", ["init", "--yes", root], { cwd: root, timeout: INIT_TIMEOUT_MS });
+			if (result.code !== 0 || result.killed || !(await hasIndex(root))) {
+				throw new Error(`CodeGraph init failed (${result.killed ? "timed out or killed" : `exit ${result.code}`}): ${(result.stderr || result.stdout).trim().slice(-2000)}`);
+			}
+			succeeded = true;
+			ctx.ui.notify("CodeGraph worktree index ready.", "info");
+		} catch (error) {
+			if (attempted) throw new Error(`${error instanceof Error ? error.message : String(error)}\n${recovery}`, { cause: error });
+			throw error;
+		} finally {
+			// A failed or interrupted init stays locked; never accept its partial DB on reload.
+			if (!attempted || succeeded) await rmdir(lock);
+		}
+	} finally {
+		ctx.ui.setStatus("pi-codegraph", undefined);
+	}
+}
+
+export default function codegraphExtension(pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			await initialize(pi, ctx);
+		} catch (error) {
+			const message = `pi-codegraph: ${error instanceof Error ? error.message : String(error)}`;
+			ctx.ui.setStatus("pi-codegraph", "CodeGraph: setup failed");
+			if (ctx.hasUI) ctx.ui.notify(message, "error");
+			else throw new Error(message, { cause: error });
+		}
+	});
+}

package/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp"],
+      "lifecycle": "lazy",
+      "toolPrefix": "none",
+      "directTools": ["codegraph_explore"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@henryqw/pi-codegraph",
+  "version": "0.1.0",
+  "description": "Initialize CodeGraph indexes in opted-in Git worktrees and expose CodeGraph through pi-mcp-adapter.",
+  "keywords": ["pi-package", "pi", "codegraph", "mcp", "worktree"],
+  "type": "module",
+  "engines": { "node": ">=22.19.0" },
+  "license": "MIT",
+  "files": ["LICENSE", "extensions", "mcp.json", "README.md"],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2024 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/codegraph.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0",
+    "pi-mcp-adapter": ">=2.36.0 <3.0.0"
+  },
+  "devDependencies": { "@earendil-works/pi-coding-agent": "0.87.0" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-harness.git",
+    "directory": "extensions/pi-codegraph"
+  },
+  "bugs": { "url": "https://github.com/HenryQW/pi-harness/issues" },
+  "publishConfig": { "access": "public" },
+  "pi": {
+    "extensions": ["./extensions/codegraph.ts"],
+    "mcp": "./mcp.json"
+  }
+}