ccdesk 0.2.1 → 0.2.3

package/dist/core/schema.js

@@ -0,0 +1,67 @@
+import {} from "typebox/error";
+import { Settings } from "typebox/system";
+import {} from "typebox/compile";
+/**
+ * What `validator` found wrong with `value`, each led by where: `label` and the path inside it,
+ * such as `sandbox.network`.
+ */
+export function schemaErrors(validator, value, label) {
+    if (validator.Check(value))
+        return [];
+    return allErrors(validator, value).flatMap((e) => messages(e).map(([path, message]) => {
+        const where = [label, ...path.split("/")].filter(Boolean).join(".");
+        return where ? `${where} ${message}` : message;
+    }));
+}
+/** The first thing wrong with a request body, such as "add.list must be string". */
+export function firstError(validator, value) {
+    return schemaErrors(validator, value, "")[0] ?? "the request is not well formed";
+}
+/**
+ * Every error, not TypeBox's first eight: a wrong hook lists what each kind of hook needs. Each
+ * value checked is one setting, server or request body, so the list stays short. The limit is
+ * TypeBox's process-wide setting, so it is put back for anything else in the process using it.
+ */
+function allErrors(validator, value) {
+    const { maxErrors } = Settings.Get();
+    Settings.Set({ maxErrors: Number.POSITIVE_INFINITY });
+    try {
+        return validator.Errors(value);
+    }
+    finally {
+        Settings.Set({ maxErrors });
+    }
+}
+/**
+ * An error as where it is and what is wrong, worded as ccdesk has always shown them: one missing
+ * property at a time, and one "must NOT have additional properties" for each property a closed
+ * object does not allow.
+ */
+function messages(e) {
+    switch (e.keyword) {
+        case "required":
+            return e.params.requiredProperties.map((p) => [
+                e.instancePath,
+                `must have required property '${p}'`,
+            ]);
+        // Said once for each extra property, through its "schema is false" error below; a property
+        // that fails an additionalProperties schema has its own error already.
+        case "additionalProperties":
+            return [];
+        case "boolean":
+            if (!e.schemaPath.endsWith("/additionalProperties"))
+                return [[e.instancePath, e.message]];
+            return [
+                [
+                    e.instancePath.slice(0, e.instancePath.lastIndexOf("/")),
+                    "must NOT have additional properties",
+                ],
+            ];
+        case "enum":
+            return [[e.instancePath, `${e.message}: ${e.params.allowedValues.join(", ")}`]];
+        case "minItems":
+            return [[e.instancePath, `must NOT have fewer than ${e.params.limit} items`]];
+        default:
+            return [[e.instancePath, e.message]];
+    }
+}

package/dist/core/secrets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A server URL as ccdesk shows it: a user name, password or query string can carry a key, so they
+ * are hidden, as Claude Code hides the URL in its own status output (docs: mcp).
+ */
+export declare function shownUrl(url: string): string;
+/**
+ * Replace values that commonly hold secrets with a placeholder, keeping the keys: env and headers
+ * values, the user, password and query of a `url`, and secret values in the `args` of a command.
+ */
+export declare function redactSecrets(value: Record<string, unknown>): Record<string, unknown>;
+export declare function redactSecrets(value: unknown): unknown;
+/**
+ * A JSON parse failure without the parser's message, which quotes the text around the fault and
+ * so can quote a secret.
+ */
+export declare function jsonSyntaxError(error: unknown): string;
+/**
+ * The text ccdesk shows for a file reached as an instruction, import, memory, agent or skill. A
+ * settings or MCP file read this way, whatever it is named, would otherwise show its env and
+ * headers values, so anything that parses as JSON is shown parsed with them hidden. Frontmatter can
+ * hold the same values, in a subagent's inline MCP servers (docs: sub-agents#scope-mcp-servers-to-a-subagent),
+ * so frontmatter that holds any is shown re-written with them hidden.
+ */
+export declare function shownText(text: string | null): string | null;
+/** A file named .json that does not parse is not shown: its text could still hold a secret. */
+export declare function shownJsonFile(text: string): string;
+/**
+ * Helpers for the values ccdesk hides. What is hidden is decided only by redactSecrets; these
+ * compare a value with its redacted form.
+ */
+/** A value as ccdesk shows it: JSON with hidden values as •••. */
+export declare function shown(value: unknown): string;
+export declare function hasHiddenValues(value: unknown): boolean;
+/**
+ * A fingerprint of the hidden values in a JSON file, so a restore can tell whether they changed.
+ * Null for a file that is not valid JSON.
+ */
+export declare function hiddenValues(text: string | null): string | null;
+/**
+ * The secret text in a value, to take out of a message that may quote it: an env or header value
+ * or a hidden argument whole, the part after `=` of `--token=value`, and a URL's user name,
+ * password and query. Longest first, so a secret that contains another is taken out whole.
+ */
+export declare function secretTexts(value: unknown): string[];

