ccdesk 0.2.2 → 0.2.4

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, 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) {
+    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) {
+    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) {
+    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;
+}

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

@@ -4,9 +4,10 @@ import { basename, dirname, isAbsolute, join } from "node:path";
 import { storeDirName } from "../shared/memory.js";
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
-import { isDir, isFile, isNetworkPath, mainWorktreeRoot } from "./scan/files.js";
+import { isDir, isFile, isNetworkPath } from "./scan/files.js";
+import { mainWorktreeRoot } from "./scan/git.js";
 import { scanDirectory } from "./scan/index.js";
-import { manifestCommandMap, manifestPaths } from "./scan/plugins.js";
+import { loadPlugin, manifestCommandMap, manifestPaths } from "./scan/plugins.js";
 /** How long one request waits for a change before answering "nothing changed". */
 const WAIT_MS = 25_000;
 /** Editors write a file in several steps; one change covers them all. */
@@ -60,7 +61,7 @@ async function targets(env, dir, extra) {
  * plugins. A missing import is watched too, so creating it shows up, even when its folder is missing
  * as well.
  */
-export async function dependencies(env, view) {
+async function dependencies(env, view) {
     const files = view.instructions.flatMap((i) => [
         i.realPath ?? i.path,
         ...i.imports.map((r) => r.resolved),
@@ -92,8 +93,10 @@ async function pluginTargets(env, view, plugin) {
     // A path from installed_plugins.json that is not absolute names no folder Claude Code would load.
     if (!isAbsolute(root))
         return [];
-    const named = await Promise.all(PLUGIN_KEYS.map((key) => manifestPaths(env, plugin, key)));
-    const commands = await manifestCommandMap(env, plugin);
+    // The scan reports a manifest that does not parse; here it only names paths to watch.
+    const loaded = await loadPlugin(env, plugin, []);
+    const named = await Promise.all(PLUGIN_KEYS.map((key) => manifestPaths(loaded, key)));
+    const commands = await manifestCommandMap(loaded);
     // Without a skills folder, each folder at the root holding SKILL.md is a skill.
     const rootSkills = view.inventory.skills
         .filter((s) => s.plugin === plugin.id && s.folder && dirname(s.folder) === root)
@@ -137,12 +140,12 @@ async function nearestWatchable(target) {
 }
 /** One set of file watchers per directory a page is looking at, shared by its requests. */
 export class Watcher {
-    env;
-    scanOf;
     subscriptions = new Map();
     /** What the latest scan of each directory read, kept for a watch that starts after the scan. */
     scanned = new Map();
     latest = new Map();
+    env;
+    scanOf;
     constructor(env, scanOf = scanDirectory) {
         this.env = env;
         this.scanOf = scanOf;
@@ -160,7 +163,7 @@ export class Watcher {
         this.scanned.set(view.path, extra);
         if (subscription && JSON.stringify(extra) !== JSON.stringify(subscription.extra)) {
             subscription.extra = extra;
-            void this.rewatch(view.path, subscription);
+            subscription.ready = this.rewatch(view.path, subscription);
         }
         return view;
     }
@@ -191,7 +194,7 @@ export class Watcher {
      * the last change time, whichever comes first.
      */
     async wait(dir, since, signal, timeoutMs = WAIT_MS) {
-        const subscription = await this.subscribe(dir);
+        const subscription = await this.watching(dir);
         clearTimeout(subscription.idle);
         // Closed while its watchers were starting: there is nothing left to wait on.
         const closed = this.subscriptions.get(dir) !== subscription;
@@ -210,30 +213,63 @@ export class Watcher {
                 });
         }
         finally {
-            // A dropped subscription has nothing left to clean up later.
-            if (subscription.waiters.size === 0 && this.subscriptions.get(dir) === subscription)
-                subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+            this.release(dir, subscription);
         }
         return { changed: subscription.changedAt > since, at: subscription.changedAt };
     }
+    /**
+     * 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.
+     */
+    async subscribe(dir, onChange) {
+        const subscription = await this.watching(dir);
+        // Closed while its watchers were starting: nothing will change.
+        if (this.subscriptions.get(dir) !== subscription)
+            return () => {
+                // Nothing was subscribed, so there is nothing to stop.
+            };
+        clearTimeout(subscription.idle);
+        // A function of its own, so the same onChange subscribed twice is unsubscribed twice.
+        const listener = () => onChange();
+        subscription.listeners.add(listener);
+        return () => {
+            if (subscription.listeners.delete(listener))
+                this.release(dir, subscription);
+        };
+    }
+    /** Drops the watchers of `dir` after a while once no one waits or listens for changes. */
+    release(dir, subscription) {
+        // A dropped subscription has nothing left to clean up later.
+        if (subscription.waiters.size === 0 &&
+            subscription.listeners.size === 0 &&
+            this.subscriptions.get(dir) === subscription)
+            subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+    }
     close() {
         for (const dir of [...this.subscriptions.keys()])
             this.drop(dir);
     }
-    async subscribe(dir) {
+    async watching(dir) {
         const existing = this.subscriptions.get(dir);
-        if (existing)
+        if (existing) {
+            // Watchers moving to a new target after a change are not watching it yet.
+            await existing.ready;
             return existing;
+        }
         const subscription = {
             watchers: [],
+            ready: Promise.resolve(),
             changedAt: 0,
             touchedAt: 0,
             watchingSince: Number.POSITIVE_INFINITY,
             waiters: new Set(),
+            listeners: new Set(),
             extra: this.scanned.get(dir) ?? [],
         };
         this.subscriptions.set(dir, subscription);
-        await this.rewatch(dir, subscription);
+        subscription.ready = this.rewatch(dir, subscription);
+        await subscription.ready;
         return subscription;
     }
     drop(dir) {
@@ -269,9 +305,10 @@ export class Watcher {
                     clearTimeout(subscription.settle);
                     subscription.settle = setTimeout(() => {
                         subscription.changedAt = Date.now();
-                        for (const wake of [...subscription.waiters])
+                        // First, so a subscriber that throws cannot leave the old watchers in place.
+                        subscription.ready = this.rewatch(dir, subscription);
+                        for (const wake of [...subscription.waiters, ...subscription.listeners])
                             wake();
-                        void this.rewatch(dir, subscription);
                     }, SETTLE_MS);
                 });
                 watcher.on("error", () => watcher.close());

package/dist/core/write.d.ts

@@ -0,0 +1,117 @@
+import { type Static, Type } from "typebox";
+import { type BackupKind } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+/** A change ccdesk refuses on purpose; the server answers 409 with the message. */
+export declare class RefusedError extends Error {
+}
+/** A write refused because its file changed after review: nothing was written. */
+export declare class StaleError extends RefusedError {
+}
+/**
+ * Runs changes one at a time, so two of them can never both pass a revision check before either
+ * writes. Every exported change goes through one; helpers it calls must not.
+ */
+export type Serially = <T>(change: () => Promise<T>) => Promise<T>;
+/** A new, empty queue of changes. Each core has its own. */
+export declare function changeQueue(): Serially;
+/** What every change's review has: the revision it was worked out from and why it cannot be saved. */
+interface Review {
+    /** Fingerprint of everything the change was worked out from. */
+    revision: string;
+    /** When there are any, nothing is saved. */
+    errors?: string[];
+}
+/** A change worked out from disk as it is now: what it shows for review, and how to make it. */
+export interface Planned<Preview extends Review, T> {
+    preview: Preview;
+    save: () => Promise<T>;
+}
+/**
+ * Plans a change again and makes it, but only when it has no errors and everything it was worked
+ * out from is as reviewed; `changed` is the refusal otherwise. Planning and saving share one turn
+ * of the queue, so no other change lands between the check and the write.
+ */
+export declare function saveReviewed<T>(queue: Serially, plan: () => Promise<Planned<Review, T>>, expectedRevision: string, changed: string): Promise<T>;
+export declare function backupRoot(env: ScanEnv): string;
+/** The file's text, or null when it does not exist. Any other read error is thrown, not hidden. */
+export declare function readIfExists(env: ScanEnv, path: string): Promise<string | null>;
+/**
+ * A JSON file that holds an object, as ccdesk edits it: missing or empty is `{}`, anything else
+ * that is not an object is refused. `reformats` says whether writing it back as 2-space JSON
+ * changes more than the edit, since its diff is rendered from the parsed file.
+ */
+export declare function readJsonObject(env: ScanEnv, path: string): Promise<{
+    raw: string | null;
+    data: Record<string, unknown>;
+    reformats: boolean;
+}>;
+/**
+ * Replaces a file's content, but only while it still has `expected` revision. The new text is
+ * written to a temporary file first and the revision is checked again just before the rename, so
+ * an edit made elsewhere while ccdesk was saving is kept and the save refused. A symlink is written
+ * through, so links into a dotfiles repository survive; the temporary file is new, unguessable and
+ * created exclusively, so nothing planted beside the target can redirect the write. A file with
+ * other hard links is refused, since the rename would leave them on the old text.
+ */
+export declare function writeAtomic(env: ScanEnv, path: string, content: string, expected: string): Promise<void>;
+/**
+ * Deletes a file only while it still has `expected` revision, and says whether it did. The file is
+ * renamed aside first, so what is removed is exactly what was checked; one that differs is put
+ * back, unless a new file took its place meanwhile, which ccdesk then refuses to overwrite.
+ */
+export declare function removeExactly(path: string, expected: string): Promise<boolean>;
+/** What a backup folder records about its change, in its manifest. */
+export declare const BackupManifestSchema: Type.TObject<{
+    kind: Type.TEnum<["settings", "mcp", "agent", "memory-index", "memory-delete", "memory-restore", "mcp-claude"]>;
+    /** The file that changed (for a deleted memory: the memory file). */
+    target: Type.TString;
+    createdAt: Type.TString;
+    /** Revision of the target before the change; "missing" when ccdesk created it. */
+    before: Type.TString;
+    /** Revision of the target right after the change; "pending" while it runs, "partial" when it failed halfway. */
+    after: Type.TString;
+    /** For a deleted memory: the MEMORY.md lines removed with it. */
+    removedIndexLines: Type.TOptional<Type.TArray<Type.TString>>;
+    /** For a change made through `claude mcp`: the commands that put it back, values hidden. */
+    undoCommands: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export type BackupManifest = Static<typeof BackupManifestSchema>;
+export declare const MANIFEST = "ccdesk-backup.json";
+/** Takes a change out of Recent changes, for one whose effect was undone again right away. */
+export declare function forgetChange(env: ScanEnv, id: string): Promise<void>;
+/** The copy of the target inside a backup folder. */
+export declare const SNAPSHOT = "before";
+/** For a change made through `claude mcp`: the affected servers after it, values hidden. */
+export declare const SHOWN_AFTER = "after";
+/**
+ * Lists a change Claude Code made through `claude mcp` in Recent changes. ccdesk cannot undo it,
+ * so it keeps only the affected servers before and after as the page shows them, secrets hidden,
+ * and the commands that would put them back; never a value the page does not show.
+ */
+export declare function recordClaudeMcpChange(env: ScanEnv, record: {
+    target: string;
+    shownBefore: string;
+    shownAfter: string;
+    undoCommands: string[];
+}): Promise<void>;
+/**
+ * Makes a change and records it in Recent changes. The file's previous text and a manifest are put
+ * in a new backup folder first, so a change interrupted halfway can still be restored; the manifest
+ * gets the new revision once the change is made. A change that fails is removed from Recent changes
+ * when its first write was refused as stale, or when `unchanged` confirms nothing on disk moved;
+ * otherwise it stays, marked partial, so it can be put back. Backups can hold settings with secrets, so only the user can read them.
+ */
+export declare function recordChange<T extends {
+    revision: string;
+}>(env: ScanEnv, record: {
+    kind: BackupKind;
+    target: string;
+    before: string | null;
+    removedIndexLines?: string[];
+    /** Whether disk is still as before the change; by default, whether the target is. */
+    unchanged?: () => Promise<boolean>;
+}, change: () => Promise<T>): Promise<T & {
+    id: string;
+    created: boolean;
+}>;
+export {};