ccdesk 0.2.1 → 0.2.3

package/dist/server/cli.js

@@ -1,105 +1,80 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { statSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
-import { scanEnvFromProcess } from "./scan/env.js";
-import { createCcdeskServer } from "./server.js";
-const HELP = `ccdesk: see and change what Claude Code loads on this machine
-
-Usage: npx ccdesk [options]
-
-Options:
-  --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)
-  -h, --help            Show this help
-
-ccdesk reads ~/.claude (or --config-dir, or $CLAUDE_CONFIG_DIR) and opens on the directory you
-run it from.
-It listens on 127.0.0.1 only.`;
-const DEV_PORT = 4319;
+import { createCore } from "../core/core.js";
+import { HELP, parse, UsageError } from "./args.js";
+import { explainText, scanJson } from "./commands.js";
+import { openBrowser } from "../core/open.js";
+import { scanEnvFromProcess } from "../core/scan/env.js";
 const DEV_TOKEN = "dev";
-function options() {
+function isFolder(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+}
+async function main() {
+    let command;
     try {
-        return parseArgs({
-            options: {
-                port: { type: "string" },
-                "config-dir": { type: "string" },
-                open: { type: "boolean", default: true },
-                dev: { type: "boolean", default: false },
-                help: { type: "boolean", short: "h", default: false },
-            },
-            allowNegative: true,
-        }).values;
+        command = parse(process.argv.slice(2));
     }
     catch (error) {
-        console.error(`ccdesk: ${error.message}\n\n${HELP}`);
-        process.exit(2);
+        if (!(error instanceof UsageError))
+            throw error;
+        console.error(error.message);
+        process.exitCode = 2;
+        return;
     }
-}
-function main() {
-    const values = options();
-    if (values.help) {
+    if (command.command === "help") {
         console.log(HELP);
         return;
     }
-    const dev = values.dev;
-    const port = values.port ? Number(values.port) : dev ? DEV_PORT : 0;
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-        console.error(`ccdesk: invalid --port ${values.port}`);
+    const { configDir } = command;
+    if (configDir !== undefined && !isFolder(configDir)) {
+        console.error(`ccdesk: --config-dir ${configDir} is not a folder`);
         process.exitCode = 2;
         return;
     }
-    const configDir = values["config-dir"];
-    if (configDir !== undefined && !statSync(configDir, { throwIfNoEntry: false })?.isDirectory()) {
-        console.error(`ccdesk: --config-dir ${configDir} is not a folder`);
+    const core = createCore(scanEnvFromProcess(configDir));
+    if (command.command === "serve")
+        return serve(core, command);
+    const dir = resolve(command.dir ?? ".");
+    if (!isFolder(dir)) {
+        console.error(`ccdesk: ${command.dir} is not a folder`);
         process.exitCode = 2;
         return;
     }
-    const token = dev ? DEV_TOKEN : randomBytes(18).toString("base64url");
-    const server = createCcdeskServer({
-        env: scanEnvFromProcess(configDir),
-        launchDir: process.cwd(),
-        token,
-        uiDir: dev ? null : fileURLToPath(new URL("../ui", import.meta.url)),
-    });
-    server.on("error", (error) => {
-        console.error(error.code === "EADDRINUSE"
-            ? `ccdesk: port ${port} is already in use`
-            : `ccdesk: ${error.message}`);
+    console.log(command.command === "scan"
+        ? await scanJson(core, dir)
+        : await explainText(core, dir, resolve(command.file)));
+}
+async function serve(core, { dev, port, open }) {
+    // Loaded here so that the subcommands, which only read, never load the HTTP server.
+    const { startServer } = await import("./start.js");
+    let server;
+    try {
+        server = await startServer({
+            core,
+            launchDir: process.cwd(),
+            token: dev ? DEV_TOKEN : randomBytes(18).toString("base64url"),
+            uiDir: dev ? null : fileURLToPath(new URL("../ui", import.meta.url)),
+            port,
+        });
+    }
+    catch (error) {
+        const { code, message } = error;
+        console.error(code === "EADDRINUSE" ? `ccdesk: port ${port} is already in use` : `ccdesk: ${message}`);
         process.exitCode = 1;
-    });
-    server.listen(port, "127.0.0.1", () => {
-        const address = server.address();
-        const actual = typeof address === "object" && address ? address.port : port;
-        if (dev) {
-            console.log(`ccdesk API on http://127.0.0.1:${actual} (dev token "${DEV_TOKEN}"); run \`pnpm dev:ui\` for the UI`);
-            return;
-        }
-        const url = `http://127.0.0.1:${actual}/#token=${token}`;
-        console.log(`ccdesk is running at ${url}\nPress Ctrl+C to stop.`);
-        if (values.open)
-            openBrowser(url);
-    });
-    const stop = () => {
-        // An open browser tab keeps a connection alive, which would hold close() open.
-        server.close(() => process.exit(0));
-        server.closeAllConnections();
-    };
+        return;
+    }
+    const stop = () => server.close().finally(() => process.exit(0));
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    if (dev) {
+        console.log(`ccdesk API on ${new URL(server.url).origin} (dev token "${DEV_TOKEN}"); run \`pnpm dev:ui\` for the UI`);
+        return;
+    }
+    console.log(`ccdesk is running at ${server.url}\nPress Ctrl+C to stop.`);
+    if (open && (await openBrowser(server.url, core.env)) !== null)
+        console.log("Could not open a browser; open the URL above.");
 }
-function openBrowser(url) {
-    const [command, args] = process.platform === "darwin"
-        ? ["open", [url]]
-        : process.platform === "win32"
-            ? ["cmd", ["/c", "start", "", url]]
-            : ["xdg-open", [url]];
-    const child = spawn(command, args, { stdio: "ignore", detached: true });
-    child.on("error", () => console.log("Could not open a browser; open the URL above."));
-    child.unref();
-}
-main();
+await main();

package/dist/server/commands.d.ts

@@ -0,0 +1,8 @@
+import { type Core } from "../core/index.ts";
+/** `ccdesk scan --json`: the DirectoryView the page gets for `dir`. */
+export declare function scanJson(core: Core, dir: string): Promise<string>;
+/**
+ * `ccdesk explain`: what joins a session started in `dir` once Claude reads or edits `file`, as the
+ * page's path test lists it. Both paths are absolute.
+ */
+export declare function explainText(core: Core, dir: string, file: string): Promise<string>;

package/dist/server/commands.js

@@ -0,0 +1,39 @@
+import {} from "../core/index.js";
+import { formatter, MATCH_KIND } from "../view/index.js";
+// The subcommands of `ccdesk`. They only read, through the core, and print what the page would
+// show: the scan is already redacted, so no value the page hides reaches the terminal.
+/** `ccdesk scan --json`: the DirectoryView the page gets for `dir`. */
+export async function scanJson(core, dir) {
+    return JSON.stringify(await core.scanDirectory(dir), null, 2);
+}
+/**
+ * `ccdesk explain`: what joins a session started in `dir` once Claude reads or edits `file`, as the
+ * page's path test lists it. Both paths are absolute.
+ */
+export async function explainText(core, dir, file) {
+    const { tilde, relativeTo } = formatter(core.env.home);
+    const result = await core.testPath(dir, file);
+    if (!result.inside)
+        return `${tilde(result.file)} is outside ${tilde(dir)}, so nothing there applies to it.`;
+    const name = relativeTo(result.file, dir);
+    const note = result.exists ? "" : " (the file does not exist yet; paths are checked anyway)";
+    if (result.matches.length === 0)
+        return `Nothing more loads for ${name}${note}.`;
+    const shownName = (m) => m.name ?? relativeTo(m.path, dir);
+    const width = (cells) => Math.max(...cells.map((cell) => cell.length));
+    const scopeWidth = width(result.matches.map((m) => m.scope));
+    const kindWidth = width(result.matches.map((m) => MATCH_KIND[m.kind]));
+    const nameWidth = width(result.matches.map(shownName));
+    return [
+        `Once Claude reads or edits ${name} in ${tilde(dir)}${note}, these load:`,
+        ...result.matches.map((m) => [
+            "",
+            m.scope.padEnd(scopeWidth),
+            MATCH_KIND[m.kind].padEnd(kindWidth),
+            shownName(m).padEnd(nameWidth),
+            m.glob ? `matches ${m.glob}` : "",
+        ]
+            .join("  ")
+            .trimEnd()),
+    ].join("\n");
+}

package/dist/server/server.d.ts

@@ -0,0 +1,12 @@
+import { type Server } from "node:http";
+import { type Core } from "../core/core.ts";
+export interface ServerOptions {
+    /** What the routes read and change; tests make one with fakes so nothing is launched. */
+    core: Core;
+    launchDir: string;
+    /** Required on every API request; the browser gets it once, in the URL fragment. */
+    token: string;
+    /** Built UI directory; null serves the API only (the Vite dev server serves the UI). */
+    uiDir: string | null;
+}
+export declare function createCcdeskServer(options: ServerOptions): Server;

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