package/dist/core/secrets.js

@@ -0,0 +1,187 @@
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { FRONTMATTER, isRecord } from "./scan/data.js";
+/**
+ * A server URL as ccdesk shows it: a user name, password or query string can carry a key, so they
+ * are hidden, as Claude Code hides the URL in its own status output (docs: mcp).
+ */
+export function shownUrl(url) {
+    try {
+        const u = new URL(url);
+        if (!u.username && !u.password && !u.search)
+            return url;
+        if (u.username || u.password) {
+            u.username = "•••";
+            u.password = "";
+        }
+        if (u.search)
+            u.search = "?•••";
+        return decodeURI(u.toString());
+    }
+    catch {
+        return url.replace(/\/\/[^/@]*@/, "//•••@").replace(/\?.*$/, "?•••");
+    }
+}
+/** A flag whose value is a secret, such as `--token` or `--api-key`. */
+const SECRET_FLAG = /^--(token|api[-_]?key|apikey|password|secret|auth|key)$/i;
+/** A value that starts like a common API key or token. */
+const KEY_PREFIX = /^(sk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[bp]-|glpat-|AKIA[0-9A-Z]{16})/;
+/**
+ * A server's command-line arguments as ccdesk shows them: the value after a secret flag, given as
+ * `--token value` or `--token=value`, a value that starts like a known key, and the credentials in
+ * a URL are hidden.
+ */
+function shownArgs(args) {
+    return args.map((arg, i) => {
+        if (typeof arg !== "string")
+            return arg;
+        const previous = args[i - 1];
+        if (typeof previous === "string" && SECRET_FLAG.test(previous) && !arg.startsWith("-"))
+            return "•••";
+        const equals = arg.indexOf("=");
+        if (equals > 0) {
+            const name = arg.slice(0, equals);
+            if (SECRET_FLAG.test(name) || KEY_PREFIX.test(arg.slice(equals + 1)))
+                return `${name}=•••`;
+        }
+        if (KEY_PREFIX.test(arg))
+            return "•••";
+        if (/^https?:\/\//i.test(arg))
+            return shownUrl(arg);
+        return arg;
+    });
+}
+export function redactSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(redactSecrets);
+    if (!isRecord(value))
+        return value;
+    // Built with fromEntries: assigning a key named __proto__ would set the prototype instead.
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => {
+        if ((key === "env" || key === "headers") && isRecord(inner))
+            return [key, Object.fromEntries(Object.keys(inner).map((k) => [k, "•••"]))];
+        if (key === "url" && typeof inner === "string")
+            return [key, shownUrl(inner)];
+        if (key === "args" && "command" in value && Array.isArray(inner))
+            return [key, shownArgs(inner)];
+        return [key, redactSecrets(inner)];
+    }));
+}
+/**
+ * A JSON parse failure without the parser's message, which quotes the text around the fault and
+ * so can quote a secret.
+ */
+export function jsonSyntaxError(error) {
+    const at = /line (\d+) column (\d+)/.exec(String(error));
+    return at ? `not valid JSON (line ${at[1]}, column ${at[2]})` : "not valid JSON";
+}
+/**
+ * The text ccdesk shows for a file reached as an instruction, import, memory, agent or skill. A
+ * settings or MCP file read this way, whatever it is named, would otherwise show its env and
+ * headers values, so anything that parses as JSON is shown parsed with them hidden. Frontmatter can
+ * hold the same values, in a subagent's inline MCP servers (docs: sub-agents#scope-mcp-servers-to-a-subagent),
+ * so frontmatter that holds any is shown re-written with them hidden.
+ */
+export function shownText(text) {
+    if (text === null)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return shownFrontmatter(text);
+    }
+    return typeof data === "object" && data !== null
+        ? `${JSON.stringify(redactSecrets(data), null, 2)}\n`
+        : text;
+}
+function shownFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    let data;
+    try {
+        data = parseYaml(match[1] ?? "");
+    }
+    catch {
+        return text;
+    }
+    const redacted = redactSecrets(data);
+    if (JSON.stringify(redacted) === JSON.stringify(data))
+        return text;
+    return `---\n${stringifyYaml(redacted)}---\n${text.slice(match[0].length)}`;
+}
+/** A file named .json that does not parse is not shown: its text could still hold a secret. */
+export function shownJsonFile(text) {
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        return "(a JSON file ccdesk could not parse, so its text is not shown; open it to see it)\n";
+    }
+    return shownText(text) ?? "";
+}
+/**
+ * Helpers for the values ccdesk hides. What is hidden is decided only by redactSecrets; these
+ * compare a value with its redacted form.
+ */
+/** A value as ccdesk shows it: JSON with hidden values as •••. */
+export function shown(value) {
+    return `${JSON.stringify(redactSecrets(value), null, 2)}\n`;
+}
+/** Every value redactSecrets changes, with where it is, what it is, and how it is shown. */
+function hiddenIn(value) {
+    const found = [];
+    // redactSecrets keeps every key and list length, so the two can be walked side by side.
+    const walk = (raw, shownValue, path) => {
+        if (Array.isArray(raw) && Array.isArray(shownValue)) {
+            for (const [i, inner] of raw.entries())
+                walk(inner, shownValue[i], [...path, i]);
+        }
+        else if (isRecord(raw) && isRecord(shownValue))
+            for (const [key, inner] of Object.entries(raw))
+                walk(inner, shownValue[key], [...path, key]);
+        else if (raw !== shownValue)
+            found.push({ path, raw, shown: shownValue });
+    };
+    walk(value, redactSecrets(value), []);
+    return found;
+}
+export function hasHiddenValues(value) {
+    return hiddenIn(value).length > 0;
+}
+/**
+ * A fingerprint of the hidden values in a JSON file, so a restore can tell whether they changed.
+ * Null for a file that is not valid JSON.
+ */
+export function hiddenValues(text) {
+    try {
+        const data = text === null ? null : JSON.parse(text);
+        return JSON.stringify(hiddenIn(data).map(({ path, raw }) => [path, raw]));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The secret text in a value, to take out of a message that may quote it: an env or header value
+ * or a hidden argument whole, the part after `=` of `--token=value`, and a URL's user name,
+ * password and query. Longest first, so a secret that contains another is taken out whole.
+ */
+export function secretTexts(value) {
+    const found = hiddenIn(value).flatMap(({ raw, shown: hidden }) => {
+        if (typeof raw !== "string")
+            return [];
+        if (hidden === "•••")
+            return [raw];
+        if (typeof hidden === "string" && hidden.endsWith("=•••"))
+            return [raw.slice(raw.indexOf("=") + 1)];
+        if (shownUrl(raw) === raw)
+            return [];
+        const url = URL.parse(raw);
+        return [url?.username, url?.password, url?.search.slice(1)];
+    });
+    return found
+        .filter((s) => s !== undefined && s !== "")
+        .sort((a, b) => b.length - a.length);
+}

package/dist/core/settings-edit.d.ts

@@ -0,0 +1,9 @@
+import { type Change, type HookEdit, type PermissionEdit, type SettingsEdit, type SettingsEditPreview } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { type Serially } from "./write.ts";
+export declare function previewSettingsEdit(env: ScanEnv, edit: SettingsEdit): Promise<SettingsEditPreview>;
+export declare function saveSettingsEdit(env: ScanEnv, edit: SettingsEdit, expectedRevision: string, queue?: Serially): Promise<Change>;
+export declare function previewPermissionEdit(env: ScanEnv, edit: PermissionEdit): Promise<SettingsEditPreview>;
+export declare function savePermissionEdit(env: ScanEnv, edit: PermissionEdit, expectedRevision: string, queue?: Serially): Promise<Change>;
+export declare function previewHookEdit(env: ScanEnv, edit: HookEdit): Promise<SettingsEditPreview>;
+export declare function saveHookEdit(env: ScanEnv, edit: HookEdit, expectedRevision: string, queue?: Serially): Promise<Change>;

package/dist/core/settings-edit.js

@@ -0,0 +1,216 @@
+import { stat } from "node:fs/promises";
+import { Compile } from "typebox/compile";
+import HOOK_EVENTS from "../shared/hook-events.json" with { type: "json" };
+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 { revisionOf } from "./scan/files.js";
+import { isRecord } from "./scan/data.js";
+import { isSkippedMcpRule } from "./scan/permissions.js";
+import { settingsFiles } from "./scan/settings.js";
+import { schemaErrors } from "./schema.js";
+import { hasHiddenValues, redactSecrets, shown } from "./secrets.js";
+import { RefusedError, readJsonObject, recordChange, saveReviewed, serially, writeAtomic, } from "./write.js";
+const properties = schema.definitions.ClaudeCodeSettings.properties;
+const validators = new Map();
+function validatorFor(key) {
+    if (!Object.hasOwn(properties, key))
+        return null;
+    let validate = validators.get(key);
+    if (!validate) {
+        validate = Compile(properties[key]);
+        validators.set(key, validate);
+    }
+    return validate;
+}
+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;
+}
+/**
+ * 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);
+    if (!validate)
+        throw new RefusedError(`${key} is not in Claude Code's settings schema (${schema.$comment}).`);
+    const { path } = file;
+    const { raw, data, reformats } = await readJsonObject(env, path);
+    const nextValue = value(data);
+    // 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 errors = nextValue === undefined
+        ? []
+        : [...schemaErrors(validate, nextValue, key), ...newHookEvents(key, data[key], nextValue)];
+    const next = { ...data };
+    if (nextValue === undefined)
+        delete next[key];
+    else
+        next[key] = nextValue;
+    const text = `${JSON.stringify(next, null, 2)}\n`;
+    const before = raw === null ? null : shown(data);
+    return {
+        preview: {
+            path,
+            before,
+            after: errors.length > 0 ? (before ?? "") : shown(next),
+            revision: revisionOf(raw),
+            reformats,
+            errors,
+        },
+        save: () => recordChange(env, { kind: "settings", target: path, before: raw }, async () => {
+            await writeAtomic(env, path, text, revisionOf(raw));
+            return { target: path, revision: revisionOf(text) };
+        }),
+    };
+}
+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) {
+            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];
+        }
+        return Object.keys(permissions).length > 0 ? permissions : undefined;
+    });
+}
+/**
+ * Hook events an edit brings in that Claude Code does not know, which the schema allows. Ones the
+ * file already has stay, so a file written for another Claude Code version can still be edited.
+ */
+function newHookEvents(key, before, after) {
+    if (key !== "hooks" || !isRecord(after))
+        return [];
+    const had = isRecord(before) ? Object.keys(before) : [];
+    return Object.keys(after)
+        .filter((event) => !HOOK_EVENTS.includes(event) && !had.includes(event))
+        .map((event) => `${event} is not a hook event Claude Code knows.`);
+}
+/** 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) => editedHooks(data.hooks, edit), true);
+}
+/** The hooks setting with the edit applied, or undefined when no hooks are left. */
+function editedHooks(value, edit) {
+    const hooks = isRecord(value) ? structuredClone(value) : {};
+    const { remove, add } = edit;
+    // Checked before any branch, so neither a new hook nor a replacement writes them.
+    if (add && hasHiddenValues(add.definition))
+        throw new RefusedError("ccdesk does not write header values it would then hide; add this hook in the file instead.");
+    if (remove && takeOutHook(hooks, remove, add) === "replaced")
+        return hooks;
+    if (add) {
+        const groups = groupsOf(hooks, 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;
+}
+/** An event's matcher groups as stored in `hooks`, or a new list when it has none. */
+function groupsOf(hooks, event) {
+    const groups = hooks[event];
+    return Array.isArray(groups) ? groups : [];
+}
+/**
+ * Takes the reviewed hook out of `hooks`, or puts `add` in its place when only its matcher or
+ * nothing about where it sits changes.
+ */
+function takeOutHook(hooks, remove, add) {
+    const groups = groupsOf(hooks, 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 "replaced";
+    }
+    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];
+    return "removed";
+}
+const CHANGED = "The file changed since you reviewed this edit; review it again.";
+export async function previewSettingsEdit(env, edit) {
+    return (await planSettingsEdit(env, edit)).preview;
+}
+export function saveSettingsEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planSettingsEdit(env, edit), expectedRevision, CHANGED);
+}
+export async function previewPermissionEdit(env, edit) {
+    return (await planPermissionEdit(env, edit)).preview;
+}
+export function savePermissionEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planPermissionEdit(env, edit), expectedRevision, CHANGED);
+}
+export async function previewHookEdit(env, edit) {
+    return (await planHookEdit(env, edit)).preview;
+}
+export function saveHookEdit(env, edit, expectedRevision, queue = serially) {
+    return saveReviewed(queue, () => planHookEdit(env, edit), expectedRevision, CHANGED);
+}

