beehaven 0.8.16

package/dist/commands/mcp-install.js

@@ -0,0 +1,476 @@
+/**
+ * mcp-install — put Clearly in front of the user's agents in one command.
+ *
+ * ## Why this exists
+ *
+ * ⚠⚠ `mcp-config` PRINTED A JSON BLOCK AND CALLED IT DONE, AND THE NUMBERS SAY IT WAS NOT.
+ * Its own header records that it was written to fix "the documented flow ended one step short of
+ * working" — and then stopped one step short itself. Measured since: 14 tokens minted from the
+ * CLI and, on production, **2 MCP tool calls in the table's entire history**. Minting is not
+ * adoption. What stands between the two is a person opening `~/.claude/mcp.json` in an editor and
+ * merging JSON by hand, correctly, in a file that may already have servers in it.
+ *
+ * The Mac app has done this properly for a while (`mcp-installer.ts`). A CLI-only user — the
+ * headless box, the Linux dev, anyone who never installs the app — got the printout.
+ *
+ * ⚠ THE CLIENT DEFINITIONS AND THE MARKER ARE DELIBERATELY IDENTICAL TO THE APP'S. Same config
+ * paths, same `_managed-by` key, same `mcp-remote` bridge for Claude Desktop's stdio transport.
+ * Two installers writing one file with different ideas of what "ours" means is how a config gets
+ * clobbered or double-written. `verify-mcp-parity.mjs` reads both files and fails if they drift.
+ *
+ * ⚠ AND IT IS ADDITIVE, NEVER AUTHORITATIVE. It merges one key into `mcpServers`, backs the file
+ * up first when it finds an entry it did not write, and leaves every other server alone. A user's
+ * MCP config is theirs; we are a guest in it.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+/** ⚠ Must match `mcp-installer.ts` in the Mac app — pinned by verify-mcp-parity. */
+export const MAGIC_KEY = '_managed-by';
+export const MAGIC_VAL = 'clearly-mac-app';
+export function clientDefs() {
+    const home = os.homedir();
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            transport: 'http',
+            /**
+             * ⚠⚠ `~/.claude.json`, NOT `~/.claude/mcp.json` — THE OLD PATH WAS NEVER READ.
+             * Proven on Claude Code 2.1.251: `claude mcp add --scope user` writes `mcpServers` into
+             * `~/.claude.json`, and `claude mcp list` outside a project with its own `.mcp.json` showed
+             * no server at all for the old file. The token was valid the whole time; the client simply
+             * never looked. `apps/electron/electron/mcp-installer.ts` had the identical bug and
+             * `verify-mcp-parity` is what caught that these two doors had stopped agreeing.
+             *
+             * ⚠ READS STILL WORK GENERICALLY because the shape is the same — `mcpServers` at the top
+             * level — so only the WRITE and REMOVE need `kind: 'claude'`. Detection is unchanged.
+             */
+            configPath: path.join(home, '.claude.json'),
+            detect: path.join(home, '.claude'),
+            kind: 'claude',
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            transport: 'stdio',
+            configPath: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+            detect: path.join(home, 'Library', 'Application Support', 'Claude'),
+            appBundle: ['/Applications/Claude.app'],
+            kind: 'json',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            transport: 'http',
+            configPath: path.join(home, '.cursor', 'mcp.json'),
+            detect: path.join(home, '.cursor'),
+            appBundle: ['/Applications/Cursor.app'],
+            kind: 'json',
+        },
+        {
+            /**
+             * ⚠ STDIO VIA `mcp-remote`, NOT CODEX'S NATIVE HTTP TRANSPORT — and the reason is the token.
+             * `codex mcp add --url` supports only `--bearer-token-env-var`, i.e. the credential must be
+             * in the ENVIRONMENT when Codex runs. We cannot reliably put it there: a GUI launch, a fresh
+             * shell or a different terminal would each miss it, and the failure is a server that is
+             * configured and silently cannot authenticate. The bridge carries the header in the config
+             * instead — the same trade already accepted for Claude Desktop, and one mechanism rather
+             * than two.
+             */
+            id: 'codex',
+            label: 'Codex',
+            transport: 'stdio',
+            configPath: path.join(home, '.codex', 'config.toml'),
+            detect: path.join(home, '.codex'),
+            kind: 'codex',
+        },
+    ];
+}
+/**
+ * The server entry we write.
+ *
+ * ⚠ CLAUDE DESKTOP SPEAKS STDIO AND OUR SERVER SPEAKS HTTP, so that one client gets the standard
+ * `mcp-remote` bridge rather than a proxy of our own. The cost is honest: it needs `npx` on PATH
+ * at launch, and if it is missing the connection fails VISIBLY in Claude Desktop's MCP panel —
+ * strictly better than a silent nothing.
+ *
+ * ⚠ THE TOKEN IS A HEADER ARG, NEVER AN ENV VAR. The server authenticates with
+ * `Authorization: Bearer`; an env var is decoration nothing reads.
+ */
+export function serverBlock(url, token, transport) {
+    const base = transport === 'http'
+        ? { type: 'http', url, headers: { Authorization: `Bearer ${token}` } }
+        : { command: 'npx', args: ['-y', 'mcp-remote', url, '--header', `Authorization: Bearer ${token}`] };
+    base[MAGIC_KEY] = MAGIC_VAL;
+    return base;
+}
+function loadJsonOrEmpty(p) {
+    if (!fs.existsSync(p))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The `mcpServers` key an install writes.
+ *
+ * ⚠⚠ IT WAS THE LITERAL `clearly` EVERYWHERE, SO A SECOND WORKSPACE SILENTLY REPLACED THE FIRST.
+ * With tokens now bound to ONE workspace, that is not a cosmetic collision: installing while
+ * connected to a team overwrote the entry for home, and the agent lost a workspace it had been
+ * using — with the config still saying `clearly`, so nothing looked wrong.
+ *
+ * ⚠ THE DEFAULT KEEPS THE OLD NAME. Every entry already on disk is called `clearly`, and both the
+ * Mac app and `mcp remove` find it by that name; renaming the primary would orphan all of them.
+ */
+export const PRIMARY_ENTRY = 'clearly';
+/**
+ * Whether an installed bearer token is already bound to the active agent.
+ *
+ * An MCP token is opaque, so the config entry itself cannot answer this. The safe comparison is
+ * the non-secret prefix against `list-mcp-tokens`, whose rows carry the server-validated
+ * `agentId`. If the row is absent or unbound, return false and let the installer mint a new
+ * token for the active identity.
+ */
+export function tokenBelongsToAgent(listResult, token, agentId) {
+    const prefix = String(token || '').slice(0, 12);
+    const wanted = String(agentId || '').trim();
+    if (!prefix || !wanted)
+        return false;
+    const rows = Array.isArray(listResult?.tokens)
+        ? listResult.tokens
+        : Array.isArray(listResult?.result?.tokens)
+            ? listResult.result.tokens
+            : [];
+    const row = rows.find((candidate) => String(candidate?.prefix || '') === prefix);
+    return !!row && !row.revokedAt && String(row.agentId || '').trim() === wanted;
+}
+/** Read one bearer credential from the named Codex MCP table without parsing unrelated TOML. */
+export function codexTokenFromConfig(raw, wanted = PRIMARY_ENTRY) {
+    const escaped = wanted.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const header = new RegExp(`^\\[mcp_servers\\.${escaped}\\][^\\r\\n]*(?:\\r?\\n(?!\\[)[^\\r\\n]*)*`, 'm');
+    const table = header.exec(raw)?.[0] ?? '';
+    const match = /Authorization: Bearer (ck_[A-Za-z0-9_-]+)/.exec(table);
+    return match?.[1] ?? null;
+}
+export function entryNameFor(address) {
+    if (!address || /^(home|workspace|me)$/i.test(address))
+        return PRIMARY_ENTRY;
+    const slug = address.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24).toLowerCase();
+    return slug ? `${PRIMARY_ENTRY}-${slug}` : PRIMARY_ENTRY;
+}
+/**
+ * Is a `[mcp_servers.<entry>]` table present in Codex's config?
+ *
+ * ⚠ A REGEX FOR A TABLE HEADER, NOT A TOML PARSE. Detecting presence needs one line; parsing the
+ * whole document to answer it would mean shipping a TOML parser to read a file we deliberately do
+ * not write ourselves. Reading is allowed to be cheap because a wrong answer costs a redundant
+ * `codex mcp add`, which is idempotent.
+ */
+function codexHasEntry(configPath, entry) {
+    try {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        return new RegExp(`^\\[mcp_servers\\.${entry.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\]`, 'm').test(raw);
+    }
+    catch {
+        return false;
+    }
+}
+/** Every `[mcp_servers.*]` table Codex knows about that looks like ours. */
+/**
+ * ⚠⚠ CLAUDE CODE HAS NO MARKER EITHER, FOR THE SAME REASON CODEX DOES NOT — and this was found by
+ * running the shipped binary, not by reading it. Its entries are written by `claude mcp add`,
+ * whose flags cover `--transport`, `--header` and `--env` and nothing else, so there is no way to
+ * stamp `_managed-by`. An ownership test that looks for the marker therefore finds NOTHING: the
+ * status line said "detected, not configured" for a server that was configured and connected, and
+ * `removeClearlyEntry` would have refused with "no clearly entry" on a live install.
+ *
+ * ⚠ SO OWNERSHIP IS BY NAME, and the consequence is stated rather than hidden — exactly as it is
+ * for Codex: a hand-written `clearly` server would be overwritten by an install and removed by an
+ * uninstall. The alternative is hand-editing `~/.claude.json`, which holds the user's entire
+ * Claude Code state and is the thing we are avoiding.
+ */
+function claudeEntries(configPath) {
+    try {
+        const cfg = loadJsonOrEmpty(configPath);
+        return Object.keys(cfg?.mcpServers ?? {})
+            .filter((n) => n === PRIMARY_ENTRY || n.startsWith(`${PRIMARY_ENTRY}-`));
+    }
+    catch {
+        return [];
+    }
+}
+function codexEntries(configPath) {
+    try {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        return [...raw.matchAll(/^\[mcp_servers\.([A-Za-z0-9_-]+)\]/gm)]
+            .map((m) => m[1])
+            .filter((n) => n === PRIMARY_ENTRY || n.startsWith(`${PRIMARY_ENTRY}-`));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * ⚠⚠ CODEX HAS NO MARKER, AND CANNOT HAVE ONE. Our JSON clients carry `_managed-by` so we never
+ * touch an entry we did not write; TOML tables here hold only the fields Codex's own schema
+ * defines, and adding a stray key would either be dropped on the next rewrite or rejected.
+ *
+ * So ownership is inferred from the NAME instead — `clearly` and `clearly-*`. That is weaker, and
+ * the consequence is stated rather than hidden: a hand-written `[mcp_servers.clearly]` would be
+ * overwritten by an install and removed by an uninstall. It is the same name our own installer
+ * would have chosen, so the collision is unlikely; it is not impossible.
+ */
+/** Run a `claude mcp …` subcommand. Same contract as `codexRun`: the tool owns its format. */
+function claudeRun(args) {
+    try {
+        execFileSync('claude', args, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 20_000 });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: (e?.stderr?.toString?.() || e?.message || String(e)).trim().slice(0, 200) };
+    }
+}
+function codexRun(args) {
+    try {
+        execFileSync('codex', args, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 20_000 });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: (e?.stderr?.toString?.() || e?.message || String(e)).trim().slice(0, 200) };
+    }
+}
+export function writeClientConfig(def, url, token, entry = PRIMARY_ENTRY) {
+    const { configPath, transport } = def;
+    let backedUpTo;
+    if (def.kind === 'claude') {
+        /**
+         * ⚠⚠ ITS OWN CLI, NEVER A HAND-EDIT. `~/.claude.json` holds Claude Code's ENTIRE user state —
+         * every project's history, onboarding flags, permissions. The same reasoning this file already
+         * applies to Codex's TOML applies with more force to a file that large: a writer that dropped
+         * a key in a config we do not own would be a destructive bug.
+         *
+         * ⚠ `add` REFUSES AN EXISTING NAME (unlike `codex mcp add`, which overwrites), so a rotated
+         * token needs the old entry removed first — without it every rotation after the first leaves
+         * the STALE credential in place and still reports success. The remove is best-effort: on a
+         * first install there is nothing to remove and it exits non-zero, which is not a failure.
+         */
+        claudeRun(['mcp', 'remove', '--scope', 'user', entry]);
+        const r = claudeRun(['mcp', 'add', '--scope', 'user', '--transport', 'http', entry, url,
+            '--header', `Authorization: Bearer ${token}`]);
+        return r.ok ? { changed: true } : { changed: false, reason: r.reason };
+    }
+    if (def.kind === 'codex') {
+        /**
+         * ⚠ `codex mcp add` IS IDEMPOTENT — adding the same name twice overwrites — so there is no
+         * read-modify-write for us to get wrong, and no need to remove first.
+         */
+        const r = codexRun(['mcp', 'add', entry, '--', 'npx', '-y', 'mcp-remote', url,
+            '--header', `Authorization: Bearer ${token}`]);
+        return r.ok ? { changed: true } : { changed: false, reason: r.reason };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 });
+    const existing = loadJsonOrEmpty(configPath);
+    /**
+     * ⚠ AN UNPARSEABLE CONFIG IS BACKED UP, NEVER SILENTLY REPLACED. `loadJsonOrEmpty` returns `{}`
+     * for a file it could not parse, and writing over that would discard every server the user had.
+     * A file that exists but reads as empty is the signature of exactly that case.
+     */
+    if (fs.existsSync(configPath) && Object.keys(existing).length === 0) {
+        try {
+            if (fs.readFileSync(configPath, 'utf8').trim()) {
+                backedUpTo = `${configPath}.backup-${Date.now()}`;
+                fs.copyFileSync(configPath, backedUpTo);
+            }
+        }
+        catch { /* best-effort */ }
+    }
+    const next = { ...existing };
+    if (!next.mcpServers || typeof next.mcpServers !== 'object')
+        next.mcpServers = {};
+    const desired = serverBlock(url, token, transport);
+    const current = next.mcpServers[entry];
+    const currentIsOurs = current && current[MAGIC_KEY] === MAGIC_VAL;
+    // A `clearly` entry we did not write is hand-tuned until proven otherwise.
+    if (current && !currentIsOurs && !backedUpTo) {
+        backedUpTo = `${configPath}.backup-${Date.now()}`;
+        try {
+            fs.copyFileSync(configPath, backedUpTo);
+        }
+        catch { /* best-effort */ }
+    }
+    next.mcpServers[entry] = desired;
+    try {
+        fs.writeFileSync(configPath, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+        /**
+         * ⚠ `mode` ON `writeFileSync` APPLIES ONLY WHEN THE FILE IS CREATED. An existing config keeps
+         * whatever permissions it had, and this file now holds a bearer token.
+         */
+        try {
+            fs.chmodSync(configPath, 0o600);
+        }
+        catch { /* best-effort */ }
+    }
+    catch (e) {
+        return { changed: false, reason: `could not write ${configPath}: ${e?.message ?? e}` };
+    }
+    return { changed: true, backedUpTo };
+}
+/**
+ * The token already installed in a client config we own, if any.
+ *
+ * ⚠⚠ THE CLI MINTED A FRESH TOKEN ON EVERY RUN AND NEVER REVOKED THE LAST ONE. Three runs today
+ * left three live `ck_mcp_` credentials, each valid for a year, each unreachable by the user
+ * because the config only holds the newest. Re-running an installer is the most ordinary thing a
+ * person does — after a reinstall, after switching machines, after a failed attempt — and it was
+ * quietly issuing a new bearer token every time.
+ *
+ * ⚠ THE MAC APP ALREADY GOT THIS RIGHT and the divergence was the bug: it caches the token and
+ * mints only when absent or past `TOKEN_ROTATE_DAYS`. The CLI has no separate store, but it does
+ * not need one — the client config IS the store, and it is the only place the token was ever kept.
+ *
+ * ⚠ ONLY FROM AN ENTRY CARRYING OUR MARKER. A `clearly` server somebody hand-wrote holds a token
+ * we did not mint and may not revoke or reuse.
+ */
+export function existingToken(wanted) {
+    for (const d of clientDefs()) {
+        try {
+            if (!fs.existsSync(d.configPath))
+                continue;
+            if (d.kind === 'codex') {
+                /** The header lives inside the `args` array Codex wrote. */
+                const raw = fs.readFileSync(d.configPath, 'utf8');
+                const token = codexTokenFromConfig(raw, wanted ?? PRIMARY_ENTRY);
+                if (token)
+                    return token;
+                continue;
+            }
+            const cfg = loadJsonOrEmpty(d.configPath);
+            const entry = cfg?.mcpServers?.[wanted ?? PRIMARY_ENTRY];
+            if (!entry || entry[MAGIC_KEY] !== MAGIC_VAL)
+                continue;
+            const header = entry?.headers?.Authorization
+                ?? (Array.isArray(entry?.args) ? String(entry.args.find((a) => /^Authorization: /.test(a)) ?? '') : '');
+            const m = /Bearer\s+(ck_[A-Za-z0-9_]+)/.exec(header);
+            if (m)
+                return m[1];
+        }
+        catch { /* unreadable — treat as absent */ }
+    }
+    return null;
+}
+/** `ck_mcp_0e40e` — the 12-char prefix `revoke-mcp-token` matches on. */
+export function tokenPrefix(token) {
+    return token.slice(0, 12);
+}
+/**
+ * Is this client actually installed?
+ *
+ * ⚠⚠ THE APP AND THE CLI ASKED DIFFERENT QUESTIONS AND GOT DIFFERENT ANSWERS. The Mac app checks
+ * for the APPLICATION (`/Applications/Cursor.app`, `which claude`); this checked only for the
+ * CONFIG DIRECTORY (`~/.cursor`). On one machine that made the app skip Cursor while the CLI
+ * configured it — a config file written for software that is not installed.
+ *
+ * ⚠ THE APP'S SIGNAL IS STRONGER AND IS USED WHERE IT EXISTS. A leftover `~/.cursor` outlives an
+ * uninstall, so the directory proves only that the client was here once.
+ *
+ * ⚠ AND THE FALLBACK IS NOT A REGRESSION, IT IS THE ONLY PORTABLE SIGNAL. `/Applications` means
+ * nothing on Linux or in a container, which is exactly where the CLI runs and the app does not.
+ * Off darwin, the config directory is the best evidence available.
+ */
+function clientPresent(d) {
+    /**
+     * ⚠ CODEX IS A CLI, SO THE TEST IS THE BINARY — the same signal the app uses for Claude Code, and
+     * the one that matters: writing to `~/.codex/config.toml` is only useful if `codex` can run.
+     * The directory alone survives an uninstall.
+     */
+    if (d.kind === 'codex') {
+        try {
+            execFileSync('/usr/bin/which', ['codex'], { stdio: ['ignore', 'pipe', 'ignore'] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (process.platform === 'darwin' && d.appBundle) {
+        return d.appBundle.some((b) => fs.existsSync(b) || fs.existsSync(path.join(os.homedir(), b.replace(/^\//, ''))));
+    }
+    return fs.existsSync(d.detect);
+}
+export function detectClients() {
+    return clientDefs().map((d) => {
+        const detected = clientPresent(d);
+        /**
+         * ⚠ COUNT EVERY ENTRY WE OWN, not just the primary. Once a workspace can have its own entry,
+         * reporting only `clearly` would call a machine "not configured" while three of our own
+         * servers sat in its config.
+         */
+        let ours = [];
+        if (d.kind === 'codex') {
+            ours = codexEntries(d.configPath);
+            return { ...d, detected, installed: ours.length > 0, entries: ours };
+        }
+        if (d.kind === 'claude') {
+            ours = claudeEntries(d.configPath);
+            return { ...d, detected, installed: ours.length > 0, entries: ours };
+        }
+        if (fs.existsSync(d.configPath)) {
+            const c = loadJsonOrEmpty(d.configPath);
+            ours = Object.entries(c?.mcpServers ?? {})
+                .filter(([, v]) => v?.[MAGIC_KEY] === MAGIC_VAL)
+                .map(([k]) => k);
+        }
+        return { ...d, detected, installed: ours.length > 0, entries: ours };
+    });
+}
+/** Remove only an entry we wrote. A hand-authored `clearly` server is left alone. */
+export function removeClientConfig(def) {
+    if (def.kind === 'claude') {
+        const mine = claudeEntries(def.configPath);
+        if (!mine.length)
+            return { removed: false, reason: 'no clearly entry' };
+        const bad = [];
+        for (const n of mine) {
+            const r = claudeRun(['mcp', 'remove', '--scope', 'user', n]);
+            if (!r.ok)
+                bad.push(`${n}: ${r.reason}`);
+        }
+        return bad.length ? { removed: false, reason: bad.join('; ') } : { removed: true };
+    }
+    if (def.kind === 'codex') {
+        const names = codexEntries(def.configPath);
+        if (!names.length)
+            return { removed: false, reason: 'no clearly entry' };
+        const failures = [];
+        for (const n of names) {
+            const r = codexRun(['mcp', 'remove', n]);
+            if (!r.ok)
+                failures.push(`${n}: ${r.reason}`);
+        }
+        return failures.length ? { removed: false, reason: failures.join('; ') } : { removed: true };
+    }
+    if (!fs.existsSync(def.configPath))
+        return { removed: false, reason: 'no config' };
+    const cfg = loadJsonOrEmpty(def.configPath);
+    const owned = Object.entries(cfg?.mcpServers ?? {})
+        .filter(([, v]) => v?.[MAGIC_KEY] === MAGIC_VAL)
+        .map(([k]) => k);
+    if (!owned.length) {
+        const anyClearly = cfg?.mcpServers?.[PRIMARY_ENTRY];
+        return { removed: false, reason: anyClearly ? 'entry is not ours — left alone' : 'no clearly entry' };
+    }
+    for (const k of owned)
+        delete cfg.mcpServers[k];
+    try {
+        fs.writeFileSync(def.configPath, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+        return { removed: true };
+    }
+    catch (e) {
+        return { removed: false, reason: e?.message ?? String(e) };
+    }
+}