ccdesk 0.2.2 → 0.2.4

package/dist/{server → core}/mcp-edit.js

@@ -3,10 +3,12 @@ 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 { revisionOf } from "./scan/files.js";
+import { isRecord, parseJson } from "./scan/data.js";
+import { claudeJsonKey, gitRoot, mainWorktreeRoot, trustKey } from "./scan/git.js";
 import { serverProblems } from "./scan/mcp.js";
-import { hasHiddenValues, secretTexts, shown } from "./secrets.js";
-import { RefusedError, readIfExists, recordChange, recordClaudeMcpChange, serially, writeAtomic, } from "./write.js";
+import { hasHiddenValues, jsonSyntaxError, redactSecrets, secretTexts, shown } from "./secrets.js";
+import { RefusedError, readIfExists, readJsonObject, recordChange, recordClaudeMcpChange, saveReviewed, 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
@@ -14,7 +16,7 @@ const exists = (path) => access(path).then(() => true, () => false);
  * 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) {
+export async function claudeProgram(path, platform) {
     if (platform !== "win32")
         return "claude";
     // Windows reads a PATH entry in quotes as the folder inside them.
@@ -44,26 +46,39 @@ function secretsIn(args) {
         }
     });
 }
-export const runClaude = async (args, cwd, configDir) => {
-    const program = await claudeProgram();
-    // Set only for a chosen profile: Claude Code also moves .claude.json into a CLAUDE_CONFIG_DIR.
-    const env = configDir === undefined ? process.env : { ...process.env, CLAUDE_CONFIG_DIR: configDir };
-    return new Promise((done, fail) => {
-        execFile(program, args, { cwd, env, 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);
-        });
-    });
+/**
+ * Why claude did not start. On Windows a claude.cmd that npm did not install, such as Scoop's,
+ * Volta's or pnpm's, is on PATH but cannot be run without a shell, so "not on PATH" would mislead.
+ */
+const CLAUDE_NOT_FOUND = {
+    win32: "ccdesk changes your user and local MCP servers through the claude command and could not start it from PATH. On Windows it runs claude.exe, or the claude.exe inside npm's package when only npm's claude.cmd is there; another installer's claude.cmd or claude.ps1 cannot be started without a shell.",
+    other: "ccdesk changes your user and local MCP servers through the claude command, which is not on PATH.",
 };
