@henryqw/pi-codegraph 0.2.0 → 0.2.2

package/README.md

@@ -1,4 +1,4 @@
-# @henryqw/pi-codegraph
+# `@henryqw/pi-codegraph`
 
 Get a separate [CodeGraph](https://github.com/colbymchenry/codegraph) index when you start Pi in a new Git worktree. Use CodeGraph's explore tool through pi-mcp-adapter from Pi.
 
@@ -10,7 +10,15 @@ pi install npm:pi-mcp-adapter
 pi install npm:@henryqw/pi-codegraph
 ```
 
-Requires `codegraph` CLI on `PATH`, and [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter).
+Requires the `codegraph` CLI on `PATH` and [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter).
+
+## Works with
+
+| Package | Relationship | Purpose |
+| --- | --- | --- |
+| [`@colbymchenry/codegraph`](https://github.com/colbymchenry/codegraph) | Required | Builds the indexes and serves CodeGraph tools over MCP. |
+| [`@henryqw/pi-footer`](https://pi.henry.wang/extensions/pi-footer) | Improves | Shows a compact CodeGraph index badge and direct tool activity when loaded. |
+| [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) | Required | Connects the MCP server to Pi. |
 
 ## Use
 
@@ -20,7 +28,15 @@ From the primary checkout, initialize CodeGraph once:
 codegraph init --yes
 ```
 
-Then launch `pi` in a linked worktree. The adapter server is `henryqw_pi-codegraph__codegraph`. It discovers tools lazily; other CodeGraph tools remain available through `mcp`.
+Then launch `pi` in a linked worktree. When the primary checkout has an index, pi-codegraph initializes a separate worktree index and exposes CodeGraph tools through pi-mcp-adapter.
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `codegraph_explore` | tool | Lets agents explore the indexed code through CodeGraph. |
+| `mcp` | tool | Lets agents call other CodeGraph tools through the `henryqw_pi-codegraph__codegraph` adapter server. |
+| CodeGraph setup status | ui | Shows users setup progress and errors, and confirms a new worktree index is ready. |
+
+The adapter discovers tools lazily.
 
 ## Flow
 
@@ -28,17 +44,22 @@ Then launch `pi` in a linked worktree. The adapter server is `henryqw_pi-codegra
 - Initialization happens when Pi launches, not when Git creates the worktree.
 - Each linked worktree keeps its own `.codegraph`; databases are never copied or shared between branches.
 - Non-Git directories and repositories without a primary index are not initialized.
-- When loaded, the extension reports whether the local index is `indexed`, `missing`, or `indexing…` through Pi's status channel. The `pi-footer` extension places a compact `CG` badge first on its third line and temporarily shows `● CG` during direct CodeGraph tool calls.
+- The extension reports `checking index…` and `indexing…` during setup, `indexed` when a database file exists, `missing` when no index was built, `prerequisites missing` when setup was skipped, and `setup failed` on an error. `indexed` does not guarantee database health.
+- If `pi-footer` is also loaded, it places a compact `CG` badge first on its third line: `✓ CG` indexed, `○ CG` missing, `◐ CG` checking or indexing, `! CG` setup problem, or `? CG` unknown state. It temporarily shows `● CG` only during direct `codegraph_explore` calls or `codegraph_*` calls through this package's MCP server, not for every MCP call.
 
 ## State and storage
 
-The extension relies on CodeGraph's own state — each worktree maintains its own `.codegraph/codegraph.db`. The extension never copies, shares, or modifies this database. Existing indexes are left alone; CodeGraph owns synchronization when its MCP server runs.
+The extension relies on CodeGraph's own state — each worktree maintains its own `.codegraph/codegraph.db`. The extension never copies or shares the database and does not write it directly: it delegates creation to `codegraph init --yes <worktree-root>`. Existing indexes are left alone; CodeGraph owns synchronization when its MCP server runs.
 
 ## Limits and recovery
 
 At startup, the extension checks for a loaded adapter and runs `codegraph --version`. If either prerequisite is unavailable, Pi warns, reports `prerequisites missing`, and skips setup. Restart Pi or run `/reload` after fixing prerequisites.
 
-Initialization uses an exclusive `pi-codegraph-init.lock` in the worktree's Git metadata. Failed or interrupted initialization keeps the lock so a partial database is not accepted. To recover: remove the lock directory with `rmdir` only after `codegraph index` succeeds, then run `/reload`.
+Initialization uses an exclusive `pi-codegraph-init.lock` in the worktree's Git metadata. Failed or interrupted initialization keeps the lock so a partial database is not accepted. To recover, first confirm no initializer is running, then run `codegraph index` **from the affected worktree root** (not the primary checkout or a nested directory). Only after it succeeds, remove the lock directory with `rmdir` using the path in the error message, then run `/reload`:
+
+```bash
+cd /path/to/affected-worktree-root && codegraph index && rmdir /path/to/pi-codegraph-init.lock
+```
 
 The package never installs prerequisites automatically. The `codegraph` executable must be available to both Pi and its MCP child process. Only Git worktree-root indexes using the default `.codegraph` directory are supported; nested monorepo indexes are not initialized automatically. The primary checkout must remain indexed for automatic opt-in detection.
 

package/extensions/codegraph.ts

@@ -74,7 +74,6 @@ async function initialize(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void
 			}
 		}
 		let attempted = false;
-		let succeeded = false;
 		try {
 			if (await hasIndex(root)) {
 				indexed = true;
@@ -91,7 +90,6 @@ async function initialize(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void
 			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;
 			indexed = true;
 			if (ctx.hasUI) {
 				ctx.ui.setWidget(WIDGET_KEY, ["pi-codegraph: index ready"]);
@@ -104,7 +102,7 @@ async function initialize(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void
 			throw error;
 		} finally {
 			// A failed or interrupted init stays locked; never accept its partial DB on reload.
-			if (!attempted || succeeded) await rmdir(lock);
+			if (!attempted || indexed) await rmdir(lock);
 		}
 	} finally {
 		ctx.ui.setStatus("pi-codegraph", indexed ? "pi-codegraph: indexed" : "pi-codegraph: missing");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-codegraph",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Initialize CodeGraph indexes in opted-in Git worktrees and expose CodeGraph through pi-mcp-adapter.",
   "keywords": [
     "pi-package",