@pharaoh-so/mcp 0.3.53 → 0.3.56

package/dist/install-skills.js

@@ -6,7 +6,7 @@
  * and OpenClaw skills in ~/.openclaw/skills/. Also merges the Pharaoh MCP
  * server config into OpenClaw.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,8 +16,11 @@ import { getPackageVersion, PACKAGE_NAME, pinnedPackageSpec } from "./version.js
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the bundled package root (one level up from dist/). */
 const PKG_ROOT = join(__dirname, "..");
-/** Path to the bundled skills directory. */
-const BUNDLED_SKILLS_DIR = join(PKG_ROOT, "skills");
+/**
+ * Path to the bundled skills: npx's render of skills/ (written by the build's
+ * generate:commands), so installs copy them as-is and never see channel markers.
+ */
+const BUNDLED_SKILLS_DIR = join(PKG_ROOT, "npx-skills");
 /** Path to the bundled slash commands directory. */
 const BUNDLED_COMMANDS_DIR = join(PKG_ROOT, "commands");
 /** Path to the bundled Claude Code hooks (hooks.json and the Grep routing hook). */
@@ -202,8 +205,9 @@ function removeLegacyClaudePlugin(home) {
 /** Plugin id the pre-marketplace installer wrote into installed_plugins.json. */
 const LEGACY_PLUGIN_ID = "pharaoh@pharaoh-so";
 /**
- * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
- * marketplace directory and any pre-marketplace install.
+ * Uninstall Pharaoh's Claude Code plugin (through the CLI, then the local
+ * marketplace directory and any pre-marketplace install) and its block in
+ * ~/.claude/CLAUDE.md. Run by --clean and --logout.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
@@ -213,6 +217,7 @@ export function uninstallClaudePlugin(home = homedir(), claude = claudeCliFor(ho
     claude(["plugin", "marketplace", "remove", MARKETPLACE_NAME]);
     rmSync(claudeMarketplaceDir(home), { recursive: true, force: true });
     removeLegacyClaudePlugin(home);
+    removeClaudeMdBlock(home);
 }
 /**
  * Copy every skill directory from `srcDir` to `dstDir`, prefixing both the
@@ -604,10 +609,11 @@ export function mergeOpenClawConfig(home = homedir()) {
 // ── Claude Code permissions ─────────────────────────────────────────
 /**
  * Rules the interactive setup adds to `permissions.allow` in
- * ~/.claude/settings.json: the six read-only tools and `pharaoh_account`,
+ * ~/.claude/settings.json: the seven read-only tools (`readOnlyHint: true`),
  * each by full name. Never a prefix rule — `mcp__pharaoh` also auto-approves
- * account deletion and `pharaoh_admin`, so a prompt injection could run them
- * with no human in the loop (security review SC-6). Those tools keep prompting.
+ * the tools that change things (`pharaoh_manage_repo`, which queues a re-map,
+ * and the superadmin tools), so a prompt injection could run them with
+ * no human in the loop (security review SC-6). Those tools keep prompting.
  */
 export const PHARAOH_ALLOW_RULES = [
     "mcp__pharaoh__get_codebase_map",
@@ -664,17 +670,210 @@ export function describeAllowReadTools(result) {
     const count = PHARAOH_ALLOW_RULES.length;
     switch (result) {
         case "added":
-            return `Pharaoh: allowed ${count} tools by name in ~/.claude/settings.json (permissions.allow): the read-only tools and pharaoh_account. Account deletion and pharaoh_admin still prompt.`;
+            return `Pharaoh: allowed ${count} read-only tools by name in ~/.claude/settings.json (permissions.allow). pharaoh_manage_repo, which switches or refreshes a repo, still asks first.`;
         case "migrated":
-            return `Pharaoh: replaced the blanket mcp__pharaoh rule in ~/.claude/settings.json with ${count} tools by name. Account deletion and pharaoh_admin prompt again.`;
+            return `Pharaoh: replaced the blanket mcp__pharaoh rule in ~/.claude/settings.json with ${count} read-only tools by name. pharaoh_manage_repo asks first again.`;
         case "current":
-            return `Pharaoh: ~/.claude/settings.json already allows the ${count} read-only and account tools by name.`;
+            return `Pharaoh: ~/.claude/settings.json already allows the ${count} read-only tools by name.`;
         case "no-settings":
             return "Pharaoh: no ~/.claude/settings.json yet, so Pharaoh's tools ask before they run. The rules to allow the read-only tools are in the README (Security).";
         case "error":
             return "Pharaoh: ~/.claude/settings.json is not valid JSON; left as is. Pharaoh's tools ask before they run.";
     }
 }
+// ── Claude Code instructions (~/.claude/CLAUDE.md) ──────────────────
+//
+// Agents acted on the Pharaoh-first line only from a CLAUDE.md, not from server
+// instructions or a hook (benchmarks/adoption/results/2026-10-23-everyday-auto-line.md).
+// The file is the user's: the interactive setup adds the line on a yes, inside
+// markers, and --clean/--logout remove exactly what it wrote.
+/** The Pharaoh-first line; same text as PHARAOH_SCOPED_LINE in scripts/adoption-grade.ts. */
+const PHARAOH_CLAUDE_MD_LINE = "In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.";
+/** What the interactive setup asks before writing the line. */
+export const CLAUDE_MD_QUESTION = `Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  "${PHARAOH_CLAUDE_MD_LINE}"\n[Y/n] `;
+/** File under ~/.pharaoh holding the user's answer, so setup asks once. */
+const CLAUDE_MD_ANSWER_FILE = "claude-md-answer";
+/**
+ * Open flags that refuse a symlink even if one is swapped in after the check
+ * (SC-7; O_NOFOLLOW is undefined on Windows). A new block is appended, so the
+ * user's bytes are never rewritten; a stale block or a removal rewrites the file.
+ */
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const APPEND_NO_FOLLOW = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | NO_FOLLOW;
+const REWRITE_NO_FOLLOW = constants.O_WRONLY | constants.O_TRUNC | NO_FOLLOW;
+/** Write `text` to `path` opened with `flags` (APPEND_NO_FOLLOW or REWRITE_NO_FOLLOW). */
+function writeNoFollow(path, text, flags) {
+    const fd = openSync(path, flags);
+    try {
+        writeFileSync(fd, text);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Pharaoh's block. `pharaoh-mcp:start+nl` records that the installer also added
+ * the newline before it (the file didn't end in one), so removal takes it back too.
+ */
+function claudeMdBlock(addedNewline) {
+    const start = `<!-- pharaoh-mcp:start${addedNewline ? "+nl" : ""} (managed by npx ${PACKAGE_NAME}; --clean or --logout removes it) -->`;
+    return `${start}\n${PHARAOH_CLAUDE_MD_LINE}\n<!-- pharaoh-mcp:end -->\n`;
+}
+/**
+ * Find the one Pharaoh block in `text`: null when there is none, "broken"
+ * when a marker is missing its pair, repeated or out of order.
+ */
+function findClaudeMdBlock(text) {
+    const starts = [...text.matchAll(/^<!-- pharaoh-mcp:start(\+nl)?\b[^\n]*\n/gm)];
+    const ends = [...text.matchAll(/^<!-- pharaoh-mcp:end -->\n?/gm)];
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    const [start, end] = [starts[0], ends[0]];
+    const body = start ? start.index + start[0].length : 0;
+    if (starts.length !== 1 || ends.length !== 1 || end.index < body)
+        return "broken";
+    return {
+        from: start.index,
+        body,
+        to: end.index,
+        through: end.index + end[0].length,
+        addedNewline: start[1] !== undefined,
+    };
+}
+/** Read ~/.claude/CLAUDE.md without following a symlink. */
+function readClaudeMd(home) {
+    const path = join(home, ".claude", "CLAUDE.md");
+    const dir = lstatSync(join(home, ".claude"), { throwIfNoEntry: false });
+    if (!dir)
+        return { state: "no-claude", path, text: "", block: null };
+    const file = lstatSync(path, { throwIfNoEntry: false });
+    if (!dir.isDirectory() || (file && !file.isFile())) {
+        return { state: "kept", path, text: "", block: null };
+    }
+    const text = file ? readFileSync(path, "utf-8") : "";
+    const block = findClaudeMdBlock(text);
+    if (block === "broken")
+        return { state: "kept", path, text, block: null };
+    if (!block) {
+        return {
+            state: text.includes(PHARAOH_CLAUDE_MD_LINE) ? "current" : "absent",
+            path,
+            text,
+            block,
+        };
+    }
+    const current = text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`;
+    return { state: current ? "current" : "stale", path, text, block };
+}
+/**
+ * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
+ * never a proxy start. Asks only when the block is absent and the user hasn't
+ * answered before; a stale block (an earlier yes) is updated without asking.
+ * The line is appended inside markers, and nothing else in the file changes.
+ *
+ * @param ask - Asks the user: true for yes, false for no, null when input ended.
+ * @param isTerminal - Whether stdin and stderr are a terminal; false asks and writes nothing.
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns What happened, for `describeClaudeMdOutcome`.
+ */
+export async function offerClaudeMdLine(ask, isTerminal, home = homedir()) {
+    if (!isTerminal)
+        return "no-terminal";
+    const answerPath = join(home, ".pharaoh", CLAUDE_MD_ANSWER_FILE);
+    try {
+        let file = readClaudeMd(home);
+        // A saved answer also silences the add-it-yourself line of "kept": a no stands.
+        const answered = lstatSync(answerPath, { throwIfNoEntry: false }) !== undefined;
+        if (answered && (file.state === "absent" || file.state === "kept"))
+            return "answered";
+        if (file.state === "absent") {
+            const yes = await ask();
+            if (yes === null)
+                return "cancelled";
+            if (!yes) {
+                saveClaudeMdAnswer(home, answerPath, "no");
+                return "declined";
+            }
+            file = readClaudeMd(home); // again: it may have changed while the user answered
+        }
+        if (file.state === "absent") {
+            const newline = file.text !== "" && !file.text.endsWith("\n");
+            writeNoFollow(file.path, `${newline ? "\n" : ""}${claudeMdBlock(newline)}`, APPEND_NO_FOLLOW);
+            saveClaudeMdAnswer(home, answerPath, "yes");
+            return "added";
+        }
+        if (file.state === "stale") {
+            const { body, to } = file.block;
+            const next = `${file.text.slice(0, body)}${PHARAOH_CLAUDE_MD_LINE}\n${file.text.slice(to)}`;
+            writeNoFollow(file.path, next, REWRITE_NO_FOLLOW);
+            return "updated";
+        }
+        return file.state;
+    }
+    catch {
+        // ALLOWED-CATCH: setup is done; the user gets the line to add by hand, and no saved answer, so the next setup asks again
+        return "failed";
+    }
+}
+/** Save the user's answer (0600). Never through a symlink: `wx` refuses any existing path. */
+function saveClaudeMdAnswer(home, answerPath, answer) {
+    try {
+        ensurePharaohHome(join(home, ".pharaoh"));
+        writeFileSync(answerPath, `${answer}\n`, { mode: 0o600, flag: "wx" });
+    }
+    catch {
+        // ALLOWED-CATCH: an answer that can't be saved only means the next setup asks again
+    }
+}
+/**
+ * The line the interactive setup prints for an `offerClaudeMdLine` outcome, or
+ * null when there is nothing to say (already current, already answered, no terminal).
+ *
+ * @param outcome - What `offerClaudeMdLine` returned.
+ */
+export function describeClaudeMdOutcome(outcome) {
+    const byHand = `To have Claude check Pharaoh first, add this line to it yourself:\n  ${PHARAOH_CLAUDE_MD_LINE}`;
+    switch (outcome) {
+        case "added":
+            return `Pharaoh: added the line to ~/.claude/CLAUDE.md, between pharaoh-mcp markers. npx ${PACKAGE_NAME} --clean removes it.`;
+        case "updated":
+            return "Pharaoh: updated its line in ~/.claude/CLAUDE.md.";
+        case "declined":
+            return "Pharaoh: left ~/.claude/CLAUDE.md as it is. Setup won't ask again.";
+        case "kept":
+            return `Pharaoh: left ~/.claude/CLAUDE.md as it is (it's a symlink, or its Pharaoh markers don't pair up). ${byHand}`;
+        case "failed":
+            return `Pharaoh: couldn't write ~/.claude/CLAUDE.md. ${byHand}`;
+        default:
+            return null;
+    }
+}
+/**
+ * Remove Pharaoh's block from ~/.claude/CLAUDE.md, taking out only bytes the
+ * installer wrote, and forget the answer so the next setup asks again. A file
+ * left empty stays: there's no telling whether the user had it before. Never
+ * throws: --clean and --logout go on to their other steps.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ */
+function removeClaudeMdBlock(home) {
+    try {
+        const { path, text, block } = readClaudeMd(home);
+        if (block) {
+            // The newline before a start+nl marker is Pharaoh's only while the block
+            // ends the file; once the user writes below it, it ends their line.
+            const ownsNewline = block.addedNewline && block.from > 0 && block.through === text.length;
+            const from = ownsNewline ? block.from - 1 : block.from;
+            writeNoFollow(path, text.slice(0, from) + text.slice(block.through), REWRITE_NO_FOLLOW);
+        }
+        rmSync(join(home, ".pharaoh", CLAUDE_MD_ANSWER_FILE), { force: true });
+    }
+    catch (err) {
+        // ALLOWED-CATCH: the other cleanup steps (credentials on --logout) must still run; the user is told what's left
+        const code = err.code;
+        process.stderr.write(`Pharaoh: couldn't remove its line from ~/.claude/CLAUDE.md${code ? ` (${code})` : ""}. Delete the pharaoh-mcp block by hand.\n`);
+    }
+}
 /**
  * Main entry point for --install-skills, also run on every proxy start.
  *

package/dist/refresh.d.ts

@@ -48,10 +48,11 @@ export type RefreshFailureAction = "reauth" | "preserve" | "transient";
  * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
  * @param path    optional custom credentials path (for tests)
  * @param timeoutMs how long the refresh request may take (for tests)
+ * @param strictOrigin require credentials from this origin and refuse refresh redirects
  * @returns New or adopted credentials, or a classified failure. A lock held by
  *   another proxy for too long is `transient` (credentials untouched).
  */
-export declare function refreshIfNeeded(creds: Credentials, server: string, path?: string, timeoutMs?: number): Promise<RefreshOutcome>;
+export declare function refreshIfNeeded(creds: Credentials, server: string, path?: string, timeoutMs?: number, strictOrigin?: boolean): Promise<RefreshOutcome>;
 /**
  * Read credentials from disk and refresh if the access token is expired.
  *
@@ -63,4 +64,9 @@ export declare function refreshIfNeeded(creds: Credentials, server: string, path
  * Intended use: called at proxy startup to replace the current "die if expired"
  * branch in index.ts.
  */
-export declare function loadAndRefresh(server: string, path?: string): Promise<RefreshOutcome | null>;
+export declare function loadAndRefresh(server: string, path?: string, strictOrigin?: boolean): Promise<RefreshOutcome | null>;
+/** Refresh for a client that accepts credentials only from its configured origin. */
+export declare function originBoundRefresh(server: string, path?: string): {
+    load: () => Promise<RefreshOutcome | null>;
+    renew: (creds: Credentials) => Promise<RefreshOutcome>;
+};

package/dist/refresh.js

@@ -41,10 +41,11 @@ const REFRESH_TIMEOUT_MS = 10_000;
  * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
  * @param path    optional custom credentials path (for tests)
  * @param timeoutMs how long the refresh request may take (for tests)
+ * @param strictOrigin require credentials from this origin and refuse refresh redirects
  * @returns New or adopted credentials, or a classified failure. A lock held by
  *   another proxy for too long is `transient` (credentials untouched).
  */
-export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_TIMEOUT_MS) {
+export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_TIMEOUT_MS, strictOrigin = false) {
     let release;
     try {
         release = await acquireCredentialsLock(path);
@@ -58,11 +59,13 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
     }
     try {
         const current = readCredentials(path);
+        const source = current ?? creds;
+        if (strictOrigin && !matchesOrigin(source, server))
+            return originMismatch();
         if (current && current.access_token !== creds.access_token && !isExpired(current)) {
             return { ok: true, creds: current };
         }
-        const source = current ?? creds;
-        const outcome = await requestRefresh(source, server, timeoutMs, path);
+        const outcome = await requestRefresh(source, server, timeoutMs, path, strictOrigin);
         if (outcome.ok || outcome.action !== "reauth")
             return outcome;
         const after = readCredentials(path);
@@ -70,6 +73,8 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
             deleteCredentials(path);
             return outcome;
         }
+        if (strictOrigin && !matchesOrigin(after, server))
+            return originMismatch();
         return isExpired(after) ? outcome : { ok: true, creds: after };
     }
     finally {
@@ -80,7 +85,7 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
  * One refresh-grant round trip: POST the refresh token, persist and return the
  * new credentials on success, or classify the failure. Caller holds the lock.
  */
-async function requestRefresh(creds, server, timeoutMs, path) {
+async function requestRefresh(creds, server, timeoutMs, path, strictOrigin = false) {
     // Guard: refresh token itself expired. No point hitting the server — the
     // grant will fail with invalid_grant. Short-circuit to reauth.
     if (isRefreshExpired(creds)) {
@@ -101,6 +106,7 @@ async function requestRefresh(creds, server, timeoutMs, path) {
             body: JSON.stringify({
                 refresh_token: creds.refresh_token,
             }),
+            redirect: strictOrigin ? "error" : undefined,
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
@@ -192,15 +198,36 @@ async function requestRefresh(creds, server, timeoutMs, path) {
  * Intended use: called at proxy startup to replace the current "die if expired"
  * branch in index.ts.
  */
-export async function loadAndRefresh(server, path) {
+export async function loadAndRefresh(server, path, strictOrigin = false) {
     const creds = readCredentials(path);
     if (!creds)
         return null;
+    if (strictOrigin && !matchesOrigin(creds, server))
+        return originMismatch();
     // Access token still valid — no refresh needed.
     const expiresAt = new Date(creds.expires_at).getTime();
     const bufferMs = creds.expires_in * 1000 * 0.1;
     if (Date.now() < expiresAt - bufferMs) {
         return { ok: true, creds };
     }
-    return refreshIfNeeded(creds, server, path);
+    return refreshIfNeeded(creds, server, path, undefined, strictOrigin);
+}
+/** A fixed-origin caller must never send credentials issued by another server. */
+function matchesOrigin(creds, server) {
+    try {
+        return new URL(creds.sse_url).origin === new URL(server).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function originMismatch() {
+    return { ok: false, action: "transient", message: "Credentials belong to a different server" };
+}
+/** Refresh for a client that accepts credentials only from its configured origin. */
+export function originBoundRefresh(server, path) {
+    return {
+        load: () => loadAndRefresh(server, path, true),
+        renew: (creds) => refreshIfNeeded(creds, server, path, undefined, true),
+    };
 }

package/dist/setup.d.ts

@@ -54,3 +54,8 @@ export declare function runSetup(options?: {
     home?: string;
     claude?: ClaudeCli;
 }): boolean;
+/** Detect the local Codex CLI before touching any settings. */
+export declare function hasCodex(): boolean;
+/** Preserve custom registrations and any existing disabled setting. */
+export declare function runCodexSetup(): boolean;
+export declare function cleanCodexSetup(): void;

package/dist/setup.js

@@ -185,3 +185,69 @@ export function runSetup(options) {
         printLines(`Pharaoh: registered as global MCP server (scope: user) running ${spec}`);
     return true;
 }
+/** Detect the local Codex CLI before touching any settings. */
+export function hasCodex() {
+    try {
+        execFileSync("codex", ["--version"], { stdio: "pipe", timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function codexMcp(args) {
+    return execFileSync("codex", ["mcp", ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30_000,
+    });
+}
+function configuredCodexPharaoh() {
+    try {
+        const { transport, enabled } = JSON.parse(codexMcp(["get", "pharaoh", "--json"]));
+        return {
+            owned: transport?.type === "stdio" &&
+                transport.command === "npx" &&
+                transport.args?.length === 1 &&
+                /^@pharaoh-so\/mcp@\d+\.\d+\.\d+$/.test(transport.args[0]) &&
+                !transport.env &&
+                !transport.env_vars?.length &&
+                !transport.cwd,
+            enabled,
+        };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "stderr" in error &&
+            typeof error.stderr === "string" &&
+            error.stderr.includes("No MCP server named 'pharaoh' found."))
+            return null;
+        throw error;
+    }
+}
+/** Preserve custom registrations and any existing disabled setting. */
+export function runCodexSetup() {
+    try {
+        const existing = configuredCodexPharaoh();
+        if (existing && (!existing.owned || existing.enabled === false))
+            return true;
+        codexMcp(["add", "pharaoh", "--", "npx", pinnedPackageSpec()]);
+        return true;
+    }
+    catch {
+        printLines("Pharaoh: Codex setup could not update its MCP registration.");
+        return false;
+    }
+}
+export function cleanCodexSetup() {
+    if (!hasCodex())
+        return;
+    try {
+        if (configuredCodexPharaoh()?.owned)
+            codexMcp(["remove", "pharaoh"]);
+    }
+    catch {
+        printLines("Pharaoh: Codex setup could not remove its MCP registration.");
+    }
+}