@pharaoh-so/mcp 0.3.53 → 0.3.56

package/project-memory/pharaoh-memory.mjs

@@ -0,0 +1,55 @@
+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", "nothing-material", "receipt"].includes(operation)
+	) {
+		throw new PilotError(
+			"Use doctor, or recall, expand, capture, receipt, or nothing-material 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 active =
+		activeMemoryRuntime("claude-code", runtime) || activeMemoryRuntime("codex", runtime);
+	const eligible = active && (await cachedMemoryCheckout(cwd, await readMemoryCredentials()));
+	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 === "true",
+	});
+	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;
+}

package/project-memory/user-target.mjs

@@ -0,0 +1,221 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hasLegacyHooks } from "./hook-config.mjs";
+import { atomicWrite, checkout, git } from "./local.mjs";
+import { PROJECT_MEMORY_ORIGIN, requestMemoryReadiness } from "./memory-api.mjs";
+
+const REVISION = /^(?!0{40}$)[a-f0-9]{40}$/;
+const READINESS_RETRY_MS = 15_000;
+const LEGACY_SETTINGS = {
+	"claude-code": ".claude/settings.local.json",
+	codex: ".codex/hooks.json",
+};
+
+export function legacySettingsPath(client, root) {
+	return join(root, LEGACY_SETTINGS[client]);
+}
+
+export function projectMemoryHint(credentials) {
+	if (!credentials || !Array.isArray(credentials.project_memory)) return [];
+	try {
+		if (new URL(credentials.sse_url).origin !== PROJECT_MEMORY_ORIGIN) return [];
+	} catch {
+		return [];
+	}
+	return credentials.project_memory;
+}
+
+function matchingHint(target, hints) {
+	return hints.find(
+		(entry) =>
+			typeof entry?.repo === "string" && entry.repo.toLowerCase() === target.repo.toLowerCase(),
+	);
+}
+
+function hasMappedCommit(target, revision) {
+	if (typeof revision !== "string" || !REVISION.test(revision)) return false;
+	try {
+		// An origin URL is editable. Require an actual GitHub-mapped commit
+		// locally, without fetching, consulting replace refs, or running hooks.
+		return git(target.root, "cat-file", "-t", revision) === "commit";
+	} catch {
+		return false;
+	}
+}
+
+export function eligibleCheckout(cwd, hints) {
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	if (target && hasMappedCommit(target, matchingHint(target, hints)?.revision)) return target;
+}
+
+function hash(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function readReadiness(path, binding) {
+	try {
+		const stat = lstatSync(path);
+		if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077 || stat.size > 512)
+			return;
+		const state = JSON.parse(readFileSync(path, "utf8"));
+		if (state.binding === binding) return state;
+	} catch {
+		// A missing or unreadable cache cannot authorize a checkout.
+	}
+}
+
+function tryReadinessLease(path, now) {
+	try {
+		try {
+			const stat = lstatSync(path);
+			if (
+				!stat.isFile() ||
+				stat.uid !== process.getuid?.() ||
+				now - stat.mtimeMs < READINESS_RETRY_MS
+			)
+				return;
+			rmSync(path, { force: true });
+		} catch (error) {
+			if (error.code !== "ENOENT") return;
+		}
+		const owner = randomUUID();
+		writeFileSync(path, owner, { flag: "wx", mode: 0o600 });
+		return () => {
+			try {
+				if (readFileSync(path, "utf8") === owner) rmSync(path, { force: true });
+			} catch {
+				// A stale lease expires without blocking ordinary work.
+			}
+		};
+	} catch {
+		// Another hook is already checking or private local state is unavailable.
+	}
+}
+
+async function resolveRevision(repo, credentials, probe) {
+	const session = credentials.project_memory_session;
+	if (typeof session !== "string" || !/^[0-9a-f-]{36}$/.test(session)) return;
+	const binding = hash(session);
+	const path = join(memoryClientRoot(), `ready-${hash(repo.toLowerCase())}.json`);
+	const saved = readReadiness(path, binding);
+	if (typeof saved?.revision === "string" && REVISION.test(saved.revision)) return saved.revision;
+	const now = Date.now();
+	if (!probe || now - (saved?.checkedAt ?? 0) < READINESS_RETRY_MS) return;
+	const release = tryReadinessLease(`${path}.lock`, now);
+	if (!release) return;
+	try {
+		const latest = readReadiness(path, binding);
+		if (typeof latest?.revision === "string" && REVISION.test(latest.revision))
+			return latest.revision;
+		if (now - (latest?.checkedAt ?? 0) < READINESS_RETRY_MS) return;
+		atomicWrite(path, JSON.stringify({ binding, checkedAt: now }));
+		const revision = await requestMemoryReadiness(repo, credentials);
+		if (typeof revision === "string" && REVISION.test(revision)) {
+			atomicWrite(path, JSON.stringify({ binding, checkedAt: now, revision }));
+			return revision;
+		}
+	} catch {
+		// A cache failure must not activate memory or block the normal prompt.
+	} finally {
+		release();
+	}
+}
+
+async function resolveMappedCheckout(target, credentials, hint, probe) {
+	const revision =
+		hint.revision === null ? await resolveRevision(hint.repo, credentials, probe) : hint.revision;
+	if (hasMappedCommit(target, revision)) return target;
+}
+
+export async function cachedMemoryCheckout(cwd, credentials) {
+	const hints = projectMemoryHint(credentials);
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	const hint = target && matchingHint(target, hints);
+	if (hint) return resolveMappedCheckout(target, credentials, hint, false);
+}
+
+export function readHookSettings(path) {
+	try {
+		const info = lstatSync(path);
+		if (!info.isFile() || info.uid !== process.getuid?.() || info.size > 512 * 1024)
+			throw new Error("Expected a regular owner-controlled hook settings file.");
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+
+export async function resolveMemoryHookTarget(client, cwd, credentials, probe = false) {
+	if (!Object.hasOwn(LEGACY_SETTINGS, client)) return;
+	const hints = projectMemoryHint(credentials);
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	const hint = target && matchingHint(target, hints);
+	if (!hint) return;
+	try {
+		// A checkout enrolled by the original pilot may still have its own hook.
+		// Leave that hook in charge until normal setup migrates the checkout.
+		if (
+			hasLegacyHooks(readHookSettings(legacySettingsPath(client, target.root)), client, target.root)
+		)
+			return;
+	} catch {
+		// A client settings file we cannot inspect is not safe to double-enroll.
+		return;
+	}
+	return resolveMappedCheckout(target, credentials, hint, probe);
+}
+
+export function memoryClientRoot(home = homedir()) {
+	return join(home, ".pharaoh", "project-memory-client");
+}
+
+export function readActiveMemoryClients(home = homedir()) {
+	try {
+		const root = memoryClientRoot(home);
+		const directory = lstatSync(root);
+		if (!directory.isDirectory() || directory.uid !== process.getuid?.() || directory.mode & 0o077)
+			return {};
+		const path = join(root, "active.json");
+		const file = lstatSync(path);
+		if (!file.isFile() || file.uid !== process.getuid?.() || file.mode & 0o077 || file.size > 512)
+			return {};
+		const active = JSON.parse(readFileSync(path, "utf8"));
+		return Object.fromEntries(
+			Object.keys(LEGACY_SETTINGS).flatMap((client) => {
+				const digest = active?.[client];
+				return typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)
+					? [[client, digest]]
+					: [];
+			}),
+		);
+	} catch {
+		return {};
+	}
+}
+
+export function activeMemoryRuntime(client, directory, home = homedir()) {
+	const digest = readActiveMemoryClients(home)[client];
+	return Boolean(digest && directory === join(realpathSync(memoryClientRoot(home)), digest));
+}
+
+export async function readMemoryCredentials() {
+	try {
+		const { CREDENTIALS_PATH, readCredentials } = await import("./runtime/credentials.js");
+		const stat = lstatSync(CREDENTIALS_PATH);
+		if (
+			stat.isFile() &&
+			stat.uid === process.getuid?.() &&
+			!(stat.mode & 0o077) &&
+			stat.size <= 65_536
+		)
+			return readCredentials();
+	} catch {
+		// No current owner-private credential file.
+	}
+}