@pharaoh-so/mcp 0.3.53 → 0.3.56

package/project-memory/local.mjs

@@ -0,0 +1,463 @@
+import { execFileSync, spawn } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import {
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmdirSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+
+const TURN_TTL = 12 * 60 * 60 * 1000;
+const LOCK_MIN_AGE = 15_000;
+const LOCK_OWNER = /^owner-[a-f0-9-]{36}\.json$/;
+const TOKEN = /^[a-f0-9]{64}$/;
+const GIT = ["/usr/bin/git", "/opt/homebrew/bin/git", "/usr/local/bin/git"].find(existsSync);
+export const hasMemoryGit = Boolean(GIT);
+const GIT_TIMEOUT_MS = 750;
+const VISIBLE_INDEX_TAG = Buffer.from("H ");
+export const REPO = /^[a-z0-9][a-z0-9-]{0,38}\/[a-z0-9_.-]{1,100}$/i;
+
+function gitProcess(cwd, args) {
+	if (!GIT) throw new Error("Project memory could not locate a system Git executable.");
+	const env = {
+		...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+		GIT_NO_LAZY_FETCH: "1",
+		GIT_ALLOW_PROTOCOL: "",
+	};
+	return {
+		args: [
+			"--no-optional-locks",
+			"--no-replace-objects",
+			"--no-pager",
+			"-c",
+			"core.fsmonitor=false",
+			"-c",
+			"core.untrackedCache=false",
+			"-C",
+			cwd,
+			...args,
+		],
+		env,
+		stdio: ["ignore", "pipe", "ignore"],
+	};
+}
+
+export function git(cwd, ...command) {
+	const { args, ...options } = gitProcess(cwd, command);
+	return execFileSync(GIT, args, {
+		...options,
+		encoding: "utf8",
+		maxBuffer: 8192,
+		timeout: GIT_TIMEOUT_MS,
+	}).trim();
+}
+
+/** Check one literal path or the entire index for flags that can hide worktree edits. */
+export async function visibleGitIndex(cwd, path) {
+	try {
+		const paths = path ? [`:(literal)${path}`] : [];
+		const { args, ...options } = gitProcess(cwd, ["ls-files", "-v", "-z", "--", ...paths]);
+		const signal = AbortSignal.timeout(GIT_TIMEOUT_MS);
+		const child = spawn(GIT, args, {
+			...options,
+			signal,
+			killSignal: "SIGKILL",
+		});
+		return await new Promise((resolve) => {
+			let prefix = 0;
+			let hasName = false;
+			let sawEntry = false;
+			let failed = false;
+			let ended = false;
+			function stop() {
+				failed = true;
+				child.stdout.destroy();
+				child.kill("SIGKILL");
+			}
+			child.on("error", () => {
+				failed = true;
+			});
+			child.stdout.once("end", () => {
+				ended = true;
+			});
+			child.stdout.on("error", stop);
+			child.stdout.on("data", (chunk) => {
+				// Only H is visible. Lowercase tags and S can hide changed files.
+				// Names can contain newlines. Carry only framing state across chunks.
+				for (const byte of chunk) {
+					if (prefix < VISIBLE_INDEX_TAG.length) {
+						if (byte !== VISIBLE_INDEX_TAG[prefix]) return stop();
+						prefix++;
+					} else if (byte === 0) {
+						if (!hasName) return stop();
+						sawEntry = true;
+						prefix = 0;
+						hasName = false;
+					} else {
+						hasName = true;
+					}
+				}
+			});
+			child.once("close", (code) =>
+				resolve(!failed && !signal.aborted && code === 0 && ended && sawEntry && prefix === 0),
+			);
+		});
+	} catch {
+		return false;
+	}
+}
+
+/** Accept only an unambiguous GitHub origin, independent of the branch name. */
+export function checkout(cwd) {
+	if (typeof cwd !== "string" || !isAbsolute(cwd)) return;
+	try {
+		const root = realpathSync(git(cwd, "rev-parse", "--show-toplevel"));
+		const origin = git(root, "config", "--local", "--get-all", "remote.origin.url");
+		const repo = /^(?:https:\/\/github\.com\/|ssh:\/\/git@github\.com\/|git@github\.com:)([^\n]+)$/i
+			.exec(origin)?.[1]
+			.replace(/\.git$/i, "");
+		if (repo && REPO.test(repo)) return { root, repo };
+	} catch {
+		// Non-repositories and unreadable worktrees are outside the pilot.
+	}
+}
+
+export function shellWord(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+export async function readStdin(maxBytes) {
+	const chunks = [];
+	let bytes = 0;
+	for await (const chunk of process.stdin) {
+		bytes += chunk.length;
+		if (bytes > maxBytes) throw new Error("Input exceeds the size limit.");
+		chunks.push(chunk);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+export function atomicWrite(path, contents) {
+	const temporary = join(dirname(path), `.pharaoh-memory-${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporary, contents, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+
+function readJson(path) {
+	try {
+		const file = lstatSync(path);
+		if (!file.isFile() || (file.mode & 0o077) !== 0 || file.size > 8192) return;
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		// State can expire or be removed by another event.
+	}
+}
+
+function makePrivateDirectory(path) {
+	mkdirSync(path, { mode: 0o700, recursive: true });
+	const info = lstatSync(path);
+	if (!info.isDirectory() || (info.mode & 0o077) !== 0 || info.uid !== process.getuid?.()) {
+		throw new Error("Project memory needs a private local state directory.");
+	}
+}
+
+export function sessionKey(client, sessionId) {
+	if (typeof sessionId !== "string" || !sessionId || sessionId.length > 256) return;
+	return createHash("sha256").update(`${client}\0${sessionId}`).digest("hex");
+}
+
+function releaseLock(path, owner) {
+	try {
+		unlinkSync(join(path, owner));
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+	try {
+		rmdirSync(path);
+	} catch (error) {
+		// A replacement always appears already populated, so rmdir cannot remove it.
+		if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+	}
+}
+
+function acquireLock(directory, path, now) {
+	const owner = `owner-${randomUUID()}.json`;
+	const candidate = mkdtempSync(join(directory, "lock-candidate-"));
+	try {
+		writeFileSync(join(candidate, owner), JSON.stringify({ pid: process.pid, createdAt: now }), {
+			flag: "wx",
+			mode: 0o600,
+		});
+		// POSIX rename installs the prepared directory only if the destination is
+		// absent or empty. No process can see a new lock without its owner marker.
+		renameSync(candidate, path);
+		return () => releaseLock(path, owner);
+	} catch (error) {
+		if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
+	} finally {
+		rmSync(candidate, { recursive: true, force: true });
+	}
+}
+
+function recoverLock(path, now) {
+	let entries;
+	try {
+		entries = readdirSync(path);
+	} catch (error) {
+		if (error.code === "ENOENT") return true;
+		throw error;
+	}
+	if (entries.length === 0) return true;
+	if (entries.length !== 1 || !LOCK_OWNER.test(entries[0])) return false;
+	const [owner] = entries;
+	const metadata = readJson(join(path, owner));
+	if (
+		!Number.isInteger(metadata?.pid) ||
+		metadata.pid < 1 ||
+		metadata.pid > 2_147_483_647 ||
+		!Number.isFinite(metadata.createdAt) ||
+		now - metadata.createdAt < LOCK_MIN_AGE
+	)
+		return false;
+	try {
+		process.kill(metadata.pid, 0);
+		return false;
+	} catch (error) {
+		// A reused PID, a live owner, or inability to confirm death keeps the lock.
+		if (error.code !== "ESRCH") return false;
+	}
+	releaseLock(path, owner);
+	return true;
+}
+
+/** Serialize local state transitions only; network operations never hold this lock. */
+export function turnStore(home = homedir(), now = Date.now) {
+	const directory = join(home, ".pharaoh", "project-memory-turns-v2");
+	makePrivateDirectory(directory);
+	const sessionPath = (key) => join(directory, `session-${key}.json`);
+	const indexPath = (token) => join(directory, `turn-${token}.json`);
+	const overlapPath = (key) => join(directory, `overlap-${key}.json`);
+	const receiptPath = (token) => join(directory, `receipt-${token}.json`);
+	function current(key) {
+		const state = readJson(sessionPath(key));
+		if (!state || state.expires > now()) return state;
+		remove(key, state);
+	}
+	function put(key, state) {
+		atomicWrite(sessionPath(key), JSON.stringify(state));
+	}
+	function remove(key, state) {
+		if (TOKEN.test(state?.token)) rmSync(indexPath(state.token), { force: true });
+		rmSync(sessionPath(key), { force: true });
+	}
+	function lock(key, fn, { onBusy, canClearFence, onFence } = {}) {
+		if (!TOKEN.test(key)) return;
+		const path = join(directory, `${key}.lock`);
+		const time = now();
+		const release =
+			acquireLock(directory, path, time) ??
+			(recoverLock(path, time) ? acquireLock(directory, path, time) : undefined);
+		if (!release) return onBusy?.();
+		try {
+			const stored = readJson(overlapPath(key));
+			const fence = typeof stored === "number" ? { expires: stored } : stored;
+			const active = fence?.expires > time;
+			if (active && !canClearFence?.(fence)) return onFence?.();
+			if (stored !== undefined) rmSync(overlapPath(key), { force: true });
+			return fn(current(key), active);
+		} finally {
+			release();
+		}
+	}
+	function fence(key, nativeTurn) {
+		atomicWrite(overlapPath(key), JSON.stringify({ nativeTurn, expires: now() + TURN_TTL }));
+	}
+	function sameCheckout(state, target) {
+		return (
+			state?.root === target.root &&
+			state.repo.toLowerCase() === target.repo.toLowerCase() &&
+			(!state.runtime || state.runtime === target.runtime)
+		);
+	}
+	function withTurn(token, target, fn) {
+		if (!TOKEN.test(token)) return;
+		const key = readJson(indexPath(token));
+		if (typeof key !== "string") return;
+		return lock(key, (state) => {
+			if (sameCheckout(state, target) && state.token === token) return fn(key, state);
+		});
+	}
+	return {
+		begin(key, target, client, nativeTurn, { skip, readOnly }) {
+			return lock(
+				key,
+				(previous) => {
+					if (previous) {
+						if (nativeTurn && previous.nativeTurn === nativeTurn) {
+							// Duplicate native events belong to the same task. Keep its
+							// token unless the user expressly opted out of this turn.
+							if (skip) remove(key, previous);
+							return;
+						}
+						if (nativeTurn) {
+							// A new native turn cannot be mistaken for an earlier Stop or CLI result.
+							remove(key, previous);
+						} else {
+							if (TOKEN.test(previous.token)) rmSync(indexPath(previous.token), { force: true });
+							put(key, { ...previous, phase: "ambiguous" });
+							return { degraded: "overlap" };
+						}
+					}
+					if (skip) return;
+					const token = randomBytes(32).toString("hex");
+					const state = {
+						...target,
+						client,
+						nativeTurn,
+						token,
+						operationId: randomUUID(),
+						expires: now() + TURN_TTL,
+						phase: "pending",
+						readOnly,
+					};
+					atomicWrite(indexPath(token), JSON.stringify(key));
+					put(key, state);
+					return { token };
+				},
+				{
+					onBusy: () => {
+						fence(key, nativeTurn);
+						return { degraded: "busy" };
+					},
+					canClearFence: (entry) => Boolean(nativeTurn && entry.nativeTurn !== nativeTurn),
+					onFence: () => ({ degraded: "overlap" }),
+				},
+			);
+		},
+		stop(key, target, nativeTurn, mayNudge, isContinuation) {
+			return lock(
+				key,
+				(state, fenced) => {
+					if (!sameCheckout(state, target)) return;
+					if (fenced) {
+						if (state.nativeTurn === nativeTurn) remove(key, state);
+						return;
+					}
+					if (
+						nativeTurn &&
+						state.nativeTurn !== nativeTurn &&
+						!(isContinuation && state.continuationTurn === nativeTurn)
+					)
+						return;
+					if (state.phase === "ambiguous" && !nativeTurn) return;
+					if (!mayNudge || state.readOnly || !["recalled", "expanding"].includes(state.phase)) {
+						remove(key, state);
+						return;
+					}
+					put(key, { ...state, phase: "nudged" });
+					return state.token;
+				},
+				{
+					canClearFence: (entry) => Boolean(nativeTurn && nativeTurn === entry.nativeTurn),
+				},
+			);
+		},
+		registerContinuation(key, target, nativeTurn, token) {
+			lock(key, (state) => {
+				if (sameCheckout(state, target) && state.token === token && state.phase === "nudged") {
+					put(key, { ...state, continuationTurn: nativeTurn });
+				}
+			});
+		},
+		cancel(key, target, nativeTurn) {
+			lock(
+				key,
+				(state) => {
+					if (
+						sameCheckout(state, target) &&
+						(!nativeTurn ||
+							state.nativeTurn === nativeTurn ||
+							state.continuationTurn === nativeTurn)
+					)
+						remove(key, state);
+				},
+				{
+					onBusy: () => fence(key, nativeTurn),
+					canClearFence: (entry) => !nativeTurn || entry.nativeTurn === nativeTurn,
+				},
+			);
+		},
+		transition(token, target, from, to) {
+			return withTurn(token, target, (key, state) => {
+				if (!from.includes(state.phase)) return;
+				put(key, { ...state, phase: to });
+				return state;
+			});
+		},
+		finishRecall(token, target, pairs) {
+			return withTurn(token, target, (key, state) => {
+				if (state.phase !== "recalling") return;
+				put(key, { ...state, phase: "recalled", pairs, expansions: 0 });
+				return true;
+			});
+		},
+		beginExpand(token, target, id, version) {
+			return withTurn(token, target, (key, state) => {
+				if (
+					state.phase !== "recalled" ||
+					state.expansions >= 2 ||
+					!state.pairs?.some(
+						([recordId, recordVersion]) => recordId === id && recordVersion === version,
+					)
+				)
+					return;
+				const expansions = state.expansions + 1;
+				put(key, { ...state, phase: "expanding", expansions });
+				return { repo: state.repo, attempt: expansions };
+			});
+		},
+		finishExpand(token, target, attempt) {
+			return withTurn(token, target, (key, state) => {
+				if (state.phase !== "expanding" || state.expansions !== attempt) return;
+				put(key, { ...state, phase: "recalled" });
+				return true;
+			});
+		},
+		saveReceipt(token, target, record) {
+			if (!TOKEN.test(token)) return;
+			atomicWrite(
+				receiptPath(token),
+				JSON.stringify({
+					...target,
+					record: { id: record.id, status: record.status },
+					expires: now() + TURN_TTL,
+				}),
+			);
+		},
+		readReceipt(token, target) {
+			if (!TOKEN.test(token)) return;
+			const path = receiptPath(token);
+			const receipt = readJson(path);
+			if (receipt && receipt.expires <= now()) {
+				rmSync(path, { force: true });
+				return;
+			}
+			if (sameCheckout(receipt, target)) return { record: receipt.record };
+		},
+	};
+}

package/project-memory/memory-api.mjs

@@ -0,0 +1,182 @@
+export const PROJECT_MEMORY_ORIGIN = "https://mcp.pharaoh.so";
+const READY_TIMEOUT_MS = 1_200;
+const BUILD = new URL("runtime/refresh.js", import.meta.url);
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const STATUS = new Set(["candidate", "approved", "superseded", "retracted"]);
+
+export class PilotError extends Error {}
+
+async function responseJson(response) {
+	if (!response.body) throw new PilotError("Pharaoh returned an incomplete response.");
+	const chunks = [];
+	let bytes = 0;
+	for await (const chunk of response.body) {
+		bytes += chunk.length;
+		if (bytes > 32_768) throw new PilotError("Pharaoh returned an oversized response.");
+		chunks.push(chunk);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+export async function refreshHelper() {
+	try {
+		const helper = await import(BUILD.href);
+		if (typeof helper.originBoundRefresh === "function") return helper;
+	} catch {
+		// Missing or incomplete build.
+	}
+	throw new PilotError(
+		"The installed project memory bundle has no compatible refresh helper. Rerun normal Pharaoh setup.",
+	);
+}
+
+/** Check only mapping metadata using the current device session. Normal proxy
+ * startup handles token refresh; the prompt hook never waits on a refresh lock. */
+export async function requestMemoryReadiness(repo, credentials) {
+	const expiresAt = Date.parse(credentials?.expires_at);
+	if (typeof credentials?.access_token !== "string" || !(expiresAt > Date.now())) return;
+	try {
+		if (new URL(credentials.sse_url).origin !== PROJECT_MEMORY_ORIGIN) return;
+		const response = await fetch(`${PROJECT_MEMORY_ORIGIN}/api/project-memory/readiness`, {
+			method: "POST",
+			redirect: "error",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${credentials.access_token}`,
+			},
+			body: JSON.stringify({ repo }),
+			signal: AbortSignal.timeout(READY_TIMEOUT_MS),
+		});
+		if (!response.ok) {
+			await response.body?.cancel();
+			return;
+		}
+		const result = await responseJson(response);
+		return result?.revision;
+	} catch {
+		// Pending, denied, unavailable and timed-out lookups leave hooks dormant.
+	}
+}
+
+export async function requestMemory(operation, payload, { fetcher = fetch, helper } = {}) {
+	if (!["recall", "capture", "expand"].includes(operation))
+		throw new PilotError("Unknown memory request.");
+	const { originBoundRefresh } = helper ?? (await refreshHelper());
+	const refresh = originBoundRefresh(PROJECT_MEMORY_ORIGIN);
+	const outcome = await refresh.load();
+	if (!outcome?.ok)
+		throw new PilotError(
+			"Connect to Pharaoh with its device sign-in, or retry if sign-in is temporarily unavailable.",
+		);
+	const send = async (creds) => {
+		try {
+			return await fetcher(`${PROJECT_MEMORY_ORIGIN}/api/project-memory/${operation}`, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${creds.access_token}`,
+				},
+				body: JSON.stringify(payload),
+				signal: AbortSignal.timeout(12_000),
+			});
+		} catch {
+			throw new PilotError(
+				operation === "capture"
+					? "Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying."
+					: "Pharaoh project memory could not respond before the request ended.",
+			);
+		}
+	};
+	const response = await send(outcome.creds);
+	if (!response.ok) {
+		await response.body?.cancel();
+		// The shared credential file can now name a different OAuth session. Do
+		// not reuse an already prepared operation under newly loaded credentials.
+		if (response.status === 401)
+			throw new PilotError("Pharaoh rejected this sign-in. Reconnect before trying again.");
+		if (response.status === 404)
+			throw new PilotError("Project memory is unavailable for this repository or account.");
+		if (response.status === 400 || response.status === 413)
+			throw new PilotError(
+				"Pharaoh rejected the memory payload. Check its shape, size, and sensitive content.",
+			);
+		if (response.status === 409)
+			throw new PilotError(
+				"Pharaoh could not save this candidate because the operation conflicts or the project log is full.",
+			);
+		if (response.status === 429)
+			throw new PilotError("Pharaoh project memory reached its request limit.");
+		if (operation === "capture" && response.status >= 500) {
+			throw new PilotError(
+				"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+			);
+		}
+		throw new PilotError("Pharaoh project memory is temporarily unavailable.");
+	}
+	let result;
+	try {
+		result = await responseJson(response);
+	} catch (error) {
+		if (operation === "capture")
+			throw new PilotError(
+				"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+			);
+		throw error;
+	}
+	if (
+		operation === "recall" &&
+		Array.isArray(result?.records) &&
+		result.records.length <= 5 &&
+		result.records.every((record) => typeof record?.id === "string" && UUID.test(record.id))
+	) {
+		if (payload.format === "compact-v1") {
+			if (
+				result.format === "compact-v1" &&
+				typeof result.repo === "string" &&
+				result.repo.toLowerCase() === payload.repo.toLowerCase() &&
+				typeof result.moreMatches === "boolean" &&
+				Number.isInteger(result.omittedRecords) &&
+				result.omittedRecords >= 0 &&
+				result.records.every(
+					(record) =>
+						Number.isInteger(record.version) &&
+						record.version >= 1 &&
+						record.version <= 1_000_000 &&
+						STATUS.has(record.status),
+				)
+			)
+				return result;
+			throw new PilotError("Pharaoh returned an incomplete compact recall packet.");
+		}
+		return { records: result.records, graph: result.graph };
+	}
+	if (
+		operation === "expand" &&
+		result?.record?.id === payload.id &&
+		result.record.version === payload.version &&
+		STATUS.has(result.record.status) &&
+		Number.isInteger(result.current?.version) &&
+		result.current.version >= payload.version &&
+		STATUS.has(result.current.status)
+	) {
+		const omitted = result.omittedHistoricalEvidence;
+		return {
+			record: result.record,
+			current: result.current,
+			...(Number.isInteger(omitted) && omitted >= 0 && { omittedHistoricalEvidence: omitted }),
+		};
+	}
+	if (
+		operation === "capture" &&
+		typeof result?.record?.id === "string" &&
+		UUID.test(result.record.id)
+	) {
+		return { record: { id: result.record.id, status: result.record.status } };
+	}
+	if (operation === "capture")
+		throw new PilotError(
+			"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+		);
+	throw new PilotError("Pharaoh returned an incomplete response.");
+}

package/project-memory/pharaoh-memory-hook.mjs

@@ -0,0 +1,33 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { handleEvent } from "./hook-events.mjs";
+import { readStdin } from "./local.mjs";
+import {
+	activeMemoryRuntime,
+	readMemoryCredentials,
+	resolveMemoryHookTarget,
+} from "./user-target.mjs";
+
+try {
+	const [client, root, repo] = process.argv.slice(2);
+	const input = await readStdin(1024 * 1024);
+	let target = { root, repo };
+	if (root === "--user") {
+		const runtime = dirname(fileURLToPath(import.meta.url));
+		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
+		const eligible = await resolveMemoryHookTarget(
+			client,
+			input?.cwd,
+			await readMemoryCredentials(),
+			input?.hook_event_name === "UserPromptSubmit" &&
+				typeof input?.prompt === "string" &&
+				Boolean(input.prompt.trim()),
+		);
+		if (!eligible) process.exit(0);
+		target = { ...eligible, runtime };
+	}
+	const result = handleEvent(input, { client, ...target });
+	if (result) process.stdout.write(JSON.stringify(result));
+} catch {
+	// Fail open. handleEvent reports state failures when the prompt is eligible.
+}