ccdesk 0.2.2 → 0.2.3

package/dist/core/schema.js

@@ -0,0 +1,67 @@
+import {} from "typebox/error";
+import { Settings } from "typebox/system";
+import {} from "typebox/compile";
+/**
+ * What `validator` found wrong with `value`, each led by where: `label` and the path inside it,
+ * such as `sandbox.network`.
+ */
+export function schemaErrors(validator, value, label) {
+    if (validator.Check(value))
+        return [];
+    return allErrors(validator, value).flatMap((e) => messages(e).map(([path, message]) => {
+        const where = [label, ...path.split("/")].filter(Boolean).join(".");
+        return where ? `${where} ${message}` : message;
+    }));
+}
+/** The first thing wrong with a request body, such as "add.list must be string". */
+export function firstError(validator, value) {
+    return schemaErrors(validator, value, "")[0] ?? "the request is not well formed";
+}
+/**
+ * Every error, not TypeBox's first eight: a wrong hook lists what each kind of hook needs. Each
+ * value checked is one setting, server or request body, so the list stays short. The limit is
+ * TypeBox's process-wide setting, so it is put back for anything else in the process using it.
+ */
+function allErrors(validator, value) {
+    const { maxErrors } = Settings.Get();
+    Settings.Set({ maxErrors: Number.POSITIVE_INFINITY });
+    try {
+        return validator.Errors(value);
+    }
+    finally {
+        Settings.Set({ maxErrors });
+    }
+}
+/**
+ * An error as where it is and what is wrong, worded as ccdesk has always shown them: one missing
+ * property at a time, and one "must NOT have additional properties" for each property a closed
+ * object does not allow.
+ */
+function messages(e) {
+    switch (e.keyword) {
+        case "required":
+            return e.params.requiredProperties.map((p) => [
+                e.instancePath,
+                `must have required property '${p}'`,
+            ]);
+        // Said once for each extra property, through its "schema is false" error below; a property
+        // that fails an additionalProperties schema has its own error already.
+        case "additionalProperties":
+            return [];
+        case "boolean":
+            if (!e.schemaPath.endsWith("/additionalProperties"))
+                return [[e.instancePath, e.message]];
+            return [
+                [
+                    e.instancePath.slice(0, e.instancePath.lastIndexOf("/")),
+                    "must NOT have additional properties",
+                ],
+            ];
+        case "enum":
+            return [[e.instancePath, `${e.message}: ${e.params.allowedValues.join(", ")}`]];
+        case "minItems":
+            return [[e.instancePath, `must NOT have fewer than ${e.params.limit} items`]];
+        default:
+            return [[e.instancePath, e.message]];
+    }
+}

package/dist/core/secrets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A server URL as ccdesk shows it: a user name, password or query string can carry a key, so they
+ * are hidden, as Claude Code hides the URL in its own status output (docs: mcp).
+ */
+export declare function shownUrl(url: string): string;
+/**
+ * Replace values that commonly hold secrets with a placeholder, keeping the keys: env and headers
+ * values, the user, password and query of a `url`, and secret values in the `args` of a command.
+ */
+export declare function redactSecrets(value: Record<string, unknown>): Record<string, unknown>;
+export declare function redactSecrets(value: unknown): unknown;
+/**
+ * A JSON parse failure without the parser's message, which quotes the text around the fault and
+ * so can quote a secret.
+ */
+export declare function jsonSyntaxError(error: unknown): string;
+/**
+ * The text ccdesk shows for a file reached as an instruction, import, memory, agent or skill. A
+ * settings or MCP file read this way, whatever it is named, would otherwise show its env and
+ * headers values, so anything that parses as JSON is shown parsed with them hidden. Frontmatter can
+ * hold the same values, in a subagent's inline MCP servers (docs: sub-agents#scope-mcp-servers-to-a-subagent),
+ * so frontmatter that holds any is shown re-written with them hidden.
+ */
+export declare function shownText(text: string | null): string | null;
+/** A file named .json that does not parse is not shown: its text could still hold a secret. */
+export declare function shownJsonFile(text: string): string;
+/**
+ * Helpers for the values ccdesk hides. What is hidden is decided only by redactSecrets; these
+ * compare a value with its redacted form.
+ */
+/** A value as ccdesk shows it: JSON with hidden values as •••. */
+export declare function shown(value: unknown): string;
+export declare function hasHiddenValues(value: unknown): boolean;
+/**
+ * A fingerprint of the hidden values in a JSON file, so a restore can tell whether they changed.
+ * Null for a file that is not valid JSON.
+ */
+export declare function hiddenValues(text: string | null): string | null;
+/**
+ * The secret text in a value, to take out of a message that may quote it: an env or header value
+ * or a hidden argument whole, the part after `=` of `--token=value`, and a URL's user name,
+ * password and query. Longest first, so a secret that contains another is taken out whole.
+ */
+export declare function secretTexts(value: unknown): string[];

