ccdesk 0.0.0-stage → 0.1.0

package/dist/server/server.js

@@ -0,0 +1,258 @@
+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 { listBackups, previewRestore, restoreBackup } from "./backups.js";
+import { changeMemory, isMemoryAction, previewMemoryChange } from "./mutations.js";
+import { openInEditor } from "./open.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 { testPath } from "./scan/path-test.js";
+import { previewPermissionEdit, previewSettingsEdit, savePermissionEdit, saveSettingsEdit, } from "./settings-edit.js";
+import { Watcher } from "./watch.js";
+import { isCredentials, RefusedError } from "./write.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2",
+    ".png": "image/png",
+    ".json": "application/json",
+};
+const SECURITY_HEADERS = {
+    "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cache-Control": "no-store",
+};
+/** A request ccdesk will not take, answered with `status`. */
+class RequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export function createCcdeskServer(options) {
+    const watcher = new Watcher(options.env);
+    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) });
+        });
+    });
+    server.on("close", () => watcher.close());
+    return server;
+}
+async function handle(options, watcher, 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.
+    const allowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    if (!allowedHosts.includes(req.headers.host ?? ""))
+        return send(res, 421, { error: "Unexpected host" });
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    if (!url.pathname.startsWith("/api/"))
+        return serveStatic(options.uiDir, url.pathname, res);
+    if (req.headers["x-ccdesk-token"] !== options.token)
+        return send(res, 401, { error: "Missing or wrong token" });
+    const origin = req.headers.origin;
+    if (req.method !== "GET" &&
+        origin !== undefined &&
+        !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 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))
+        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 (!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;
+}
+async function answer(res, action) {
+    try {
+        send(res, 200, await action());
+    }
+    catch (error) {
+        if (error instanceof RefusedError)
+            return send(res, 409, { error: error.message });
+        throw error;
+    }
+}
+const MAX_BODY = 64 * 1024;
+async function readBody(req) {
+    if (!(req.headers["content-type"] ?? "").startsWith("application/json"))
+        throw new RequestError(415, "Send JSON");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new RequestError(413, "Request too large");
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new RequestError(400, "Not valid JSON");
+    }
+}
+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(/^[/\\]+/, "");
+    const target = join(uiDir, rel === "" ? "index.html" : rel);
+    if (!target.startsWith(uiDir + sep) && target !== uiDir)
+        return send(res, 403, { error: "Forbidden" });
+    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"];
+    res.writeHead(200, { ...SECURITY_HEADERS, "Content-Type": type });
+    res.end(body);
+}
+function send(res, status, body) {
+    res.writeHead(status, { ...SECURITY_HEADERS, "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}

package/dist/server/settings-edit.js

@@ -0,0 +1,152 @@
+import { stat } from "node:fs/promises";
+import { Ajv } 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 { settingsFiles } from "./scan/settings.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))
+        return null;
+    let validate = validators.get(key);
+    if (!validate) {
+        validate = ajv.compile(properties[key]);
+        validators.set(key, validate);
+    }
+    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)
+        throw new RefusedError(missing);
+    if (file.scope === "managed")
+        throw new RefusedError("Managed settings are set by your organisation.");
+    if (file.scope !== "user" && !(await stat(dir).catch(() => null))?.isDirectory())
+        throw new RefusedError(`${dir} is not a directory on this machine.`);
+    return file;
+}
+async function readSettings(env, path) {
+    const raw = await readIfExists(env, path);
+    if (raw === null || raw.trim() === "")
+        return { raw, data: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new RefusedError(`${path} is ${jsonSyntaxError(error)}; fix it by hand first.`);
+    }
+    if (!isRecord(parsed))
+        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) {
+    if (!allowedScopes(key).includes(file.scope))
+        throw new RefusedError(`${ignoredReason(key)}, so a ${file.scope} value would do nothing.`);
+    const validate = validatorFor(key);
+    if (!validate)
+        throw new RefusedError(`${key} is not in Claude Code's settings schema (${schema.$comment}).`);
+    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 }))
+        throw new RefusedError(`${key} holds hidden values; edit it in the file instead.`);
+    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"}`);
+        return {
+            path,
+            scope: file.scope,
+            raw,
+            next: null,
+            preview: { ...base, after: before ?? "", errors },
+        };
+    }
+    else {
+        next[key] = nextValue;
+    }
+    return {
+        path,
+        scope: file.scope,
+        raw,
+        next: `${JSON.stringify(next, null, 2)}\n`,
+        preview: { ...base, after: shown(next), errors: [] },
+    };
+}
+async function planSettingsEdit(env, edit) {
+    const file = await editableFile(env, edit.dir, (f) => f.scope === edit.scope && !f.legacy, edit.scope === "project"
+        ? "In your home directory this file is your user settings; edit it as User."
+        : undefined);
+    return planKey(env, file, edit.key, () => edit.value);
+}
+/** One rule taken out of its list and/or added to another, applied to the file as it is on disk. */
+async function planPermissionEdit(env, edit) {
+    const file = await editableFile(env, edit.dir, (f) => f.path === edit.file);
+    return planKey(env, file, "permissions", (data) => {
+        const permissions = isRecord(data.permissions) ? { ...data.permissions } : {};
+        const { remove, add } = edit;
+        if (remove) {
+            const list = Array.isArray(permissions[remove.list])
+                ? permissions[remove.list]
+                : [];
+            if (!list.includes(remove.rule))
+                throw new RefusedError(`${remove.rule} is no longer in ${remove.list} in this file.`);
+            const kept = list.filter((r) => r !== remove.rule);
+            if (kept.length > 0)
+                permissions[remove.list] = kept;
+            else
+                delete permissions[remove.list];
+        }
+        if (add) {
+            const list = Array.isArray(permissions[add.list]) ? permissions[add.list] : [];
+            if (!list.includes(add.rule))
+                permissions[add.list] = [...list, add.rule];
+        }
+        return Object.keys(permissions).length > 0 ? permissions : undefined;
+    });
+}
+/** 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)
+        throw new RefusedError(plan.preview.errors.join("; "));
+    if (plan.preview.revision !== expectedRevision)
+        throw new RefusedError("The file changed since you reviewed this edit; review it again.");
+    const next = plan.next;
+    return recordChange(env, { kind: "settings", target: plan.path, before: plan.raw }, async () => {
+        await writeAtomic(env, plan.path, next, expectedRevision);
+        return { target: plan.path, revision: revisionOf(next) };
+    });
+}
+export async function previewSettingsEdit(env, edit) {
+    return (await planSettingsEdit(env, edit)).preview;
+}
+export function saveSettingsEdit(env, edit, expectedRevision) {
+    return serially(async () => commit(env, await planSettingsEdit(env, edit), expectedRevision));
+}
+export async function previewPermissionEdit(env, edit) {
+    return (await planPermissionEdit(env, edit)).preview;
+}
+export function savePermissionEdit(env, edit, expectedRevision) {
+    return serially(async () => commit(env, await planPermissionEdit(env, edit), expectedRevision));
+}

package/dist/server/watch.js

@@ -0,0 +1,172 @@
+import { watch } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { isNetworkPath, mainWorktreeRoot } from "./scan/files.js";
+import { storeDirName } from "./scan/memory.js";
+/** How long one request waits for a change before answering "nothing changed". */
+const WAIT_MS = 25_000;
+/** Editors write a file in several steps; one change covers them all. */
+const SETTLE_MS = 300;
+/** Watchers outlive a request by this much, so nothing is missed between two polls. */
+const IDLE_MS = 60_000;
+const CONFIG_FOLDERS = ["rules", "agents", "skills", "commands", "output-styles"];
+/**
+ * The files and folders whose changes alter what ccdesk shows for `dir`. A `.claude` folder is
+ * watched only for its config files and folders, never recursively, because Claude Code keeps
+ * whole checkouts in `.claude/worktrees`. ~/.claude.json is left out: Claude Code rewrites it
+ * during every session, and focusing the tab picks up its changes.
+ */
+async function targets(env, dir, extra) {
+    const claude = (folder) => [
+        {
+            path: folder,
+            recursive: false,
+            names: ["settings.json", "settings.local.json", "CLAUDE.md", "AGENTS.md", ...CONFIG_FOLDERS],
+        },
+        ...CONFIG_FOLDERS.map((sub) => ({ path: join(folder, sub), recursive: true })),
+    ];
+    const memoryKey = (await mainWorktreeRoot(dir)) ?? dir;
+    const out = [
+        ...claude(env.claudeDir),
+        { path: join(env.claudeDir, "plugins"), recursive: false },
+        { path: join(env.claudeDir, "projects", storeDirName(memoryKey), "memory"), recursive: false },
+        { path: env.managedDir, recursive: false },
+        { path: join(env.managedDir, "managed-settings.d"), recursive: false },
+        ...extra,
+    ];
+    // The start directory and every parent can hold instructions, rules and settings.
+    for (let d = dir;; d = dirname(d)) {
+        out.push({
+            path: d,
+            recursive: false,
+            names: ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", ".mcp.json", ".claude"],
+        });
+        if (join(d, ".claude") !== env.claudeDir)
+            out.push(...claude(join(d, ".claude")));
+        if (dirname(d) === d)
+            break;
+    }
+    if (memoryKey !== dir)
+        out.push(...claude(join(memoryKey, ".claude")));
+    return out.filter((t) => !isNetworkPath(t.path));
+}
+/** Files a scan read that the fixed list does not cover: a custom memory folder, imports. */
+export function dependencies(view) {
+    const files = view.instructions.flatMap((i) => [
+        i.realPath ?? i.path,
+        ...i.imports.filter((r) => r.exists).map((r) => r.resolved),
+    ]);
+    const byFolder = new Map();
+    for (const file of files) {
+        const names = byFolder.get(dirname(file)) ?? new Set();
+        names.add(basename(file));
+        byFolder.set(dirname(file), names);
+    }
+    return [
+        ...[...byFolder].map(([path, names]) => ({ path, recursive: false, names: [...names] })),
+        ...(view.memory ? [{ path: view.memory.dir, recursive: false }] : []),
+    ];
+}
+/** One set of file watchers per directory a page is looking at, shared by its requests. */
+export class Watcher {
+    env;
+    subscriptions = new Map();
+    constructor(env) {
+        this.env = env;
+    }
+    /** Remembers what the latest scan of `dir` read, so those files are watched too. */
+    track(dir, view) {
+        const subscription = this.subscriptions.get(dir);
+        const extra = dependencies(view);
+        if (!subscription || JSON.stringify(extra) === JSON.stringify(subscription.extra))
+            return;
+        subscription.extra = extra;
+        void this.rewatch(dir, subscription);
+    }
+    /**
+     * Answers once something changed after `since` (ms since the epoch), or after `timeoutMs` with
+     * the last change time, whichever comes first.
+     */
+    async wait(dir, since, signal, timeoutMs = WAIT_MS) {
+        const subscription = await this.subscribe(dir);
+        clearTimeout(subscription.idle);
+        try {
+            if (subscription.changedAt <= since && !signal.aborted)
+                await new Promise((resolve) => {
+                    const done = () => {
+                        clearTimeout(timer);
+                        signal.removeEventListener("abort", done);
+                        subscription.waiters.delete(done);
+                        resolve();
+                    };
+                    const timer = setTimeout(done, timeoutMs);
+                    signal.addEventListener("abort", done);
+                    subscription.waiters.add(done);
+                });
+        }
+        finally {
+            if (subscription.waiters.size === 0)
+                subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+        }
+        return { changed: subscription.changedAt > since, at: subscription.changedAt };
+    }
+    close() {
+        for (const dir of [...this.subscriptions.keys()])
+            this.drop(dir);
+    }
+    async subscribe(dir) {
+        const existing = this.subscriptions.get(dir);
+        if (existing)
+            return existing;
+        const subscription = {
+            watchers: [],
+            changedAt: 0,
+            waiters: new Set(),
+            extra: [],
+        };
+        this.subscriptions.set(dir, subscription);
+        await this.rewatch(dir, subscription);
+        return subscription;
+    }
+    drop(dir) {
+        const subscription = this.subscriptions.get(dir);
+        if (!subscription)
+            return;
+        clearTimeout(subscription.idle);
+        clearTimeout(subscription.settle);
+        for (const w of subscription.watchers)
+            w.close();
+        this.subscriptions.delete(dir);
+    }
+    /** (Re)creates the watchers, so a folder created since, such as a new .claude, is watched. */
+    async rewatch(dir, subscription) {
+        const list = await targets(this.env, dir, subscription.extra);
+        for (const w of subscription.watchers)
+            w.close();
+        subscription.watchers = [];
+        if (this.subscriptions.get(dir) !== subscription)
+            return;
+        for (const target of list) {
+            try {
+                const watcher = watch(target.path, { recursive: target.recursive }, (_event, name) => {
+                    const changed = name === null ? "" : String(name);
+                    if (target.names && !target.names.includes(basename(changed)))
+                        return;
+                    clearTimeout(subscription.settle);
+                    subscription.settle = setTimeout(() => {
+                        subscription.changedAt = Date.now();
+                        for (const wake of [...subscription.waiters])
+                            wake();
+                        void this.rewatch(dir, subscription);
+                    }, SETTLE_MS);
+                });
+                watcher.on("error", () => watcher.close());
+                subscription.watchers.push(watcher);
+            }
+            catch {
+                // A folder that does not exist yet is caught by watching its parent.
+            }
+        }
+    }
+}