package/dist/core/watch.d.ts

@@ -0,0 +1,45 @@
+import { type DirectoryView, type SessionProfile } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+import { scanDirectory } from "./scan/index.ts";
+/** One set of file watchers per directory a page is looking at, shared by its requests. */
+export declare class Watcher {
+    private readonly subscriptions;
+    /** What the latest scan of each directory read, kept for a watch that starts after the scan. */
+    private readonly scanned;
+    private readonly latest;
+    private readonly env;
+    private readonly scanOf;
+    constructor(env: ScanEnv, scanOf?: typeof scanDirectory);
+    /** Scans `dir` and remembers what the scan read, so those files are watched too. */
+    scan(dir: string, profile?: SessionProfile): Promise<DirectoryView>;
+    /**
+     * The view of `dir`: the latest scan while it is known to be current, else a new scan. It is
+     * current only while watchers that started before it have seen no change since it started, and
+     * ~/.claude.json, which is not watched, is as it was. Only an interactive scan is reused, as the
+     * path tester describes an interactive session.
+     */
+    view(dir: string): Promise<DirectoryView>;
+    /** ~/.claude.json's size and time; Claude Code rewrites it too often to watch. */
+    private stateFile;
+    /**
+     * Answers once something changed after `since` (ms since the epoch), or after `timeoutMs` with
+     * the last change time, whichever comes first.
+     */
+    wait(dir: string, since: number, signal: AbortSignal, timeoutMs?: number): Promise<{
+        changed: boolean;
+        at: number;
+    }>;
+    /**
+     * Calls `onChange` once after each change to what ccdesk shows for `dir`, until the returned
+     * function is called. Resolves once the watchers have started, so a change made after it
+     * resolves is seen. `close` stops the calls without making one.
+     */
+    subscribe(dir: string, onChange: () => void): Promise<() => void>;
+    /** Drops the watchers of `dir` after a while once no one waits or listens for changes. */
+    private release;
+    close(): void;
+    private watching;
+    private drop;
+    /** (Re)creates the watchers, so a folder created since, such as a new .claude, is watched. */
+    private rewatch;
+}