@zhalker/gentle-shell-codegraph-subagents 0.1.0 → 0.2.0

package/src/daemonclient.ts

@@ -0,0 +1,122 @@
+import net from "node:net";
+import { readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+
+/** The hello line a CodeGraph daemon sends carries `protocol`; this is the only one spoken here. */
+export const DAEMON_PROTOCOL = 1;
+/** An explore answer is tens of kilobytes; anything near this size is not one worth keeping in memory. */
+export const MAX_REPLY_CHARS = 1_000_000;
+/** CodeGraph answers an explore without a project with this plain text, not with an error. */
+export const NO_PROJECT_TEXT = "No CodeGraph project is loaded";
+
+export type DaemonExploreResult =
+	| { status: "ok"; text: string }
+	/** No daemon to ask, or it did not behave as expected: the caller should use another way. */
+	| { status: "unavailable" }
+	/** A daemon was there but did not answer in time: a second attempt would only be slower. */
+	| { status: "timeout" };
+
+export interface DaemonOptions {
+	/** Where daemons register themselves; defaults to `~/.codegraph/daemons`. */
+	registryDir?: string;
+}
+
+/** The same project can be spelled with another letter case or a trailing separator. */
+export function normalizeRoot(path: string): string {
+	let real: string;
+	try { real = realpathSync(path); } catch { real = resolve(path); }
+	while (real.length > 1 && (real.endsWith(sep) || real.endsWith("/")) && !/^[A-Za-z]:[\\/]$/.test(real)) real = real.slice(0, -1);
+	return process.platform === "win32" ? real.toLowerCase() : real;
+}
+
+/** Named pipes of the daemons registered for `root`, newest first. Reads the registry only; starts nothing. */
+function socketsFor(root: string, registryDir: string): string[] {
+	let files: string[];
+	try { files = readdirSync(registryDir).filter((file) => file.endsWith(".json")); } catch { return []; }
+	const wanted = normalizeRoot(root);
+	const found: { socketPath: string; startedAt: number }[] = [];
+	for (const file of files) {
+		try {
+			const entry = JSON.parse(readFileSync(join(registryDir, file), "utf8"));
+			if (typeof entry.root !== "string" || typeof entry.socketPath !== "string") continue;
+			if (normalizeRoot(entry.root) !== wanted) continue;
+			found.push({ socketPath: entry.socketPath, startedAt: typeof entry.startedAt === "number" ? entry.startedAt : 0 });
+		} catch { /* a damaged record is not a daemon */ }
+	}
+	return found.sort((a, b) => b.startedAt - a.startedAt).map((entry) => entry.socketPath);
+}
+
+/** One conversation with one daemon: hello, initialize, one codegraph_explore. */
+function ask(socketPath: string, query: string, timeoutMs: number): Promise<DaemonExploreResult> {
+	return new Promise((resolveResult) => {
+		let settled = false;
+		const socket = net.createConnection(socketPath);
+		const finish = (result: DaemonExploreResult) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			resolveResult(result);
+		};
+		const timer = setTimeout(() => finish({ status: "timeout" }), Math.max(1, timeoutMs));
+		const send = (message: object) => socket.write(JSON.stringify(message) + "\n");
+		let buffer = "";
+		let stage: "hello" | "initialize" | "explore" = "hello";
+		socket.setEncoding("utf8");
+		socket.on("error", () => finish({ status: "unavailable" }));
+		socket.on("close", () => finish({ status: "unavailable" }));
+		socket.on("data", (chunk: string) => {
+			buffer += chunk;
+			if (buffer.length > MAX_REPLY_CHARS) return finish({ status: "unavailable" });
+			let newline: number;
+			while ((newline = buffer.indexOf("\n")) >= 0) {
+				const line = buffer.slice(0, newline).trim();
+				buffer = buffer.slice(newline + 1);
+				if (line.length === 0) continue;
+				let message: any;
+				try { message = JSON.parse(line); } catch { return finish({ status: "unavailable" }); }
+				if (stage === "hello") {
+					if (typeof message.codegraph !== "string" || message.protocol !== DAEMON_PROTOCOL) return finish({ status: "unavailable" });
+					stage = "initialize";
+					send({
+						jsonrpc: "2.0",
+						id: 1,
+						method: "initialize",
+						params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "gentle-shell-codegraph-subagents", version: "0" } },
+					});
+				} else if (stage === "initialize" && message.id === 1) {
+					if (message.error !== undefined) return finish({ status: "unavailable" });
+					stage = "explore";
+					send({ jsonrpc: "2.0", method: "notifications/initialized" });
+					send({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "codegraph_explore", arguments: { query } } });
+				} else if (stage === "explore" && message.id === 2) {
+					// CodeGraph reports a crashed query worker with isError and a text, not with a JSON-RPC error.
+					const text = message.result?.content?.[0]?.text;
+					const failed = message.error !== undefined || message.result?.isError === true;
+					if (failed || typeof text !== "string" || text.startsWith(NO_PROJECT_TEXT)) return finish({ status: "unavailable" });
+					return finish({ status: "ok", text });
+				}
+			}
+		});
+	});
+}
+
+/**
+ * Runs `codegraph_explore` through the daemon already serving `root`, the same text the CLI prints but without
+ * a process of its own. It only reads the daemon registry and connects: it never starts a daemon, and never
+ * throws.
+ */
+export async function exploreViaDaemon(root: string, query: string, timeoutMs: number, options: DaemonOptions = {}): Promise<DaemonExploreResult> {
+	try {
+		const registryDir = options.registryDir ?? join(homedir(), ".codegraph", "daemons");
+		const deadline = Date.now() + timeoutMs;
+		for (const socketPath of socketsFor(root, registryDir)) {
+			const result = await ask(socketPath, query, deadline - Date.now());
+			if (result.status !== "unavailable") return result;
+		}
+		return { status: "unavailable" };
+	} catch {
+		return { status: "unavailable" };
+	}
+}

