rivet-design 0.12.4 → 0.13.1

package/dist/install/harnesses.js

@@ -36,533 +36,337 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.updateHarnesses = exports.uninstallHarnesses = exports.installHarnesses = exports.sendButtonLabelFor = exports.detectedHarnesses = exports.findHarness = exports.HARNESSES = exports.buildCursorLocalRivetEntry = exports.buildCursorHostedRivetEntry = exports.resolveNpxCommand = void 0;
+exports.verifyCodexRules = exports.updateHarnesses = exports.uninstallHarnesses = exports.installHarnesses = exports.sendButtonLabelFor = exports.detectedHarnesses = exports.findHarness = exports.HARNESSES = void 0;
 /* eslint-disable no-console */
 const childProcess = __importStar(require("child_process"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const skillWriter_1 = require("../utils/skillWriter");
-// ---------------------------------------------------------------------------
-// Shared helpers (previously duplicated per harness in index.ts)
-// ---------------------------------------------------------------------------
-/**
- * Resolve `npx` to an absolute path using the install-time shell PATH.
- *
- * Why: editors like Claude desktop inherit a sanitized PATH at launch that can
- * put stale node versions first, causing `npx` to dispatch to a node so old it
- * can't even `require('node:url')`. Writing the absolute path into the MCP
- * config bypasses that lookup. Falls back to literal "npx" with a warning so
- * install never hard-blocks on a quirky environment.
- */
-const resolveNpxCommand = () => {
-    const which = process.platform === 'win32' ? 'where' : 'which';
+const allowlists_1 = require("./allowlists");
+Object.defineProperty(exports, "verifyCodexRules", { enumerable: true, get: function () { return allowlists_1.verifyCodexRules; } });
+const codexGuidance_1 = require("./codexGuidance");
+const legacyMcp_1 = require("./legacyMcp");
+const mcpRegistration_1 = require("./mcpRegistration");
+const binaryDetect = (bin) => () => {
     try {
-        const out = childProcess.execSync(`${which} npx`, {
-            stdio: ['ignore', 'pipe', 'ignore'],
-            encoding: 'utf8',
-        });
-        // `where` on Windows can return multiple lines (npx, npx.cmd, npx.ps1).
-        // Prefer .cmd / .exe over a shebanged shell script so Windows can spawn
-        // the resolved path directly.
-        const lines = out
-            .split(/\r?\n/)
-            .map((l) => l.trim())
-            .filter((l) => l.length > 0 && fs_1.default.existsSync(l));
-        if (lines.length === 0) {
-            throw new Error('which returned no usable paths');
-        }
-        if (process.platform === 'win32') {
-            const directlySpawnable = lines.find((l) => /\.(cmd|exe|bat)$/i.test(l));
-            return directlySpawnable ?? lines[0];
-        }
-        return lines[0];
+        childProcess.execSync(`${bin} --version`, { stdio: 'ignore' });
+        return true;
     }
     catch {
-        console.log('  Warning: could not resolve `npx` to an absolute path. Falling back to "npx" — if your editor uses an outdated Node, it may fail to start the server.');
-        return 'npx';
+        return false;
     }
 };
-exports.resolveNpxCommand = resolveNpxCommand;
-/**
- * Surface a diagnostic when an existing rivet MCP entry's `command` is an
- * absolute path that no longer exists. Common when the user removes the node
- * version that was resolved at install time.
- */
-const warnIfStaleRivetCommand = (entry, editorLabel) => {
-    if (typeof entry !== 'object' || entry === null)
-        return;
-    const cmd = entry.command;
-    if (typeof cmd !== 'string')
-        return;
-    if (!path_1.default.isAbsolute(cmd))
-        return;
-    if (fs_1.default.existsSync(cmd))
-        return;
-    console.log(`  Note: previous Rivet command for ${editorLabel} (${cmd}) no longer exists. Re-resolving.`);
-};
-/**
- * Read and validate an MCP config JSON file. Refuses to proceed on malformed
- * input so a merge never clobbers a file we couldn't parse. A missing file is
- * a valid empty config.
- */
-const parseConfigFile = (configPath) => {
-    if (!fs_1.default.existsSync(configPath))
-        return { ok: true, config: {} };
-    let parsed;
-    try {
-        parsed = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+const reportAllowlistWrite = (label, filePath, result) => {
+    if (!result.ok) {
+        console.log(`  Error: could not write the ${label} command allowlist (${filePath}): ${result.error}`);
+        console.log('  Run this in your own terminal instead:');
+        console.log('    npx -y rivet-design@latest install');
+        return false;
     }
-    catch {
-        return {
-            ok: false,
-            error: `could not parse ${configPath}. Fix or delete the file manually, then re-run.`,
-        };
-    }
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        return {
-            ok: false,
-            error: `${configPath} is not a JSON object. Fix or delete the file manually, then re-run.`,
-        };
+    console.log(result.changed
+        ? `✓ Command allowlist written to ${filePath}`
+        : `✓ Command allowlist already present in ${filePath}`);
+    if (result.verified) {
+        console.log('✓ Verified: `rivet` invocations run without an approval prompt.');
     }
-    const config = parsed;
-    if (config.mcpServers !== undefined &&
-        (typeof config.mcpServers !== 'object' || Array.isArray(config.mcpServers))) {
-        return {
-            ok: false,
-            error: `mcpServers in ${configPath} is not an object. Fix it manually, then re-run.`,
-        };
+    else {
+        console.log('  Warning: could not verify the allowlist entry — the host may still prompt per call.');
     }
-    return { ok: true, config };
-};
-const writeConfigFile = (configPath, config) => {
-    fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-};
-const ACCESS_ERROR_CODES = new Set(['EACCES', 'EPERM']);
-const CODING_AGENT_ENV_KEYS = [
-    'CLAUDECODE',
-    'CODEX_SANDBOX',
-    'CURSOR_AGENT',
-    'CURSOR_TRACE_ID',
-    'GITHUB_ACTIONS',
-];
-/**
- * Detect shells commonly launched by coding agents or automation.
- */
-const isCodingAgentShell = () => CODING_AGENT_ENV_KEYS.some((key) => Boolean(process.env[key]));
-/**
- * Extract a stable error code from filesystem exceptions.
- */
-const errorCodeFor = (err) => {
-    if (typeof err !== 'object' || err === null)
-        return undefined;
-    const code = err.code;
-    return typeof code === 'string' ? code : undefined;
-};
-/**
- * Convert an unknown thrown value into terminal-safe text.
- */
-const errorMessageFor = (err) => {
-    if (err instanceof Error)
-        return err.message;
-    return String(err);
-};
-/**
- * Determine whether a config write failed because this process lacks access.
- */
-const isAccessWriteError = (err) => {
-    const code = errorCodeFor(err);
-    return code ? ACCESS_ERROR_CODES.has(code) : false;
+    return true;
 };
-/**
- * Convert child process output into terminal-safe text.
- */
-const processOutputFor = (output) => {
-    if (Buffer.isBuffer(output))
-        return output.toString('utf8');
-    if (typeof output === 'string')
-        return output;
-    return '';
+const claudeSkillDir = () => path_1.default.join(os_1.default.homedir(), '.claude', 'skills', 'rivet');
+/** Uniform progress line for an `--mcp` registration attempt. */
+const reportMcpRegistration = (label, result) => {
+    if (!result.ok) {
+        console.log(`  Error: could not register the Rivet MCP server with ${label}: ${result.error}`);
+        return false;
+    }
+    console.log(result.changed
+        ? `✓ Registered the Rivet MCP server (\`rivet mcp serve\`) with ${label}`
+        : `✓ Rivet MCP server already registered with ${label}`);
+    return true;
 };
-/**
- * Detect permission failures emitted by editor CLIs.
- */
-const isAccessFailureText = (text) => /\b(?:EPERM|EACCES)\b|operation not permitted|permission denied|failed to write|failed to persist config/i.test(text);
 // ---------------------------------------------------------------------------
-// MCP entry builders (exported for tests / back-compat re-export from index)
+// The registry — the single source of truth for supported harnesses
 // ---------------------------------------------------------------------------
-const CURSOR_HOSTED_MCP_URL = 'https://rivet-proxy.onrender.com/mcp';
-const CURSOR_MCP_INSTALL_URL = 'https://cursor.com/install-mcp';
-const CURSOR_HOSTED_SERVER_NAME = 'rivet';
-const buildCursorHostedRivetEntry = () => ({
-    url: CURSOR_HOSTED_MCP_URL,
-});
-exports.buildCursorHostedRivetEntry = buildCursorHostedRivetEntry;
-/**
- * Build Cursor's one-click install URL for the hosted Rivet MCP server.
- */
-const buildCursorHostedInstallUrl = () => {
-    const params = new URLSearchParams({
-        name: CURSOR_HOSTED_SERVER_NAME,
-        config: Buffer.from(JSON.stringify((0, exports.buildCursorHostedRivetEntry)()), 'utf8').toString('base64'),
-    });
-    return `${CURSOR_MCP_INSTALL_URL}?${params.toString()}`;
-};
-const buildCursorLocalRivetEntry = () => ({
-    command: (0, exports.resolveNpxCommand)(),
-    args: ['-y', 'rivet-design@latest', 'mcp', '--editor', 'cursor'],
-});
-exports.buildCursorLocalRivetEntry = buildCursorLocalRivetEntry;
-const buildClaudeDesktopRivetEntry = () => ({
-    command: (0, exports.resolveNpxCommand)(),
-    args: ['-y', 'rivet-design@latest', 'mcp', '--editor', 'claude-desktop'],
-});
-/**
- * Path to the Claude desktop app's MCP config file.
- *   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- *   Win:   %APPDATA%\Claude\claude_desktop_config.json
- *   Linux: ~/.config/Claude/claude_desktop_config.json
- */
-const claudeDesktopConfigPath = () => {
-    const home = os_1.default.homedir();
-    if (process.platform === 'darwin') {
-        return path_1.default.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-    }
-    if (process.platform === 'win32') {
-        const appData = process.env.APPDATA ?? path_1.default.join(home, 'AppData', 'Roaming');
-        return path_1.default.join(appData, 'Claude', 'claude_desktop_config.json');
-    }
-    return path_1.default.join(home, '.config', 'Claude', 'claude_desktop_config.json');
-};
-const cliHarness = (opts) => {
-    const detect = () => {
-        try {
-            childProcess.execSync(`${opts.bin} --version`, { stdio: 'ignore' });
-            return true;
+const claudeHarness = {
+    id: 'claude',
+    label: 'Claude Code',
+    sendButtonLabel: 'Send to Claude Code',
+    installUrl: 'https://claude.ai/download',
+    supportsMcp: true,
+    detect: binaryDetect('claude'),
+    notInstalledMessage: () => 'Claude Code is not installed or not in your PATH.\nInstall it: https://claude.ai/download',
+    install: (options) => {
+        const skill = (0, skillWriter_1.writeSkillFileIfNeeded)();
+        if (skill.success) {
+            console.log('✓ Rivet CLI skill installed for Claude Code');
         }
-        catch {
-            return false;
+        else {
+            console.log(`  Warning: could not write skill file to ${claudeSkillDir()}: ${skill.error}`);
         }
-    };
-    /** Run the harness's `mcp add`. Treats "already exists" as success. */
-    const register = () => {
-        try {
-            const output = childProcess.execSync(opts.addCmd, {
-                stdio: 'pipe',
-                encoding: 'utf8',
-            });
-            if (output)
-                process.stdout.write(output);
-            console.log(`✓ Rivet MCP server added to ${opts.label}`);
-            return true;
-        }
-        catch (err) {
-            const stderr = processOutputFor(err.stderr);
-            if (stderr.includes('already exists')) {
-                console.log(`✓ Rivet MCP server already registered with ${opts.label}`);
-                return true;
-            }
-            if (isAccessFailureText(stderr)) {
-                console.log(`  Could not register Rivet with ${opts.label} from this shell.`);
-                console.log('  Looks like this was launched by a coding agent or sandboxed shell, which may not be allowed to edit that app config.');
-            }
-            else {
-                const message = stderr.trim().split(/\r?\n/)[0];
-                if (message)
-                    console.log(`  Error: ${message}`);
-            }
-            console.log('  Run this in your own terminal instead:');
-            console.log(`    ${opts.addCmd}`);
-            return false;
+        const allowlistOk = reportAllowlistWrite('Claude Code', (0, allowlists_1.claudeSettingsPath)(), (0, allowlists_1.writeClaudeAllowlist)());
+        if ((0, legacyMcp_1.cleanupClaudeLegacyMcp)().changed) {
+            console.log('✓ Removed the MCP registration a previous Rivet version wrote');
         }
-    };
-    const writeSkill = (verb) => {
-        if (!opts.skill)
-            return;
-        const result = opts.skill.write();
-        if (result.success) {
-            console.log(`✓ Rivet skill ${verb} for ${opts.label}`);
+        let mcpOk = true;
+        if (options?.mcp) {
+            mcpOk = reportMcpRegistration('Claude Code', (0, mcpRegistration_1.registerClaudeCodeMcp)());
         }
-        else {
-            console.log(`  Warning: could not write skill file to ${opts.skill.dir}: ${result.error}`);
+        return { ok: skill.success && allowlistOk && mcpOk, changed: true };
+    },
+    uninstall: () => {
+        let changed = false;
+        if (fs_1.default.existsSync(claudeSkillDir())) {
+            fs_1.default.rmSync(claudeSkillDir(), { recursive: true, force: true });
+            console.log('✓ Rivet skill file removed for Claude Code');
+            changed = true;
         }
-    };
-    return {
-        id: opts.id,
-        label: opts.label,
-        sendButtonLabel: opts.sendButtonLabel,
-        installUrl: opts.installUrl,
-        detect,
-        notInstalledMessage: () => `${opts.label} is not installed or not in your PATH.\nInstall it: ${opts.installUrl}`,
-        install: () => {
-            if (!register())
-                return { ok: false, changed: false };
-            writeSkill('installed');
-            return { ok: true, changed: true };
-        },
-        uninstall: () => {
-            if (!detect()) {
-                console.log(`  ${opts.label} is not installed — skipping.`);
-                return false;
-            }
-            let changed = false;
-            try {
-                childProcess.execSync(opts.removeCmd, { stdio: 'pipe' });
-                console.log(`✓ Rivet MCP server removed from ${opts.label}`);
-                changed = true;
-            }
-            catch {
-                console.log(`  Rivet was not registered with ${opts.label} (nothing to remove).`);
-            }
-            if (opts.skill && fs_1.default.existsSync(opts.skill.dir)) {
-                fs_1.default.rmSync(opts.skill.dir, { recursive: true, force: true });
-                console.log(`✓ Rivet skill file removed for ${opts.label}`);
-                changed = true;
-            }
-            return changed;
-        },
-        update: () => {
-            if (!detect())
-                return false;
-            try {
-                childProcess.execSync(opts.removeCmd, { stdio: 'pipe' });
-            }
-            catch {
-                // not registered yet — re-adding below still does the right thing
-            }
-            if (!register()) {
-                console.log(`  Failed to update Rivet for ${opts.label}.`);
-                return false;
-            }
-            writeSkill('updated');
-            return true;
-        },
-        nextSteps: opts.nextSteps,
-        summaryHint: opts.summaryHint,
-        restartHint: opts.restartHint,
-    };
-};
-/**
- * Print manual recovery steps when an editor config cannot be written.
- */
-const printManualJsonInstallInstructions = ({ configPath, err, opts, }) => {
-    const code = errorCodeFor(err);
-    console.log(`  Could not update ${opts.label} MCP config${code ? ` (${code})` : ''}: ${configPath}`);
-    if (opts.id === 'cursor') {
-        console.log("  Looks like this was launched by a coding agent, which can't modify ~/.cursor/.");
-    }
-    else if (isCodingAgentShell()) {
-        console.log('  Looks like this was launched by a coding agent or sandboxed shell, which may not be allowed to edit that app config.');
-    }
-    else {
-        console.log('  If this was launched by a coding agent or sandboxed shell, it may not be allowed to edit that app config.');
-    }
-    if (opts.manualInstallUrl) {
-        console.log('\n  Click this link to install the hosted MCP server:');
-        console.log(`    ${opts.manualInstallUrl()}`);
-    }
-    console.log('\n  Run this in your own terminal instead:');
-    console.log(`    npx -y rivet-design@latest install ${opts.id}`);
-};
-/**
- * Print a one-click install link for editor-hosted MCP registration.
- */
-const printJsonInstallLink = (opts) => {
-    if (!opts.manualInstallUrl)
-        return;
-    console.log('\nCursor one-click hosted MCP install link:');
-    console.log(`  ${opts.manualInstallUrl()}`);
-    console.log('Click it if Cursor still asks you to approve the MCP server.');
-};
-/**
- * Print a compact write failure for non-install config mutations.
- */
-const printJsonWriteFailure = (configPath, err) => {
-    console.log(`  Error: could not write Rivet MCP config to ${configPath}: ${errorMessageFor(err)}`);
-};
-const jsonHarness = (opts) => {
-    const ownedKeys = () => Object.keys(opts.entries());
-    const detect = () => fs_1.default.existsSync(opts.detectDir);
-    return {
-        id: opts.id,
-        label: opts.label,
-        sendButtonLabel: opts.sendButtonLabel,
-        installUrl: opts.installUrl,
-        detect,
-        notInstalledMessage: opts.notInstalledMessage,
-        install: () => {
-            const configPath = opts.configPath();
-            const parsed = parseConfigFile(configPath);
-            if (!parsed.ok) {
-                console.log(`  Error: ${parsed.error}`);
-                return { ok: false, changed: false };
-            }
-            const { config } = parsed;
-            const entries = opts.entries();
-            config.mcpServers = { ...config.mcpServers, ...entries };
-            try {
-                writeConfigFile(configPath, config);
-            }
-            catch (err) {
-                if (isAccessWriteError(err)) {
-                    printManualJsonInstallInstructions({
-                        configPath,
-                        err,
-                        opts,
-                    });
-                }
-                else {
-                    printJsonWriteFailure(configPath, err);
-                }
-                return { ok: false, changed: false };
-            }
-            console.log(`✓ Rivet MCP server added to ${configPath}`);
-            printJsonInstallLink(opts);
-            return { ok: true, changed: true };
-        },
-        uninstall: () => {
-            const configPath = opts.configPath();
-            if (!fs_1.default.existsSync(configPath)) {
-                console.log(`  No ${opts.label} MCP config found — nothing to remove.`);
-                return false;
-            }
-            const parsed = parseConfigFile(configPath);
-            if (!parsed.ok) {
-                console.log(`  Error: ${parsed.error}`);
-                return false;
-            }
-            const { config } = parsed;
-            const keys = ownedKeys();
-            if (!config.mcpServers || !keys.some((k) => k in config.mcpServers)) {
-                console.log(`  Rivet was not registered with ${opts.label} (nothing to remove).`);
-                return false;
-            }
-            for (const key of keys)
-                delete config.mcpServers[key];
-            try {
-                writeConfigFile(configPath, config);
-            }
-            catch (err) {
-                printJsonWriteFailure(configPath, err);
-                return false;
-            }
-            console.log(`✓ Rivet MCP server removed from ${configPath}`);
-            return true;
-        },
-        update: () => {
-            const configPath = opts.configPath();
-            if (!fs_1.default.existsSync(configPath))
-                return false;
-            const parsed = parseConfigFile(configPath);
-            if (!parsed.ok) {
-                console.log(`  Warning: could not update ${opts.label} (${parsed.error})`);
-                return false;
-            }
-            const { config } = parsed;
-            const keys = ownedKeys();
-            if (!config.mcpServers || !keys.some((k) => k in config.mcpServers)) {
-                return false;
-            }
-            for (const key of keys)
-                warnIfStaleRivetCommand(config.mcpServers[key], opts.label);
-            config.mcpServers = { ...config.mcpServers, ...opts.entries() };
-            try {
-                writeConfigFile(configPath, config);
-            }
-            catch (err) {
-                printJsonWriteFailure(configPath, err);
-                return false;
-            }
-            console.log(`✓ Updated Rivet MCP server for ${opts.label}`);
-            return true;
-        },
-        nextSteps: opts.nextSteps,
-        summaryHint: opts.summaryHint,
-        restartHint: opts.restartHint,
-    };
-};
-// ---------------------------------------------------------------------------
-// The registry — the single source of truth for supported harnesses
-// ---------------------------------------------------------------------------
-exports.HARNESSES = [
-    cliHarness({
-        id: 'claude',
-        label: 'Claude Code',
-        sendButtonLabel: 'Send to Claude Code',
-        installUrl: 'https://claude.ai/download',
-        bin: 'claude',
-        addCmd: 'claude mcp add --transport stdio --scope user rivet -- npx -y rivet-design@latest mcp --editor claude',
-        removeCmd: 'claude mcp remove rivet',
-        skill: {
-            write: skillWriter_1.writeSkillFileIfNeeded,
-            dir: path_1.default.join(os_1.default.homedir(), '.claude', 'skills', 'rivet'),
-        },
-        nextSteps: `
+        const allowlist = (0, allowlists_1.removeClaudeAllowlist)();
+        if (allowlist.ok && allowlist.changed) {
+            console.log(`✓ Command allowlist entries removed from ${(0, allowlists_1.claudeSettingsPath)()}`);
+            changed = true;
+        }
+        // Removes the registration whatever its vintage (legacy or `mcp serve`).
+        if ((0, mcpRegistration_1.unregisterClaudeCodeMcp)().changed) {
+            console.log('✓ Rivet MCP registration removed from Claude Code');
+            changed = true;
+        }
+        return changed;
+    },
+    update: () => {
+        if (!binaryDetect('claude')())
+            return false;
+        const skill = (0, skillWriter_1.writeSkillFileIfNeeded)();
+        const allowlist = (0, allowlists_1.writeClaudeAllowlist)();
+        (0, legacyMcp_1.cleanupClaudeLegacyMcp)();
+        if ((0, mcpRegistration_1.hasServeRegistrationViaHostCli)('claude')) {
+            // Opted in: re-register so the node/bin paths track this install.
+            (0, mcpRegistration_1.registerClaudeCodeMcp)();
+        }
+        const updated = skill.success && allowlist.ok && (allowlist.changed || true);
+        if (updated) {
+            console.log('✓ Refreshed Rivet CLI guidance for Claude Code');
+        }
+        return updated;
+    },
+    nextSteps: `
 Next steps:
   1. Start a new Claude Code session
   2. Type /rivet or say "Open Rivet"
 `,
-        summaryHint: 'start a new session, then /rivet',
-        restartHint: 'Restart Claude Code to apply changes.',
-    }),
-    jsonHarness({
-        id: 'claude-desktop',
-        label: 'the Claude desktop app',
-        sendButtonLabel: 'Send to Claude',
-        installUrl: 'https://claude.ai/download',
-        detectDir: path_1.default.dirname(claudeDesktopConfigPath()),
-        configPath: claudeDesktopConfigPath,
-        entries: () => ({ rivet: buildClaudeDesktopRivetEntry() }),
-        notInstalledMessage: () => `Claude desktop does not appear to be installed (${path_1.default.dirname(claudeDesktopConfigPath())} not found).\nInstall it: https://claude.ai/download`,
-        nextSteps: `
-Next steps:
-  1. Fully quit and reopen the Claude desktop app
-  2. Open a new chat and say "Open Rivet"
-`,
-        summaryHint: 'fully restart the app, then say "Open Rivet"',
-        restartHint: 'Fully restart the Claude desktop app to apply changes.',
-    }),
-    jsonHarness({
-        id: 'cursor',
-        label: 'Cursor',
-        sendButtonLabel: 'Send to Cursor',
-        installUrl: 'https://cursor.com',
-        detectDir: path_1.default.join(os_1.default.homedir(), '.cursor'),
-        configPath: () => path_1.default.join(os_1.default.homedir(), '.cursor', 'mcp.json'),
-        entries: () => ({
-            rivet: (0, exports.buildCursorHostedRivetEntry)(),
-            'rivet-local': (0, exports.buildCursorLocalRivetEntry)(),
-        }),
-        manualInstallUrl: buildCursorHostedInstallUrl,
-        notInstalledMessage: () => 'Cursor does not appear to be installed (~/.cursor not found).\nInstall it: https://cursor.com',
-        nextSteps: `
+    summaryHint: 'start a new session, then /rivet',
+    restartHint: 'Restart Claude Code to apply changes.',
+};
+const cursorHarness = {
+    id: 'cursor',
+    label: 'Cursor',
+    sendButtonLabel: 'Send to Cursor',
+    installUrl: 'https://cursor.com',
+    supportsMcp: true,
+    detect: () => fs_1.default.existsSync(path_1.default.join(os_1.default.homedir(), '.cursor')),
+    notInstalledMessage: () => 'Cursor does not appear to be installed (~/.cursor not found).\nInstall it: https://cursor.com',
+    install: (options) => {
+        const allowlistOk = reportAllowlistWrite('Cursor', (0, allowlists_1.cursorPermissionsPath)(), (0, allowlists_1.writeCursorAllowlist)());
+        if ((0, legacyMcp_1.cleanupCursorLegacyMcp)().changed) {
+            console.log('✓ Removed the MCP entries a previous Rivet version wrote to ~/.cursor/mcp.json');
+        }
+        let mcpOk = true;
+        if (options?.mcp) {
+            mcpOk = reportMcpRegistration('Cursor (~/.cursor/mcp.json)', (0, mcpRegistration_1.registerCursorMcp)());
+        }
+        console.log('  Rivet writes its usage rules into each project (.cursor/rules/rivet.mdc) when you open it.');
+        return { ok: allowlistOk && mcpOk, changed: true };
+    },
+    uninstall: () => {
+        let changed = false;
+        const allowlist = (0, allowlists_1.removeCursorAllowlist)();
+        if (allowlist.ok && allowlist.changed) {
+            console.log(`✓ Command allowlist entries removed from ${(0, allowlists_1.cursorPermissionsPath)()}`);
+            changed = true;
+        }
+        if ((0, legacyMcp_1.cleanupCursorLegacyMcp)().changed) {
+            console.log('✓ Removed legacy Rivet MCP entries from ~/.cursor/mcp.json');
+            changed = true;
+        }
+        if ((0, mcpRegistration_1.unregisterCursorMcp)().changed) {
+            console.log('✓ Rivet MCP registration removed from ~/.cursor/mcp.json');
+            changed = true;
+        }
+        return changed;
+    },
+    update: () => {
+        if (!fs_1.default.existsSync(path_1.default.join(os_1.default.homedir(), '.cursor')))
+            return false;
+        const allowlist = (0, allowlists_1.writeCursorAllowlist)();
+        (0, legacyMcp_1.cleanupCursorLegacyMcp)();
+        if ((0, mcpRegistration_1.hasCursorServeRegistration)()) {
+            (0, mcpRegistration_1.registerCursorMcp)();
+        }
+        if (allowlist.ok) {
+            console.log('✓ Refreshed the Cursor command allowlist for Rivet');
+        }
+        return allowlist.ok;
+    },
+    nextSteps: `
 Next steps:
-  1. Fully restart Cursor
-  2. Open a new chat and say "Open Rivet"
+  1. Open a project in Cursor
+  2. Say "Open Rivet" — the agent drives Rivet with \`rivet\` commands
 `,
-        summaryHint: 'fully restart Cursor, then say "Open Rivet"',
-        restartHint: 'Restart Cursor to apply changes.',
-    }),
-    cliHarness({
-        id: 'codex',
-        label: 'OpenAI Codex CLI',
-        sendButtonLabel: 'Send to Codex',
-        installUrl: 'https://github.com/openai/codex',
-        bin: 'codex',
-        addCmd: 'codex mcp add rivet -- npx -y rivet-design@latest mcp --editor codex',
-        removeCmd: 'codex mcp remove rivet',
-        nextSteps: `
+    summaryHint: 'open a project, then say "Open Rivet"',
+    restartHint: 'Restart Cursor to apply changes.',
+};
+const codexHarness = {
+    id: 'codex',
+    label: 'OpenAI Codex CLI',
+    sendButtonLabel: 'Send to Codex',
+    installUrl: 'https://github.com/openai/codex',
+    supportsMcp: true,
+    detect: binaryDetect('codex'),
+    notInstalledMessage: () => 'OpenAI Codex CLI is not installed or not in your PATH.\nInstall it: https://github.com/openai/codex',
+    install: (options) => {
+        const guidance = (0, codexGuidance_1.writeCodexGuidance)();
+        if (guidance.ok) {
+            console.log('✓ Rivet CLI guidance written to ~/.codex/AGENTS.md');
+        }
+        else {
+            console.log(`  Warning: could not write ~/.codex/AGENTS.md guidance: ${guidance.error}`);
+        }
+        const rules = (0, allowlists_1.writeCodexRules)();
+        const rulesOk = reportAllowlistWrite('Codex execpolicy', (0, allowlists_1.codexRulesPath)(), rules);
+        if (rules.ok && !rules.verified) {
+            console.log('  Note: verification uses `codex execpolicy check` (preview); if unavailable, restart Codex and approve `rivet` once — it will be remembered.');
+        }
+        if ((0, legacyMcp_1.cleanupCodexLegacyMcp)().changed) {
+            console.log('✓ Removed the MCP registration a previous Rivet version wrote');
+        }
+        let mcpOk = true;
+        if (options?.mcp) {
+            mcpOk = reportMcpRegistration('OpenAI Codex CLI', (0, mcpRegistration_1.registerCodexMcp)());
+        }
+        return { ok: guidance.ok && rulesOk && mcpOk, changed: true };
+    },
+    uninstall: () => {
+        let changed = false;
+        const guidance = (0, codexGuidance_1.removeCodexGuidance)();
+        if (guidance.ok && guidance.changed) {
+            console.log('✓ Rivet guidance removed from ~/.codex/AGENTS.md');
+            changed = true;
+        }
+        const rules = (0, allowlists_1.removeCodexRules)();
+        if (rules.ok && rules.changed) {
+            console.log(`✓ Execpolicy rules removed (${(0, allowlists_1.codexRulesPath)()})`);
+            changed = true;
+        }
+        if ((0, mcpRegistration_1.unregisterCodexMcp)().changed) {
+            console.log('✓ Rivet MCP registration removed from Codex');
+            changed = true;
+        }
+        return changed;
+    },
+    update: () => {
+        if (!binaryDetect('codex')())
+            return false;
+        const guidance = (0, codexGuidance_1.writeCodexGuidance)();
+        const rules = (0, allowlists_1.writeCodexRules)();
+        (0, legacyMcp_1.cleanupCodexLegacyMcp)();
+        if ((0, mcpRegistration_1.hasServeRegistrationViaHostCli)('codex')) {
+            (0, mcpRegistration_1.registerCodexMcp)();
+        }
+        const updated = guidance.ok && rules.ok;
+        if (updated) {
+            console.log('✓ Refreshed Rivet CLI guidance for OpenAI Codex CLI');
+        }
+        return updated;
+    },
+    nextSteps: `
 Next steps:
   1. Start a new Codex session
   2. Say "Open Rivet"
 `,
-        summaryHint: 'start a new session, then say "Open Rivet"',
-        restartHint: 'Start a new Codex session to apply changes.',
-    }),
+    summaryHint: 'start a new session, then say "Open Rivet"',
+    restartHint: 'Start a new Codex session to apply changes.',
+};
+/**
+ * Claude Desktop is retired as a *CLI* install target: it has no shell
+ * access, so it cannot run `rivet` commands. With `--mcp` it re-enters the
+ * flow — the resident `rivet mcp serve` stdio server is exactly the bridge a
+ * shell-less host needs. Without the flag, install only cleans up what old
+ * versions wrote.
+ */
+const CLAUDE_DESKTOP_OUT_OF_SCOPE_MESSAGE = `Claude Desktop has no shell access to run the \`rivet\` CLI. To use Rivet
+from Claude Desktop, register the MCP server instead:
+
+  rivet install claude-desktop --mcp
+
+Otherwise use Claude Code (\`rivet install claude\`) — the browser editor
+still works alongside any shell-capable agent.`;
+const claudeDesktopHarness = {
+    id: 'claude-desktop',
+    label: 'the Claude desktop app',
+    sendButtonLabel: 'Send to Claude',
+    installUrl: 'https://claude.ai/download',
+    isRetired: true,
+    supportsMcp: true,
+    detect: () => fs_1.default.existsSync(path_1.default.dirname((0, legacyMcp_1.claudeDesktopConfigPath)())),
+    notInstalledMessage: () => `Claude desktop does not appear to be installed (${path_1.default.dirname((0, legacyMcp_1.claudeDesktopConfigPath)())} not found).\nInstall it: https://claude.ai/download`,
+    install: (options) => {
+        if (options?.mcp) {
+            const result = (0, mcpRegistration_1.registerClaudeDesktopMcp)();
+            const ok = reportMcpRegistration('the Claude desktop app (claude_desktop_config.json)', result);
+            if (ok) {
+                console.log('  Claude Desktop has no working directory: tools take a `project` parameter — tell the agent which project root to target.');
+            }
+            return { ok, changed: result.changed };
+        }
+        console.log(CLAUDE_DESKTOP_OUT_OF_SCOPE_MESSAGE);
+        const cleanup = (0, legacyMcp_1.cleanupClaudeDesktopLegacyMcp)();
+        if (cleanup.changed) {
+            console.log('✓ Removed the MCP registration a previous Rivet version wrote to claude_desktop_config.json');
+        }
+        return { ok: true, changed: cleanup.changed };
+    },
+    uninstall: () => {
+        // Removes the registration whatever its vintage (legacy or `mcp serve`).
+        const legacy = (0, legacyMcp_1.cleanupClaudeDesktopLegacyMcp)();
+        const serve = (0, mcpRegistration_1.unregisterClaudeDesktopMcp)();
+        const changed = legacy.changed || serve.changed;
+        if (changed) {
+            console.log(`✓ Rivet MCP registration removed from ${(0, legacyMcp_1.claudeDesktopConfigPath)()}`);
+        }
+        else {
+            console.log('  Rivet was not registered with the Claude desktop app (nothing to remove).');
+        }
+        return changed;
+    },
+    update: () => {
+        const legacy = (0, legacyMcp_1.cleanupClaudeDesktopLegacyMcp)().changed;
+        if ((0, mcpRegistration_1.hasClaudeDesktopServeRegistration)()) {
+            // Opted in: re-register so the node/bin paths track this install.
+            return (0, mcpRegistration_1.registerClaudeDesktopMcp)().changed || legacy;
+        }
+        return legacy;
+    },
+    nextSteps: `
+Next steps:
+  1. Fully restart the Claude desktop app (the MCP server loads on launch)
+  2. Ask Claude to check Rivet status — tools take a \`project\` parameter,
+     so name the project root you want to work on
+`,
+    summaryHint: 'restart the app; agent uses the rivet MCP tools',
+    restartHint: 'Fully restart the Claude desktop app to apply changes.',
+};
+exports.HARNESSES = [
+    claudeHarness,
+    claudeDesktopHarness,
+    cursorHarness,
+    codexHarness,
 ];
 const findHarness = (id) => exports.HARNESSES.find((h) => h.id === id);
 exports.findHarness = findHarness;
-const detectedHarnesses = () => exports.HARNESSES.filter((h) => h.detect());
+const detectedHarnesses = (options) => exports.HARNESSES.filter((h) => (!h.isRetired || (options?.mcp === true && h.supportsMcp === true)) &&
+    h.detect());
 exports.detectedHarnesses = detectedHarnesses;
 /** Label for the in-app "Send to …" button, by harness id. */
 const sendButtonLabelFor = (id) => (id && (0, exports.findHarness)(id)?.sendButtonLabel) ?? 'Send to Claude Code';
@@ -570,10 +374,14 @@ exports.sendButtonLabelFor = sendButtonLabelFor;
 // ---------------------------------------------------------------------------
 // Orchestration — drives install / uninstall / update over the registry
 // ---------------------------------------------------------------------------
-const MCP_INSTALL_WELCOME = `
+const CLI_INSTALL_WELCOME = `
 Welcome to Rivet!
 
-Rivet is a design agent for your coding agent.
+Rivet is a design agent for your coding agent. Your agent drives it by
+running \`rivet\` CLI commands — install writes each agent's usage guidance
+and its command allowlist so those commands run without approval prompts.
+Add --mcp to also register the resident MCP server (\`rivet mcp serve\`),
+for hosts without shell access like Claude Desktop.
 `;
 const supportedListBlock = () => exports.HARNESSES.map((h) => `  rivet install ${h.id.padEnd(16)}${h.label}`).join('\n');
 /**
@@ -581,8 +389,8 @@ const supportedListBlock = () => exports.HARNESSES.map((h) => `  rivet install $
  * (`target` undefined/`'all'`). Returns a process exit code; never exits
  * itself so the multi-install loop survives a single failure.
  */
-const installHarnesses = (target) => {
-    console.log(MCP_INSTALL_WELCOME);
+const installHarnesses = (target, options) => {
+    console.log(CLI_INSTALL_WELCOME);
     // Single, explicitly named harness — preserves the original hard errors.
     if (target && target !== 'all') {
         const harness = (0, exports.findHarness)(target);
@@ -592,21 +400,23 @@ const installHarnesses = (target) => {
             console.log('');
             return { exitCode: 1 };
         }
-        if (!harness.detect()) {
+        if (!harness.isRetired && !harness.detect()) {
             console.log(`\n${harness.notInstalledMessage()}\n`);
             return { exitCode: 1 };
         }
         console.log(`\nSetting up Rivet for ${harness.label}...\n`);
-        const result = harness.install();
-        if (result.ok)
+        const result = harness.install(options);
+        if (result.ok && result.changed)
             console.log(harness.nextSteps);
         return { exitCode: result.ok ? 0 : 1 };
     }
     // Unified path: install into everything we can detect.
-    const targets = (0, exports.detectedHarnesses)();
+    const targets = (0, exports.detectedHarnesses)(options);
     if (targets.length === 0) {
         console.log('\nNo supported agents detected. Install one of these, then re-run `rivet install`:\n');
         for (const h of exports.HARNESSES) {
+            if (h.isRetired)
+                continue;
             console.log(`  ${h.label.padEnd(24)}${h.installUrl}`);
         }
         console.log('');
@@ -619,7 +429,7 @@ const installHarnesses = (target) => {
     const failed = [];
     for (const harness of targets) {
         console.log(`\nSetting up Rivet for ${harness.label}...`);
-        const result = harness.install();
+        const result = harness.install(options);
         (result.ok ? installed : failed).push(harness);
     }
     // Completion summary — show exactly which agents got Rivet.
@@ -636,7 +446,7 @@ const installHarnesses = (target) => {
             console.log(`  ✗ ${h.label} (see messages above)`);
         }
     }
-    const skipped = exports.HARNESSES.filter((h) => !targets.includes(h));
+    const skipped = exports.HARNESSES.filter((h) => !h.isRetired && !targets.includes(h));
     if (skipped.length > 0) {
         console.log(`\nNot detected (skipped): ${skipped.map((h) => h.label).join(', ')}`);
     }
@@ -677,7 +487,7 @@ const uninstallHarnesses = (target) => {
     return { exitCode: 0 };
 };
 exports.uninstallHarnesses = uninstallHarnesses;
-/** Re-register Rivet for every detected, already-installed harness. */
+/** Refresh guidance/allowlists for every detected, already-installed harness. */
 const updateHarnesses = () => {
     console.log('\nUpdating Rivet...\n');
     const updatedAny = exports.HARNESSES.map((h) => h.update()).some(Boolean);