ccdesk 0.0.0-stage → 0.2.0

package/dist/server/cli.js

@@ -0,0 +1,105 @@
+#!/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 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
+  --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 --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";
+function options() {
+    try {
+        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 },
+            },
+            allowNegative: true,
+        }).values;
+    }
+    catch (error) {
+        console.error(`ccdesk: ${error.message}\n\n${HELP}`);
+        process.exit(2);
+    }
+}
+function main() {
+    const values = options();
+    if (values.help) {
+        console.log(HELP);
+        return;
+    }
+    const dev = values.dev;
+    const port = values.port ? Number(values.port) : dev ? DEV_PORT : 0;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error(`ccdesk: invalid --port ${values.port}`);
+        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(configDir),
+        launchDir: process.cwd(),
+        token,
+        uiDir: dev ? null : fileURLToPath(new URL("../ui", import.meta.url)),
+    });
+    server.on("error", (error) => {
+        console.error(error.code === "EADDRINUSE"
+            ? `ccdesk: port ${port} is already in use`
+            : `ccdesk: ${error.message}`);
+        process.exitCode = 1;
+    });
+    server.listen(port, "127.0.0.1", () => {
+        const address = server.address();
+        const actual = typeof address === "object" && address ? address.port : port;
+        if (dev) {
+            console.log(`ccdesk API on http://127.0.0.1:${actual} (dev token "${DEV_TOKEN}"); run \`pnpm dev:ui\` for the UI`);
+            return;
+        }
+        const url = `http://127.0.0.1:${actual}/#token=${token}`;
+        console.log(`ccdesk is running at ${url}\nPress Ctrl+C to stop.`);
+        if (values.open)
+            openBrowser(url);
+    });
+    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"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => console.log("Could not open a browser; open the URL above."));
+    child.unref();
+}
+main();

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

