ccdesk 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [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
+
+* **agents:** refuse agent text with values its review would hide ([3a9b39f](https://github.com/ayagmar/ccdesk/commit/3a9b39f2634cf4a10a9fc9a7ba7c627dddebd9da))
+* **compare:** ignore key order when comparing settings ([db71cde](https://github.com/ayagmar/ccdesk/commit/db71cde8c19c4bae292e5f41cd8d8c0cf7c578e4))
+* **context:** count a linked rule imported by its target's path once ([63830ef](https://github.com/ayagmar/ccdesk/commit/63830ef9096c2a86005cb60bad3d1c872921cdc1))
+* **context:** count a rule in a linked folder once when it is also imported ([168039b](https://github.com/ayagmar/ccdesk/commit/168039b738524b1d72f5e48edfcb51bea069a506))
+* **context:** prefer the real path the scan recorded when deduplicating ([d5a3e75](https://github.com/ayagmar/ccdesk/commit/d5a3e7566668156de9a3739b9fa51a39301cf697))
+* **env:** make a relative CLAUDE_CONFIG_DIR absolute ([2939488](https://github.com/ayagmar/ccdesk/commit/2939488c5ded1869367ca769218f17be8880fcd4))
+* **hooks:** refuse a replacement hook with hidden header values ([c40e7b4](https://github.com/ayagmar/ccdesk/commit/c40e7b4dfeda44fe104ad24cbd790a846da31266))
+* **mcp:** name the chosen profile in the claude commands ccdesk shows ([4d99fbd](https://github.com/ayagmar/ccdesk/commit/4d99fbd37087fa0a6332bc997975efb510d123b5))
+* **mcp:** run claude with the profile chosen by --config-dir ([02c6af0](https://github.com/ayagmar/ccdesk/commit/02c6af0bd56235874dd1a46dd1a3aaf124f299b8))
+* **path-test:** apply startup's rules to a subfolder's linked rules ([49d426c](https://github.com/ayagmar/ccdesk/commit/49d426c07beb5ce8e6538c2091b5e3c989d356e1))
+* **path-test:** keep AGENTS.md out when a subfolder's CLAUDE.md is skipped ([c05ed89](https://github.com/ayagmar/ccdesk/commit/c05ed89f04db3a83b1dad2e35b803cbb4af2e4a3))
+* **path-test:** match a linked rule's target against excludes only as startup does ([dfb6a79](https://github.com/ayagmar/ccdesk/commit/dfb6a79ae70c7eb4c94f4905c76b78f081c8afce))
+* **path-test:** skip subfolder instructions and rules over 4 MiB ([3696d74](https://github.com/ayagmar/ccdesk/commit/3696d74ec070dda64184b100b9eecef181e52884))
+* **scan:** cite the docs section on MCP rules with parentheses ([901c372](https://github.com/ayagmar/ccdesk/commit/901c3729ed4089bdfd5dd19a6265a5995aae1458))
+* **scan:** treat a name starting with two dots as inside its folder ([af6b025](https://github.com/ayagmar/ccdesk/commit/af6b02549e55a24394197da08326412bb1890059))
+* **settings:** refuse hook events Claude Code does not know ([b6561e6](https://github.com/ayagmar/ccdesk/commit/b6561e6f9b5a86a9fa27b3138cb570f493edb0d5))
+* **usage:** do not start a count for a page that already left ([4984a58](https://github.com/ayagmar/ccdesk/commit/4984a585d6a6ccd3914f2e06b9f274bd4b66eb21))
+* **watch:** answer a wait whose watcher closed while it was starting ([5c63129](https://github.com/ayagmar/ccdesk/commit/5c63129bdb60d9bc5f6d13a7665e4f273dcfb406))
+* **watch:** answer waiting pages when the watcher closes ([ad1c5ea](https://github.com/ayagmar/ccdesk/commit/ad1c5ea1080362858755e5f2c09e4bf19a3682e2))
+* **watch:** refresh when a file inside an installed plugin changes ([a09a99e](https://github.com/ayagmar/ccdesk/commit/a09a99e38c37c765c5117138324d50174ad7b142))
+* **watch:** refresh when a missing import is created ([279b033](https://github.com/ayagmar/ccdesk/commit/279b03353f414ed9faeaf0a86450c49da56aea1a))
+* **watch:** refresh when a missing import's folder appears later ([91f6444](https://github.com/ayagmar/ccdesk/commit/91f644452c3975dd09b2f1fbb86b2c96cf5da561))
+* **watch:** watch ~/.claude/plugins only for the install list ([382b6b0](https://github.com/ayagmar/ccdesk/commit/382b6b0990c82f71dab37cfd8840bd1aec42c47e))
+* **watch:** watch only the plugin files the scan reads ([8d12adc](https://github.com/ayagmar/ccdesk/commit/8d12adcfa0cdf74097273516d04130a99cffe578))
+
 ## [0.2.1](https://github.com/ayagmar/ccdesk/compare/v0.2.0...v0.2.1) (2026-10-12)
 
 ### Features

package/README.md

@@ -8,6 +8,7 @@
 [![npm](https://img.shields.io/npm/v/ccdesk?style=flat-square&color=141414)](https://www.npmjs.com/package/ccdesk)
 [![CI](https://img.shields.io/github/actions/workflow/status/ayagmar/ccdesk/ci.yml?branch=master&style=flat-square&label=ci)](https://github.com/ayagmar/ccdesk/actions/workflows/ci.yml)
 [![node](https://img.shields.io/node/v/ccdesk?style=flat-square&color=141414)](https://github.com/ayagmar/ccdesk/blob/master/package.json)
+[![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-blue)](https://deepwiki.com/ayagmar/ccdesk)
 [![license](https://img.shields.io/github/license/ayagmar/ccdesk?style=flat-square&color=141414)](https://github.com/ayagmar/ccdesk/blob/master/LICENSE)
 
 See and change everything Claude Code loads on your machine: instruction files, settings, permissions, hooks, MCP servers, subagents, skills, plugins and auto memory.
@@ -16,7 +17,7 @@ See and change everything Claude Code loads on your machine: instruction files,
 npx ccdesk
 ```
 
-Each piece lives in its own file, at one of six scopes: managed, user, project, local, auto memory or a plugin. ccdesk opens in your browser on the directory you ran it from, lists everything that applies there in the order Claude Code loads it, and names the file behind each piece. When something is wrong, change it on the same page: you review the diff first, and every edit has a backup and an undo. It is not a session viewer or a usage dashboard.
+Each piece lives in its own file, at one of six scopes: managed, user, project, local, auto memory or a plugin. ccdesk opens in your browser on the directory you ran it from, lists everything that applies there in the order Claude Code loads it, and names the file behind each piece. When something is wrong, change it on the same page: you review the diff first, and every file ccdesk writes is backed up and can be undone. It is not a session viewer or a usage dashboard.
 
 **Docs:** [ayagmar.github.io/ccdesk](https://ayagmar.github.io/ccdesk/)
 
@@ -74,7 +75,7 @@ Each piece lives in its own file, at one of six scopes: managed, user, project,
 - The old file is backed up to `~/.claude/backups/ccdesk/` first. Undo is one click, and **Recent changes** can restore any earlier edit.
 - A settings file that is a symlink, such as one in a dotfiles repository, is written through and stays a link.
 - A file with other hard links is not saved: replacing it would split it from its other names. Edit it in your editor.
-- ccdesk never writes `~/.claude.json`. User and local MCP server changes go through Claude Code's own `claude mcp` command, so they need `claude` on your PATH.
+- ccdesk never writes `~/.claude.json`. User and local MCP server changes go through Claude Code's own `claude mcp` command, so they need `claude` on your PATH. ccdesk keeps no backup of these and cannot undo them; **Recent changes** lists each one with the commands that reverse it.
 
 Details: [Recent changes, backups and undo](https://ayagmar.github.io/ccdesk/recent-changes/)
 
@@ -95,16 +96,19 @@ 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. 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
 
@@ -125,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, serially, 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);
@@ -40,38 +42,35 @@ async function plan(env, edit) {
     // from it would lose them; it can still be deleted, as a whole.
     if (edit.text !== null && before !== raw)
         throw new RefusedError(`${path} has env, header or URL values ccdesk does not show; edit it in your editor instead.`);
-    const errors = edit.text === null ? [] : agentProblems(edit.text);
+    let errors = edit.text === null ? [] : agentProblems(edit.text);
+    // Nor does it write values its review would hide.
+    if (edit.text !== null && errors.length === 0 && shownText(edit.text) !== edit.text)
+        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 = serially) {
+    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,23 +1,13 @@
 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 {} 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, serially, 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.
@@ -33,17 +23,7 @@ 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;
 }
 /** The changes ccdesk made, newest first, a page at a time. */
 export async function listBackups(env, { before, limit }) {
@@ -131,26 +111,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 +239,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 = serially) {
+    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, readUsage } from "./scan/usage.ts";
+export { hasHiddenValues, redactSecrets, shown, shownText } from "./secrets.ts";
+export { Watcher } from "./watch.ts";
+export { previewAgentEdit, saveAgentEdit } from "./agent-edit.ts";
+export { claudeProgram, claudeRunner, previewMcpEdit, type RunClaude, runClaude, saveMcpEdit, } from "./mcp-edit.ts";
+export { changeMemory, isMemoryAction, previewMemoryChange } from "./mutations.ts";
+export { InvalidEditError, parseAgentEdit, parseHookEdit, parseMcpEdit, parsePermissionEdit, parseSettingsEdit, } from "./parse-edit.ts";
+export { previewHookEdit, previewPermissionEdit, previewSettingsEdit, saveHookEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.ts";
+export { RefusedError, StaleError } from "./write.ts";
+export { listBackups, previewRestore, restoreBackup } 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 the reads and changes below with the env
+// already passed, its own change queue and usage cache, and the editor and claude its env names.
+export { createCore } from "./core.js";
+// Environment: every function below takes the ScanEnv first. Called directly, they share one
+// change queue and one usage cache across the process; they stay for one release beside createCore.
+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, readUsage } 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, 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, saveAgentEdit } from "./agent-edit.js";
+export { claudeProgram, claudeRunner, previewMcpEdit, runClaude, saveMcpEdit, } from "./mcp-edit.js";
+export { changeMemory, isMemoryAction, previewMemoryChange } from "./mutations.js";
+export { InvalidEditError, parseAgentEdit, parseHookEdit, parseMcpEdit, parsePermissionEdit, parseSettingsEdit, } from "./parse-edit.js";
+export { previewHookEdit, previewPermissionEdit, previewSettingsEdit, saveHookEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
+export { RefusedError, StaleError } from "./write.js";
+// History: every change ccdesk saves is a backup that can be restored by its id.
+export { listBackups, previewRestore, restoreBackup } 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,25 @@
+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;
+/** claudeRunner for this process's PATH and environment, read on each run; use a core's instead. */
+export declare const runClaude: 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;
+}>;