package/dist/core/secrets.js

@@ -0,0 +1,187 @@
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { FRONTMATTER, isRecord } from "./scan/data.js";
+/**
+ * A server URL as ccdesk shows it: a user name, password or query string can carry a key, so they
+ * are hidden, as Claude Code hides the URL in its own status output (docs: mcp).
+ */
+export function shownUrl(url) {
+    try {
+        const u = new URL(url);
+        if (!u.username && !u.password && !u.search)
+            return url;
+        if (u.username || u.password) {
+            u.username = "•••";
+            u.password = "";
+        }
+        if (u.search)
+            u.search = "?•••";
+        return decodeURI(u.toString());
+    }
+    catch {
+        return url.replace(/\/\/[^/@]*@/, "//•••@").replace(/\?.*$/, "?•••");
+    }
+}
+/** A flag whose value is a secret, such as `--token` or `--api-key`. */
+const SECRET_FLAG = /^--(token|api[-_]?key|apikey|password|secret|auth|key)$/i;
+/** A value that starts like a common API key or token. */
+const KEY_PREFIX = /^(sk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[bp]-|glpat-|AKIA[0-9A-Z]{16})/;
+/**
+ * A server's command-line arguments as ccdesk shows them: the value after a secret flag, given as
+ * `--token value` or `--token=value`, a value that starts like a known key, and the credentials in
+ * a URL are hidden.
+ */
+function shownArgs(args) {
+    return args.map((arg, i) => {
+        if (typeof arg !== "string")
+            return arg;
+        const previous = args[i - 1];
+        if (typeof previous === "string" && SECRET_FLAG.test(previous) && !arg.startsWith("-"))
+            return "•••";
+        const equals = arg.indexOf("=");
+        if (equals > 0) {
+            const name = arg.slice(0, equals);
+            if (SECRET_FLAG.test(name) || KEY_PREFIX.test(arg.slice(equals + 1)))
+                return `${name}=•••`;
+        }
+        if (KEY_PREFIX.test(arg))
+            return "•••";
+        if (/^https?:\/\//i.test(arg))
+            return shownUrl(arg);
+        return arg;
+    });
+}
+export function redactSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(redactSecrets);
+    if (!isRecord(value))
+        return value;
+    // Built with fromEntries: assigning a key named __proto__ would set the prototype instead.
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => {
+        if ((key === "env" || key === "headers") && isRecord(inner))
+            return [key, Object.fromEntries(Object.keys(inner).map((k) => [k, "•••"]))];
+        if (key === "url" && typeof inner === "string")
+            return [key, shownUrl(inner)];
+        if (key === "args" && "command" in value && Array.isArray(inner))
+            return [key, shownArgs(inner)];
+        return [key, redactSecrets(inner)];
+    }));
+}
+/**
+ * A JSON parse failure without the parser's message, which quotes the text around the fault and
+ * so can quote a secret.
+ */
+export function jsonSyntaxError(error) {
+    const at = /line (\d+) column (\d+)/.exec(String(error));
+    return at ? `not valid JSON (line ${at[1]}, column ${at[2]})` : "not valid JSON";
+}
+/**
+ * The text ccdesk shows for a file reached as an instruction, import, memory, agent or skill. A
+ * settings or MCP file read this way, whatever it is named, would otherwise show its env and
+ * headers values, so anything that parses as JSON is shown parsed with them hidden. Frontmatter can
+ * hold the same values, in a subagent's inline MCP servers (docs: sub-agents#scope-mcp-servers-to-a-subagent),
+ * so frontmatter that holds any is shown re-written with them hidden.
+ */
+export function shownText(text) {
+    if (text === null)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return shownFrontmatter(text);
+    }
+    return typeof data === "object" && data !== null
+        ? `${JSON.stringify(redactSecrets(data), null, 2)}\n`
+        : text;
+}
+function shownFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    let data;
+    try {
+        data = parseYaml(match[1] ?? "");
+    }
+    catch {
+        return text;
+    }
+    const redacted = redactSecrets(data);
+    if (JSON.stringify(redacted) === JSON.stringify(data))
+        return text;
+    return `---\n${stringifyYaml(redacted)}---\n${text.slice(match[0].length)}`;
+}
+/** A file named .json that does not parse is not shown: its text could still hold a secret. */
+export function shownJsonFile(text) {
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        return "(a JSON file ccdesk could not parse, so its text is not shown; open it to see it)\n";
+    }
+    return shownText(text) ?? "";
+}
+/**
+ * Helpers for the values ccdesk hides. What is hidden is decided only by redactSecrets; these
+ * compare a value with its redacted form.
+ */
+/** A value as ccdesk shows it: JSON with hidden values as •••. */
+export function shown(value) {
+    return `${JSON.stringify(redactSecrets(value), null, 2)}\n`;
+}
+/** Every value redactSecrets changes, with where it is, what it is, and how it is shown. */
+function hiddenIn(value) {
+    const found = [];
+    // redactSecrets keeps every key and list length, so the two can be walked side by side.
+    const walk = (raw, shownValue, path) => {
+        if (Array.isArray(raw) && Array.isArray(shownValue)) {
+            for (const [i, inner] of raw.entries())
+                walk(inner, shownValue[i], [...path, i]);
+        }
+        else if (isRecord(raw) && isRecord(shownValue))
+            for (const [key, inner] of Object.entries(raw))
+                walk(inner, shownValue[key], [...path, key]);
+        else if (raw !== shownValue)
+            found.push({ path, raw, shown: shownValue });
+    };
+    walk(value, redactSecrets(value), []);
+    return found;
+}
+export function hasHiddenValues(value) {
+    return hiddenIn(value).length > 0;
+}
+/**
+ * A fingerprint of the hidden values in a JSON file, so a restore can tell whether they changed.
+ * Null for a file that is not valid JSON.
+ */
+export function hiddenValues(text) {
+    try {
+        const data = text === null ? null : JSON.parse(text);
+        return JSON.stringify(hiddenIn(data).map(({ path, raw }) => [path, raw]));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The secret text in a value, to take out of a message that may quote it: an env or header value
+ * or a hidden argument whole, the part after `=` of `--token=value`, and a URL's user name,
+ * password and query. Longest first, so a secret that contains another is taken out whole.
+ */
+export function secretTexts(value) {
+    const found = hiddenIn(value).flatMap(({ raw, shown: hidden }) => {
+        if (typeof raw !== "string")
+            return [];
+        if (hidden === "•••")
+            return [raw];
+        if (typeof hidden === "string" && hidden.endsWith("=•••"))
+            return [raw.slice(raw.indexOf("=") + 1)];
+        if (shownUrl(raw) === raw)
+            return [];
+        const url = URL.parse(raw);
+        return [url?.username, url?.password, url?.search.slice(1)];
+    });
+    return found
+        .filter((s) => s !== undefined && s !== "")
+        .sort((a, b) => b.length - a.length);
+}

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

@@ -0,0 +1,9 @@
+import { type Change, type HookEdit, type PermissionEdit, type SettingsEdit, type SettingsEditPreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+export declare function previewSettingsEdit(env: ScanEnv, edit: SettingsEdit): Promise<SettingsEditPreview>;
+export declare function saveSettingsEdit(env: ScanEnv, edit: SettingsEdit, expectedRevision: string, queue?: Serially): Promise<Change>;
+export declare function previewPermissionEdit(env: ScanEnv, edit: PermissionEdit): Promise<SettingsEditPreview>;
+export declare function savePermissionEdit(env: ScanEnv, edit: PermissionEdit, expectedRevision: string, queue?: Serially): Promise<Change>;
+export declare function previewHookEdit(env: ScanEnv, edit: HookEdit): Promise<SettingsEditPreview>;
+export declare function saveHookEdit(env: ScanEnv, edit: HookEdit, expectedRevision: string, queue?: Serially): Promise<Change>;

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

@@ -1,16 +1,17 @@
 import { stat } from "node:fs/promises";
-import {} from "ajv";
+import { Compile } from "typebox/compile";
 import HOOK_EVENTS from "../shared/hook-events.json" with { type: "json" };
 import { allowedScopes, ignoredReason } from "../shared/scopes.js";
 import schema from "../shared/settings.schema.json" with { type: "json" };
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
-import { isRecord, jsonSyntaxError, redactSecrets, revisionOf } from "./scan/files.js";
+import { revisionOf } from "./scan/files.js";
+import { isRecord } from "./scan/data.js";
 import { isSkippedMcpRule } from "./scan/permissions.js";
 import { settingsFiles } from "./scan/settings.js";
-import { ajv, schemaErrors } from "./schema.js";
-import { hasHiddenValues, shown } from "./secrets.js";
-import { RefusedError, readIfExists, recordChange, serially, writeAtomic } from "./write.js";
+import { schemaErrors } from "./schema.js";
+import { hasHiddenValues, redactSecrets, shown } from "./secrets.js";
+import { RefusedError, readJsonObject, recordChange, saveReviewed, serially, writeAtomic, } from "./write.js";
 const properties = schema.definitions.ClaudeCodeSettings.properties;
 const validators = new Map();
 function validatorFor(key) {
@@ -18,7 +19,7 @@ function validatorFor(key) {
         return null;
     let validate = validators.get(key);
     if (!validate) {
-        validate = ajv.compile(properties[key]);
+        validate = Compile(properties[key]);
         validators.set(key, validate);
     }
     return validate;
@@ -33,21 +34,6 @@ async function editableFile(env, dir, pick, missing = "That is not a settings fi
         throw new RefusedError(`${dir} is not a directory on this machine.`);
     return file;
 }
-async function readSettings(env, path) {
-    const raw = await readIfExists(env, path);
-    if (raw === null || raw.trim() === "")
-        return { raw, data: {} };
-    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.`);
-    return { raw, data: parsed };
-}
 /**
  * Works out the file change that sets or removes one key, refusing what ccdesk cannot do safely.
  * `checksHiddenValues` is for a key whose edit checks the part it changes itself, so values it
@@ -60,7 +46,7 @@ async function planKey(env, file, key, value, checksHiddenValues = false) {
     if (!validate)
         throw new RefusedError(`${key} is not in Claude Code's settings schema (${schema.$comment}).`);
     const { path } = file;
-    const { raw, data } = await readSettings(env, path);
+    const { raw, data, reformats } = await readJsonObject(env, path);
     const nextValue = value(data);
     // ccdesk never shows hidden values, so it must not write them either.
     if (!checksHiddenValues &&
@@ -68,33 +54,29 @@ async function planKey(env, file, key, value, checksHiddenValues = false) {
         throw new RefusedError(`${key} holds hidden values; edit it in the file instead.`);
     if (raw !== null && JSON.stringify(nextValue) === JSON.stringify(data[key]))
         throw new RefusedError("This file already says that; there is nothing to change.");
-    const before = raw === null ? null : shown(data);
-    // The diff is rendered from the parsed file, so a file in another layout is reported as
-    // reformatted instead of diffing its raw text.
-    const reformats = raw !== null && raw.trim() !== "" && raw !== `${JSON.stringify(data, null, 2)}\n`;
-    const base = { path, before, revision: revisionOf(raw), reformats };
     const errors = nextValue === undefined
         ? []
         : [...schemaErrors(validate, nextValue, key), ...newHookEvents(key, data[key], nextValue)];
-    if (errors.length > 0)
-        return {
-            path,
-            scope: file.scope,
-            raw,
-            next: null,
-            preview: { ...base, after: before ?? "", errors },
-        };
     const next = { ...data };
     if (nextValue === undefined)
         delete next[key];
     else
         next[key] = nextValue;
+    const text = `${JSON.stringify(next, null, 2)}\n`;
+    const before = raw === null ? null : shown(data);
     return {
-        path,
-        scope: file.scope,
-        raw,
-        next: `${JSON.stringify(next, null, 2)}\n`,
-        preview: { ...base, after: shown(next), errors: [] },
+        preview: {
+            path,
+            before,
+            after: errors.length > 0 ? (before ?? "") : shown(next),
+            revision: revisionOf(raw),
+            reformats,
+            errors,
+        },
+        save: () => recordChange(env, { kind: "settings", target: path, before: raw }, async () => {
+            await writeAtomic(env, path, text, revisionOf(raw));
+            return { target: path, revision: revisionOf(text) };
+        }),
     };
 }
 async function planSettingsEdit(env, edit) {
@@ -150,88 +132,85 @@ function matcherOf(group) {
 /** One hook taken out, replaced or added, applied to the file as it is on disk. */
 async function planHookEdit(env, edit) {
     const file = await editableFile(env, edit.dir, (f) => f.path === edit.file);
-    return planKey(env, file, "hooks", (data) => {
-        const hooks = isRecord(data.hooks)
-            ? structuredClone(data.hooks)
-            : {};
-        const groupsOf = (event) => {
-            const groups = hooks[event];
-            return Array.isArray(groups) ? groups : [];
-        };
-        const { remove, add } = edit;
-        // Checked before any branch, so neither a new hook nor a replacement writes them.
-        if (add && hasHiddenValues(add.definition))
-            throw new RefusedError("ccdesk does not write header values it would then hide; add this hook in the file instead.");
-        if (remove) {
-            const groups = groupsOf(remove.event);
-            const group = groups[remove.at.group];
-            const list = isRecord(group) && Array.isArray(group.hooks) ? group.hooks : null;
-            const hook = list?.[remove.at.index];
-            if (!list || JSON.stringify(redactSecrets(hook)) !== JSON.stringify(remove.definition))
-                throw new RefusedError("This hook changed in the file since ccdesk read it; review it again.");
-            // The page saw this hook with its header values hidden, so a changed copy would lose them.
-            if (add && hasHiddenValues(hook))
-                throw new RefusedError("This hook sends header values ccdesk does not show; edit it in the file, or remove it and add it again.");
-            const matcher = add?.matcher ?? "";
-            // A hook alone in its group keeps the group when only its matcher changes, unless another
-            // group already has that matcher.
-            const inPlace = add?.event === remove.event &&
-                (matcher === matcherOf(group) ||
-                    (list.length === 1 && !groups.some((g) => g !== group && matcherOf(g) === matcher)));
-            if (add && inPlace && isRecord(group)) {
-                list[remove.at.index] = add.definition;
-                if (matcher)
-                    group.matcher = matcher;
-                else
-                    delete group.matcher;
-                return hooks;
-            }
-            list.splice(remove.at.index, 1);
-            if (list.length === 0)
-                groups.splice(remove.at.group, 1);
-            if (groups.length === 0 && add?.event !== remove.event)
-                delete hooks[remove.event];
-        }
-        if (add) {
-            const groups = groupsOf(add.event);
-            const matcher = add.matcher ?? "";
-            const group = groups.find((g) => matcherOf(g) === matcher && isRecord(g) && Array.isArray(g.hooks));
-            if (isRecord(group) && Array.isArray(group.hooks))
-                group.hooks.push(add.definition);
-            else
-                groups.push({ ...(matcher ? { matcher } : {}), hooks: [add.definition] });
-            hooks[add.event] = groups;
-        }
-        return Object.keys(hooks).length > 0 ? hooks : undefined;
-    }, true);
-}
-/** Writes a planned edit, but only if the file is still the revision the preview was made from. */
-async function commit(env, plan, expectedRevision) {
-    if (plan.next === null)
-        throw new RefusedError(plan.preview.errors.join("; "));
-    if (plan.preview.revision !== expectedRevision)
-        throw new RefusedError("The file changed since you reviewed this edit; review it again.");
-    const next = plan.next;
-    return recordChange(env, { kind: "settings", target: plan.path, before: plan.raw }, async () => {
-        await writeAtomic(env, plan.path, next, expectedRevision);
-        return { target: plan.path, revision: revisionOf(next) };
-    });
+    return planKey(env, file, "hooks", (data) => editedHooks(data.hooks, edit), true);
+}
+/** The hooks setting with the edit applied, or undefined when no hooks are left. */
+function editedHooks(value, edit) {
+    const hooks = isRecord(value) ? structuredClone(value) : {};
+    const { remove, add } = edit;
+    // Checked before any branch, so neither a new hook nor a replacement writes them.
+    if (add && hasHiddenValues(add.definition))
+        throw new RefusedError("ccdesk does not write header values it would then hide; add this hook in the file instead.");
+    if (remove && takeOutHook(hooks, remove, add) === "replaced")
+        return hooks;
+    if (add) {
+        const groups = groupsOf(hooks, add.event);
+        const matcher = add.matcher ?? "";
+        const group = groups.find((g) => matcherOf(g) === matcher && isRecord(g) && Array.isArray(g.hooks));
+        if (isRecord(group) && Array.isArray(group.hooks))
+            group.hooks.push(add.definition);
+        else
+            groups.push({ ...(matcher ? { matcher } : {}), hooks: [add.definition] });
+        hooks[add.event] = groups;
+    }
+    return Object.keys(hooks).length > 0 ? hooks : undefined;
 }
+/** An event's matcher groups as stored in `hooks`, or a new list when it has none. */
+function groupsOf(hooks, event) {
+    const groups = hooks[event];
+    return Array.isArray(groups) ? groups : [];
+}
+/**
+ * Takes the reviewed hook out of `hooks`, or puts `add` in its place when only its matcher or
+ * nothing about where it sits changes.
+ */
+function takeOutHook(hooks, remove, add) {
+    const groups = groupsOf(hooks, remove.event);
+    const group = groups[remove.at.group];
+    const list = isRecord(group) && Array.isArray(group.hooks) ? group.hooks : null;
+    const hook = list?.[remove.at.index];
+    if (!list || JSON.stringify(redactSecrets(hook)) !== JSON.stringify(remove.definition))
+        throw new RefusedError("This hook changed in the file since ccdesk read it; review it again.");
+    // The page saw this hook with its header values hidden, so a changed copy would lose them.
+    if (add && hasHiddenValues(hook))
+        throw new RefusedError("This hook sends header values ccdesk does not show; edit it in the file, or remove it and add it again.");
+    const matcher = add?.matcher ?? "";
+    // A hook alone in its group keeps the group when only its matcher changes, unless another
+    // group already has that matcher.
+    const inPlace = add?.event === remove.event &&
+        (matcher === matcherOf(group) ||
+            (list.length === 1 && !groups.some((g) => g !== group && matcherOf(g) === matcher)));
+    if (add && inPlace && isRecord(group)) {
+        list[remove.at.index] = add.definition;
+        if (matcher)
+            group.matcher = matcher;
+        else
+            delete group.matcher;
+        return "replaced";
+    }
+    list.splice(remove.at.index, 1);
+    if (list.length === 0)
+        groups.splice(remove.at.group, 1);
+    if (groups.length === 0 && add?.event !== remove.event)
+        delete hooks[remove.event];
+    return "removed";
+}
+const CHANGED = "The file changed since you reviewed this edit; review it again.";
 export async function previewSettingsEdit(env, edit) {
     return (await planSettingsEdit(env, edit)).preview;
 }
-export function saveSettingsEdit(env, edit, expectedRevision) {
-    return serially(async () => commit(env, await planSettingsEdit(env, edit), expectedRevision));
+export function saveSettingsEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planSettingsEdit(env, edit), expectedRevision, CHANGED);
 }
 export async function previewPermissionEdit(env, edit) {
     return (await planPermissionEdit(env, edit)).preview;
 }
-export function savePermissionEdit(env, edit, expectedRevision) {
-    return serially(async () => commit(env, await planPermissionEdit(env, edit), expectedRevision));
+export function savePermissionEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planPermissionEdit(env, edit), expectedRevision, CHANGED);
 }
 export async function previewHookEdit(env, edit) {
     return (await planHookEdit(env, edit)).preview;
 }
-export function saveHookEdit(env, edit, expectedRevision) {
-    return serially(async () => commit(env, await planHookEdit(env, edit), expectedRevision));
+export function saveHookEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planHookEdit(env, edit), expectedRevision, CHANGED);
 }

package/dist/core/watch.d.ts

@@ -0,0 +1,45 @@
+import { type DirectoryView, type SessionProfile } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { scanDirectory } from "./scan/index.ts";
+/** One set of file watchers per directory a page is looking at, shared by its requests. */
+export declare class Watcher {
+    private readonly subscriptions;
+    /** What the latest scan of each directory read, kept for a watch that starts after the scan. */
+    private readonly scanned;
+    private readonly latest;
+    private readonly env;
+    private readonly scanOf;
+    constructor(env: ScanEnv, scanOf?: typeof scanDirectory);
+    /** Scans `dir` and remembers what the scan read, so those files are watched too. */
+    scan(dir: string, profile?: SessionProfile): Promise<DirectoryView>;
+    /**
+     * The view of `dir`: the latest scan while it is known to be current, else a new scan. It is
+     * current only while watchers that started before it have seen no change since it started, and
+     * ~/.claude.json, which is not watched, is as it was. Only an interactive scan is reused, as the
+     * path tester describes an interactive session.
+     */
+    view(dir: string): Promise<DirectoryView>;
+    /** ~/.claude.json's size and time; Claude Code rewrites it too often to watch. */
+    private stateFile;
+    /**
+     * Answers once something changed after `since` (ms since the epoch), or after `timeoutMs` with
+     * the last change time, whichever comes first.
+     */
+    wait(dir: string, since: number, signal: AbortSignal, timeoutMs?: number): Promise<{
+        changed: boolean;
+        at: number;
+    }>;
+    /**
+     * Calls `onChange` once after each change to what ccdesk shows for `dir`, until the returned
+     * function is called. Resolves once the watchers have started, so a change made after it
+     * resolves is seen. `close` stops the calls without making one.
+     */
+    subscribe(dir: string, onChange: () => void): Promise<() => void>;
+    /** Drops the watchers of `dir` after a while once no one waits or listens for changes. */
+    private release;
+    close(): void;
+    private watching;
+    private drop;
+    /** (Re)creates the watchers, so a folder created since, such as a new .claude, is watched. */
+    private rewatch;
+}