ccdesk 0.1.0 → 0.2.1

package/dist/server/server.js

@@ -1,18 +1,23 @@
 import { readFile, stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { extname, isAbsolute, join, normalize, resolve, sep } from "node:path";
-import {} from "../shared/types.js";
+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 { isRecord } from "./scan/files.js";
-import { scanDirectory, scanOverview } from "./scan/index.js";
-import { readUsage } from "./scan/usage.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 { previewPermissionEdit, previewSettingsEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
+import { previewHookEdit, previewPermissionEdit, previewSettingsEdit, saveHookEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
 import { Watcher } from "./watch.js";
-import { isCredentials, RefusedError } from "./write.js";
+import { RefusedError } from "./write.js";
 const MIME = {
     ".html": "text/html; charset=utf-8",
     ".js": "text/javascript; charset=utf-8",
@@ -38,17 +43,141 @@ class RequestError extends Error {
 }
 export function createCcdeskServer(options) {
     const watcher = new Watcher(options.env);
+    const table = routes(options, watcher);
     const server = createServer((req, res) => {
-        handle(options, watcher, server, req, res).catch((error) => {
-            if (error instanceof RequestError)
-                return send(res, error.status, { error: error.message });
-            send(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        handle(options, table, server, req, res).catch((error) => {
+            const [status, message] = failure(error);
+            send(res, status, { error: message });
         });
     });
     server.on("close", () => watcher.close());
     return server;
 }
-async function handle(options, watcher, server, req, res) {
+/** The status and message an API request that failed is answered with. */
+function failure(error) {
+    if (error instanceof RequestError)
+        return [error.status, error.message];
+    // A change ccdesk refuses on purpose.
+    if (error instanceof RefusedError)
+        return [409, error.message];
+    if (error instanceof CountStopped)
+        return [503, error.message];
+    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`) {
+    const value = url.searchParams.get(name);
+    if (!value)
+        throw new RequestError(400, message);
+    return value;
+}
+/** 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;
+    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/directory", ({ url }) => {
+            const profile = url.searchParams.get("profile") ?? "interactive";
+            if (!SESSION_PROFILES.includes(profile))
+                throw new RequestError(400, `profile is one of ${SESSION_PROFILES.join(", ")}`);
+            return watcher.scan(param(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) });
+        }),
+        post("/api/memory/preview", async ({ body }) => {
+            const { action, path } = stringFields(body, ["action", "path"]);
+            if (!isMemoryAction(action))
+                throw new RequestError(400, "unknown memory action");
+            return previewMemoryChange(env, action, path);
+        }),
+        post("/api/memory/change", async ({ body }) => {
+            const { action, path, revision } = stringFields(body, ["action", "path", "revision"]);
+            if (!isMemoryAction(action))
+                throw new RequestError(400, "unknown memory action");
+            return changeMemory(env, action, path, revision);
+        }),
+        post("/api/open", async ({ body }) => {
+            const { path } = stringFields(body, ["path"]);
+            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) };
+        }),
+        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)),
+        get("/api/watch", async ({ url, res }) => {
+            const dir = url.searchParams.get("dir");
+            const since = Number(url.searchParams.get("since") ?? "0");
+            if (!dir || !isAbsolute(dir) || !Number.isInteger(since))
+                throw new RequestError(400, "dir is required");
+            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/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);
+        }),
+    ];
+}
+/**
+ * Every request passes the same checks before its route runs: the Host header, then for the API
+ * the token, the Origin of anything but a GET, and a POST's body. Failures are answered by
+ * `failure`.
+ */
+async function handle(options, table, server, req, res) {
     const address = server.address();
     const port = typeof address === "object" && address ? address.port : 0;
     // Reject DNS-rebinding requests: only our own loopback origin may talk to this server.
@@ -66,123 +195,21 @@ async function handle(options, watcher, server, req, res) {
         !allowedHosts.some((h) => origin === `http://${h}`)) {
         return send(res, 403, { error: "Cross-origin request refused" });
     }
-    const { env, launchDir } = options;
-    if (req.method === "GET" && url.pathname === "/api/overview") {
-        return send(res, 200, await scanOverview(env, launchDir));
-    }
-    if (req.method === "GET" && url.pathname === "/api/directory") {
-        const path = url.searchParams.get("path");
-        if (!path)
-            return send(res, 400, { error: "path is required" });
-        const view = await scanDirectory(env, path);
-        watcher.track(view.path, view);
-        return send(res, 200, view);
-    }
-    if (req.method === "POST" && url.pathname === "/api/usage") {
-        const body = await readBody(req);
-        const { path } = stringFields(body, ["path"]);
-        const rules = body.rules;
-        if (!Array.isArray(rules))
-            return send(res, 400, { error: "rules must be a list" });
-        return send(res, 200, await readUsage(env, path, rules.map((r) => {
-            const { list, rule } = stringFields(r, ["list", "rule"]);
-            if (!LISTS.includes(list))
-                throw new RequestError(400, "a rule needs a list: allow, ask or deny");
-            return { list: list, rule };
-        })));
-    }
-    if (req.method === "POST" && url.pathname === "/api/memory/preview") {
-        const { action, path } = await fields(req, ["action", "path"]);
-        if (!isMemoryAction(action))
-            return send(res, 400, { error: "unknown memory action" });
-        return answer(res, () => previewMemoryChange(env, action, path));
-    }
-    if (req.method === "POST" && url.pathname === "/api/memory/change") {
-        const { action, path, revision } = await fields(req, ["action", "path", "revision"]);
-        if (!isMemoryAction(action))
-            return send(res, 400, { error: "unknown memory action" });
-        return answer(res, () => changeMemory(env, action, path, revision));
-    }
-    if (req.method === "POST" && url.pathname === "/api/open") {
-        const { path } = await fields(req, ["path"]);
-        if (!isAbsolute(path))
-            return send(res, 400, { error: "an absolute path is required" });
-        const info = await stat(path).catch(() => null);
-        if (!info?.isFile() && !info?.isDirectory())
-            return send(res, 409, { error: "That file or folder no longer exists." });
-        if (await isCredentials(env, path))
-            return send(res, 409, { error: "ccdesk does not open credentials." });
-        const open = options.openFile ?? openInEditor;
-        return answer(res, async () => ({ editor: await open(path) }));
-    }
-    if (req.method === "POST" && url.pathname === "/api/settings/preview") {
-        const edit = settingsEditFrom(await readBody(req));
-        return answer(res, () => previewSettingsEdit(env, edit));
-    }
-    if (req.method === "POST" && url.pathname === "/api/settings/save") {
-        const body = await readBody(req);
-        const edit = settingsEditFrom(body);
-        const { revision } = stringFields(body, ["revision"]);
-        return answer(res, () => saveSettingsEdit(env, edit, revision));
-    }
-    if (req.method === "POST" && url.pathname === "/api/permissions/preview") {
-        const edit = permissionEditFrom(await readBody(req));
-        return answer(res, () => previewPermissionEdit(env, edit));
-    }
-    if (req.method === "POST" && url.pathname === "/api/permissions/save") {
-        const body = await readBody(req);
-        const edit = permissionEditFrom(body);
-        const { revision } = stringFields(body, ["revision"]);
-        return answer(res, () => savePermissionEdit(env, edit, revision));
-    }
-    if (req.method === "GET" && url.pathname === "/api/watch") {
-        const dir = url.searchParams.get("dir");
-        const since = Number(url.searchParams.get("since") ?? "0");
-        if (!dir || !isAbsolute(dir) || !Number.isInteger(since))
-            return send(res, 400, { error: "dir is required" });
-        // Stop waiting when the page goes away or asks for another directory.
-        const stop = new AbortController();
-        res.once("close", () => stop.abort());
-        return send(res, 200, await watcher.wait(resolve(dir), since, stop.signal));
-    }
-    if (req.method === "GET" && url.pathname === "/api/path-test") {
-        const dir = url.searchParams.get("dir");
-        const file = url.searchParams.get("file");
-        if (!dir || !isAbsolute(dir) || !file)
-            return send(res, 400, { error: "dir and file are required" });
-        return answer(res, () => testPath(env, dir, file));
-    }
-    if (req.method === "GET" && url.pathname === "/api/backups") {
-        const before = url.searchParams.get("before") ?? undefined;
-        const limit = Number(url.searchParams.get("limit") ?? "50");
-        if (!Number.isInteger(limit) || limit < 1 || limit > 200)
-            return send(res, 400, { error: "limit must be 1 to 200" });
-        return send(res, 200, await listBackups(env, { ...(before ? { before } : {}), limit }));
-    }
-    if (req.method === "POST" && url.pathname === "/api/backups/preview") {
-        const { id } = await fields(req, ["id"]);
-        return answer(res, () => previewRestore(env, id));
-    }
-    if (req.method === "POST" && url.pathname === "/api/backups/restore") {
-        const { id, revision } = await fields(req, ["id", "revision"]);
-        return answer(res, () => restoreBackup(env, id, revision));
-    }
-    return send(res, 404, { error: "Not found" });
+    const route = table.find((r) => r.method === req.method && r.path === url.pathname);
+    if (!route)
+        return send(res, 404, { error: "Not found" });
+    const body = route.method === "POST" ? await readBody(req) : undefined;
+    return send(res, 200, await route.action({ url, body, res }));
 }
-const SCOPES = ["managed", "user", "project", "local"];
-const LISTS = ["allow", "ask", "deny"];
 /** 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;
 }
-async function fields(req, names) {
-    return stringFields(await readBody(req), names);
-}
 function settingsEditFrom(body) {
     const { dir, scope, key } = stringFields(body, ["dir", "scope", "key"]);
-    if (!SCOPES.includes(scope))
+    if (!EVERY_FILE.includes(scope))
         throw new RequestError(400, "unknown scope");
     const value = body.value;
     return { dir, scope: scope, key, ...(value === undefined ? {} : { value }) };
@@ -193,7 +220,7 @@ function permissionEditFrom(body) {
         if (value === undefined)
             return undefined;
         const { list, rule } = stringFields(value, ["list", "rule"]);
-        if (!LISTS.includes(list) || rule.trim() === "")
+        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 };
     };
@@ -209,15 +236,75 @@ function permissionEditFrom(body) {
         throw new RequestError(400, "remove or add is required");
     return edit;
 }
-async function answer(res, action) {
-    try {
-        send(res, 200, await action());
+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 };
     }
-    catch (error) {
-        if (error instanceof RefusedError)
-            return send(res, 409, { error: error.message });
-        throw error;
+    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) {
@@ -241,7 +328,14 @@ async function readBody(req) {
 async function serveStatic(uiDir, pathname, res) {
     if (!uiDir)
         return send(res, 404, { error: "UI is served by the Vite dev server" });
-    const rel = normalize(decodeURIComponent(pathname)).replace(/^[/\\]+/, "");
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return send(res, 400, { error: "Bad request" });
+    }
+    const rel = normalize(decoded).replace(/^[/\\]+/, "");
     const target = join(uiDir, rel === "" ? "index.html" : rel);
     if (!target.startsWith(uiDir + sep) && target !== uiDir)
         return send(res, 403, { error: "Forbidden" });

package/dist/server/settings-edit.js

@@ -1,14 +1,16 @@
 import { stat } from "node:fs/promises";
-import { Ajv } from "ajv";
+import {} from "ajv";
 import { allowedScopes, ignoredReason } from "../shared/scopes.js";
 import schema from "../shared/settings.schema.json" with { type: "json" };
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
 import { isRecord, jsonSyntaxError, redactSecrets, revisionOf } from "./scan/files.js";
+import { isSkippedMcpRule } from "./scan/permissions.js";
 import { settingsFiles } from "./scan/settings.js";
+import { ajv, schemaErrors } from "./schema.js";
+import { hasHiddenValues, shown } from "./secrets.js";
 import { RefusedError, readIfExists, recordChange, serially, writeAtomic } from "./write.js";
 const properties = schema.definitions.ClaudeCodeSettings.properties;
-const ajv = new Ajv({ allErrors: true, strict: false });
 const validators = new Map();
 function validatorFor(key) {
     if (!Object.hasOwn(properties, key))
@@ -20,12 +22,6 @@ function validatorFor(key) {
     }
     return validate;
 }
-function shown(data) {
-    return `${JSON.stringify(redactSecrets(data), null, 2)}\n`;
-}
-function hasHiddenValues(value) {
-    return JSON.stringify(redactSecrets(value)) !== JSON.stringify(value);
-}
 async function editableFile(env, dir, pick, missing = "That is not a settings file Claude Code reads here.") {
     const file = (await settingsFiles(env, dir)).find(pick);
     if (!file)
@@ -51,8 +47,12 @@ async function readSettings(env, path) {
         throw new RefusedError(`${path} does not hold a JSON object.`);
     return { raw, data: parsed };
 }
-/** Works out the file change that sets or removes one key, refusing what ccdesk cannot do safely. */
-async function planKey(env, file, key, value) {
+/**
+ * Works out the file change that sets or removes one key, refusing what ccdesk cannot do safely.
+ * `checksHiddenValues` is for a key whose edit checks the part it changes itself, so values it
+ * leaves alone are written back exactly as they were.
+ */
+async function planKey(env, file, key, value, checksHiddenValues = false) {
     if (!allowedScopes(key).includes(file.scope))
         throw new RefusedError(`${ignoredReason(key)}, so a ${file.scope} value would do nothing.`);
     const validate = validatorFor(key);
@@ -61,20 +61,19 @@ async function planKey(env, file, key, value) {
     const { path } = file;
     const { raw, data } = await readSettings(env, path);
     const nextValue = value(data);
-    // ccdesk never shows env or header values, so it must not write them either.
-    if (hasHiddenValues({ [key]: data[key] }) || hasHiddenValues({ [key]: nextValue }))
+    // ccdesk never shows hidden values, so it must not write them either.
+    if (!checksHiddenValues &&
+        (hasHiddenValues({ [key]: data[key] }) || hasHiddenValues({ [key]: nextValue })))
         throw new RefusedError(`${key} holds hidden values; edit it in the file instead.`);
+    if (raw !== null && JSON.stringify(nextValue) === JSON.stringify(data[key]))
+        throw new RefusedError("This file already says that; there is nothing to change.");
     const before = raw === null ? null : shown(data);
     // The diff is rendered from the parsed file, so a file in another layout is reported as
     // reformatted instead of diffing its raw text.
     const reformats = raw !== null && raw.trim() !== "" && raw !== `${JSON.stringify(data, null, 2)}\n`;
     const base = { path, before, revision: revisionOf(raw), reformats };
-    const next = { ...data };
-    if (nextValue === undefined) {
-        delete next[key];
-    }
-    else if (!validate(nextValue)) {
-        const errors = (validate.errors ?? []).map((e) => `${key}${e.instancePath.replaceAll("/", ".")} ${e.message ?? "is invalid"}`);
+    const errors = nextValue === undefined ? [] : schemaErrors(validate, nextValue, key);
+    if (errors.length > 0)
         return {
             path,
             scope: file.scope,
@@ -82,10 +81,11 @@ async function planKey(env, file, key, value) {
             next: null,
             preview: { ...base, after: before ?? "", errors },
         };
-    }
-    else {
+    const next = { ...data };
+    if (nextValue === undefined)
+        delete next[key];
+    else
         next[key] = nextValue;
-    }
     return {
         path,
         scope: file.scope,
@@ -119,6 +119,8 @@ async function planPermissionEdit(env, edit) {
                 delete permissions[remove.list];
         }
         if (add) {
+            if (isSkippedMcpRule(add.rule))
+                throw new RefusedError("Claude Code skips an MCP rule with parentheses in a settings file. To match a parameter of an MCP tool, pass a deny rule with --disallowedTools.");
             const list = Array.isArray(permissions[add.list]) ? permissions[add.list] : [];
             if (!list.includes(add.rule))
                 permissions[add.list] = [...list, add.rule];
@@ -126,6 +128,67 @@ async function planPermissionEdit(env, edit) {
         return Object.keys(permissions).length > 0 ? permissions : undefined;
     });
 }
+/** The matcher a group is written with; a missing or empty one matches everything. */
+function matcherOf(group) {
+    return isRecord(group) && typeof group.matcher === "string" ? group.matcher : "";
+}
+/** One hook taken out, replaced or added, applied to the file as it is on disk. */
+async function planHookEdit(env, edit) {
+    const file = await editableFile(env, edit.dir, (f) => f.path === edit.file);
+    return planKey(env, file, "hooks", (data) => {
+        const hooks = isRecord(data.hooks)
+            ? structuredClone(data.hooks)
+            : {};
+        const groupsOf = (event) => {
+            const groups = hooks[event];
+            return Array.isArray(groups) ? groups : [];
+        };
+        const { remove, add } = edit;
+        if (remove) {
+            const groups = groupsOf(remove.event);
+            const group = groups[remove.at.group];
+            const list = isRecord(group) && Array.isArray(group.hooks) ? group.hooks : null;
+            const hook = list?.[remove.at.index];
+            if (!list || JSON.stringify(redactSecrets(hook)) !== JSON.stringify(remove.definition))
+                throw new RefusedError("This hook changed in the file since ccdesk read it; review it again.");
+            // The page saw this hook with its header values hidden, so a changed copy would lose them.
+            if (add && hasHiddenValues(hook))
+                throw new RefusedError("This hook sends header values ccdesk does not show; edit it in the file, or remove it and add it again.");
+            const matcher = add?.matcher ?? "";
+            // A hook alone in its group keeps the group when only its matcher changes, unless another
+            // group already has that matcher.
+            const inPlace = add?.event === remove.event &&
+                (matcher === matcherOf(group) ||
+                    (list.length === 1 && !groups.some((g) => g !== group && matcherOf(g) === matcher)));
+            if (add && inPlace && isRecord(group)) {
+                list[remove.at.index] = add.definition;
+                if (matcher)
+                    group.matcher = matcher;
+                else
+                    delete group.matcher;
+                return hooks;
+            }
+            list.splice(remove.at.index, 1);
+            if (list.length === 0)
+                groups.splice(remove.at.group, 1);
+            if (groups.length === 0 && add?.event !== remove.event)
+                delete hooks[remove.event];
+        }
+        if (add) {
+            if (hasHiddenValues(add.definition))
+                throw new RefusedError("ccdesk does not write header values it would then hide; add this hook in the file instead.");
+            const groups = groupsOf(add.event);
+            const matcher = add.matcher ?? "";
+            const group = groups.find((g) => matcherOf(g) === matcher && isRecord(g) && Array.isArray(g.hooks));
+            if (isRecord(group) && Array.isArray(group.hooks))
+                group.hooks.push(add.definition);
+            else
+                groups.push({ ...(matcher ? { matcher } : {}), hooks: [add.definition] });
+            hooks[add.event] = groups;
+        }
+        return Object.keys(hooks).length > 0 ? hooks : undefined;
+    }, true);
+}
 /** Writes a planned edit, but only if the file is still the revision the preview was made from. */
 async function commit(env, plan, expectedRevision) {
     if (plan.next === null)
@@ -150,3 +213,9 @@ export async function previewPermissionEdit(env, edit) {
 export function savePermissionEdit(env, edit, expectedRevision) {
     return serially(async () => commit(env, await planPermissionEdit(env, edit), expectedRevision));
 }
+export async function previewHookEdit(env, edit) {
+    return (await planHookEdit(env, edit)).preview;
+}
+export function saveHookEdit(env, edit, expectedRevision) {
+    return serially(async () => commit(env, await planHookEdit(env, edit), expectedRevision));
+}