ccdesk 0.2.2 → 0.2.4

package/dist/server/server.js

@@ -1,25 +1,21 @@
-import { readFile, stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { extname, isAbsolute, join, normalize, resolve, sep } from "node:path";
-import HOOK_EVENTS from "../shared/hook-events.json" with { type: "json" };
-import { EVERY_FILE, PERMISSION_LISTS } from "../shared/scopes.js";
-import { SESSION_PROFILES, } from "../shared/types.js";
-import { listBackups, previewRestore, restoreBackup } from "./backups.js";
-import { previewAgentEdit, saveAgentEdit } from "./agent-edit.js";
-import { previewMcpEdit, runClaude, saveMcpEdit } from "./mcp-edit.js";
-import { changeMemory, isMemoryAction, previewMemoryChange } from "./mutations.js";
-import { openInEditor } from "./open.js";
-import { compareSettings } from "./scan/compare.js";
-import {} from "./scan/env.js";
-import { isCredentials, isRecord } from "./scan/files.js";
-import { scanOverview } from "./scan/index.js";
-import { CountStopped, readUsage } from "./scan/usage.js";
-import { testPath } from "./scan/path-test.js";
-import { previewHookEdit, previewPermissionEdit, previewSettingsEdit, saveHookEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
-import { Watcher } from "./watch.js";
-import { RefusedError } from "./write.js";
+import {} from "typebox";
+import { Compile } from "typebox/compile";
+import {} from "../core/core.js";
+import { BackupBody, MemoryBody, OpenBody, RevisionBody, UsageBody } from "../shared/requests.js";
+import { SESSION_PROFILES } from "../shared/types.js";
+import { isMemoryAction } from "../core/mutations.js";
+import { InvalidEditError, parseAgentEdit, parseHookEdit, parseMcpEdit, parsePermissionEdit, parseSettingsEdit, } from "../core/parse-edit.js";
+import { REFERENCE } from "../core/reference.js";
+import { CountStopped } from "../core/scan/usage.js";
+import { firstError } from "../core/schema.js";
+import { Watcher } from "../core/watch.js";
+import { RefusedError } from "../core/write.js";
+const HTML = "text/html; charset=utf-8";
 const MIME = {
-    ".html": "text/html; charset=utf-8",
+    ".html": HTML,
     ".js": "text/javascript; charset=utf-8",
     ".css": "text/css; charset=utf-8",
     ".svg": "image/svg+xml",
@@ -42,8 +38,8 @@ class RequestError extends Error {
     }
 }
 export function createCcdeskServer(options) {
-    const watcher = new Watcher(options.env);
-    const table = routes(options, watcher);
+    const watcher = new Watcher(options.core.env);
+    const table = routes(options.core, watcher, options.launchDir);
     const server = createServer((req, res) => {
         handle(options, table, server, req, res).catch((error) => {
             const [status, message] = failure(error);
@@ -57,6 +53,8 @@ export function createCcdeskServer(options) {
 function failure(error) {
     if (error instanceof RequestError)
         return [error.status, error.message];
+    if (error instanceof InvalidEditError)
+        return [400, error.message];
     // A change ccdesk refuses on purpose.
     if (error instanceof RefusedError)
         return [409, error.message];
@@ -65,111 +63,101 @@ function failure(error) {
     return [500, error instanceof Error ? error.message : String(error)];
 }
 /** The query parameter `name`; a missing one is a 400. */
-function param(url, name, message = `${name} is required`) {
+function param(url, name) {
     const value = url.searchParams.get(name);
     if (!value)
-        throw new RequestError(400, message);
+        throw new RequestError(400, `${name} is required`);
     return value;
 }
+/** The query parameter `name`, which must be an absolute path. */
+function absoluteParam(url, name) {
+    const value = param(url, name);
+    if (!isAbsolute(value))
+        throw new RequestError(400, `${name} must be an absolute path`);
+    return value;
+}
+const revisionBody = Compile(RevisionBody);
+const usageBody = Compile(UsageBody);
+const memoryBody = Compile(MemoryBody);
+const openBody = Compile(OpenBody);
+const backupBody = Compile(BackupBody);
+/** A POST body `validator` accepts; anything else is a 400 naming what is wrong. */
+function checked(validator, body) {
+    if (!validator.Check(body))
+        throw new RequestError(400, firstError(validator, body));
+    return body;
+}
 /** Aborts when the page goes away or asks for something else. */
 function stopOnClose(res) {
     const stop = new AbortController();
     res.once("close", () => stop.abort());
     return stop.signal;
 }
-function routes(options, watcher) {
-    const { env, launchDir } = options;
-    const run = options.runClaude ?? runClaude;
-    const revision = (body) => stringFields(body, ["revision"]).revision;
+function routes(core, watcher, launchDir) {
+    const revision = (body) => checked(revisionBody, body).revision;
     const get = (path, action) => ({ method: "GET", path, action });
     const post = (path, action) => ({ method: "POST", path, action });
     return [
-        get("/api/overview", () => scanOverview(env, launchDir)),
+        get("/api/overview", () => core.scanOverview(launchDir)),
+        // Sent instead of bundled with the page: the catalog and schema are most of its size.
+        get("/api/reference", async () => REFERENCE),
         get("/api/directory", ({ url }) => {
-            const profile = url.searchParams.get("profile") ?? "interactive";
-            if (!SESSION_PROFILES.includes(profile))
+            const asked = url.searchParams.get("profile") ?? "interactive";
+            const profile = SESSION_PROFILES.find((p) => p === asked);
+            if (!profile)
                 throw new RequestError(400, `profile is one of ${SESSION_PROFILES.join(", ")}`);
-            return watcher.scan(param(url, "path"), profile);
+            return watcher.scan(absoluteParam(url, "path"), profile);
         }),
         post("/api/usage", ({ body, res }) => {
-            const { path } = stringFields(body, ["path"]);
-            const rules = body.rules;
-            if (!Array.isArray(rules))
-                throw new RequestError(400, "rules must be a list");
-            const inEffect = rules.map((r) => {
-                const { list, rule } = stringFields(r, ["list", "rule"]);
-                if (!PERMISSION_LISTS.includes(list))
-                    throw new RequestError(400, "a rule needs a list: allow, ask or deny");
-                return { list: list, rule };
-            });
-            return readUsage(env, path, inEffect, { signal: stopOnClose(res) });
+            const { path, rules } = checked(usageBody, body);
+            return core.readUsage(path, rules, { signal: stopOnClose(res) });
         }),
         post("/api/memory/preview", async ({ body }) => {
-            const { action, path } = stringFields(body, ["action", "path"]);
+            const { action, path } = checked(memoryBody, body);
             if (!isMemoryAction(action))
                 throw new RequestError(400, "unknown memory action");
-            return previewMemoryChange(env, action, path);
+            return core.previewMemoryChange(action, path);
         }),
         post("/api/memory/change", async ({ body }) => {
-            const { action, path, revision } = stringFields(body, ["action", "path", "revision"]);
+            const { action, path } = checked(memoryBody, body);
             if (!isMemoryAction(action))
                 throw new RequestError(400, "unknown memory action");
-            return changeMemory(env, action, path, revision);
+            return core.changeMemory(action, path, revision(body));
         }),
         post("/api/open", async ({ body }) => {
-            const { path } = stringFields(body, ["path"]);
+            const { path } = checked(openBody, body);
             if (!isAbsolute(path))
-                throw new RequestError(400, "an absolute path is required");
-            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 { editor: await (options.openFile ?? openInEditor)(path) };
+                throw new RequestError(400, "path must be an absolute path");
+            return { editor: await core.openFile(path) };
         }),
-        post("/api/settings/preview", async ({ body }) => previewSettingsEdit(env, settingsEditFrom(body))),
-        post("/api/settings/save", async ({ body }) => saveSettingsEdit(env, settingsEditFrom(body), revision(body))),
-        post("/api/permissions/preview", async ({ body }) => previewPermissionEdit(env, permissionEditFrom(body))),
-        post("/api/permissions/save", async ({ body }) => savePermissionEdit(env, permissionEditFrom(body), revision(body))),
-        post("/api/hooks/preview", async ({ body }) => previewHookEdit(env, hookEditFrom(body))),
-        post("/api/hooks/save", async ({ body }) => saveHookEdit(env, hookEditFrom(body), revision(body))),
-        post("/api/agents/preview", async ({ body }) => previewAgentEdit(env, agentEditFrom(body))),
-        post("/api/agents/save", async ({ body }) => saveAgentEdit(env, agentEditFrom(body), revision(body))),
-        post("/api/mcp/preview", async ({ body }) => previewMcpEdit(env, mcpEditFrom(body), run)),
-        post("/api/mcp/save", async ({ body }) => saveMcpEdit(env, mcpEditFrom(body), revision(body), run)),
+        post("/api/settings/preview", async ({ body }) => core.previewSettingsEdit(parseSettingsEdit(body))),
+        post("/api/settings/save", async ({ body }) => core.saveSettingsEdit(parseSettingsEdit(body), revision(body))),
+        post("/api/permissions/preview", async ({ body }) => core.previewPermissionEdit(parsePermissionEdit(body))),
+        post("/api/permissions/save", async ({ body }) => core.savePermissionEdit(parsePermissionEdit(body), revision(body))),
+        post("/api/hooks/preview", async ({ body }) => core.previewHookEdit(parseHookEdit(body))),
+        post("/api/hooks/save", async ({ body }) => core.saveHookEdit(parseHookEdit(body), revision(body))),
+        post("/api/agents/preview", async ({ body }) => core.previewAgentEdit(parseAgentEdit(body))),
+        post("/api/agents/save", async ({ body }) => core.saveAgentEdit(parseAgentEdit(body), revision(body))),
+        post("/api/mcp/preview", async ({ body }) => core.previewMcpEdit(parseMcpEdit(body))),
+        post("/api/mcp/save", async ({ body }) => core.saveMcpEdit(parseMcpEdit(body), revision(body))),
         get("/api/watch", async ({ url, res }) => {
-            const dir = url.searchParams.get("dir");
+            const dir = absoluteParam(url, "dir");
             const since = Number(url.searchParams.get("since") ?? "0");
-            if (!dir || !isAbsolute(dir) || !Number.isInteger(since))
-                throw new RequestError(400, "dir is required");
+            if (!Number.isInteger(since))
+                throw new RequestError(400, "since must be a whole number");
             return watcher.wait(resolve(dir), since, stopOnClose(res));
         }),
-        get("/api/compare", async ({ url }) => {
-            const a = url.searchParams.get("a");
-            const b = url.searchParams.get("b");
-            if (!a || !b || !isAbsolute(a) || !isAbsolute(b))
-                throw new RequestError(400, "a and b must be absolute paths");
-            return compareSettings(env, a, b);
-        }),
-        get("/api/path-test", async ({ url }) => {
-            const dir = url.searchParams.get("dir");
-            const file = url.searchParams.get("file");
-            if (!dir || !isAbsolute(dir) || !file)
-                throw new RequestError(400, "dir and file are required");
-            return testPath(env, dir, file, (cwd) => watcher.view(cwd));
-        }),
+        get("/api/compare", async ({ url }) => core.compareSettings(absoluteParam(url, "a"), absoluteParam(url, "b"))),
+        get("/api/path-test", async ({ url }) => core.testPath(absoluteParam(url, "dir"), param(url, "file"), (cwd) => watcher.view(cwd))),
         get("/api/backups", async ({ url }) => {
             const before = url.searchParams.get("before") ?? undefined;
             const limit = Number(url.searchParams.get("limit") ?? "50");
             if (!Number.isInteger(limit) || limit < 1 || limit > 200)
                 throw new RequestError(400, "limit must be 1 to 200");
-            return listBackups(env, { ...(before ? { before } : {}), limit });
-        }),
-        post("/api/backups/preview", async ({ body }) => previewRestore(env, stringFields(body, ["id"]).id)),
-        post("/api/backups/restore", async ({ body }) => {
-            const { id, revision } = stringFields(body, ["id", "revision"]);
-            return restoreBackup(env, id, revision);
+            return core.listBackups({ ...(before ? { before } : {}), limit });
         }),
+        post("/api/backups/preview", async ({ body }) => core.previewRestore(checked(backupBody, body).id)),
+        post("/api/backups/restore", async ({ body }) => core.restoreBackup(checked(backupBody, body).id, revision(body))),
     ];
 }
 /**
@@ -201,111 +189,6 @@ async function handle(options, table, server, req, res) {
     const body = route.method === "POST" ? await readBody(req) : undefined;
     return send(res, 200, await route.action({ url, body, res }));
 }
-/** The named string fields of a JSON body; anything else is a 400. */
-function stringFields(body, names) {
-    if (!isRecord(body) || names.some((n) => typeof body[n] !== "string"))
-        throw new RequestError(400, `${names.join(", ")} ${names.length === 1 ? "is" : "are"} required`);
-    return body;
-}
-function settingsEditFrom(body) {
-    const { dir, scope, key } = stringFields(body, ["dir", "scope", "key"]);
-    if (!EVERY_FILE.includes(scope))
-        throw new RequestError(400, "unknown scope");
-    const value = body.value;
-    return { dir, scope: scope, key, ...(value === undefined ? {} : { value }) };
-}
-function permissionEditFrom(body) {
-    const { dir, file } = stringFields(body, ["dir", "file"]);
-    const rule = (value) => {
-        if (value === undefined)
-            return undefined;
-        const { list, rule } = stringFields(value, ["list", "rule"]);
-        if (!PERMISSION_LISTS.includes(list) || rule.trim() === "")
-            throw new RequestError(400, "a rule needs a list (allow, ask or deny) and text");
-        return { list: list, rule };
-    };
-    const { remove, add } = body;
-    const edit = { dir, file };
-    const removed = rule(remove);
-    const added = rule(add);
-    if (removed)
-        edit.remove = removed;
-    if (added)
-        edit.add = added;
-    if (!removed && !added)
-        throw new RequestError(400, "remove or add is required");
-    return edit;
-}
-function hookEditFrom(body) {
-    const { dir, file } = stringFields(body, ["dir", "file"]);
-    const { remove, add } = body;
-    const edit = { dir, file };
-    if (remove !== undefined) {
-        const { event } = stringFields(remove, ["event"]);
-        const { at, definition } = remove;
-        const index = (n) => (Number.isInteger(n) && n >= 0 ? n : -1);
-        const group = isRecord(at) ? index(at.group) : -1;
-        const hook = isRecord(at) ? index(at.index) : -1;
-        if (group < 0 || hook < 0)
-            throw new RequestError(400, "remove needs the hook's place");
-        edit.remove = { event, at: { group, index: hook }, definition };
-    }
-    if (add !== undefined) {
-        const { event } = stringFields(add, ["event"]);
-        if (!HOOK_EVENTS.includes(event))
-            throw new RequestError(400, `${event} is not a hook event Claude Code knows`);
-        const { matcher, definition } = add;
-        if (matcher !== undefined && typeof matcher !== "string")
-            throw new RequestError(400, "matcher must be text");
-        if (!isRecord(definition))
-            throw new RequestError(400, "a hook must be a JSON object");
-        edit.add = { event, ...(matcher ? { matcher } : {}), definition };
-    }
-    if (!edit.remove && !edit.add)
-        throw new RequestError(400, "remove or add is required");
-    return edit;
-}
-function agentEditFrom(body) {
-    const { dir } = stringFields(body, ["dir"]);
-    const { path, create, text } = body;
-    if (text !== null && typeof text !== "string")
-        throw new RequestError(400, "text must be the agent file, or null to delete it");
-    const edit = { dir, text };
-    if (typeof path === "string")
-        edit.path = path;
-    else if (create !== undefined) {
-        const { scope, file } = stringFields(create, ["scope", "file"]);
-        if (scope !== "user" && scope !== "project")
-            throw new RequestError(400, "a new agent goes in user or project scope");
-        if (text === null)
-            throw new RequestError(400, "a new agent needs its text");
-        edit.create = { scope, file };
-    }
-    else
-        throw new RequestError(400, "path or create is required");
-    return edit;
-}
-function mcpEditFrom(body) {
-    const { dir, scope } = stringFields(body, ["dir", "scope"]);
-    if (scope !== "user" && scope !== "local" && scope !== "project")
-        throw new RequestError(400, "scope must be user, local or project");
-    const { remove, add } = body;
-    const edit = { dir, scope };
-    if (remove !== undefined) {
-        const { name } = stringFields(remove, ["name"]);
-        edit.remove = { name, definition: remove.definition };
-    }
-    if (add !== undefined) {
-        const { name } = stringFields(add, ["name"]);
-        const { definition } = add;
-        if (!isRecord(definition))
-            throw new RequestError(400, "a server must be a JSON object");
-        edit.add = { name, definition };
-    }
-    if (!edit.remove && !edit.add)
-        throw new RequestError(400, "remove or add is required");
-    return edit;
-}
 const MAX_BODY = 64 * 1024;
 async function readBody(req) {
     if (!(req.headers["content-type"] ?? "").startsWith("application/json"))
@@ -313,10 +196,12 @@ async function readBody(req) {
     const chunks = [];
     let size = 0;
     for await (const chunk of req) {
-        size += chunk.length;
+        // A request without setEncoding yields Buffers.
+        const piece = chunk;
+        size += piece.length;
         if (size > MAX_BODY)
             throw new RequestError(413, "Request too large");
-        chunks.push(chunk);
+        chunks.push(piece);
     }
     try {
         return JSON.parse(Buffer.concat(chunks).toString("utf8"));
@@ -342,7 +227,7 @@ async function serveStatic(uiDir, pathname, res) {
     const file = await readFile(target).catch(() => null);
     // Unknown paths fall back to the app shell so client-side routes reload correctly.
     const body = file ?? (await readFile(join(uiDir, "index.html")));
-    const type = file ? (MIME[extname(target)] ?? "application/octet-stream") : MIME[".html"];
+    const type = file ? (MIME[extname(target)] ?? "application/octet-stream") : HTML;
     res.writeHead(200, { ...SECURITY_HEADERS, "Content-Type": type });
     res.end(body);
 }

package/dist/server/start.d.ts

@@ -0,0 +1,13 @@
+import { type ServerOptions } from "./server.ts";
+export interface StartOptions extends ServerOptions {
+    /** 0 picks a free port. */
+    port: number;
+}
+export interface RunningServer {
+    /** The page's address on 127.0.0.1, with the token in its fragment. */
+    url: string;
+    /** Stops listening and drops open connections, such as a browser tab's. */
+    close: () => Promise<void>;
+}
+/** Serves `options.core` on 127.0.0.1; rejects when it cannot listen, such as on a port in use. */
+export declare function startServer(options: StartOptions): Promise<RunningServer>;

package/dist/server/start.js

@@ -0,0 +1,21 @@
+import {} from "node:net";
+import { createCcdeskServer } from "./server.js";
+/** Serves `options.core` on 127.0.0.1; rejects when it cannot listen, such as on a port in use. */
+export function startServer(options) {
+    const server = createCcdeskServer(options);
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, "127.0.0.1", () => {
+            server.off("error", reject);
+            const { port } = server.address();
+            resolve({
+                url: `http://127.0.0.1:${port}/#token=${options.token}`,
+                close: () => new Promise((closed, failed) => {
+                    server.close((error) => (error ? failed(error) : closed()));
+                    // An open browser tab keeps a connection alive, which would hold close() open.
+                    server.closeAllConnections();
+                }),
+            });
+        });
+    });
+}

package/dist/shared/compare.d.ts

@@ -0,0 +1,25 @@
+import { type Scope } from "./types.ts";
+/** The value a key has in one directory, and the settings files it comes from. */
+export interface ComparedValue {
+    /** As ccdesk shows it, with hidden values as •••. */
+    value: unknown;
+    /** The files that decide it, lowest precedence first; several when lists or objects are combined. */
+    sources: Array<{
+        scope: Scope;
+        path: string;
+    }>;
+}
+export interface ComparedSetting {
+    key: string;
+    /** Null where no settings file Claude Code reads there sets the key. */
+    a: ComparedValue | null;
+    b: ComparedValue | null;
+    /** Whether both have the same value as ccdesk shows it; two hidden values count as the same. */
+    same: boolean;
+}
+/** The effective settings of two directories, key by key. */
+export interface SettingsComparison {
+    a: string;
+    b: string;
+    settings: ComparedSetting[];
+}

package/dist/shared/memory.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Claude Code names a project's store after its path with every non-alphanumeric character as "-".
+ * A name over 200 characters is cut there and ends with "-" and a hash of the whole path, so deep
+ * paths that share a start get different stores (observed in the SDK 0.3.296; the docs do not say).
+ */
+export declare function storeDirName(projectPath: string): string;

package/dist/shared/memory.js

@@ -1,4 +1,20 @@
-/** Claude Code names a project's store after its path with every non-alphanumeric character as "-". */
+/** Longest store name Claude Code keeps as it is; a longer one is cut and given a hash of the path. */
+const MAX_STORE_NAME = 200;
+/**
+ * Claude Code names a project's store after its path with every non-alphanumeric character as "-".
+ * A name over 200 characters is cut there and ends with "-" and a hash of the whole path, so deep
+ * paths that share a start get different stores (observed in the SDK 0.3.296; the docs do not say).
+ */
 export function storeDirName(projectPath) {
-    return projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+    const name = projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+    if (name.length <= MAX_STORE_NAME)
+        return name;
+    return `${name.slice(0, MAX_STORE_NAME)}-${Math.abs(pathHash(projectPath)).toString(36)}`;
+}
+/** Java's 32-bit string hash, over UTF-16 code units, as Claude Code computes it. */
+function pathHash(text) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++)
+        hash = ((hash << 5) - hash + text.charCodeAt(i)) | 0;
+    return hash;
 }

package/dist/shared/requests.d.ts

@@ -0,0 +1,104 @@
+import { type Static, Type } from "typebox";
+/** Set one top-level key in one settings file; `value` undefined removes the key. */
+export declare const SettingsEditBody: Type.TObject<{
+    dir: Type.TString;
+    scope: Type.TEnum<import("./types.ts").Scope[]>;
+    key: Type.TString;
+    value: Type.TOptional<Type.TUnknown>;
+}>;
+export type SettingsEdit = Static<typeof SettingsEditBody>;
+/** Take one permission rule out of its list and/or add one, in one settings file. */
+export declare const PermissionEditBody: Type.TObject<{
+    dir: Type.TString;
+    file: Type.TString;
+    remove: Type.TOptional<Type.TObject<{
+        list: Type.TEnum<import("./types.ts").PermissionList[]>;
+        rule: Type.TString;
+    }>>;
+    add: Type.TOptional<Type.TObject<{
+        list: Type.TEnum<import("./types.ts").PermissionList[]>;
+        rule: Type.TString;
+    }>>;
+}>;
+export type PermissionEdit = Static<typeof PermissionEditBody>;
+/**
+ * One hook change to a settings file. With both, the hook is replaced in place when it stays in
+ * the same event and matcher, and moved otherwise.
+ */
+export declare const HookEditBody: Type.TObject<{
+    dir: Type.TString;
+    file: Type.TString;
+    /** The hook to take out, as the scan showed it; refused when the file no longer has it there. */
+    remove: Type.TOptional<Type.TObject<{
+        event: Type.TString;
+        at: Type.TObject<{
+            group: Type.TInteger;
+            index: Type.TInteger;
+        }>;
+        definition: Type.TUnknown;
+    }>>;
+    /** The hook to write: the matcher group it goes in, and the hook itself. */
+    add: Type.TOptional<Type.TObject<{
+        event: Type.TString;
+        /** Empty or absent for a group without a matcher, which matches everything. */
+        matcher: Type.TOptional<Type.TString>;
+        definition: Type.TUnknown;
+    }>>;
+}>;
+export type HookEdit = Static<typeof HookEditBody>;
+/** One subagent file change: a new agent, a changed one, or one deleted. */
+export declare const AgentEditBody: Type.TObject<{
+    dir: Type.TString;
+    /** An agent the scan shows here; absent when creating one. */
+    path: Type.TOptional<Type.TString>;
+    /** Where a new agent goes, and its file name without .md. */
+    create: Type.TOptional<Type.TObject<{
+        scope: Type.TEnum<["user", "project"]>;
+        file: Type.TString;
+    }>>;
+    /** The whole file; null deletes the agent. */
+    text: Type.TUnion<[Type.TString, Type.TNull]>;
+}>;
+export type AgentEdit = Static<typeof AgentEditBody>;
+/**
+ * One MCP server change. Project servers are changed in .mcp.json; user and local ones through
+ * `claude mcp`. With both, the server is replaced, keeping its place in .mcp.json.
+ */
+export declare const McpEditBody: Type.TObject<{
+    dir: Type.TString;
+    scope: Type.TEnum<["user", "local", "project"]>;
+    /** The server to take out, as the scan showed it; refused when it changed since. */
+    remove: Type.TOptional<Type.TObject<{
+        name: Type.TString;
+        definition: Type.TUnknown;
+    }>>;
+    add: Type.TOptional<Type.TObject<{
+        name: Type.TString;
+        definition: Type.TUnknown;
+    }>>;
+}>;
+export type McpEdit = Static<typeof McpEditBody>;
+/** A save's or restore's revision: the one its preview returned. */
+export declare const RevisionBody: Type.TObject<{
+    revision: Type.TString;
+}>;
+/** Count which permission rules the transcripts under `path` used. */
+export declare const UsageBody: Type.TObject<{
+    path: Type.TString;
+    rules: Type.TArray<Type.TObject<{
+        list: Type.TEnum<import("./types.ts").PermissionList[]>;
+        rule: Type.TString;
+    }>>;
+}>;
+/** Preview a memory change; changing it also sends the revision. */
+export declare const MemoryBody: Type.TObject<{
+    action: Type.TString;
+    path: Type.TString;
+}>;
+export declare const OpenBody: Type.TObject<{
+    path: Type.TString;
+}>;
+/** Preview restoring a backup; restoring it also sends the revision. */
+export declare const BackupBody: Type.TObject<{
+    id: Type.TString;
+}>;

package/dist/shared/requests.js

@@ -0,0 +1,73 @@
+// What each API request sends, as JSON Schema. The server checks bodies against these, and each
+// type is read from its schema. The page imports only the types, re-exported from types.ts, so
+// TypeBox stays out of its bundle.
+import { Type } from "typebox";
+import { EVERY_FILE, PERMISSION_LISTS } from "./scopes.js";
+/** Set one top-level key in one settings file; `value` undefined removes the key. */
+export const SettingsEditBody = Type.Object({
+    dir: Type.String(),
+    scope: Type.Enum(EVERY_FILE),
+    key: Type.String(),
+    value: Type.Optional(Type.Unknown()),
+});
+/** One permission rule. */
+const Rule = Type.Object({ list: Type.Enum(PERMISSION_LISTS), rule: Type.String() });
+/** Take one permission rule out of its list and/or add one, in one settings file. */
+export const PermissionEditBody = Type.Object({
+    dir: Type.String(),
+    file: Type.String(),
+    remove: Type.Optional(Rule),
+    add: Type.Optional(Rule),
+});
+const place = Type.Integer({ minimum: 0 });
+/**
+ * One hook change to a settings file. With both, the hook is replaced in place when it stays in
+ * the same event and matcher, and moved otherwise.
+ */
+export const HookEditBody = Type.Object({
+    dir: Type.String(),
+    file: Type.String(),
+    /** The hook to take out, as the scan showed it; refused when the file no longer has it there. */
+    remove: Type.Optional(Type.Object({
+        event: Type.String(),
+        at: Type.Object({ group: place, index: place }),
+        definition: Type.Unknown(),
+    })),
+    /** The hook to write: the matcher group it goes in, and the hook itself. */
+    add: Type.Optional(Type.Object({
+        event: Type.String(),
+        /** Empty or absent for a group without a matcher, which matches everything. */
+        matcher: Type.Optional(Type.String()),
+        definition: Type.Unknown(),
+    })),
+});
+/** One subagent file change: a new agent, a changed one, or one deleted. */
+export const AgentEditBody = Type.Object({
+    dir: Type.String(),
+    /** An agent the scan shows here; absent when creating one. */
+    path: Type.Optional(Type.String()),
+    /** Where a new agent goes, and its file name without .md. */
+    create: Type.Optional(Type.Object({ scope: Type.Enum(["user", "project"]), file: Type.String() })),
+    /** The whole file; null deletes the agent. */
+    text: Type.Union([Type.String(), Type.Null()]),
+});
+/**
+ * One MCP server change. Project servers are changed in .mcp.json; user and local ones through
+ * `claude mcp`. With both, the server is replaced, keeping its place in .mcp.json.
+ */
+export const McpEditBody = Type.Object({
+    dir: Type.String(),
+    scope: Type.Enum(["user", "local", "project"]),
+    /** The server to take out, as the scan showed it; refused when it changed since. */
+    remove: Type.Optional(Type.Object({ name: Type.String(), definition: Type.Unknown() })),
+    add: Type.Optional(Type.Object({ name: Type.String(), definition: Type.Unknown() })),
+});
+/** A save's or restore's revision: the one its preview returned. */
+export const RevisionBody = Type.Object({ revision: Type.String() });
+/** Count which permission rules the transcripts under `path` used. */
+export const UsageBody = Type.Object({ path: Type.String(), rules: Type.Array(Rule) });
+/** Preview a memory change; changing it also sends the revision. */
+export const MemoryBody = Type.Object({ action: Type.String(), path: Type.String() });
+export const OpenBody = Type.Object({ path: Type.String() });
+/** Preview restoring a backup; restoring it also sends the revision. */
+export const BackupBody = Type.Object({ id: Type.String() });

package/dist/shared/scopes.d.ts

@@ -0,0 +1,10 @@
+import { type PermissionList, type Scope } from "./types.ts";
+export declare const EVERY_FILE: Scope[];
+/** Settings files by precedence: managed beats local beats project beats user. */
+export declare const HIGHEST_FIRST: Scope[];
+/** The settings files ccdesk writes to; managed settings belong to your organisation. */
+export declare const EDITABLE_SCOPES: Scope[];
+/** The permission lists, in the order ccdesk shows them. */
+export declare const PERMISSION_LISTS: PermissionList[];
+export declare function allowedScopes(key: string): Scope[];
+export declare function ignoredReason(key: string): string;