@pharaoh-so/mcp 0.3.54 → 0.3.57

package/project-memory/memory-api.mjs

@@ -0,0 +1,200 @@
+export const PROJECT_MEMORY_ORIGIN = "https://mcp.pharaoh.so";
+const READY_TIMEOUT_MS = 1_200;
+const REQUEST_TIMEOUT_MS = 12_000;
+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 {
+	constructor(message, rejected = false) {
+		super(message);
+		this.rejected = rejected;
+	}
+}
+
+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, deadline = Infinity) {
+	const expiresAt = Date.parse(credentials?.expires_at);
+	if (typeof credentials?.access_token !== "string" || !(expiresAt > Date.now())) return;
+	const timeout = Math.min(READY_TIMEOUT_MS, Math.floor(deadline - performance.now()));
+	if (timeout < 1) 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(timeout),
+		});
+		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, credentials } = {},
+) {
+	if (!["recall", "capture", "expand"].includes(operation))
+		throw new PilotError("Unknown memory request.");
+	// Capture supplies its session snapshot so dispatch cannot adopt a different sign-in.
+	if (!credentials) {
+		const { originBoundRefresh } = helper ?? (await refreshHelper());
+		const outcome = await originBoundRefresh(PROJECT_MEMORY_ORIGIN).load();
+		if (outcome?.ok) credentials = outcome.creds;
+	}
+	if (!credentials)
+		throw new PilotError(
+			"Connect to Pharaoh with its device sign-in, or retry if sign-in is temporarily unavailable.",
+		);
+	let response;
+	try {
+		response = await fetcher(`${PROJECT_MEMORY_ORIGIN}/api/project-memory/${operation}`, {
+			method: "POST",
+			redirect: "error",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${credentials.access_token}`,
+			},
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		});
+	} 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.",
+		);
+	}
+	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.", true);
+		if (response.status === 404)
+			throw new PilotError("Project memory is unavailable for this repository or account.", true);
+		if (response.status === 400 || response.status === 413)
+			throw new PilotError(
+				"Pharaoh rejected the memory payload. Check its shape, size, and sensitive content.",
+				true,
+			);
+		if (response.status === 409)
+			throw new PilotError(
+				"Pharaoh could not save this candidate because the operation conflicts or the project log is full.",
+				true,
+			);
+		if (response.status === 429)
+			throw new PilotError("Pharaoh project memory reached its request limit.", true);
+		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.",
+			response.status >= 400 && response.status < 500,
+		);
+	}
+	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,47 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { handleEvent } from "./hook-events.mjs";
+import { checkout, readStdin } from "./local.mjs";
+import {
+	activeMemoryRuntime,
+	readMemoryCredentials,
+	resolveMemoryHookTarget,
+} from "./user-target.mjs";
+
+// Leave margin inside the client's three-second hook timeout. The process
+// clock includes startup and imports, and no late network request can start.
+const deadline = 2_400;
+const exitQuietly = setTimeout(() => process.exit(0), Math.max(0, deadline - performance.now()));
+try {
+	const [client, root, repo] = process.argv.slice(2);
+	const input = await readStdin(1024 * 1024);
+	const credentials = await readMemoryCredentials();
+	let target = { root, repo };
+	if (root === "--user") {
+		const runtime = dirname(fileURLToPath(import.meta.url));
+		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
+		const isPrompt = input?.hook_event_name === "UserPromptSubmit";
+		const eligible = await resolveMemoryHookTarget(
+			client,
+			input?.cwd,
+			credentials,
+			isPrompt && typeof input?.prompt === "string" && Boolean(input.prompt.trim()),
+			deadline,
+		);
+		// Cleanup must still close the turn after sign-out or loss of eligibility.
+		const resolved = eligible ?? (!isPrompt && checkout(input?.cwd, deadline));
+		if (!resolved) process.exit(0);
+		target = { ...resolved, runtime };
+	}
+	const result = handleEvent(input, {
+		client,
+		...target,
+		credentials,
+		deadline,
+	});
+	if (result) process.stdout.write(JSON.stringify(result));
+} catch {
+	// Project memory never blocks ordinary work or opens a continuation.
+} finally {
+	clearTimeout(exitQuietly);
+}

package/project-memory/pharaoh-memory.mjs

@@ -0,0 +1,60 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { executeTurn } from "./execute-turn.mjs";
+import { checkout, readStdin, turnStore } from "./local.mjs";
+import { PilotError, refreshHelper } from "./memory-api.mjs";
+import {
+	activeMemoryRuntime,
+	cachedMemoryCheckout,
+	readMemoryCredentials,
+} from "./user-target.mjs";
+
+async function main(args) {
+	const [operation, option, token, compactFlag, ...extra] = args;
+	if (operation === "doctor" && args.length === 1) {
+		await refreshHelper();
+		process.stdout.write("The local Pharaoh refresh helper is ready.\n");
+		return;
+	}
+	if (
+		option !== "--turn" ||
+		!/^[a-f0-9]{64}$/.test(token) ||
+		extra.length > 0 ||
+		(compactFlag !== undefined && (compactFlag !== "--compact" || operation !== "recall")) ||
+		!["recall", "expand", "capture", "receipt"].includes(operation)
+	) {
+		throw new PilotError(
+			"Use doctor, or recall, expand, capture, or receipt with the active hook's --turn token.",
+		);
+	}
+	const cwd = process.cwd();
+	const target = checkout(cwd);
+	if (!target) throw new PilotError("Run this inside the enrolled GitHub checkout.");
+	const runtime = dirname(fileURLToPath(import.meta.url));
+	const isActive = () =>
+		activeMemoryRuntime("claude-code", runtime) || activeMemoryRuntime("codex", runtime);
+	const credentials = await readMemoryCredentials();
+	const eligible = isActive() && (await cachedMemoryCheckout(cwd, credentials));
+	const result = await executeTurn(operation, token, {
+		target: eligible ? { ...target, runtime } : target,
+		store: turnStore(),
+		read: () => readStdin(8_192),
+		compact: compactFlag === "--compact" || process.env.PHARAOH_PROJECT_MEMORY_COMPACT !== "false",
+		loadCaptureCredentials: async () => {
+			const current = await readMemoryCredentials();
+			if (eligible && (await cachedMemoryCheckout(cwd, current)) && isActive()) return current;
+		},
+	});
+	if (result !== undefined) process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+try {
+	await main(process.argv.slice(2));
+} catch (error) {
+	const message =
+		error instanceof PilotError
+			? error.message
+			: "Pharaoh project memory is temporarily unavailable.";
+	process.stderr.write(`${message}\n`);
+	process.exitCode = 1;
+}

package/project-memory/setup.d.mts

@@ -0,0 +1,14 @@
+export function syncMemoryHooks(options?: {
+	credentials?: {
+		sse_url: string;
+		project_memory?: Array<{ repo: string; revision: string | null }>;
+		project_memory_status?: "unavailable";
+	};
+	clients?: string[];
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+	cwd?: string;
+	node?: string;
+	removeLegacy?: boolean;
+	packageRoot?: URL;
+}): string[];

package/project-memory/setup.mjs

@@ -0,0 +1,151 @@
+import { lstatSync, mkdirSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { bundledHook, installMemoryBundle, packagedMemoryBundle } from "./bundle.mjs";
+import { hasLegacyHooks, updateHooks, updateUserHooks } from "./hook-config.mjs";
+import { atomicWrite, checkout, git, hasMemoryGit } from "./local.mjs";
+import {
+	eligibleCheckout,
+	legacySettingsPath,
+	memoryClientRoot,
+	projectMemoryHint,
+	readActiveMemoryClients,
+	readHookSettings,
+} from "./user-target.mjs";
+
+function userSettings(client, home, env) {
+	const codex = client === "codex";
+	const directory =
+		(codex ? env.CODEX_HOME : env.CLAUDE_CONFIG_DIR) ?? join(home, codex ? ".codex" : ".claude");
+	if (!isAbsolute(directory)) throw new Error("Client configuration directory must be absolute.");
+	return join(directory, codex ? "hooks.json" : "settings.json");
+}
+
+function writeSettings(path, previous, next) {
+	if (JSON.stringify(previous) === JSON.stringify(next)) return;
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	const info = lstatSync(directory);
+	if (!info.isDirectory() || info.uid !== process.getuid?.())
+		throw new Error("Client settings directory is not owner-controlled.");
+	atomicWrite(path, `${JSON.stringify(next, null, "\t")}\n`);
+}
+
+function migrateCheckout(client, target) {
+	if (!target) return;
+	const path = legacySettingsPath(client, target.root);
+	const before = readHookSettings(path);
+	if (!hasLegacyHooks(before, client, target.root)) return;
+	const relative = path.slice(target.root.length + 1);
+	if (realpathSync(dirname(path)) !== dirname(path) || git(target.root, "ls-files", "--", relative))
+		throw new Error("The earlier checkout hook is in tracked or linked settings.");
+	// The legacy installer always wrote ignored files. Never create or alter
+	// Git excludes, and never migrate project settings that can be committed.
+	git(target.root, "check-ignore", "--quiet", "--no-index", "--", relative);
+	writeSettings(path, before, updateHooks(before, client, target, true));
+}
+
+/** Run only as part of a deliberate normal setup, upgrade, clean or logout. */
+export function syncMemoryHooks({
+	credentials,
+	clients = [],
+	home = homedir(),
+	env = process.env,
+	cwd = process.cwd(),
+	node = process.execPath,
+	removeLegacy = false,
+	packageRoot,
+} = {}) {
+	const hint = projectMemoryHint(credentials);
+	const root = memoryClientRoot(home);
+	const previous = readActiveMemoryClients(home);
+	if (!removeLegacy && credentials?.project_memory_status === "unavailable") {
+		return [
+			"Pharaoh: project memory eligibility could not be checked. Existing hook settings were kept. Rerun normal setup to retry.",
+		];
+	}
+	if (!hint.length && !Object.keys(previous).length && !removeLegacy) return [];
+	const notices = [];
+	const active = {};
+	const configured = [];
+	let installed;
+	let digest;
+	const target = removeLegacy ? checkout(cwd) : eligibleCheckout(cwd, hint);
+	const pendingCheckout =
+		!target && hint.some((entry) => entry?.revision === null) ? checkout(cwd) : undefined;
+	const pendingRoot =
+		pendingCheckout &&
+		hint.some(
+			(entry) =>
+				entry?.revision === null &&
+				entry.repo?.toLowerCase() === pendingCheckout.repo.toLowerCase(),
+		)
+			? pendingCheckout.root
+			: undefined;
+
+	if (hint.length) {
+		try {
+			if (!hasMemoryGit || typeof process.getuid !== "function")
+				throw new Error("Project memory needs a POSIX client with system Git.");
+			const bundle = packagedMemoryBundle(packageRoot);
+			digest = bundle.sha256;
+			installed = bundledHook(installMemoryBundle(root, target?.root ?? pendingRoot, bundle));
+		} catch (error) {
+			return [`Pharaoh: project memory setup unavailable. ${error.message}`];
+		}
+	}
+
+	for (const client of ["claude-code", "codex"]) {
+		const desired = clients.includes(client) ? installed : undefined;
+		if (!desired && !previous[client] && !removeLegacy) continue;
+		try {
+			const path = userSettings(client, home, env);
+			const before = readHookSettings(path);
+			writeSettings(path, before, updateUserHooks(before, client, desired, node));
+			if (desired) {
+				active[client] = digest;
+				configured.push(client);
+			}
+		} catch {
+			if (desired && previous[client]) active[client] = previous[client];
+			if (desired || previous[client])
+				notices.push(
+					`Pharaoh: project memory could not update ${client} hooks. Check the client settings and rerun normal setup.`,
+				);
+		}
+	}
+
+	// This private activation record makes older hook commands inert even if a
+	// client still has them loaded or its settings could not be updated.
+	const activePath = join(root, "active.json");
+	if (Object.keys(active).length) {
+		if (JSON.stringify(previous) !== JSON.stringify(active))
+			atomicWrite(activePath, `${JSON.stringify(active)}\n`);
+		if (configured.length) {
+			notices.push(
+				"Pharaoh project memory is set up for your eligible repositories. Start a new local conversation.",
+			);
+			if (hint.some((entry) => entry?.revision === null))
+				notices.push(
+					"A connected repository is still mapping. Its hooks will start memory automatically when the mapped revision is available.",
+				);
+			if (configured.includes("codex"))
+				notices.push("In Codex, review and trust the Pharaoh hooks in /hooks or Settings > Hooks.");
+		}
+	} else if (Object.keys(previous).length) {
+		rmSync(activePath, { force: true });
+	}
+	// The old checkout hook is a fallback until its replacement settings and
+	// the private activation record are both in place.
+	for (const client of ["claude-code", "codex"]) {
+		if (!removeLegacy && !configured.includes(client)) continue;
+		try {
+			migrateCheckout(client, target);
+		} catch {
+			notices.push(
+				`Pharaoh: the earlier ${client} checkout hook remains in place for this checkout.`,
+			);
+		}
+	}
+	return notices;
+}