ccdesk 0.2.1 → 0.2.3

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 } from "./scan/data.js";
+import { 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, 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
@@ -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,24 +46,35 @@ function secretsIn(args) {
         }
     });
 }
-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);
+/** 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("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);
+            });
         });
-    });
-};
+    };
+}
+/** claudeRunner for this process's PATH and environment, read on each run; use a core's instead. */
+export const runClaude = (args, cwd, configDir) => 
+// biome-ignore lint/style/noProcessEnv: the documented default of the free runClaude; a core passes its own.
+claudeRunner({ platform: process.platform, processEnv: process.env })(args, cwd, configDir);
 /** 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("'", "'\\''")}'`;
@@ -107,20 +120,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) };
@@ -133,7 +133,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 () => {
@@ -143,11 +143,12 @@ 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 {
@@ -158,21 +159,21 @@ async function planClaudeJson(env, edit, run) {
     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 projects = isRecord(data.projects) ? data.projects : {};
     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) => [
+    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",
@@ -180,25 +181,76 @@ async function planClaudeJson(env, edit, run) {
         "--",
         name,
         JSON.stringify(definition),
-    ];
-    const addCommand = (name, definition) => `claude mcp add-json --scope ${edit.scope} -- ${quoted(name)} ${quoted(JSON.stringify(definition))}`;
+    ],
+};
+/**
+ * `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 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,
@@ -211,37 +263,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);
-            // 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 };
-        },
+        save,
     };
 }
 function plan(env, edit, run) {
@@ -251,13 +279,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 = serially) {
+    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, 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.");
@@ -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 = serially) {
+    return saveReviewed(queue, () => PLANS[action](env, path), expectedRevision, REVIEW_AGAIN);
 }

package/dist/core/open.d.ts

@@ -0,0 +1,31 @@
+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. Without `host` it uses this process's platform and environment; use a core's instead.
+ */
+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,
@@ -126,14 +125,42 @@ function launch([command, args], path) {
         });
     });
 }
-/** 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. Without `host` it uses this process's platform and environment; use a core's instead.
+ */
+export async function openInEditor(path, 
+// biome-ignore lint/style/noProcessEnv: the documented default of the free openInEditor; a core passes its own.
+host = { platform: process.platform, processEnv: process.env }) {
     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

@@ -1,10 +1,11 @@
 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.
@@ -28,7 +29,8 @@ export async function compareSettings(env, a, b) {
     const settings = keys.map((key) => {
         const x = left.get(key) ?? null;
         const y = right.get(key) ?? null;
-        return { key, a: x, b: y, same: JSON.stringify(x?.value) === JSON.stringify(y?.value) };
+        // The order keys are written in does not change a setting.
+        return { key, a: x, b: y, same: isDeepStrictEqual(x?.value, y?.value) };
     });
     return { a: resolve(a), b: resolve(b), settings };
 }

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 {};