package/src/initlock.ts

@@ -0,0 +1,230 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalizeRoot } from "./daemonclient.ts";
+
+/**
+ * One `codegraph init` per project at a time, across every Pi session of this user on the machine (the temp folder
+ * is per user, so sessions of another Windows account are not seen). CodeGraph's own `init`
+ * can hang for good when two start at the same instant, or when anything opens the database in the first
+ * moments after the index was created, so the sessions that lose the race leave the index alone.
+ *
+ * The lock is a directory in the temp folder (creating a directory is atomic) holding `owner.json`. Clearing a
+ * stale lock happens under a second directory, `<lock>.takeover`, so only one session at a time can do it.
+ * The pids in `owner.json` are not the whole truth: on Windows `codegraph` is started through a shell, and that
+ * shell can die while the init itself goes on. CodeGraph's own `.codegraph/codegraph.lock` names the process that
+ * really writes the index, so it is consulted as well.
+ */
+
+/** The longest an init is allowed to run (10 minutes) plus a minute: beyond that the lock is not trusted. */
+export const LOCK_MAX_AGE_MS = 11 * 60_000;
+/** An empty lock directory this young is an owner about to write its record; older ones were abandoned. */
+const UNWRITTEN_GRACE_MS = 10_000;
+/** Clearing a stale lock takes milliseconds: a takeover guard older than this was left by a session that died. */
+const TAKEOVER_GRACE_MS = 10_000;
+/**
+ * How long a record whose adopted pid may be only the shell around the real init is trusted after that spawn.
+ * The shell can die while the init goes on, and the init announces itself in CodeGraph's own lock only a
+ * moment later (about half a second here); before that there is nothing to tell a starting init from a dead one.
+ */
+export const PROXY_TRUST_MS = 60_000;
+
+export interface LockOptions {
+	/** Where lock directories live; defaults to the temp folder. */
+	dir?: string;
+	isAlive?(pid: number): boolean;
+	now?(): number;
+	/** Tests only: called after a stale lock was found and before it is cleared. */
+	onStale?(): void;
+}
+
+export type LockAttempt =
+	| {
+		status: "acquired";
+		/**
+		 * Records the init process too: the lock stays held while it lives, even after this session is gone.
+		 * `proxy: true` when the pid is only the process that was spawned around the real init (Windows runs
+		 * `codegraph` through a shell): that shell can die while the init goes on, so the record is trusted for
+		 * {@link PROXY_TRUST_MS} after the spawn as well, until CodeGraph's own lock names the init.
+		 */
+		adopt(pid: number, options?: { proxy?: boolean }): void;
+		release(): void;
+	}
+	| { status: "busy" };
+
+/** What `autoIndex` needs from a lock; the real one is {@link realInitLock}. */
+export interface InitLock {
+	acquire(project: string): LockAttempt;
+	isHeld(project: string): boolean;
+}
+
+interface Owner {
+	pid: number;
+	startedAt: number;
+	/** Tells this session's lock apart from a later one taken by a session with the same pid. */
+	token: string;
+	/** The init process this session started, which can outlive the session. */
+	initPid?: number;
+	/** When `initPid` was adopted, for the window in which a proxy pid is trusted on its own. */
+	initPidAt?: number;
+	/** `initPid` is the process that was spawned around the init (a shell), not the init itself. */
+	initProxy?: boolean;
+}
+
+function lockPath(project: string, options: LockOptions): string {
+	const key = createHash("sha256").update(normalizeRoot(project)).digest("hex").slice(0, 16);
+	return join(options.dir ?? tmpdir(), `pcs-init-${key}`);
+}
+
+function processExists(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM: the process exists but belongs to someone else.
+		return (error as { code?: string }).code === "EPERM";
+	}
+}
+
+/** CodeGraph writes the pid of whatever writes the index here and removes the file when it ends, on failure too. */
+const CODEGRAPH_LOCK = join(".codegraph", "codegraph.lock");
+
+/**
+ * Whether a CodeGraph process is writing the index of `project` right now, whoever started it (another Pi, the
+ * project daemon, a git hook, a terminal). CodeGraph holds `.codegraph/codegraph.lock` for every operation that
+ * writes the index (`init`, `sync`, a file index) and removes it when it ends; reads and queries never hold it.
+ * A pid that is not alive left the file behind. Any other error is a false: this never throws.
+ */
+export function codegraphWritingIndex(project: string): boolean {
+	try {
+		const pid = Number.parseInt(readFileSync(join(project, CODEGRAPH_LOCK), "utf8").trim(), 10);
+		return Number.isInteger(pid) && pid > 0 && processExists(pid);
+	} catch {
+		return false;
+	}
+}
+
+function readOwner(lock: string): Owner | undefined {
+	try {
+		const owner = JSON.parse(readFileSync(join(lock, "owner.json"), "utf8"));
+		const valid = Number.isInteger(owner.pid) && typeof owner.startedAt === "number" && typeof owner.token === "string"
+			&& (owner.initPid === undefined || Number.isInteger(owner.initPid))
+			&& (owner.initPidAt === undefined || typeof owner.initPidAt === "number")
+			&& (owner.initProxy === undefined || typeof owner.initProxy === "boolean");
+		return valid ? owner : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Whether the lock at `lock` still belongs to someone who is working. A missing lock is not held. */
+function held(project: string, lock: string, options: LockOptions): boolean {
+	const now = options.now?.() ?? Date.now();
+	let directory;
+	try { directory = statSync(lock); } catch { return false; }
+	const owner = readOwner(lock);
+	// No readable record: its owner is probably still writing it, unless it has been this way for a while.
+	if (owner === undefined) return now - directory.mtimeMs < UNWRITTEN_GRACE_MS;
+	if (now - owner.startedAt > LOCK_MAX_AGE_MS) return false;
+	const isAlive = options.isAlive ?? processExists;
+	if (isAlive(owner.pid)) return true;
+	if (owner.initPid !== undefined && isAlive(owner.initPid)) return true;
+	// The process writing the index itself, whatever pid this session spawned or adopted: on Windows the
+	// adopted pid is the shell, and a shell dies with the session that started it while the init goes on.
+	// That pid is another process, so it is judged with the real process table, not with a test hook.
+	if (codegraphWritingIndex(project)) return true;
+	// Right after the spawn CodeGraph has not written its lock yet; until then the record speaks for the init.
+	return owner.initProxy === true && owner.initPidAt !== undefined && now - owner.initPidAt < PROXY_TRUST_MS;
+}
+
+/** Replaces the owner record in one step, so a reader sees the old record or the new one, never none. */
+function writeOwner(lock: string, owner: Owner): void {
+	const draft = join(lock, `owner.${owner.token}.tmp`);
+	writeFileSync(draft, JSON.stringify(owner));
+	renameSync(draft, join(lock, "owner.json"));
+}
+
+/**
+ * Clears the stale lock at `lock`; true when the caller may try to take it again. Only the session holding the
+ * takeover guard gets this far, and it checks again under the guard: another session may have taken the lock
+ * over since this one judged it stale.
+ */
+function clearStale(project: string, lock: string, options: LockOptions, token: string): boolean {
+	const guard = `${lock}.takeover`;
+	try {
+		mkdirSync(guard);
+	} catch {
+		// Someone else is taking it over right now, or died doing it: then the next session gets its turn.
+		try {
+			if ((options.now?.() ?? Date.now()) - statSync(guard).mtimeMs > TAKEOVER_GRACE_MS) rmSync(guard, { recursive: true, force: true });
+		} catch { /* already gone */ }
+		return false;
+	}
+	try {
+		if (held(project, lock, options)) return false;
+		const judged = readOwner(lock)?.token;
+		const aside = `${lock}.stale-${token}`;
+		try { renameSync(lock, aside); } catch { return true; /* its owner removed it meanwhile */ }
+		if (readOwner(aside)?.token !== judged) {
+			// Not the lock judged stale: its owner left and another session took it in between. Give it back.
+			try { renameSync(aside, lock); } catch { /* the lock is taken again; the moved one is lost either way */ }
+			return false;
+		}
+		try { rmSync(aside, { recursive: true, force: true }); } catch { /* leftovers are harmless */ }
+		return true;
+	} finally {
+		try { rmSync(guard, { recursive: true, force: true }); } catch { /* a guard left behind expires */ }
+	}
+}
+
+/**
+ * Takes the init lock of `project`. Never throws: when the temp folder cannot be used the session goes on as if
+ * it had the lock, which is how it behaved before locks existed.
+ */
+export function tryAcquireInitLock(project: string, options: LockOptions = {}): LockAttempt {
+	const lock = lockPath(project, options);
+	const mine: Owner = { pid: process.pid, startedAt: options.now?.() ?? Date.now(), token: randomBytes(8).toString("hex") };
+	const adopt = (pid: number, adoptOptions: { proxy?: boolean } = {}) => {
+		if (readOwner(lock)?.token !== mine.token) return;
+		mine.initPid = pid;
+		mine.initPidAt = options.now?.() ?? Date.now();
+		mine.initProxy = adoptOptions.proxy === true;
+		try { writeOwner(lock, mine); } catch { /* the lock still holds while this session lives */ }
+	};
+	const release = () => {
+		// Only remove what is still ours: after a takeover the lock belongs to someone else.
+		const owner = readOwner(lock);
+		if (owner && owner.token === mine.token) rmSync(lock, { recursive: true, force: true });
+	};
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			mkdirSync(lock);
+			writeOwner(lock, mine);
+			return { status: "acquired", adopt, release };
+		} catch (error) {
+			if ((error as { code?: string }).code !== "EEXIST") return { status: "acquired", adopt: () => {}, release: () => {} };
+		}
+		if (held(project, lock, options)) return { status: "busy" };
+		options.onStale?.();
+		if (!clearStale(project, lock, options, mine.token)) return { status: "busy" };
+	}
+	return { status: "busy" };
+}
+
+/**
+ * Whether the init lock of `project` is held right now: a session is running an init, or CodeGraph itself is still
+ * writing the index it started. Reads only.
+ */
+export function isInitLocked(project: string, options: LockOptions = {}): boolean {
+	try {
+		return held(project, lockPath(project, options), options);
+	} catch {
+		return false;
+	}
+}
+
+export const realInitLock: InitLock = {
+	acquire: (project) => tryAcquireInitLock(project),
+	isHeld: (project) => isInitLocked(project),
+};

