ccdesk 0.1.0 → 0.2.0

package/dist/server/backups.js

@@ -3,9 +3,18 @@ import { basename, dirname, join } from "node:path";
 import {} from "../shared/types.js";
 import { assertMemoryDir, indexPathIn, revisionOfBoth } from "./mutations.js";
 import {} from "./scan/env.js";
-import { isRecord, isWithin, redactSecrets, revisionOf, shownText, shownUrl, } from "./scan/files.js";
-import { backupRoot, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SNAPSHOT, serially, writeAtomic, } from "./write.js";
-const KINDS = new Set(["settings", "memory-index", "memory-delete"]);
+import { isRecord, isWithin, revisionOf, shownText } from "./scan/files.js";
+import { hiddenValues, shown } from "./secrets.js";
+import { backupRoot, forgetChange, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SHOWN_AFTER, SNAPSHOT, StaleError, serially, writeAtomic, } from "./write.js";
+const KINDS = new Set([
+    "settings",
+    "mcp",
+    "agent",
+    "memory-index",
+    "memory-delete",
+    "memory-restore",
+    "mcp-claude",
+]);
 function strings(value) {
     return Array.isArray(value) && value.every((v) => typeof v === "string");
 }
@@ -31,7 +40,8 @@ async function readManifest(env, id) {
         typeof data.createdAt !== "string" ||
         typeof data.before !== "string" ||
         typeof data.after !== "string" ||
-        (data.removedIndexLines !== undefined && !strings(data.removedIndexLines)))
+        (data.removedIndexLines !== undefined && !strings(data.removedIndexLines)) ||
+        (data.undoCommands !== undefined && !strings(data.undoCommands)))
         return null;
     return data;
 }
@@ -65,46 +75,28 @@ function isSettingsFile(env, path) {
     return (["settings.json", "settings.local.json"].includes(basename(path)) &&
         basename(dirname(path)) === ".claude");
 }