+/** Runs the claude on `host`'s PATH, with `host`'s environment. */
+export function claudeRunner(host) {
+    return async (args, cwd, configDir) => {
+        const program = await claudeProgram(host.processEnv.PATH ?? "", host.platform);
+        // Set only for a chosen profile: Claude Code also moves .claude.json into a CLAUDE_CONFIG_DIR.
+        const env = configDir === undefined
+            ? host.processEnv
+            : { ...host.processEnv, CLAUDE_CONFIG_DIR: configDir };
+        return new Promise((done, fail) => {
+            execFile(program, args, { cwd, env, timeout: 30_000 }, (error, stdout, stderr) => {
+                if (error?.code === "ENOENT")
+                    return fail(new RefusedError(CLAUDE_NOT_FOUND[host.platform === "win32" ? "win32" : "other"]));
+                // 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("'", "'\\''")}'`;
@@ -109,20 +124,7 @@ async function planProject(env, edit) {
     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 { raw, data, reformats } = await readJsonObject(env, path);
     const servers = isRecord(data.mcpServers) ? data.mcpServers : {};
     checked(servers, edit);
     const next = { ...data, mcpServers: edited(servers, edit) };
@@ -135,7 +137,7 @@ async function planProject(env, edit) {
             before,
             after: errors.length > 0 ? (before ?? "") : shown(next),
             revision: revisionOf(raw),
-            reformats: raw !== null && raw.trim() !== "" && raw !== `${JSON.stringify(data, null, 2)}\n`,
+            reformats,
             errors,
         },
         save: () => recordChange(env, { kind: "mcp", target: path, before: raw }, async () => {
@@ -145,36 +147,37 @@ async function planProject(env, edit) {
     };
 }
 /**
- * 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.
+ * The user or local servers an edit changes in ~/.claude.json, and the folder claude runs in for
+ * them. Local servers are kept per project, under the key the scan reads them from; Claude Code
+ * files them there from any folder below. User servers do not depend on the folder, so claude runs
+ * in your home directory for them.
  */
-async function planClaudeJson(env, edit, run) {
-    const dir = resolve(edit.dir);
+async function claudeJsonServers(env, edit) {
     const raw = await readIfExists(env, env.claudeJson);
     let data = {};
     try {
-        const parsed = raw === null ? {} : JSON.parse(raw);
+        const parsed = raw === null ? {} : parseJson(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;
+    const dir = resolve(edit.dir);
+    const cwd = edit.scope === "user"
+        ? env.home
+        : trustKey(dir, await mainWorktreeRoot(dir), await gitRoot(dir));
     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 projects = isRecord(data.projects) ? data.projects : {};
+    const holder = edit.scope === "user" ? data : projects[claudeJsonKey(env, 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) => [
+    return { cwd, servers };
+}
+/** The `claude mcp` arguments for an edit; names follow "--", so one such as --help is a name. */
+const claudeArgs = {
+    remove: (edit, name) => ["mcp", "remove", "--scope", edit.scope, "--", name],
+    add: (edit, name, definition) => [
         "mcp",
         "add-json",
         "--scope",
@@ -182,27 +185,76 @@ async function planClaudeJson(env, edit, run) {
         "--",
         name,
         JSON.stringify(definition),
-    ];
-    // The commands shown and recorded name the profile, so pasting one changes the same servers.
+    ],
+};
+/**
+ * `claude` with these arguments as you would type it in bash, zsh or Git Bash: the server's name
+ * and definition after "--" are quoted, and the profile ccdesk reads is named, so pasting the line
+ * changes the same servers. With `cwd`, it starts by going to the folder claude ran in.
+ */
+function commandLine(env, args, cwd) {
+    const names = args.indexOf("--") + 1;
     const claude = env.configDir === undefined ? "claude" : `CLAUDE_CONFIG_DIR=${quoted(env.configDir)} claude`;
-    const addCommand = (name, definition) => `${claude} mcp add-json --scope ${edit.scope} -- ${quoted(name)} ${quoted(JSON.stringify(definition))}`;
+    const line = [claude, ...args.slice(0, names), ...args.slice(names).map(quoted)].join(" ");
+    return cwd === undefined ? line : `cd ${quoted(cwd)} && ${line}`;
+}
+/**
+ * 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 { cwd, servers } = await claudeJsonServers(env, edit);
+    checked(servers, edit);
+    const { remove, add } = edit;
+    const errors = add ? serverProblems(add.definition) : [];
     const before = Object.keys(servers).length > 0 ? shown(servers) : null;
+    // A local server's commands to paste go to the folder it belongs to first.
+    const from = edit.scope === "local" ? cwd : undefined;
     // 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.
+    // them, and the commands that put them back.
     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]))}`] : []),
+                ...(add ? [commandLine(env, claudeArgs.remove(edit, add.name), from)] : []),
+                ...(remove
+                    ? [
+                        commandLine(env, claudeArgs.add(edit, remove.name, redactSecrets(servers[remove.name])), from),
+                    ]
+                    : []),
             ],
         });
     };
+    const save = async () => {
+        if (remove)
+            await run(claudeArgs.remove(edit, remove.name), cwd, env.configDir);
+        // 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(claudeArgs.add(edit, add.name, add.definition), cwd, env.configDir);
+        }
+        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; a replaced server has no hidden values
+            // (see checked), so the command shows nothing the page does not.
+            const putBack = claudeArgs.add(edit, remove.name, servers[remove.name]);
+            await run(putBack, cwd, env.configDir).catch(() => {
+                throw new RefusedError(`ccdesk removed ${remove.name}, then could not add it back. In bash, zsh or Git Bash, put it back with: ${commandLine(env, putBack, from)} (${error instanceof Error ? error.message : String(error)})`);
+            });
+            throw error;
+        }
+        await record().catch(() => undefined);
+        return { target: env.claudeJson };
+    };
     return {
         preview: {
             path: env.claudeJson,
@@ -215,37 +267,13 @@ async function planClaudeJson(env, edit, run) {
             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))] : []),
+                ...(remove ? [commandLine(env, claudeArgs.remove(edit, remove.name))] : []),
+                ...(add
+                    ? [commandLine(env, claudeArgs.add(edit, add.name, redactSecrets(add.definition)))]
+                    : []),
             ],
         },
-        save: async () => {
-            if (remove)
-                await run(["mcp", "remove", "--scope", edit.scope, "--", remove.name], cwd, env.configDir);
-            // 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, env.configDir);
-            }
-            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, env.configDir).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 };
-        },
+        save,
     };
 }
 function plan(env, edit, run) {
@@ -255,13 +283,6 @@ 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();
-    });
+export function saveMcpEdit(env, edit, expectedRevision, run, queue) {
+    return saveReviewed(queue, () => plan(env, edit, run), expectedRevision, "The servers changed since you reviewed this edit; review it again.");
 }

package/dist/core/mutations.d.ts

@@ -0,0 +1,20 @@
+import { type Change, type MemoryAction, type MemoryChangePreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+/** A real `<config>/projects/<store>/memory` folder, after following links. */
+export declare function assertMemoryDir(env: ScanEnv, dir: string): Promise<string>;
+/**
+ * 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 declare function indexPathIn(store: string): Promise<string>;
+/** One fingerprint for two files, so a change can require both as they were reviewed. */
+export declare function revisionOfBoth(first: string | null, second: string | null): string;
+export declare function isMemoryAction(value: string): value is MemoryAction;
+/** What a memory action would change, for review. */
+export declare function previewMemoryChange(env: ScanEnv, action: MemoryAction, path: string): Promise<MemoryChangePreview>;
+/**
+ * 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 declare function changeMemory(env: ScanEnv, action: MemoryAction, path: string, expectedRevision: string, queue: Serially): Promise<Change>;

package/dist/{server → core}/mutations.js

@@ -2,9 +2,11 @@ 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 { isWithin, revisionOf, stringField } from "./scan/files.js";
+import { parseFrontmatter } from "./scan/data.js";
+import { shownText } from "./secrets.js";
 import { deadLinks, indexMentions } from "./scan/memory.js";
-import { RefusedError, readIfExists, recordChange, removeExactly, serially, writeAtomic, } from "./write.js";
+import { RefusedError, readIfExists, recordChange, removeExactly, saveReviewed, writeAtomic, } from "./write.js";
 async function projectsRoot(env) {
     return realpath(join(env.claudeDir, "projects")).catch(() => {
         throw new RefusedError("There is no auto memory folder.");
@@ -47,16 +49,7 @@ async function assertMemoryFile(env, path) {
 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();
-    });
-}
+const REVIEW_AGAIN = "The memory or MEMORY.md changed since you reviewed this; review it again.";
 /** MEMORY.md's lines without the empty ones a trailing newline leaves. */
 function indexLines(index) {
     const lines = (index ?? "").split("\n");
@@ -103,7 +96,7 @@ async function planDelete(env, path) {
                     });
             }
             if (!removed)
-                throw reviewAgain();
+                throw new RefusedError(REVIEW_AGAIN);
             // The lines are kept as they were in the backup; the page gets them as ccdesk shows text.
             return {
                 target: real,
@@ -188,6 +181,6 @@ export async function previewMemoryChange(env, action, path) {
  * 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);
+export function changeMemory(env, action, path, expectedRevision, queue) {
+    return saveReviewed(queue, () => PLANS[action](env, path), expectedRevision, REVIEW_AGAIN);
 }

package/dist/core/open.d.ts

@@ -0,0 +1,28 @@
+import { type ScanEnv } from "./scan/env.ts";
+type Command = [string, string[]];
+/** The machine an editor is looked for and started on. */
+type Host = Pick<ScanEnv, "platform" | "processEnv">;
+/**
+ * The commands to try, in order: `CCDESK_EDITOR` alone when set; else `VISUAL` or `EDITOR` when
+ * they name a graphical editor, then graphical editors found on PATH, then the system's opener.
+ * The system opener comes last because on Linux it often picks a terminal editor or nothing for
+ * JSON and Markdown.
+ */
+export declare function editorCommands(env: NodeJS.ProcessEnv, platform: NodeJS.Platform, found?: (name: string) => boolean): Command[];
+/**
+ * How to start `command` on `path`. On Windows a .cmd or .bat file (VS Code's `code`) or a bare
+ * name that may resolve to one cannot be started directly, so it goes through cmd.exe, quoted.
+ */
+export declare function spawnPlan(command: string, args: string[], path: string, platform: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    verbatim: boolean;
+};
+/**
+ * Opens `url` in the default browser on `host`; resolves null once the opener started, else why it
+ * failed. On Windows `start` is a cmd.exe builtin, so cmd.exe is the command.
+ */
+export declare function openBrowser(url: string, host: Host): Promise<string | null>;
+/** Opens a file or folder in the first editor that starts on `host`; resolves with the command used. */
+export declare function openInEditor(path: string, host: Host): Promise<string>;
+export {};

package/dist/{server → core}/open.js

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { delimiter, join, posix, win32 } from "node:path";
+import {} from "./scan/env.js";
+import { RefusedError } from "./write.js";
 /** Editors that need a terminal; started from a background server they would have none. */
 const TERMINAL_EDITORS = new Set([
     "vi",
@@ -72,11 +74,7 @@ export function editorCommands(env, platform, found = (name) => onPath(env, plat
     for (const editor of GUI_EDITORS)
         if (found(editor))
             out.push([editor, []]);
-    out.push(platform === "darwin"
-        ? ["open", []]
-        : platform === "win32"
-            ? ["explorer", []]
-            : ["xdg-open", []]);
+    out.push(fileOpener(platform));
     return out.filter((c, i) => out.findIndex((o) => o[0] === c[0]) === i);
 }
 /** Splits an editor setting into words, keeping quoted parts such as "C:\Program Files\…" whole. */
@@ -98,16 +96,17 @@ export function spawnPlan(command, args, path, platform) {
     return { file: "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
 }
 /** Starts one command; resolves null once it is running or exited cleanly, else why it failed. */
-function launch([command, args], path) {
+function launch([command, args], path, host) {
     return new Promise((resolve) => {
         let plan;
         try {
-            plan = spawnPlan(command, args, path, process.platform);
+            plan = spawnPlan(command, args, path, host.platform);
         }
         catch (error) {
             return resolve(error.message);
         }
         const child = spawn(plan.file, plan.args, {
+            env: host.processEnv,
             detached: true,
             stdio: "ignore",
             windowsVerbatimArguments: plan.verbatim,
@@ -122,18 +121,44 @@ function launch([command, args], path) {
         });
         child.once("exit", (code) => {
             clearTimeout(timer);
-            resolve(code === 0 ? null : `${command} exited with code ${code}`);
+            // explorer.exe hands the file to the running shell and exits with 1 even when that worked.
+            if (code === 0 || command === "explorer")
+                return resolve(null);
+            resolve(`${command} exited with code ${code}`);
         });
     });
 }
-/** Opens a file or folder in the first editor that starts; resolves with the command used. */
-export async function openInEditor(path) {
+/**
+ * Opens `url` in the default browser on `host`; resolves null once the opener started, else why it
+ * failed. On Windows `start` is a cmd.exe builtin, so cmd.exe is the command.
+ */
+export function openBrowser(url, host) {
+    return launch(browserOpener(host.platform), url, host);
+}
+/** The system's own way to open a file in the app it belongs to. */
+function fileOpener(platform) {
+    if (platform === "darwin")
+        return ["open", []];
+    if (platform === "win32")
+        return ["explorer", []];
+    return ["xdg-open", []];
+}
+/** The system's own way to open a URL in the default browser. */
+function browserOpener(platform) {
+    if (platform === "darwin")
+        return ["open", []];
+    if (platform === "win32")
+        return ["cmd.exe", ["/c", "start", ""]];
+    return ["xdg-open", []];
+}
+/** Opens a file or folder in the first editor that starts on `host`; resolves with the command used. */
+export async function openInEditor(path, host) {
     const failures = [];
-    for (const command of editorCommands(process.env, process.platform)) {
-        const failure = await launch(command, path);
+    for (const command of editorCommands(host.processEnv, host.platform)) {
+        const failure = await launch(command, path, host);
         if (failure === null)
             return command[0];
         failures.push(failure);
     }
-    throw new Error(`Could not open it (${failures.join("; ")}). Set CCDESK_EDITOR to your editor.`);
+    throw new RefusedError(`Could not open it (${failures.join("; ")}). Set CCDESK_EDITOR to your editor.`);
 }

package/dist/core/parse-edit.d.ts

@@ -0,0 +1,12 @@
+import { type AgentEdit, type HookEdit, type McpEdit, type PermissionEdit, type SettingsEdit } from "../shared/types.ts";
+/**
+ * An edit that is not well formed, such as an unknown scope or a missing field: the caller sent
+ * something no review could have produced. The edit modules trust the edits these parsers return.
+ */
+export declare class InvalidEditError extends Error {
+}
+export declare function parseSettingsEdit(body: unknown): SettingsEdit;
+export declare function parsePermissionEdit(body: unknown): PermissionEdit;
+export declare function parseHookEdit(body: unknown): HookEdit;
+export declare function parseAgentEdit(body: unknown): AgentEdit;
+export declare function parseMcpEdit(body: unknown): McpEdit;

package/dist/core/parse-edit.js

@@ -0,0 +1,64 @@
+import { Compile } from "typebox/compile";
+import HOOK_EVENTS from "../shared/hook-events.json" with { type: "json" };
+import { AgentEditBody, HookEditBody, McpEditBody, PermissionEditBody, SettingsEditBody, } from "../shared/requests.js";
+import {} from "../shared/types.js";
+import { isRecord } from "./scan/data.js";
+import { firstError } from "./schema.js";
+/**
+ * An edit that is not well formed, such as an unknown scope or a missing field: the caller sent
+ * something no review could have produced. The edit modules trust the edits these parsers return.
+ */
+export class InvalidEditError extends Error {
+}
+const settingsEdit = Compile(SettingsEditBody);
+const permissionEdit = Compile(PermissionEditBody);
+const hookEdit = Compile(HookEditBody);
+const agentEdit = Compile(AgentEditBody);
+const mcpEdit = Compile(McpEditBody);
+export function parseSettingsEdit(body) {
+    if (!settingsEdit.Check(body))
+        throw new InvalidEditError(firstError(settingsEdit, body));
+    return body;
+}
+export function parsePermissionEdit(body) {
+    if (!permissionEdit.Check(body))
+        throw new InvalidEditError(firstError(permissionEdit, body));
+    if (!body.remove && !body.add)
+        throw new InvalidEditError("remove or add is required");
+    if (body.remove?.rule.trim() === "" || body.add?.rule.trim() === "")
+        throw new InvalidEditError("a rule needs a list (allow, ask or deny) and text");
+    return body;
+}
+export function parseHookEdit(body) {
+    if (!hookEdit.Check(body))
+        throw new InvalidEditError(firstError(hookEdit, body));
+    if (!body.remove && !body.add)
+        throw new InvalidEditError("remove or add is required");
+    if (body.add) {
+        if (!HOOK_EVENTS.includes(body.add.event))
+            throw new InvalidEditError(`${body.add.event} is not a hook event Claude Code knows`);
+        if (!isRecord(body.add.definition))
+            throw new InvalidEditError("a hook must be a JSON object");
+    }
+    return body;
+}
+export function parseAgentEdit(body) {
+    if (!agentEdit.Check(body))
+        throw new InvalidEditError(firstError(agentEdit, body));
+    if (body.path !== undefined)
+        return body;
+    if (!body.create)
+        throw new InvalidEditError("path or create is required");
+    if (body.text === null)
+        throw new InvalidEditError("a new agent needs its text");
+    return body;
+}
+export function parseMcpEdit(body) {
+    if (!mcpEdit.Check(body))
+        throw new InvalidEditError(firstError(mcpEdit, body));
+    if (!body.remove && !body.add)
+        throw new InvalidEditError("remove or add is required");
+    if (body.add && !isRecord(body.add.definition))
+        throw new InvalidEditError("a server must be a JSON object");
+    return body;
+}

package/dist/core/reference.d.ts

@@ -0,0 +1,3 @@
+import { type Reference } from "../shared/types.ts";
+/** Claude Code's settings data a front end edits against, from the files generated into src/shared. */
+export declare const REFERENCE: Reference;

package/dist/core/reference.js

@@ -0,0 +1,11 @@
+import HOOK_EVENTS from "../shared/hook-events.json" with { type: "json" };
+import catalog from "../shared/settings-catalog.json" with { type: "json" };
+import schema from "../shared/settings.schema.json" with { type: "json" };
+import {} from "../shared/types.js";
+/** Claude Code's settings data a front end edits against, from the files generated into src/shared. */
+export const REFERENCE = {
+    schemaSource: schema.$comment,
+    settings: schema.definitions.ClaudeCodeSettings.properties,
+    catalog: Object.entries(catalog.keys).map(([key, entry]) => ({ key, ...entry })),
+    hookEvents: HOOK_EVENTS,
+};

package/dist/core/scan/compare.d.ts

@@ -0,0 +1,7 @@
+import { type SettingsComparison } from "../../shared/compare.ts";
+import { type ScanEnv } from "./env.ts";
+/**
+ * The effective settings of two directories side by side. Values are compared as ccdesk shows
+ * them, so hidden values stay hidden and two of them count as the same.
+ */
+export declare function compareSettings(env: ScanEnv, a: string, b: string): Promise<SettingsComparison>;

package/dist/{server → core}/scan/compare.js

@@ -2,10 +2,10 @@ import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import {} from "../../shared/compare.js";
 import {} from "./env.js";
-import { effectiveSettings, readSettingsLayers } from "./settings.js";
+import { effectiveSettings, readManagedSettings, readSettingsLayers } from "./settings.js";
 /** Each key Claude Code applies in `dir`, with its value and the files it comes from. */
 async function valuesIn(env, dir) {
-    const layers = await readSettingsLayers(env, dir);
+    const layers = await readSettingsLayers(env, dir, await readManagedSettings(env));
     const values = new Map();
     for (const setting of effectiveSettings(layers)) {
         // A key every file sets where Claude Code does not read it applies nowhere.

package/dist/core/scan/context.d.ts

@@ -0,0 +1,13 @@
+import { type ContextBlock, type EffectiveSetting, type Instruction, type Inventory, type MemoryStore } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+interface ContextInput {
+    env: ScanEnv;
+    projectRoot: string;
+    instructions: Instruction[];
+    memory: MemoryStore | null;
+    inventory: Inventory;
+    effective: EffectiveSetting[];
+}
+/** What Claude Code puts in context at session start in this directory, in load order. */
+export declare function buildContext(input: ContextInput): Promise<ContextBlock[]>;
+export {};