package/src/mcp.ts

@@ -1,25 +1,93 @@
-/**
- * Pi declares MCP tools to the model only for servers with `exposure: "direct"`;
- * the default, `codemode`, makes them reachable from scripts but never callable
- * as a tool, so an agent `tools:` entry like `mcp__codegraph__*` would match nothing.
- * Returns the config with the codegraph server set to `direct`; identical text when nothing changes.
- */
-export function normalizeMcpConfig(text: string): string {
-	let config: unknown;
-	try {
-		config = JSON.parse(text);
-	} catch {
-		return text;
-	}
-	if (typeof config !== "object" || config === null || Array.isArray(config)) return text;
-	const servers = (config as { mcpServers?: unknown }).mcpServers;
-	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return text;
-	const server = (servers as Record<string, unknown>).codegraph;
-	if (typeof server !== "object" || server === null || Array.isArray(server)) return text;
-	const entry = server as Record<string, unknown>;
-	if (entry.enabled === false || entry.exposure === "direct") return text;
-
-	entry.exposure = "direct";
-	const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
-	return JSON.stringify(config, null, indent) + "\n";
-}
+const EXPLORE = "codegraph_explore";
+
+function matchingExposure(entry: Record<string, unknown>): string | undefined {
+	const tools = entry.toolExposure;
+	if (!tools || typeof tools !== "object" || Array.isArray(tools)) return undefined;
+	const values = tools as Record<string, unknown>;
+	if (typeof values[EXPLORE] === "string") return values[EXPLORE] as string;
+	for (const [pattern, exposure] of Object.entries(values)) {
+		if (!pattern.includes("*") || typeof exposure !== "string") continue;
+		const regex = new RegExp(`^${pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+		if (regex.test(EXPLORE)) return exposure;
+	}
+	return undefined;
+}
+
+function codegraphServer(text: string): Record<string, unknown> | undefined {
+	try {
+		const config = JSON.parse(text);
+		const entry = config?.mcpServers?.codegraph;
+		return entry && typeof entry === "object" && !Array.isArray(entry) ? entry : undefined;
+	} catch { return undefined; }
+}
+
+/** Missing is distinct from disabled, invalid configuration and servers registered by extensions. */
+export function isCodegraphServerMissing(globalText: string, projectText?: string, registered = false): boolean {
+	if (registered) return false;
+	const read = (text: string): Record<string, unknown> | undefined => {
+		try {
+			const value = JSON.parse(text);
+			return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+		} catch { return undefined; }
+	};
+	const global = read(globalText);
+	const project = projectText === undefined ? undefined : read(projectText);
+	if (!global || (projectText !== undefined && !project)) return false;
+	const hasServer = (config: Record<string, unknown>): boolean => {
+		const servers = config.mcpServers;
+		return !!servers && typeof servers === "object" && !Array.isArray(servers)
+			&& Object.prototype.hasOwnProperty.call(servers, "codegraph");
+	};
+	if (hasServer(global)) return false;
+	if (!project || !hasServer(project)) return true;
+	const servers = project.mcpServers as Record<string, unknown>;
+	const entry = servers.codegraph;
+	// A project-only override cannot create a server without a transport definition.
+	if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+		return !("command" in entry || "url" in entry || "type" in entry);
+	}
+	return false; // Let Pi report an invalid server entry instead of claiming it is absent.
+}
+
+/** Explicit restrictions must be respected, not overridden silently. */
+export function inspectMcpExposure(text: string): string | undefined {
+	const entry = codegraphServer(text);
+	if (!entry) return undefined;
+	if (entry.enabled === false) return "disabled";
+	const selected = matchingExposure(entry);
+	if (entry.exposure === "hidden" && selected === "direct") return "hidden-with-direct";
+	if (selected !== undefined) return selected === "direct" ? undefined : selected;
+	const exposure = typeof entry.exposure === "string" ? entry.exposure : "codemode";
+	return exposure === "direct" ? undefined : exposure;
+}
+
+/** Inspect the effective file configuration, including a trusted project's override when supplied. */
+export function inspectEffectiveMcpExposure(globalText: string, projectText?: string): string | undefined {
+	const global = codegraphServer(globalText);
+	const project = projectText === undefined ? undefined : codegraphServer(projectText);
+	if (!project) return inspectMcpExposure(globalText);
+	const replacement = "command" in project || "url" in project || "type" in project;
+	const entry = replacement ? project : { ...global, ...project };
+	return inspectMcpExposure(JSON.stringify({ mcpServers: { codegraph: entry } }));
+}
+
+/** Select direct access for explore without changing the server-wide exposure. */
+export function normalizeMcpConfig(text: string): string {
+	let config: unknown;
+	try {
+		config = JSON.parse(text);
+	} catch {
+		return text;
+	}
+	if (typeof config !== "object" || config === null || Array.isArray(config)) return text;
+	const servers = (config as { mcpServers?: unknown }).mcpServers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return text;
+	const server = (servers as Record<string, unknown>).codegraph;
+	if (typeof server !== "object" || server === null || Array.isArray(server)) return text;
+	const entry = server as Record<string, unknown>;
+	if (entry.enabled === false || matchingExposure(entry) !== undefined || entry.exposure === "hidden") return text;
+	if (entry.toolExposure !== undefined && (typeof entry.toolExposure !== "object" || entry.toolExposure === null || Array.isArray(entry.toolExposure))) return text;
+	entry.toolExposure = { ...(entry.toolExposure as Record<string, unknown> | undefined), [EXPLORE]: "direct" };
+	const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+	return JSON.stringify(config, null, indent) + "\n";
+}