ccdesk 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.2.4](https://github.com/ayagmar/ccdesk/compare/v0.2.3...v0.2.4) (2026-10-13)
+
+### Features
+
+* **core:** warn when a higher managed source than the files is present ([cb04a30](https://github.com/ayagmar/ccdesk/commit/cb04a30e72293270bdf4e3529a938ef13188bb41))
+
+### Bug Fixes
+
+* **core:** count Explorer as having opened the file on Windows ([eb1a120](https://github.com/ayagmar/ccdesk/commit/eb1a12090507be426765c38d2e71a5f5500622ef))
+* **core:** hide header values and more secret flags in MCP server args ([3a9ee02](https://github.com/ayagmar/ccdesk/commit/3a9ee024a124602f486b3e8f41e23fffa7c84565))
+* **core:** look up ~/.claude.json folders as Claude Code keys them on Windows ([67a445d](https://github.com/ayagmar/ccdesk/commit/67a445d2a569bccd8f1615e798af099ece5dbe38))
+* **core:** name long project stores as Claude Code does ([98f4dd8](https://github.com/ayagmar/ccdesk/commit/98f4dd8f4efbe1ce0c2154e58b554c9a05baed95))
+* **core:** read JSON files that start with a byte order mark ([6bb2fd3](https://github.com/ayagmar/ccdesk/commit/6bb2fd302d468f1603d2230270ce5c9999027e93))
+* **core:** report a backup folder ccdesk cannot read instead of listing none ([1209b9c](https://github.com/ayagmar/ccdesk/commit/1209b9c0a360939a3247fd3e92ad9b0d41b579f6))
+* **core:** say why claude did not start on Windows instead of "not on PATH" ([9c0d3ad](https://github.com/ayagmar/ccdesk/commit/9c0d3adcc0ad0cb1ff4ed6b66377b603c1b1f4da))
+
+### Performance Improvements
+
+* **core:** group hand-approved calls without copying each group ([9ab7219](https://github.com/ayagmar/ccdesk/commit/9ab7219986690e08669f3aceacb93f3f48777e11))
+* **ui:** refresh the overview on focus and saves, not on watched changes ([9010576](https://github.com/ayagmar/ccdesk/commit/901057643dfcded5f2463ccb09353a5d264f109d))
+
+## [0.2.3](https://github.com/ayagmar/ccdesk/compare/v0.2.2...v0.2.3) (2026-10-13)
+
+### Features
+
+* **cli:** add read-only scan --json and explain subcommands ([fc59aed](https://github.com/ayagmar/ccdesk/commit/fc59aed4935371e2a979991a03a94cf01c0e2e68))
+* **core:** add Watcher.subscribe to push changes ([3eb360e](https://github.com/ayagmar/ccdesk/commit/3eb360e286fa34eede2c23aa1b3fe69f2fb6b129))
+* **core:** make the core importable as the package entry point ([82a4107](https://github.com/ayagmar/ccdesk/commit/82a41075f88c6b0ab475eb559afe1cf13aacc25a))
+* **view:** export the view logic as ccdesk/view ([b0e4365](https://github.com/ayagmar/ccdesk/commit/b0e436513da85184e9e141d2502fba1d297f39ee))
+
+### Bug Fixes
+
+* **core:** refuse to open a file when no editor starts, instead of failing ([a359842](https://github.com/ayagmar/ccdesk/commit/a359842ecd33db582b565878e56a63ac00ad664e))
+* **core:** refuse to open credentials or missing paths in createCore ([9562aab](https://github.com/ayagmar/ccdesk/commit/9562aab75961097c97b193f9edac8f5a34f8c701))
+* **core:** report broken ~/.claude.json, managed-mcp.json and plugin files ([03710a6](https://github.com/ayagmar/ccdesk/commit/03710a6ff76557bde8e3b935244b700c8b1daf37))
+* **core:** report memory, agent and skill files the scan cannot read ([3b91804](https://github.com/ayagmar/ccdesk/commit/3b9180401fd0479aa584c86f56dead7aa12b6dbf))
+* **core:** resolve Watcher.subscribe and wait once moved watchers start ([039bb73](https://github.com/ayagmar/ccdesk/commit/039bb73282c014f2389ad37c37b5b80f6a91511e))
+* **ui:** disable Undo while it runs and clear stale errors in Recent changes ([2c0c1e5](https://github.com/ayagmar/ccdesk/commit/2c0c1e5e381b49b40c1d99a5b9b3cfd1ce2d25a7))
+* **ui:** say how to recover from an expired token wherever a call fails ([f9864a2](https://github.com/ayagmar/ccdesk/commit/f9864a24cf105691e8396de369c4167aa92f9750))
+* **ui:** stop warning that the file changed after saving a setting ([e807947](https://github.com/ayagmar/ccdesk/commit/e80794746c9eed8503baa5a6cfa694568ab37740))
+* **watch:** rewatch before calling subscribers, so one that throws cannot skip it ([d63fa49](https://github.com/ayagmar/ccdesk/commit/d63fa49cdf947795c8cafabc8e76458f91689601))
+
+### Performance Improvements
+
+* **ui:** load the settings schema and catalog from the server ([34ba654](https://github.com/ayagmar/ccdesk/commit/34ba654ca9d5513a792ed5c44a50490a9d79dd54))
+
 ## [0.2.2](https://github.com/ayagmar/ccdesk/compare/v0.2.1...v0.2.2) (2026-10-12)
 
 ### Bug Fixes

package/README.md

@@ -96,21 +96,24 @@ More in [Reading the interface](https://ayagmar.github.io/ccdesk/interface/).
 ## Options
 
 ```
-npx ccdesk [options]
+npx ccdesk [options]                     Open the page in your browser
+npx ccdesk scan [dir] --json             Print what Claude Code loads in dir, as JSON
+npx ccdesk explain <file> [--dir <dir>]  Print what loads once Claude reads or edits file
 
   --port <n>            Port to listen on (default: a free port)
   --no-open             Print the URL instead of opening a browser
   --config-dir <path>   Claude folder to read, as CLAUDE_CONFIG_DIR sets it for Claude Code
                         (wins over $CLAUDE_CONFIG_DIR)
+  --dir <dir>           For explain: the folder the session starts in (default: the current one)
   -h, --help            Show this help
 ```
 
-ccdesk reads `~/.claude` and `~/.claude.json`, or `$CLAUDE_CONFIG_DIR` when it is set, as Claude Code does. To look at another profile without exporting the variable, pass `--config-dir <path>`. Edits made in another editor or by Claude show up within a second. Changes to `~/.claude.json`, such as trust decisions and MCP approvals, show up when you return to the tab. Requires Node.js 22.19 or newer. See [Platform notes](https://ayagmar.github.io/ccdesk/platforms/) for Windows, macOS and WSL.
+ccdesk reads `~/.claude` and `~/.claude.json`, or `$CLAUDE_CONFIG_DIR` when it is set, as Claude Code does. To look at another profile without exporting the variable, pass `--config-dir <path>`. `ccdesk scan` prints the same view the page shows for a directory, for scripts; `ccdesk explain` lists the path rules, skills and folder instructions that load once Claude reads or edits a file. Both only read, and hidden values stay hidden in what they print. Edits made in another editor or by Claude show up within a second. Changes to `~/.claude.json`, such as trust decisions and MCP approvals, show up when you return to the tab. Requires Node.js 22.19 or newer. See [Platform notes](https://ayagmar.github.io/ccdesk/platforms/) for Windows, macOS and WSL.
 
 ## Privacy and safety
 
 - The server listens on `127.0.0.1` only, and every API call needs a token generated for that run. Nothing leaves your machine.
-- Values under `env` and `headers`, and keys in an MCP server's `args` (after flags such as `--token` or `--api-key`, or starting like `sk-` or `ghp_`), are hidden everywhere in the UI, diffs included, and ccdesk refuses any edit that would change them.
+- Values under `env` and `headers`, and keys in an MCP server's `args` (after flags such as `--token` or `--api-key`, in a `--header` such as `Authorization: Bearer …`, or starting like `sk-` or `ghp_`), are hidden everywhere in the UI, diffs included, and ccdesk refuses any edit that would change them.
 - ccdesk never reads `~/.claude/.credentials.json`.
 - From your transcripts, only counts and rule patterns (a command's program and subcommand, a fetch's domain) reach the page, never commands or file contents.
 - Backups are readable only by you on Linux and macOS.
@@ -126,7 +129,7 @@ pnpm dev:ui     # UI with hot reload on localhost:4320
 pnpm check      # typecheck, lint, format, tests, build
 ```
 
-Tests never touch your real `~/.claude`; each one builds a throwaway home directory. The settings schema, scopes and built-in tools are generated from [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and Claude Code's docs, and a daily workflow opens a pull request when they change. [Contributing](https://ayagmar.github.io/ccdesk/contributing/) covers the generators, the docs site and releases.
+Tests never touch your real `~/.claude`; each one builds a throwaway home directory. The settings schema, scopes and built-in tools are generated from [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and Claude Code's docs, and a daily workflow opens a pull request when they change. [Contributing](https://ayagmar.github.io/ccdesk/contributing/) covers the generators, the docs site and releases. [ARCHITECTURE.md](ARCHITECTURE.md) explains how the code fits together, and [`docs/`](docs/) holds the plan for splitting the core from the web server and feature ideas.
 
 ## License
 

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

@@ -0,0 +1,6 @@
+import { type AgentEdit, type Change, type SettingsEditPreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+export declare function previewAgentEdit(env: ScanEnv, edit: AgentEdit): Promise<SettingsEditPreview>;
+/** Writes or deletes an agent file, backed up first, only while it is as reviewed. */
+export declare function saveAgentEdit(env: ScanEnv, edit: AgentEdit, expectedRevision: string, queue: Serially): Promise<Change>;

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

@@ -1,10 +1,12 @@
 import { join, resolve } from "node:path";
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
-import { gitRoot, revisionOf, shownText } from "./scan/files.js";
+import { revisionOf } from "./scan/files.js";
+import { gitRoot } from "./scan/git.js";
+import { shownText } from "./secrets.js";
 import { scanDirectory } from "./scan/index.js";
 import { agentProblems } from "./scan/inventory.js";
-import { RefusedError, readIfExists, recordChange, removeExactly, serially, StaleError, writeAtomic, } from "./write.js";
+import { RefusedError, readIfExists, recordChange, removeExactly, StaleError, saveReviewed, writeAtomic, } from "./write.js";
 /** The file an edit changes: an agent the scan shows here, or a new one in your or the project's folder. */
 async function targetOf(env, edit) {
     const dir = resolve(edit.dir);
@@ -46,37 +48,29 @@ async function plan(env, edit) {
         errors = [
             "ccdesk does not write env, header or URL values it would then hide; add them in your editor instead.",
         ];
+    const { text } = edit;
     return {
-        path,
-        raw,
         preview: {
             path,
             before,
-            after: errors.length > 0 ? (before ?? "") : (shownText(edit.text) ?? ""),
+            after: errors.length > 0 ? (before ?? "") : (shownText(text) ?? ""),
             revision: revisionOf(raw),
             reformats: false,
             errors,
         },
+        save: () => recordChange(env, { kind: "agent", target: path, before: raw }, async () => {
+            if (text !== null)
+                await writeAtomic(env, path, text, revisionOf(raw));
+            else if (!(await removeExactly(path, revisionOf(raw))))
+                throw new StaleError(`${path} changed while ccdesk deleted it; nothing was deleted.`);
+            return { target: path, revision: revisionOf(text) };
+        }),
     };
 }
 export async function previewAgentEdit(env, edit) {
     return (await plan(env, edit)).preview;
 }
 /** Writes or deletes an agent file, backed up first, only while it is as reviewed. */
-export function saveAgentEdit(env, edit, expectedRevision) {
-    return serially(async () => {
-        const { path, raw, preview } = await plan(env, edit);
-        if (preview.errors.length > 0)
-            throw new RefusedError(preview.errors.join(" "));
-        if (preview.revision !== expectedRevision)
-            throw new RefusedError("The agent changed since you reviewed this; review it again.");
-        const { text } = edit;
-        return recordChange(env, { kind: "agent", target: path, before: raw }, async () => {
-            if (text !== null)
-                await writeAtomic(env, path, text, expectedRevision);
-            else if (!(await removeExactly(path, expectedRevision)))
-                throw new StaleError(`${path} changed while ccdesk deleted it; nothing was deleted.`);
-            return { target: path, revision: revisionOf(text) };
-        });
-    });
+export function saveAgentEdit(env, edit, expectedRevision, queue) {
+    return saveReviewed(queue, () => plan(env, edit), expectedRevision, "The agent changed since you reviewed this; review it again.");
 }

package/dist/core/backups.d.ts

@@ -0,0 +1,19 @@
+import { type BackupSummary, type RestorePreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+/** The changes ccdesk made, newest first, a page at a time. */
+export declare function listBackups(env: ScanEnv, { before, limit }: {
+    before?: string;
+    limit: number;
+}): Promise<{
+    changes: BackupSummary[];
+    more: boolean;
+}>;
+export declare function previewRestore(env: ScanEnv, id: string): Promise<RestorePreview>;
+/**
+ * Puts a backed-up file back, or removes a file ccdesk created, if the file is still as it was
+ * when the restore was reviewed. A removed file is backed up first, so it can be put back too.
+ */
+export declare function restoreBackup(env: ScanEnv, id: string, expectedRevision: string, queue: Serially): Promise<{
+    target: string;
+}>;

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

@@ -1,29 +1,29 @@
 import { lstat, readdir, readFile, realpath } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { Compile } from "typebox/compile";
 import {} from "../shared/types.js";
 import { assertMemoryDir, indexPathIn, revisionOfBoth } from "./mutations.js";
+import { parseJson } from "./scan/data.js";
 import {} from "./scan/env.js";
-import { isRecord, isWithin, revisionOf, shownText } from "./scan/files.js";
-import { hiddenValues, shown } from "./secrets.js";
-import { backupRoot, forgetChange, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SHOWN_AFTER, SNAPSHOT, StaleError, serially, writeAtomic, } from "./write.js";
-const KINDS = new Set([
-    "settings",
-    "mcp",
-    "agent",
-    "memory-index",
-    "memory-delete",
-    "memory-restore",
-    "mcp-claude",
-]);
-function strings(value) {
-    return Array.isArray(value) && value.every((v) => typeof v === "string");
-}
+import { isWithin, revisionOf } from "./scan/files.js";
+import { hiddenValues, shown, shownText } from "./secrets.js";
+import { BackupManifestSchema, backupRoot, forgetChange, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SHOWN_AFTER, SNAPSHOT, StaleError, writeAtomic, } from "./write.js";
+const backupManifest = Compile(BackupManifestSchema);
 /** A backup folder's manifest; anything that does not look like one ccdesk wrote is skipped. */
 async function readManifest(env, id) {
     // ccdesk's ids are letters, digits and dashes, so no id can name a folder outside the root.
     if (!/^[\w-]+$/.test(id))
         return null;
-    const text = await readIfExists(env, join(backupRoot(env), id, MANIFEST)).catch(() => null);
+    let text;
+    try {
+        text = await readIfExists(env, join(backupRoot(env), id, MANIFEST));
+    }
+    catch (error) {
+        // A stray file in the backup folder is not a backup; a folder ccdesk cannot read is an error.
+        if (error.code === "ENOTDIR")
+            return null;
+        throw error;
+    }
     if (text === null)
         return null;
     let data;
@@ -33,21 +33,25 @@ async function readManifest(env, id) {
     catch {
         return null;
     }
-    if (!isRecord(data) ||
-        typeof data.kind !== "string" ||
-        !KINDS.has(data.kind) ||
-        typeof data.target !== "string" ||
-        typeof data.createdAt !== "string" ||
-        typeof data.before !== "string" ||
-        typeof data.after !== "string" ||
-        (data.removedIndexLines !== undefined && !strings(data.removedIndexLines)) ||
-        (data.undoCommands !== undefined && !strings(data.undoCommands)))
-        return null;
-    return data;
+    return backupManifest.Check(data) ? data : null;
+}
+/**
+ * Backup folder names, newest first. No folder yet means no changes; one ccdesk cannot read, such
+ * as one a `sudo ccdesk` left owned by root, is an error rather than an empty list.
+ */
+async function backupIds(env) {
+    try {
+        return (await readdir(backupRoot(env))).sort().reverse();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
 }
 /** The changes ccdesk made, newest first, a page at a time. */
 export async function listBackups(env, { before, limit }) {
-    const ids = (await readdir(backupRoot(env)).catch(() => [])).sort().reverse();
+    const ids = await backupIds(env);
     const changes = [];
     for (const id of ids) {
         if (before !== undefined && id >= before)
@@ -89,7 +93,7 @@ function shownSettings(text) {
     if (text === null)
         return null;
     try {
-        return shown(JSON.parse(text));
+        return shown(parseJson(text));
     }
     catch {
         return "(not valid JSON; open the file to see it)\n";
@@ -131,26 +135,38 @@ async function claudeMcpPreview(id, manifest, dir) {
 }
 async function planRestore(env, id) {
     const { manifest, dir } = await backupAt(env, id);
-    if (manifest.kind === "mcp-claude")
-        throw new RefusedError(MADE_BY_CLAUDE);
     let target = manifest.target;
-    if (manifest.kind === "settings" && !isSettingsFile(env, target))
-        throw new RefusedError("This backup does not point at a settings file.");
-    if (manifest.kind === "mcp" && basename(target) !== ".mcp.json")
-        throw new RefusedError("This backup does not point at a .mcp.json.");
-    if (manifest.kind === "agent" && !isAgentFile(env, target))
-        throw new RefusedError("This backup does not point at a subagent file.");
-    if (manifest.kind === "memory-index" && basename(target) !== "MEMORY.md")
-        throw new RefusedError("This backup does not point at a MEMORY.md.");
-    if (manifest.kind !== "settings" && manifest.kind !== "mcp" && manifest.kind !== "agent") {
-        const store = await assertMemoryDir(env, dirname(target));
+    switch (manifest.kind) {
+        case "mcp-claude":
+            throw new RefusedError(MADE_BY_CLAUDE);
+        case "settings":
+            if (!isSettingsFile(env, target))
+                throw new RefusedError("This backup does not point at a settings file.");
+            break;
+        case "mcp":
+            if (basename(target) !== ".mcp.json")
+                throw new RefusedError("This backup does not point at a .mcp.json.");
+            break;
+        case "agent":
+            if (!isAgentFile(env, target))
+                throw new RefusedError("This backup does not point at a subagent file.");
+            break;
         // The same confinement as any other MEMORY.md change: a link out of the folder is refused.
-        target =
-            manifest.kind === "memory-index" ? await indexPathIn(store) : join(store, basename(target));
+        case "memory-index": {
+            if (basename(target) !== "MEMORY.md")
+                throw new RefusedError("This backup does not point at a MEMORY.md.");
+            target = await indexPathIn(await assertMemoryDir(env, dirname(target)));
+            break;
+        }
         // A deleted memory comes back only as a topic file, as ccdesk deletes only those.
-        if (manifest.kind !== "memory-index" &&
-            (!target.endsWith(".md") || basename(target) === "MEMORY.md"))
-            throw new RefusedError("This backup does not point at a memory file.");
+        case "memory-delete":
+        case "memory-restore": {
+            const store = await assertMemoryDir(env, dirname(target));
+            target = join(store, basename(target));
+            if (!target.endsWith(".md") || basename(target) === "MEMORY.md")
+                throw new RefusedError("This backup does not point at a memory file.");
+            break;
+        }
     }
     let saved = null;
     if (manifest.before !== revisionOf(null)) {
@@ -247,8 +263,8 @@ export async function previewRestore(env, id) {
  * Puts a backed-up file back, or removes a file ccdesk created, if the file is still as it was
  * when the restore was reviewed. A removed file is backed up first, so it can be put back too.
  */
-export function restoreBackup(env, id, expectedRevision) {
-    return serially(async () => {
+export function restoreBackup(env, id, expectedRevision, queue) {
+    return queue(async () => {
         const plan = await planRestore(env, id);
         const { manifest, current, saved, index } = plan;
         const blocked = blockedReason(plan);

package/dist/core/core.d.ts

@@ -0,0 +1,96 @@
+import { type RunClaude } from "./mcp-edit.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type AgentEdit, type HookEdit, type McpEdit, type MemoryAction, type PermissionEdit, type SettingsEdit } from "../shared/types.ts";
+export interface CoreOptions {
+    /** Runs `claude` for user and local MCP servers. By default, the claude on `env`'s PATH. */
+    runClaude?: RunClaude;
+    /**
+     * Opens a file or folder and resolves with the command used. By default, the editor `env` names
+     * or has. The core refuses a missing path and the credentials file before calling it.
+     */
+    openFile?: (path: string) => Promise<string>;
+}
+/**
+ * The core for one machine: every read and change, with `env` already passed. Changes made through
+ * one core run one at a time, and its usage counts share one cache. Two cores share neither, so
+ * make one per Claude folder: two on the same folder could both pass a revision check.
+ */
+export declare function createCore(env: ScanEnv, options?: CoreOptions): {
+    env: ScanEnv;
+    openFile: (path: string) => Promise<string>;
+    scanOverview: (launchDir: string) => Promise<import("../shared/types.ts").Overview>;
+    scanDirectory: (dir: string, profile?: import("../shared/types.ts").SessionProfile | undefined) => Promise<import("../shared/types.ts").DirectoryView>;
+    compareSettings: (a: string, b: string) => Promise<import("./index.ts").SettingsComparison>;
+    testPath: (dir: string, file: string, viewOf?: ((cwd: string) => Promise<import("../shared/types.ts").DirectoryView>) | undefined) => Promise<import("../shared/types.ts").PathTest>;
+    readUsage: (dir: string, rules: import("./scan/usage.ts").RuleInEffect[], args_2?: {
+        signal?: AbortSignal;
+        timeLimitMs?: number;
+        maxCachedCalls?: number;
+    } | undefined) => Promise<import("../shared/types.ts").Usage>;
+    previewSettingsEdit: (edit: {
+        dir: string;
+        scope: import("../shared/types.ts").Scope;
+        key: string;
+        value?: unknown;
+    }) => Promise<import("../shared/types.ts").SettingsEditPreview>;
+    saveSettingsEdit: (edit: SettingsEdit, revision: string) => Promise<import("../shared/types.ts").Change>;
+    previewPermissionEdit: (edit: {
+        dir: string;
+        file: string;
+        remove?: {
+            list: import("../shared/types.ts").PermissionList;
+            rule: string;
+        };
+        add?: {
+            list: import("../shared/types.ts").PermissionList;
+            rule: string;
+        };
+    }) => Promise<import("../shared/types.ts").SettingsEditPreview>;
+    savePermissionEdit: (edit: PermissionEdit, revision: string) => Promise<import("../shared/types.ts").Change>;
+    previewHookEdit: (edit: {
+        dir: string;
+        file: string;
+        remove?: {
+            event: string;
+            at: {
+                group: number;
+                index: number;
+            };
+            definition: unknown;
+        };
+        add?: {
+            event: string;
+            matcher?: string;
+            definition: unknown;
+        };
+    }) => Promise<import("../shared/types.ts").SettingsEditPreview>;
+    saveHookEdit: (edit: HookEdit, revision: string) => Promise<import("../shared/types.ts").Change>;
+    previewAgentEdit: (edit: {
+        dir: string;
+        path?: string;
+        create?: {
+            scope: "project" | "user";
+            file: string;
+        };
+        text: string | null;
+    }) => Promise<import("../shared/types.ts").SettingsEditPreview>;
+    saveAgentEdit: (edit: AgentEdit, revision: string) => Promise<import("../shared/types.ts").Change>;
+    previewMcpEdit: (edit: McpEdit) => Promise<import("../shared/types.ts").SettingsEditPreview>;
+    saveMcpEdit: (edit: McpEdit, revision: string) => Promise<import("../shared/types.ts").Change | {
+        target: string;
+    }>;
+    previewMemoryChange: (action: MemoryAction, path: string) => Promise<import("../shared/types.ts").MemoryChangePreview>;
+    changeMemory: (action: MemoryAction, path: string, revision: string) => Promise<import("../shared/types.ts").Change>;
+    listBackups: (args_0: {
+        before?: string;
+        limit: number;
+    }) => Promise<{
+        changes: import("../shared/types.ts").BackupSummary[];
+        more: boolean;
+    }>;
+    previewRestore: (id: string) => Promise<import("../shared/types.ts").RestorePreview>;
+    restoreBackup: (id: string, revision: string) => Promise<{
+        target: string;
+    }>;
+};
+export type Core = ReturnType<typeof createCore>;

package/dist/core/core.js

@@ -0,0 +1,57 @@
+import { stat } from "node:fs/promises";
+import { previewAgentEdit, saveAgentEdit } from "./agent-edit.js";
+import { listBackups, previewRestore, restoreBackup } from "./backups.js";
+import { claudeRunner, previewMcpEdit, saveMcpEdit } from "./mcp-edit.js";
+import { changeMemory, previewMemoryChange } from "./mutations.js";
+import { openInEditor } from "./open.js";
+import { compareSettings } from "./scan/compare.js";
+import {} from "./scan/env.js";
+import { isCredentials } from "./scan/files.js";
+import { scanDirectory, scanOverview } from "./scan/index.js";
+import { testPath } from "./scan/path-test.js";
+import { usageCounter } from "./scan/usage.js";
+import { previewHookEdit, previewPermissionEdit, previewSettingsEdit, saveHookEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
+import { changeQueue, RefusedError } from "./write.js";
+import {} from "../shared/types.js";
+/**
+ * The core for one machine: every read and change, with `env` already passed. Changes made through
+ * one core run one at a time, and its usage counts share one cache. Two cores share neither, so
+ * make one per Claude folder: two on the same folder could both pass a revision check.
+ */
+export function createCore(env, options = {}) {
+    const run = options.runClaude ?? claudeRunner(env);
+    const open = options.openFile ?? ((path) => openInEditor(path, env));
+    const queue = changeQueue();
+    const bound = (read) => (...args) => read(env, ...args);
+    return {
+        env,
+        openFile: async (path) => {
+            const info = await stat(path).catch(() => null);
+            if (!info?.isFile() && !info?.isDirectory())
+                throw new RefusedError("That file or folder no longer exists.");
+            if (await isCredentials(env, path))
+                throw new RefusedError("ccdesk does not open credentials.");
+            return open(path);
+        },
+        scanOverview: bound(scanOverview),
+        scanDirectory: bound(scanDirectory),
+        compareSettings: bound(compareSettings),
+        testPath: bound(testPath),
+        readUsage: bound(usageCounter()),
+        previewSettingsEdit: bound(previewSettingsEdit),
+        saveSettingsEdit: (edit, revision) => saveSettingsEdit(env, edit, revision, queue),
+        previewPermissionEdit: bound(previewPermissionEdit),
+        savePermissionEdit: (edit, revision) => savePermissionEdit(env, edit, revision, queue),
+        previewHookEdit: bound(previewHookEdit),
+        saveHookEdit: (edit, revision) => saveHookEdit(env, edit, revision, queue),
+        previewAgentEdit: bound(previewAgentEdit),
+        saveAgentEdit: (edit, revision) => saveAgentEdit(env, edit, revision, queue),
+        previewMcpEdit: (edit) => previewMcpEdit(env, edit, run),
+        saveMcpEdit: (edit, revision) => saveMcpEdit(env, edit, revision, run, queue),
+        previewMemoryChange: bound(previewMemoryChange),
+        changeMemory: (action, path, revision) => changeMemory(env, action, path, revision, queue),
+        listBackups: bound(listBackups),
+        previewRestore: bound(previewRestore),
+        restoreBackup: (id, revision) => restoreBackup(env, id, revision, queue),
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,22 @@
+export { type Core, type CoreOptions, createCore } from "./core.ts";
+export { isConfigHome, type ScanEnv, scanEnvFromProcess } from "./scan/env.ts";
+export { compareSettings } from "./scan/compare.ts";
+export { revisionOf } from "./scan/files.ts";
+export { scanDirectory, scanOverview } from "./scan/index.ts";
+export { testPath } from "./scan/path-test.ts";
+export { CountStopped } from "./scan/usage.ts";
+export { hasHiddenValues, redactSecrets, shown, shownText } from "./secrets.ts";
+export { Watcher } from "./watch.ts";
+export { previewAgentEdit } from "./agent-edit.ts";
+export { claudeProgram, claudeRunner, previewMcpEdit, type RunClaude } from "./mcp-edit.ts";
+export { isMemoryAction, previewMemoryChange } from "./mutations.ts";
+export { InvalidEditError, parseAgentEdit, parseHookEdit, parseMcpEdit, parsePermissionEdit, parseSettingsEdit, } from "./parse-edit.ts";
+export { previewHookEdit, previewPermissionEdit, previewSettingsEdit } from "./settings-edit.ts";
+export { RefusedError, StaleError } from "./write.ts";
+export { listBackups, previewRestore } from "./backups.ts";
+export { openInEditor } from "./open.ts";
+export { REFERENCE } from "./reference.ts";
+export * from "../shared/compare.ts";
+export * from "../shared/memory.ts";
+export * from "../shared/scopes.ts";
+export * from "../shared/types.ts";

package/dist/core/index.js

@@ -0,0 +1,38 @@
+// The core: everything a front end needs to read and change Claude Code's configuration, without
+// HTTP. It re-exports the modules in src/core and src/shared; see ARCHITECTURE.md for how they
+// fit together and docs/split-plan.md for where they are going.
+// The core for one machine: createCore(env) returns every read and change with the env already
+// passed, its own change queue and usage cache, and the editor and claude its env names. Changes,
+// usage counts and undo are made only through a core, so they run on its queue and cache.
+export { createCore } from "./core.js";
+// Environment: every function below takes the ScanEnv first.
+export { isConfigHome, scanEnvFromProcess } from "./scan/env.js";
+// Read.
+export { compareSettings } from "./scan/compare.js";
+export { revisionOf } from "./scan/files.js";
+export { scanDirectory, scanOverview } from "./scan/index.js";
+export { testPath } from "./scan/path-test.js";
+export { CountStopped } from "./scan/usage.js";
+export { hasHiddenValues, redactSecrets, shown, shownText } from "./secrets.js";
+export { Watcher } from "./watch.js";
+// Edits: the parse functions turn input from outside (JSON, arguments) into an edit, or throw
+// InvalidEditError. Preview returns a revision, and a core's save takes it back. Both refuse with
+// RefusedError, also when the file changed since the preview; StaleError, a RefusedError, means it
+// changed while ccdesk was writing it.
+export { previewAgentEdit } from "./agent-edit.js";
+export { claudeProgram, claudeRunner, previewMcpEdit } from "./mcp-edit.js";
+export { isMemoryAction, previewMemoryChange } from "./mutations.js";
+export { InvalidEditError, parseAgentEdit, parseHookEdit, parseMcpEdit, parsePermissionEdit, parseSettingsEdit, } from "./parse-edit.js";
+export { previewHookEdit, previewPermissionEdit, previewSettingsEdit } from "./settings-edit.js";
+export { RefusedError, StaleError } from "./write.js";
+// History: every change ccdesk saves is a backup that a core can restore by its id.
+export { listBackups, previewRestore } from "./backups.js";
+// Host.
+export { openInEditor } from "./open.js";
+// Claude Code's settings schema, settings catalog and hook events.
+export { REFERENCE } from "./reference.js";
+// Types and constants shared with the web UI.
+export * from "../shared/compare.js";
+export * from "../shared/memory.js";
+export * from "../shared/scopes.js";
+export * from "../shared/types.js";

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

@@ -0,0 +1,23 @@
+import { type Change, type McpEdit, type SettingsEditPreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+/**
+ * Runs `claude` with these arguments in `cwd`, with the profile ccdesk reads so its edits land
+ * where the page shows them, and resolves with its output. Replaced in tests, so nothing outside
+ * the test changes.
+ */
+export type RunClaude = (args: string[], cwd: string, configDir: string | undefined) => Promise<string>;
+/**
+ * The program to run for `claude`. On Windows, npm installs Claude Code as a claude.cmd that starts
+ * the package's claude.exe; Node cannot run a .cmd without a shell, which would read the server's
+ * JSON as shell syntax, so ccdesk runs that claude.exe itself. A claude.exe earlier on PATH, as the
+ * native installer puts there, comes first, as it would in a terminal.
+ */
+export declare function claudeProgram(path: string, platform: NodeJS.Platform): Promise<string>;
+/** Runs the claude on `host`'s PATH, with `host`'s environment. */
+export declare function claudeRunner(host: Pick<ScanEnv, "platform" | "processEnv">): RunClaude;
+export declare function previewMcpEdit(env: ScanEnv, edit: McpEdit, run: RunClaude): Promise<SettingsEditPreview>;
+/** Makes a reviewed MCP edit, only while the servers are still as reviewed. */
+export declare function saveMcpEdit(env: ScanEnv, edit: McpEdit, expectedRevision: string, run: RunClaude, queue: Serially): Promise<Change | {
+    target: string;
+}>;