-/**
- * Every value ccdesk shows hidden and never changes in a settings file: env and headers objects,
- * and URLs with a user, password or query.
- */
-function hiddenValues(text) {
-    const found = [];
-    const walk = (value) => {
-        if (Array.isArray(value))
-            value.forEach(walk);
-        if (!isRecord(value))
-            return;
-        for (const [key, inner] of Object.entries(value)) {
-            if ((key === "env" || key === "headers") && isRecord(inner))
-                found.push(inner);
-            else if (key === "url" && typeof inner === "string" && shownUrl(inner) !== inner)
-                found.push(inner);
-            else
-                walk(inner);
-        }
-    };
-    try {
-        walk(text === null ? null : JSON.parse(text));
-    }
-    catch {
-        return text ?? "";
-    }
-    return JSON.stringify(found);
+/** A `.md` file in your agents folder or a project's `.claude/agents`, or a subfolder of one. */
+function isAgentFile(env, path) {
+    if (!path.endsWith(".md"))
+        return false;
+    if (isWithin(join(env.claudeDir, "agents"), path))
+        return true;
+    const parts = path.split(/[/\\]/);
+    return parts.some((part, i) => part === ".claude" && parts[i + 1] === "agents" && i + 2 < parts.length);
 }
 /** Settings are shown parsed with env and header values hidden, as everywhere else in ccdesk. */
 function shownSettings(text) {
     if (text === null)
         return null;
     try {
-        return `${JSON.stringify(redactSecrets(JSON.parse(text)), null, 2)}\n`;
+        return shown(JSON.parse(text));
     }
     catch {
         return "(not valid JSON; open the file to see it)\n";
     }
 }
-async function planRestore(env, id) {
+/** A backup's manifest and its folder, which must be inside the backup folder. */
+async function backupAt(env, id) {
     const manifest = await readManifest(env, id);
     if (!manifest)
         throw new RefusedError("That backup is gone or was not made by ccdesk.");
@@ -112,18 +104,51 @@ async function planRestore(env, id) {
     const dir = await realpath(join(root, id));
     if (!isWithin(root, dir) || dir === root)
         throw new RefusedError("Not a ccdesk backup.");
+    return { manifest, dir };
+}
+const MADE_BY_CLAUDE = "Claude Code made this change through claude mcp, so ccdesk cannot undo it. Run the commands below to put it back.";
+/**
+ * What a change made through `claude mcp` did, as ccdesk recorded it: the servers before and
+ * after, values hidden, and the commands that put them back.
+ */
+async function claudeMcpPreview(id, manifest, dir) {
+    const read = async (name, revision) => {
+        const text = await readFile(join(dir, name), "utf8").catch(() => null);
+        if (text === null || revisionOf(text) !== revision)
+            throw new RefusedError("The record of this change is missing or was changed.");
+        return text;
+    };
+    return {
+        id,
+        kind: manifest.kind,
+        target: manifest.target,
+        before: await read(SNAPSHOT, manifest.before),
+        after: await read(SHOWN_AFTER, manifest.after),
+        revision: manifest.after,
+        blocked: MADE_BY_CLAUDE,
+        undoCommands: manifest.undoCommands ?? [],
+    };
+}
+async function planRestore(env, id) {
+    const { manifest, dir } = await backupAt(env, id);
+    if (manifest.kind === "mcp-claude")
+        throw new RefusedError(MADE_BY_CLAUDE);
     let target = manifest.target;
     if (manifest.kind === "settings" && !isSettingsFile(env, target))
         throw new RefusedError("This backup does not point at a settings file.");
+    if (manifest.kind === "mcp" && basename(target) !== ".mcp.json")
+        throw new RefusedError("This backup does not point at a .mcp.json.");
+    if (manifest.kind === "agent" && !isAgentFile(env, target))
+        throw new RefusedError("This backup does not point at a subagent file.");
     if (manifest.kind === "memory-index" && basename(target) !== "MEMORY.md")
         throw new RefusedError("This backup does not point at a MEMORY.md.");
-    if (manifest.kind !== "settings") {
+    if (manifest.kind !== "settings" && manifest.kind !== "mcp" && manifest.kind !== "agent") {
         const store = await assertMemoryDir(env, dirname(target));
         // The same confinement as any other MEMORY.md change: a link out of the folder is refused.
         target =
             manifest.kind === "memory-index" ? await indexPathIn(store) : join(store, basename(target));
         // A deleted memory comes back only as a topic file, as ccdesk deletes only those.
-        if (manifest.kind === "memory-delete" &&
+        if (manifest.kind !== "memory-index" &&
             (!target.endsWith(".md") || basename(target) === "MEMORY.md"))
             throw new RefusedError("This backup does not point at a memory file.");
     }
@@ -140,6 +165,7 @@ async function planRestore(env, id) {
         manifest: { ...manifest, target },
         current: await readIfExists(env, target),
         saved,
+        linked: (await lstat(target).catch(() => null))?.isSymbolicLink() ?? false,
     };
     if (manifest.kind === "memory-delete") {
         const path = await indexPathIn(dirname(target));
@@ -153,22 +179,55 @@ async function planRestore(env, id) {
 function planRevision({ current, index }) {
     return index ? revisionOfBoth(current, index.text) : revisionOf(current);
 }
-function blockedReason({ manifest, current, saved }) {
-    if (saved === null)
-        return "ccdesk created this file, so there is no earlier version to put back. Change it in place instead.";
-    if (manifest.kind === "settings" && hiddenValues(current) !== hiddenValues(saved))
-        return "Hidden values in this file (env, headers or a URL's key) changed since the backup. ccdesk does not show or change those, so restore this one by hand.";
+/**
+ * A delete that stopped halfway, after Claude rewrote the memory: the memory was never removed, so
+ * only the MEMORY.md lines the delete took out come back, and the memory stays as it is now.
+ */
+function onlyIndexLines({ manifest, current, saved, index }) {
+    return (manifest.kind === "memory-delete" &&
+        manifest.after === "partial" &&
+        current !== null &&
+        current !== saved &&
+        (index?.missing.length ?? 0) > 0);
+}
+function blockedReason(plan) {
+    const { manifest, current, saved } = plan;
+    if (saved === null && manifest.kind === "memory-restore")
+        return "This put a deleted memory back. To undo it, delete the memory again.";
+    // Undoing a change that created its file removes the file, but only the one ccdesk wrote.
+    if (saved === null) {
+        if (manifest.after === "pending" || manifest.after === "partial")
+            return "This change stopped halfway, so ccdesk cannot tell what it wrote. Remove the file by hand if you need to.";
+        if (current === null)
+            return "The file ccdesk created is gone already.";
+        if (plan.linked || revisionOf(current) !== manifest.after)
+            return "The file changed after ccdesk created it, so ccdesk does not remove it. Change it in place instead.";
+        return undefined;
+    }
+    if (onlyIndexLines(plan))
+        return undefined;
+    // A file broken since the backup has no values ccdesk could keep; the backup is the way out of it,
+    // and the broken file is itself backed up before the restore replaces it.
+    const now = hiddenValues(current);
+    if ((manifest.kind === "settings" || manifest.kind === "mcp") &&
+        current !== null &&
+        now !== null &&
+        now !== hiddenValues(saved))
+        return "Hidden values in this file (env, headers, a URL's key or a key in args) changed since the backup. ccdesk does not show or change those, so restore this one by hand.";
     // A retry after a restore that wrote the memory but not MEMORY.md finds the memory already back.
     if (manifest.kind === "memory-delete" && current !== null && current !== saved)
         return "A memory with this file name exists again; delete or rename it first.";
     return undefined;
 }
 export async function previewRestore(env, id) {
+    const { manifest: recorded, dir } = await backupAt(env, id);
+    if (recorded.kind === "mcp-claude")
+        return claudeMcpPreview(id, recorded, dir);
     const plan = await planRestore(env, id);
     const { manifest, current, saved, index } = plan;
-    const shown = manifest.kind === "settings" ? shownSettings : shownText;
-    const before = shown(current);
-    const after = shown(saved) ?? "";
+    const show = manifest.kind === "settings" || manifest.kind === "mcp" ? shownSettings : shownText;
+    const before = show(current);
+    const after = (onlyIndexLines(plan) ? before : show(saved)) ?? "";
     const blocked = blockedReason(plan);
     return {
         id,
@@ -177,21 +236,35 @@ export async function previewRestore(env, id) {
         before,
         after,
         revision: planRevision(plan),
+        ...(saved === null ? { removes: true } : {}),
         ...(blocked ? { blocked } : {}),
-        ...(index && index.missing.length > 0 ? { indexLines: index.missing } : {}),
+        ...(index && index.missing.length > 0
+            ? { indexLines: index.missing.map((line) => shownText(line) ?? line) }
+            : {}),
     };
 }
-/** Puts a backed-up file back, if the file is still as it was when the restore was reviewed. */
+/**
+ * Puts a backed-up file back, or removes a file ccdesk created, if the file is still as it was
+ * when the restore was reviewed. A removed file is backed up first, so it can be put back too.
+ */
 export function restoreBackup(env, id, expectedRevision) {
     return serially(async () => {
         const plan = await planRestore(env, id);
         const { manifest, current, saved, index } = plan;
         const blocked = blockedReason(plan);
-        if (blocked || saved === null)
+        if (blocked)
             throw new RefusedError(blocked);
         if (planRevision(plan) !== expectedRevision)
             throw new RefusedError("The file changed since you reviewed this restore; review it again.");
         const { target } = manifest;
+        if (saved === null) {
+            await recordChange(env, { kind: manifest.kind, target, before: current }, async () => {
+                if (!(await removeExactly(target, revisionOf(current))))
+                    throw new StaleError(`${target} changed while ccdesk was removing it; nothing was removed. Review it again.`);
+                return { revision: revisionOf(null) };
+            });
+            return { target };
+        }
         if (manifest.kind !== "memory-delete") {
             await recordChange(env, { kind: manifest.kind, target, before: current }, async () => {
                 await writeAtomic(env, target, saved, revisionOf(current));
@@ -200,10 +273,14 @@ export function restoreBackup(env, id, expectedRevision) {
             return { target };
         }
         // A memory and its MEMORY.md lines come back together: when the index cannot be written, the
-        // memory just put back is removed again, so a refused restore leaves both as they were.
-        const created = current === null;
-        if (created)
-            await writeAtomic(env, target, saved, revisionOf(null));
+        // memory just put back is removed again, with its record, so a refused restore leaves both as
+        // they were.
+        const created = current === null
+            ? await recordChange(env, { kind: "memory-restore", target, before: null }, async () => {
+                await writeAtomic(env, target, saved, revisionOf(null));
+                return { revision: revisionOf(saved) };
+            })
+            : null;
         try {
             if (index && index.missing.length > 0) {
                 const lines = (index.text ?? "").split("\n");
@@ -217,8 +294,8 @@ export function restoreBackup(env, id, expectedRevision) {
             }
         }
         catch (error) {
-            if (created)
-                await removeExactly(target, revisionOf(saved));
+            if (created && (await removeExactly(target, revisionOf(saved))))
+                await forgetChange(env, created.id);
             throw error;
         }
         return { target };

package/dist/server/cli.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { scanEnvFromProcess } from "./scan/env.js";
 import { createCcdeskServer } from "./server.js";
-const HELP = `ccdesk: see and manage what shapes Claude Code on this machine
+const HELP = `ccdesk: see and change what Claude Code loads on this machine
 
 Usage: npx ccdesk [options]
 
 Options:
-  --port <n>   Port to listen on (default: a free port)
-  --no-open    Print the URL instead of opening a browser
-  -h, --help   Show this help
+  --port <n>            Port to listen on (default: a free port)
+  --no-open             Print the URL instead of opening a browser
+  --config-dir <path>   Claude folder to read, as CLAUDE_CONFIG_DIR sets it for Claude Code
+                        (wins over $CLAUDE_CONFIG_DIR)
+  -h, --help            Show this help
 
-ccdesk reads ~/.claude (or $CLAUDE_CONFIG_DIR) and opens on the directory you run it from.
+ccdesk reads ~/.claude (or --config-dir, or $CLAUDE_CONFIG_DIR) and opens on the directory you
+run it from.
 It listens on 127.0.0.1 only.`;
 const DEV_PORT = 4319;
 const DEV_TOKEN = "dev";
@@ -23,6 +27,7 @@ function options() {
         return parseArgs({
             options: {
                 port: { type: "string" },
+                "config-dir": { type: "string" },
                 open: { type: "boolean", default: true },
                 dev: { type: "boolean", default: false },
                 help: { type: "boolean", short: "h", default: false },
@@ -48,9 +53,15 @@ function main() {
         process.exitCode = 2;
         return;
     }
+    const configDir = values["config-dir"];
+    if (configDir !== undefined && !statSync(configDir, { throwIfNoEntry: false })?.isDirectory()) {
+        console.error(`ccdesk: --config-dir ${configDir} is not a folder`);
+        process.exitCode = 2;
+        return;
+    }
     const token = dev ? DEV_TOKEN : randomBytes(18).toString("base64url");
     const server = createCcdeskServer({
-        env: scanEnvFromProcess(),
+        env: scanEnvFromProcess(configDir),
         launchDir: process.cwd(),
         token,
         uiDir: dev ? null : fileURLToPath(new URL("../ui", import.meta.url)),
@@ -73,11 +84,13 @@ function main() {
         if (values.open)
             openBrowser(url);
     });
-    process.once("SIGINT", () => {
+    const stop = () => {
         // An open browser tab keeps a connection alive, which would hold close() open.
         server.close(() => process.exit(0));
         server.closeAllConnections();
-    });
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
 }
 function openBrowser(url) {
     const [command, args] = process.platform === "darwin"

package/dist/server/mcp-edit.js

@@ -0,0 +1,263 @@
+import { execFile } from "node:child_process";
+import { access, stat } from "node:fs/promises";
+import { delimiter, join, resolve } from "node:path";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { gitRoot, isRecord, jsonSyntaxError, mainWorktreeRoot, redactSecrets, revisionOf, } from "./scan/files.js";
+import { serverProblems } from "./scan/mcp.js";
+import { hasHiddenValues, secretTexts, shown } from "./secrets.js";
+import { RefusedError, readIfExists, recordChange, recordClaudeMcpChange, serially, writeAtomic, } from "./write.js";
+const exists = (path) => access(path).then(() => true, () => false);
+/**
+ * The program to run for `claude`. On Windows, npm installs Claude Code as a claude.cmd that starts
+ * the package's claude.exe; Node cannot run a .cmd without a shell, which would read the server's
+ * JSON as shell syntax, so ccdesk runs that claude.exe itself. A claude.exe earlier on PATH, as the
+ * native installer puts there, comes first, as it would in a terminal.
+ */
+export async function claudeProgram(path = process.env.PATH ?? "", platform = process.platform) {
+    if (platform !== "win32")
+        return "claude";
+    // Windows reads a PATH entry in quotes as the folder inside them.
+    for (const dir of path
+        .split(delimiter)
+        .map((d) => d.replace(/^"(.*)"$/, "$1"))
+        .filter(Boolean)) {
+        if (await exists(join(dir, "claude.exe")))
+            return join(dir, "claude.exe");
+        const fromNpm = join(dir, "node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe");
+        if ((await exists(join(dir, "claude.cmd"))) && (await exists(fromNpm)))
+            return fromNpm;
+    }
+    return "claude";
+}
+/** The secret values in a server definition passed to claude, which add-json takes as one JSON argument. */
+function secretsIn(args) {
+    return args.flatMap((arg) => {
+        if (!arg.startsWith("{"))
+            return [];
+        try {
+            return secretTexts(JSON.parse(arg));
+        }
+        catch {
+            // Not JSON after all, so it holds no definition.
+            return [];
+        }
+    });
+}
+export const runClaude = async (args, cwd) => {
+    const program = await claudeProgram();
+    return new Promise((done, fail) => {
+        execFile(program, args, { cwd, timeout: 30_000 }, (error, stdout, stderr) => {
+            if (error?.code === "ENOENT")
+                return fail(new RefusedError("ccdesk changes your user and local MCP servers through the claude command, which is not on PATH."));
+            // Node's own message repeats the command, with the server's env and header values in it.
+            if (error) {
+                // claude's own message may quote the definition it was given.
+                const said = secretsIn(args).reduce((text, secret) => text.replaceAll(secret, "•••"), stderr);
+                const reason = said.trim() ||
+                    (error.killed ? "it took longer than 30 seconds" : `it exited with code ${error.code}`);
+                return fail(new RefusedError(`claude ${args[1]} failed: ${reason}`));
+            }
+            done(stdout);
+        });
+    });
+};
+/** Quotes a word for a POSIX shell, so a command shown to you can be pasted as it is. */
+function quoted(word) {
+    return `'${word.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * Checks what an edit asks for against the servers as they are now: the one to remove must still
+ * be as the scan showed it, and the one to add must not take another server's name.
+ */
+function checked(servers, edit) {
+    const { remove, add } = edit;
+    if (remove) {
+        const now = servers[remove.name];
+        if (now === undefined ||
+            JSON.stringify(redactSecrets(now)) !== JSON.stringify(remove.definition))
+            throw new RefusedError(`${remove.name} changed since ccdesk read it; review it again.`);
+        // ccdesk never shows hidden values, so it cannot write them back either.
+        if (add && hasHiddenValues(now))
+            throw new RefusedError(`${remove.name} has values ccdesk does not show, in env, headers, its url or its args; edit it in the file, or remove it and add it again.`);
+    }
+    if (add) {
+        if (add.name.trim() === "" || /[\p{Cc}\p{Cf}\s]/u.test(add.name))
+            throw new RefusedError("A server name needs letters or digits and no spaces.");
+        if (add.name !== remove?.name && Object.hasOwn(servers, add.name))
+            throw new RefusedError(`There is already a server named ${add.name} here.`);
+    }
+}
+/** The servers after the edit, with a replaced server kept in its place. */
+function edited(servers, edit) {
+    const { remove, add } = edit;
+    // Built with fromEntries: assigning a server named __proto__ would set the prototype instead.
+    const next = Object.entries(servers).flatMap(([name, config]) => {
+        if (name !== remove?.name)
+            return [[name, config]];
+        return add ? [[add.name, add.definition]] : [];
+    });
+    if (add && !remove)
+        next.push([add.name, add.definition]);
+    return Object.fromEntries(next);
+}
+/** A project server: ccdesk changes .mcp.json itself, backed up and listed in Recent changes. */
+async function planProject(env, edit) {
+    const dir = resolve(edit.dir);
+    if (!(await stat(dir).catch(() => null))?.isDirectory())
+        throw new RefusedError(`${dir} is not a directory on this machine.`);
+    const path = join(dir, ".mcp.json");
+    const raw = await readIfExists(env, path);
+    let data = {};
+    if (raw !== null && raw.trim() !== "") {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new RefusedError(`${path} is ${jsonSyntaxError(error)}; fix it by hand first.`);
+        }
+        if (!isRecord(parsed))
+            throw new RefusedError(`${path} does not hold a JSON object.`);
+        data = parsed;
+    }
+    const servers = isRecord(data.mcpServers) ? data.mcpServers : {};
+    checked(servers, edit);
+    const next = { ...data, mcpServers: edited(servers, edit) };
+    const text = `${JSON.stringify(next, null, 2)}\n`;
+    const errors = edit.add ? serverProblems(edit.add.definition) : [];
+    const before = raw === null ? null : shown(data);
+    return {
+        preview: {
+            path,
+            before,
+            after: errors.length > 0 ? (before ?? "") : shown(next),
+            revision: revisionOf(raw),
+            reformats: raw !== null && raw.trim() !== "" && raw !== `${JSON.stringify(data, null, 2)}\n`,
+            errors,
+        },
+        save: () => recordChange(env, { kind: "mcp", target: path, before: raw }, async () => {
+            await writeAtomic(env, path, text, revisionOf(raw));
+            return { target: path, revision: revisionOf(text) };
+        }),
+    };
+}
+/**
+ * A user or local server, which lives in ~/.claude.json: ccdesk runs Claude Code's own
+ * `claude mcp` commands rather than write that file, which Claude Code rewrites all the time.
+ */
+async function planClaudeJson(env, edit, run) {
+    const dir = resolve(edit.dir);
+    const raw = await readIfExists(env, env.claudeJson);
+    let data = {};
+    try {
+        const parsed = raw === null ? {} : JSON.parse(raw);
+        if (isRecord(parsed))
+            data = parsed;
+    }
+    catch (error) {
+        throw new RefusedError(`${env.claudeJson} is ${jsonSyntaxError(error)}; fix it by hand first.`);
+    }
+    // Local servers are kept per project, under the key the scan reads them from: the main
+    // checkout's root, or this folder outside git. Claude Code files them there from any folder below.
+    const projects = isRecord(data.projects) ? data.projects : {};
+    const root = (await mainWorktreeRoot(dir)) ?? (await gitRoot(dir)) ?? dir;
+    // User servers do not depend on the folder, so claude runs in your home directory for them.
+    const cwd = edit.scope === "user" ? env.home : root;
+    if (!(await stat(cwd).catch(() => null))?.isDirectory())
+        throw new RefusedError(`${cwd} is not a directory on this machine.`);
+    const holder = edit.scope === "user" ? data : projects[cwd];
+    const servers = isRecord(holder) && isRecord(holder.mcpServers) ? holder.mcpServers : {};
+    checked(servers, edit);
+    const { remove, add } = edit;
+    const errors = add ? serverProblems(add.definition) : [];
+    // Names follow "--", so one such as --help is a name, not an option.
+    const addArgs = (name, definition) => [
+        "mcp",
+        "add-json",
+        "--scope",
+        edit.scope,
+        "--",
+        name,
+        JSON.stringify(definition),
+    ];
+    const addCommand = (name, definition) => `claude mcp add-json --scope ${edit.scope} -- ${quoted(name)} ${quoted(JSON.stringify(definition))}`;
+    const before = Object.keys(servers).length > 0 ? shown(servers) : null;
+    // Recent changes lists the edit with the servers it touched, values hidden as the page shows
+    // them, and the commands that put them back from the folder claude ran in.
+    const record = () => {
+        const names = [remove?.name, add?.name].filter((n) => n !== undefined);
+        const touched = (all) => Object.fromEntries(Object.entries(all).filter(([name]) => names.includes(name)));
+        const at = edit.scope === "local" ? `cd ${quoted(cwd)} && ` : "";
+        return recordClaudeMcpChange(env, {
+            target: env.claudeJson,
+            shownBefore: shown(touched(servers)),
+            shownAfter: shown(touched(edited(servers, edit))),
+            undoCommands: [
+                ...(add ? [`${at}claude mcp remove --scope ${edit.scope} -- ${quoted(add.name)}`] : []),
+                ...(remove ? [`${at}${addCommand(remove.name, redactSecrets(servers[remove.name]))}`] : []),
+            ],
+        });
+    };
+    return {
+        preview: {
+            path: env.claudeJson,
+            before,
+            after: errors.length > 0 ? (before ?? "") : shown(edited(servers, edit)),
+            // Of the servers as stored, so a changed hidden value, which the page never sees,
+            // still makes a reviewed edit stale.
+            revision: revisionOf(JSON.stringify(servers)),
+            reformats: false,
+            errors,
+            // Shown with secrets hidden; the command that runs has the values you typed.
+            commands: [
+                ...(remove ? [`claude mcp remove --scope ${edit.scope} -- ${quoted(remove.name)}`] : []),
+                ...(add ? [addCommand(add.name, redactSecrets(add.definition))] : []),
+            ],
+        },
+        save: async () => {
+            if (remove)
+                await run(["mcp", "remove", "--scope", edit.scope, "--", remove.name], cwd);
+            // The change is made by then; a record that cannot be written only leaves it unlisted.
+            if (!add) {
+                await record().catch(() => undefined);
+                return { target: env.claudeJson };
+            }
+            try {
+                await run(addArgs(add.name, add.definition), cwd);
+            }
+            catch (error) {
+                if (!remove)
+                    throw error;
+                // A replaced server goes back as it was, so a refused add does not lose it. When that
+                // fails too, the error gives the command that puts it back, from the folder a local server
+                // belongs to; a replaced server has no hidden values (see checked), so the command shows
+                // nothing the page does not.
+                const original = servers[remove.name];
+                await run(addArgs(remove.name, original), cwd).catch(() => {
+                    throw new RefusedError(`ccdesk removed ${remove.name}, then could not add it back. In bash, zsh or Git Bash, put it back with: ${edit.scope === "local" ? `cd ${quoted(cwd)} && ` : ""}${addCommand(remove.name, original)} (${error instanceof Error ? error.message : String(error)})`);
+                });
+                throw error;
+            }
+            await record().catch(() => undefined);
+            return { target: env.claudeJson };
+        },
+    };
+}
+function plan(env, edit, run) {
+    return edit.scope === "project" ? planProject(env, edit) : planClaudeJson(env, edit, run);
+}
+export async function previewMcpEdit(env, edit, run) {
+    return (await plan(env, edit, run)).preview;
+}
+/** Makes a reviewed MCP edit, only while the servers are still as reviewed. */
+export function saveMcpEdit(env, edit, expectedRevision, run) {
+    return serially(async () => {
+        const planned = await plan(env, edit, run);
+        if (planned.preview.errors.length > 0)
+            throw new RefusedError(planned.preview.errors.join(" "));
+        if (planned.preview.revision !== expectedRevision)
+            throw new RefusedError("The servers changed since you reviewed this edit; review it again.");
+        return planned.save();
+    });
+}

package/dist/server/mutations.js

@@ -3,7 +3,7 @@ import { basename, dirname, join } from "node:path";
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
 import { isWithin, parseFrontmatter, revisionOf, shownText, stringField } from "./scan/files.js";
-import { deadLinks } from "./scan/memory.js";
+import { deadLinks, indexMentions } from "./scan/memory.js";
 import { RefusedError, readIfExists, recordChange, removeExactly, serially, writeAtomic, } from "./write.js";
 async function projectsRoot(env) {
     return realpath(join(env.claudeDir, "projects")).catch(() => {
@@ -72,7 +72,7 @@ async function planDelete(env, path) {
     const index = await readIfExists(env, indexPath);
     const removedIndexLines = [];
     const kept = (index ?? "").split("\n").filter((line) => {
-        if (!line.includes(`(${basename(real)})`))
+        if (!indexMentions(line, basename(real)))
             return true;
         removedIndexLines.push(line);
         return false;
@@ -104,7 +104,12 @@ async function planDelete(env, path) {
             }
             if (!removed)
                 throw reviewAgain();
-            return { target: real, revision: revisionOfBoth(null, next), removedIndexLines };
+            // The lines are kept as they were in the backup; the page gets them as ccdesk shows text.
+            return {
+                target: real,
+                revision: revisionOfBoth(null, next),
+                removedIndexLines: removedIndexLines.map((line) => shownText(line) ?? line),
+            };
         });
     };
     return {