pi-graphnav 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sorin Albu-Irimies
+
+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

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# pi-graphnav
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/pi-graphnav.svg)](https://www.npmjs.com/package/pi-graphnav)
+[![CI](https://github.com/sorinirimies/pi-graphnav/actions/workflows/ci.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Audit](https://github.com/sorinirimies/pi-graphnav/actions/workflows/security.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/security.yml)
+[![Fuzz](https://github.com/sorinirimies/pi-graphnav/actions/workflows/fuzz.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/fuzz.yml)
+
+CodeGraph-first code navigation for pi: the agent understands code through
+[CodeGraph](https://github.com/colbymchenry/codegraph)'s symbol graph instead of grepping and
+reading file after file, without being told to.
+
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension.
+
+## What it does
+
+* **Keeps the index current.** At session start, in the background: `codegraph init` for a git repo
+  without an index, a full `codegraph index` when the index is stale or was built by another
+  CodeGraph version, `codegraph sync` for pending changes. An index a killed run left half-built
+  is rebuilt (unless another process is indexing right now), and a failure on a stale lock gets
+  `codegraph unlock` and one more try. While pi runs, the server's file watcher follows your edits.
+* **The `codegraph_*` tools** (`explore`, `search`, `node`, `callers`, `callees`, `impact`,
+  `files`, `status`) on one long-lived `codegraph serve --mcp` per project: no process start per
+  call, and the watcher stays alive. Resilient, with
+  [arrow-resilience-kit](https://www.npmjs.com/package/arrow-resilience-kit): a server that dies
+  under a call is restarted and the call retried once; after 3 failed calls in a row CodeGraph
+  counts as unavailable for a minute, so calls fail fast and the gate stops sending the agent to
+  it (status line: `codegraph: unavailable`).
+* **Steers symbol searches to CodeGraph.** `rg parseConfig`, `grep -rn UserService src`,
+  `git grep`, `ag`, `ack` and pi's `grep` tool with a symbol-like pattern are blocked once with
+  the CodeGraph call that answers it (`enforce`), or run with that hint appended (`nudge`).
+  Running the same command again is allowed: CodeGraph cannot answer everything. Searches for
+  phrases, string literals or in docs and config (`*.md`, `--type yaml`, …) are never touched,
+  nor symbols already looked up with CodeGraph. Searches a codemode script makes with literal
+  `tools.bash({ command })` / `tools.grep({ pattern })` are gated the same way.
+* **Nudges file-name lookups.** `fd UserService`, `find . -name '*ParseConfig*'` and pi's `find`
+  tool with a camelCase or snake_case name run, with a hint to `codegraph_search` (never blocked).
+* **Hints after blind reading.** Reading several source files before any CodeGraph call adds
+  one hint to use `codegraph_explore`; reading a whole source file over 400 lines adds one to
+  fetch just the symbol with `codegraph_node`.
+* **Shows whether it helps.** `/codegraph status` counts blocked searches, how many the agent
+  answered with CodeGraph and how many it re-ran instead.
+* **Prompt guidance** that stays the same every turn, so the prompt cache survives.
+
+Needs the CodeGraph CLI: `npm i -g @colbymchenry/codegraph`. The project is the nearest
+directory with `.codegraph/`, else the git work tree; never your home directory.
+
+## Demos
+
+A repo without an index: indexed in the background, then a symbol `rg` is blocked and the
+answer comes from `codegraph_search` and `codegraph_callers`.
+
+![Overview: background indexing, a blocked rg, CodeGraph answers](examples/vhs/generated/overview.gif)
+
+`nudge` mode: the search runs, and its output points at CodeGraph.
+
+![Nudge mode: rg runs and its output carries the CodeGraph hint](examples/vhs/generated/nudge.gif)
+
+The `/codegraph` command: status, mode, off/on, sync.
+
+![The /codegraph command](examples/vhs/generated/commands.gif)
+
+Recorded with [VHS](https://github.com/charmbracelet/vhs) against a throw-away sample project and a
+scripted local model (`just vhs`, `scripts/vhs.nu`, `examples/vhs/`): a real pi with only this plugin.
+
+## Install
+
+```bash
+pi install npm:pi-graphnav
+```
+
+## Use
+
+| Command | |
+|---|---|
+| `/codegraph` or `/codegraph status` | project, index state, mode, blocked/nudged counts |
+| `/codegraph [on\|off]` | switch it all (remembered across sessions) |
+| `/codegraph mode <mode>` | symbol searches: `enforce` (default), `nudge` or `off` |
+| `/codegraph sync` | sync the index with changed files |
+| `/codegraph reindex` | rebuild the index from scratch |
+| `/codegraph init` | create the index (for a directory that is not a git repo) |
+
+Settings live in `<pi agent dir>/codegraph.json` (`PI_CODING_AGENT_DIR`, else `~/.pi/agent`):
+
+| Key | Default | |
+|---|---|---|
+| `enabled` | `true` | master switch |
+| `showStatus` | `true` | status line entry |
+| `mode` | `"enforce"` | `enforce`, `nudge` or `off` |
+| `autoInit` | `true` | init a git repo that has no index |
+| `autoSync` | `true` | sync or rebuild a stale index at session start |
+| `watch` | `true` | keep the server's file watcher running |
+| `readHintAfter` | `3` | source files read before the CodeGraph hint (`0`: never) |
+| `timeoutMs` | `30000` | per-call timeout of the CodeGraph server |
+
+A project can override `enabled`, `mode`, `autoInit`, `autoSync` and `readHintAfter` for itself in
+`<project>/.pi/codegraph.json` (commit it to share), e.g. `{ "mode": "nudge" }` for a repo full of
+generated code. A `/codegraph` command still wins for the session.
+
+Replaces `@vndv/pi-codegraph` (same tool names): uninstall that one first.
+
+## Development
+
+```bash
+bun install
+just check   # typecheck + tests (95% coverage gate) + pack check + nu script tests
+just --list  # everything else: fuzz, audit, release, remotes
+```
+
+Layout:
+
+| Path | What |
+|---|---|
+| `extensions/graphnav.ts` | wiring: hooks, tools, the command, the status line |
+| `extensions/core/gate.ts` | spotting symbol searches in shell commands; the gate decision |
+| `extensions/core/project.ts` | project root, `codegraph status -j`, what keeps the index current |
+| `extensions/core/mcp.ts` | the long-lived `codegraph serve --mcp` client |
+| `extensions/core/resilience.ts` | circuit breaker and crash retry (arrow-resilience-kit) |
+| `extensions/core/tools.ts` | tool definitions and prompt guidelines |
+| `extensions/core/config.ts`, `extensions/command/parse.ts` | settings, `/codegraph` parsing |
+| `tests/` | `bun test`: one file per module, `extension` (hooks), `fuzz` (randomised properties) |
+| `scripts/` | Nushell only, each with a test in `scripts/tests/` |
+| `examples/vhs/` | demo tapes, the scripted model, the rendered GIFs |
+| `.github/`, `.gitea/` | CI, release, nightlies on both hosts |
+
+Releases: `just release patch` bumps `package.json`, regenerates `CHANGELOG.md` with git-cliff, tags and
+pushes; the Release workflow publishes to npm (secret `NPM_TOKEN`).
+
+## License
+
+MIT

package/extensions/command/parse.ts

@@ -0,0 +1,75 @@
+/** `/codegraph ...`: parsing and argument completion. Pure: the handler in graphnav.ts acts on the result. */
+import { MODES, type Mode } from "../core/config.ts";
+
+export type Command =
+	| { kind: "status" }
+	| { kind: "on" }
+	| { kind: "off" }
+	| { kind: "mode"; mode: Mode }
+	| { kind: "sync" }
+	| { kind: "reindex" }
+	| { kind: "init" }
+	| { kind: "invalid"; message: string };
+
+export const USAGE = "Usage: /codegraph [status] · on · off · mode <enforce|nudge|off> · sync · reindex · init";
+
+export function parseCommand(args: string | undefined): Command {
+	const [cmd, ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	switch (cmd?.toLowerCase()) {
+		case undefined:
+		case "status":
+			return { kind: "status" };
+		case "on":
+		case "enable":
+			return { kind: "on" };
+		case "off":
+		case "disable":
+			return { kind: "off" };
+		case "mode": {
+			const m = rest[0]?.toLowerCase();
+			return MODES.includes(m as Mode) && rest.length === 1
+				? { kind: "mode", mode: m as Mode }
+				: { kind: "invalid", message: "Usage: /codegraph mode <enforce|nudge|off>" };
+		}
+		case "sync":
+			return { kind: "sync" };
+		case "reindex":
+		case "index":
+			return { kind: "reindex" };
+		case "init":
+			return { kind: "init" };
+		default:
+			return { kind: "invalid", message: `Unknown option "${cmd}". ${USAGE}` };
+	}
+}
+
+export interface CompletionItem {
+	value: string;
+	/** Required by pi: it calls `label.endsWith(...)` when applying a completion. */
+	label: string;
+	description?: string;
+}
+
+const TOP_LEVEL: CompletionItem[] = [
+	{ value: "status", label: "status", description: "Index state, mode and gate counts" },
+	{ value: "on", label: "on", description: "Turn CodeGraph-first on" },
+	{ value: "off", label: "off", description: "Turn CodeGraph-first off" },
+	{ value: "mode ", label: "mode", description: "Symbol searches: enforce, nudge or off" },
+	{ value: "sync", label: "sync", description: "Sync the index with changed files" },
+	{ value: "reindex", label: "reindex", description: "Rebuild the index from scratch" },
+	{ value: "init", label: "init", description: "Create the index for this project" },
+];
+
+const MODE_ITEMS: CompletionItem[] = [
+	{ value: "mode enforce", label: "enforce", description: "Block a symbol search once, pointing to CodeGraph" },
+	{ value: "mode nudge", label: "nudge", description: "Let it run, add a CodeGraph hint to the result" },
+	{ value: "mode off", label: "off", description: "Leave text searches alone" },
+];
+
+/** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
+export function completions(prefix: string): CompletionItem[] | null {
+	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
+	const pool = text.startsWith("mode ") ? MODE_ITEMS : TOP_LEVEL;
+	const out = pool.filter((i) => i.value.startsWith(text));
+	return out.length > 0 ? out : null;
+}

package/extensions/core/config.ts

@@ -0,0 +1,135 @@
+/**
+ * The persisted settings: <agent dir>/codegraph.json.
+ *
+ * A hand-edited file can hold anything, so `sanitizeConfig` keeps valid values and defaults the
+ * rest. A missing file is not a problem (defaults); a broken one is reported, never thrown.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Mode = "enforce" | "nudge" | "off";
+export const MODES: readonly Mode[] = ["enforce", "nudge", "off"];
+
+export interface Config {
+	/** Master switch: when false the extension adds no guidance, gates nothing and indexes nothing. */
+	enabled: boolean;
+	/** Show the status line entry. */
+	showStatus: boolean;
+	/** Symbol searches with rg/grep: block once (`enforce`), only add a hint (`nudge`) or leave alone (`off`). */
+	mode: Mode;
+	/** Create the index (`codegraph init`) for a git repo that has none. */
+	autoInit: boolean;
+	/** Sync or rebuild a stale index when the session starts. */
+	autoSync: boolean;
+	/** Keep the CodeGraph server's file watcher running, so the index follows edits. */
+	watch: boolean;
+	/** Source files read before any CodeGraph call that earn a hint (0 = never). */
+	readHintAfter: number;
+	/** Per-call timeout for the CodeGraph server, in ms. */
+	timeoutMs: number;
+}
+
+export const DEFAULT_CONFIG: Config = {
+	enabled: true,
+	showStatus: true,
+	mode: "enforce",
+	autoInit: true,
+	autoSync: true,
+	watch: true,
+	readHintAfter: 3,
+	timeoutMs: 30_000,
+};
+
+export const clampInt = (v: unknown, min: number, max: number, fallback: number): number =>
+	typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, Math.round(v))) : fallback;
+
+export function sanitizeConfig(raw: unknown): Config {
+	const r = (typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<string, unknown>;
+	const d = DEFAULT_CONFIG;
+	return {
+		enabled: typeof r.enabled === "boolean" ? r.enabled : d.enabled,
+		showStatus: typeof r.showStatus === "boolean" ? r.showStatus : d.showStatus,
+		mode: MODES.includes(r.mode as Mode) ? (r.mode as Mode) : d.mode,
+		autoInit: typeof r.autoInit === "boolean" ? r.autoInit : d.autoInit,
+		autoSync: typeof r.autoSync === "boolean" ? r.autoSync : d.autoSync,
+		watch: typeof r.watch === "boolean" ? r.watch : d.watch,
+		readHintAfter: clampInt(r.readHintAfter, 0, 100, d.readHintAfter),
+		timeoutMs: clampInt(r.timeoutMs, 1000, 600_000, d.timeoutMs),
+	};
+}
+
+/** Where pi keeps its config: PI_CODING_AGENT_DIR, then $XDG_CONFIG_HOME/pi/agent, then ~/.pi/agent. */
+export function resolveAgentDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.PI_CODING_AGENT_DIR) return env.PI_CODING_AGENT_DIR;
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi", "agent");
+	return join(home, ".pi", "agent");
+}
+
+export const configPath = (env: Record<string, string | undefined> = process.env, home = homedir()): string =>
+	join(resolveAgentDir(env, home), "codegraph.json");
+
+/** The config, plus a `problem` when the file exists but cannot be used. */
+export async function readConfig(path = configPath()): Promise<{ config: Config; problem?: string }> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (e) {
+		const code = (e as { code?: string } | null)?.code;
+		return code === "ENOENT" ? { config: sanitizeConfig({}) } : { config: sanitizeConfig({}), problem: `cannot read ${path} (${code ?? "error"})` };
+	}
+	try {
+		return { config: sanitizeConfig(JSON.parse(raw)) };
+	} catch {
+		return { config: sanitizeConfig({}), problem: `${path} is not valid JSON` };
+	}
+}
+
+export async function loadConfig(path = configPath()): Promise<Config> {
+	return (await readConfig(path)).config;
+}
+
+/** Atomic: written to a temp file and renamed, so a crash or a second pi session never leaves half a file. */
+export async function saveConfig(config: Config, path = configPath()): Promise<void> {
+	await mkdir(join(path, ".."), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+		await rename(tmp, path);
+	} catch (e) {
+		await Promise.allSettled([rm(tmp, { force: true })]); // the original error matters more
+		throw e;
+	}
+}
+
+/** What a project may override for itself, in `<project>/.pi/codegraph.json` (committable). */
+export type ProjectOverrides = Partial<Pick<Config, "enabled" | "mode" | "autoInit" | "autoSync" | "readHintAfter">>;
+
+/** Keep only the valid override keys; anything else in the file is ignored. */
+export function sanitizeOverrides(raw: unknown): ProjectOverrides {
+	const r = (typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<string, unknown>;
+	const out: ProjectOverrides = {};
+	for (const key of ["enabled", "autoInit", "autoSync"] as const) if (typeof r[key] === "boolean") out[key] = r[key] as boolean;
+	if (MODES.includes(r.mode as Mode)) out.mode = r.mode as Mode;
+	if (typeof r.readHintAfter === "number" && Number.isFinite(r.readHintAfter)) out.readHintAfter = clampInt(r.readHintAfter, 0, 100, 0);
+	return out;
+}
+
+export const projectConfigPath = (root: string): string => join(root, ".pi", "codegraph.json");
+
+/** A project's overrides; none when the file is missing, a `problem` when it is unusable. */
+export async function readProjectConfig(root: string): Promise<{ overrides: ProjectOverrides; problem?: string }> {
+	const path = projectConfigPath(root);
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (e) {
+		const code = (e as { code?: string } | null)?.code;
+		return code === "ENOENT" ? { overrides: {} } : { overrides: {}, problem: `cannot read ${path} (${code ?? "error"})` };
+	}
+	try {
+		return { overrides: sanitizeOverrides(JSON.parse(raw)) };
+	} catch {
+		return { overrides: {}, problem: `${path} is not valid JSON` };
+	}
+}