@@ -0,0 +1,193 @@
+import { access, constants, readdir, realpath, stat } from "node:fs/promises";
+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, 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(() => {
+        throw new RefusedError("There is no auto memory folder.");
+    });
+}
+/** A real `<config>/projects/<store>/memory` folder, after following links. */
+export async function assertMemoryDir(env, dir) {
+    const real = await realpath(dir).catch(() => {
+        throw new RefusedError("That memory folder no longer exists.");
+    });
+    const root = await projectsRoot(env);
+    if (real === root || !isWithin(root, real) || basename(real) !== "memory")
+        throw new RefusedError("ccdesk only changes auto memory under ~/.claude/projects.");
+    return real;
+}
+/**
+ * A memory folder's MEMORY.md. When it is a link, the file it leads to must be in the same folder,
+ * so changing the index can never rewrite a file elsewhere.
+ */
+export async function indexPathIn(store) {
+    const path = join(store, "MEMORY.md");
+    const real = await realpath(path).catch(() => path);
+    if (dirname(real) !== store)
+        throw new RefusedError("This MEMORY.md links outside its memory folder; ccdesk leaves it alone.");
+    return path;
+}
+/** A topic file inside a memory folder: the only kind of file ccdesk deletes. */
+async function assertMemoryFile(env, path) {
+    const real = await realpath(path).catch(() => {
+        throw new RefusedError("That memory file no longer exists.");
+    });
+    await assertMemoryDir(env, dirname(real));
+    if (!real.endsWith(".md") || basename(real) === "MEMORY.md")
+        throw new RefusedError("MEMORY.md is the index Claude maintains; delete individual memories instead.");
+    if (!(await stat(real)).isFile())
+        throw new RefusedError("Not a file.");
+    return real;
+}
+/** One fingerprint for two files, so a change can require both as they were reviewed. */
+export function revisionOfBoth(first, second) {
+    return `${revisionOf(first)}+${revisionOf(second)}`;
+}
+const reviewAgain = () => new RefusedError("The memory or MEMORY.md changed since you reviewed this; review it again.");
+/** Runs a plan only while everything it was worked out from is as reviewed. */
+function saveReviewed(plan, expectedRevision) {
+    return serially(async () => {
+        const planned = await plan();
+        if (planned.preview.revision !== expectedRevision)
+            throw reviewAgain();
+        return planned.save();
+    });
+}
+/** MEMORY.md's lines without the empty ones a trailing newline leaves. */
+function indexLines(index) {
+    const lines = (index ?? "").split("\n");
+    while (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+/** Deletes a memory with the MEMORY.md lines that point at it. */
+async function planDelete(env, path) {
+    const real = await assertMemoryFile(env, path);
+    const text = await readIfExists(env, real);
+    const indexPath = await indexPathIn(dirname(real));
+    const index = await readIfExists(env, indexPath);
+    const removedIndexLines = [];
+    const kept = (index ?? "").split("\n").filter((line) => {
+        if (!indexMentions(line, basename(real)))
+            return true;
+        removedIndexLines.push(line);
+        return false;
+    });
+    const next = removedIndexLines.length > 0 ? kept.join("\n") : index;
+    const revision = revisionOfBoth(text, index);
+    const save = async () => {
+        // A folder that refuses the delete would leave MEMORY.md changed with the memory still there.
+        await access(dirname(real), constants.W_OK);
+        // Nothing of the delete is left when the index is as reviewed and the memory is still there,
+        // even if Claude rewrote the memory meanwhile.
+        const unchanged = async () => revisionOf(await readIfExists(env, indexPath)) === revisionOf(index) &&
+            (await readIfExists(env, real)) !== null;
+        return recordChange(env, { kind: "memory-delete", target: real, before: text, removedIndexLines, unchanged }, async () => {
+            // The index goes first: if it changed meanwhile, nothing has been removed yet.
+            if (next !== index)
+                await writeAtomic(env, indexPath, next ?? "", revisionOf(index));
+            let removed = false;
+            try {
+                removed = await removeExactly(real, revisionOf(text));
+            }
+            finally {
+                // Claude may have rewritten the memory while the index was saved; then the index goes back.
+                if (!removed && next !== index)
+                    await writeAtomic(env, indexPath, index ?? "", revisionOf(next)).catch((error) => {
+                        // The index was already changed, so this is not a "nothing written" refusal.
+                        throw new RefusedError(`MEMORY.md changed again, so ccdesk could not put its line back: ${error instanceof Error ? error.message : error}`);
+                    });
+            }
+            if (!removed)
+                throw reviewAgain();
+            // 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 {
+        preview: {
+            files: [
+                { path: real, before: text, after: null },
+                ...(next !== index ? [{ path: indexPath, before: index, after: next }] : []),
+            ],
+            revision,
+        },
+        save,
+    };
+}
+/** Rewrites MEMORY.md through `edit`, recorded in Recent changes. */
+async function planIndex(env, store, edit, 
+/** Other text the new index was worked out from, bound into the revision. */
+source) {
+    const path = await indexPathIn(store);
+    const before = await readIfExists(env, path);
+    const after = `${edit(indexLines(before)).join("\n")}\n`;
+    if (after === before)
+        throw new RefusedError("MEMORY.md already says that.");
+    const save = () => recordChange(env, { kind: "memory-index", target: path, before }, async () => {
+        await writeAtomic(env, path, after, revisionOf(before));
+        return { target: path, revision: revisionOf(after) };
+    });
+    return {
+        preview: { files: [{ path, before, after }], revision: revisionOfBoth(before, source) },
+        save,
+    };
+}
+/** One line of text: frontmatter can hold multi-line strings, an index line cannot. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** Adds a memory that MEMORY.md does not mention, in the `- [name](file) — description` form. */
+async function planAdd(env, memoryPath) {
+    const real = await assertMemoryFile(env, memoryPath);
+    const text = await readIfExists(env, real);
+    const { data } = parseFrontmatter(text ?? "");
+    const name = oneLine(stringField(data, "name")) || basename(real, ".md");
+    const description = oneLine(stringField(data, "description"));
+    const line = `- [${name}](${basename(real)})${description ? ` — ${description}` : ""}`;
+    return planIndex(env, dirname(real), (lines) => [...lines, line], text);
+}
+/** Removes every MEMORY.md line that points at a memory file that no longer exists. */
+async function planRemoveDead(env, indexPath) {
+    if (basename(indexPath) !== "MEMORY.md")
+        throw new RefusedError("Only a memory folder's MEMORY.md can be changed.");
+    const store = await assertMemoryDir(env, dirname(indexPath));
+    const files = (await readdir(store)).sort();
+    return planIndex(env, store, (lines) => lines.filter((line) => deadLinks(line, files).length === 0), files.join("\n"));
+}
+const PLANS = {
+    delete: planDelete,
+    add: planAdd,
+    "remove-dead": planRemoveDead,
+};
+export function isMemoryAction(value) {
+    return Object.hasOwn(PLANS, value);
+}
+/** What a memory action would change, for review. */
+export async function previewMemoryChange(env, action, path) {
+    // Shown like any other text: a memory folder could hold a JSON file with secrets.
+    const { files, revision } = (await PLANS[action](env, path)).preview;
+    return {
+        files: files.map((f) => ({
+            path: f.path,
+            before: shownText(f.before),
+            after: shownText(f.after),
+        })),
+        revision,
+    };
+}
+/**
+ * Makes a reviewed memory action. `path` is the memory file, or MEMORY.md for remove-dead; the
+ * action runs only while everything its review was worked out from is unchanged.
+ */
+export function changeMemory(env, action, path, expectedRevision) {
+    return saveReviewed(() => PLANS[action](env, path), expectedRevision);
+}