ccdesk 0.2.2 → 0.2.4

package/dist/{server → core}/scan/usage.js

@@ -1,73 +1,79 @@
-import { open, realpath, stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { storeDirName } from "../../shared/memory.js";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isCredentials, isDir, isRecord, isWithin, listDir, wildcard, worktrees } from "./files.js";
+import { isCredentials, isDir, isWithin, listDir, openUnlessCredentials, wildcard, } from "./files.js";
+import { isRecord } from "./data.js";
+import { worktrees } from "./git.js";
 import { namesTool, parseRule } from "./tools.js";
-/**
- * Transcripts already counted, by path, so reopening a directory reads only what was added. Kept
- * in memory only, least recently counted first; once they hold more than MAX_CACHED_CALLS calls,
- * the oldest are dropped and read again when needed.
- */
-const transcripts = new Map();
 /** Roughly how many calls the cache keeps, beyond those of the directory counted last. */
-export const MAX_CACHED_CALLS = 100_000;
+const MAX_CACHED_CALLS = 100_000;
 /** A transcript is read in parts this size, so one huge file never becomes one huge string. */
 const CHUNK = 8 * 1024 * 1024;
-let queue = Promise.resolve();
-/** Requests waiting their turn, so a burst of the same request runs once. */
-const waiting = new Map();
 /** How long one count may take before it stops; what it read by then stays counted. */
 const TIME_LIMIT_MS = 60_000;
 /** A count that stopped before it finished, because it took too long or nobody wanted it. */
 export class CountStopped extends Error {
 }
 /**
- * Counts the tool calls in the sessions started in `dir`, or anywhere in its repository and its
- * worktrees, since rules at a repository's root apply there too (docs: permissions#permission-system).
- * Subagents are included. It also counts the calls you approved or refused by hand, which Claude
- * Code records on each call's result as `permissionDecision` (not documented; older transcripts
- * lack it), and how many calls each rule covers. Requests run one at a time, since they share the
- * cache. A count stops when every `signal` it was asked with aborts, or after `timeLimitMs`: it
- * rejects with CountStopped and the next one starts, even if a read of the stopped count never
- * returns.
+ * A counter with its own cache of transcripts and its own queue: counts made through it run one at
+ * a time and reuse what earlier ones read. Each core has one.
  */
-export function readUsage(env, dir, rules, { signal, timeLimitMs = TIME_LIMIT_MS, maxCachedCalls = MAX_CACHED_CALLS, } = {}) {
-    const key = JSON.stringify([env.claudeDir, resolve(dir), rules, timeLimitMs, maxCachedCalls]);
-    let run = waiting.get(key);
-    // Nobody would wait for a new count, so none starts to hold up the queue.
-    if (!run && signal?.aborted)
-        return Promise.reject(stoppedBecause(signal));
-    if (!run) {
-        const stop = new AbortController();
-        const promise = queue.then(() => {
-            waiting.delete(key);
-            const during = AbortSignal.any([stop.signal, AbortSignal.timeout(timeLimitMs)]);
-            // A stopped count answers right away, even while one of its reads never returns.
-            const stopped = new Promise((_, fail) => {
-                const onStop = () => fail(stoppedBecause(during));
-                if (during.aborted)
-                    onStop();
-                else
-                    during.addEventListener("abort", onStop, { once: true });
+export function usageCounter() {
+    const transcripts = new Map();
+    let queue = Promise.resolve();
+    /** Requests waiting their turn, so a burst of the same request runs once. */
+    const waiting = new Map();
+    /**
+     * Counts the tool calls in the sessions started in `dir`, or anywhere in its repository and its
+     * worktrees, since rules at a repository's root apply there too (docs: permissions#permission-system).
+     * Subagents are included. It also counts the calls you approved or refused by hand, which Claude
+     * Code records on each call's result as `permissionDecision` (not documented; older transcripts
+     * lack it), and how many calls each rule covers. Requests run one at a time, since they share the
+     * cache. A count stops when every `signal` it was asked with aborts, or after `timeLimitMs`: it
+     * rejects with CountStopped and the next one starts, even if a read of the stopped count never
+     * returns.
+     */
+    return function countUsage(env, dir, rules, { signal, timeLimitMs = TIME_LIMIT_MS, maxCachedCalls = MAX_CACHED_CALLS, } = {}) {
+        const key = JSON.stringify([env.claudeDir, resolve(dir), rules, timeLimitMs, maxCachedCalls]);
+        let run = waiting.get(key);
+        // Nobody would wait for a new count, so none starts to hold up the queue.
+        if (!run && signal?.aborted)
+            return Promise.reject(stoppedBecause(signal));
+        if (!run) {
+            const stop = new AbortController();
+            const promise = queue.then(() => {
+                waiting.delete(key);
+                const during = AbortSignal.any([stop.signal, AbortSignal.timeout(timeLimitMs)]);
+                // A stopped count answers right away, even while one of its reads never returns.
+                const stopped = new Promise((_, fail) => {
+                    const onStop = () => fail(stoppedBecause(during));
+                    if (during.aborted)
+                        onStop();
+                    else
+                        during.addEventListener("abort", onStop, { once: true });
+                });
+                return Promise.race([
+                    count(transcripts, env, resolve(dir), rules, during, maxCachedCalls),
+                    stopped,
+                ]);
             });
-            return Promise.race([count(env, resolve(dir), rules, during, maxCachedCalls), stopped]);
-        });
-        run = { promise, stop, waiters: 0 };
-        waiting.set(key, run);
-        // The queue moves on when the count settles or stops: a stopped count changes nothing more.
-        queue = promise.catch(() => undefined);
-    }
-    const current = run;
-    if (signal?.aborted)
+            run = { promise, stop, waiters: 0 };
+            waiting.set(key, run);
+            // The queue moves on when the count settles or stops: a stopped count changes nothing more.
+            queue = promise.catch(() => undefined);
+        }
+        const current = run;
+        if (signal?.aborted)
+            return current.promise;
+        current.waiters++;
+        signal?.addEventListener("abort", () => {
+            if (--current.waiters === 0)
+                current.stop.abort();
+        }, { once: true });
         return current.promise;
-    current.waiters++;
-    signal?.addEventListener("abort", () => {
-        if (--current.waiters === 0)
-            current.stop.abort();
-    }, { once: true });
-    return current.promise;
+    };
 }
 function stoppedBecause(signal) {
     return new CountStopped(signal.reason instanceof DOMException && signal.reason.name === "TimeoutError"
@@ -79,7 +85,7 @@ function checkStopped(signal) {
     if (signal.aborted)
         throw stoppedBecause(signal);
 }
-async function count(env, dir, rules, signal, maxCachedCalls) {
+async function count(transcripts, env, dir, rules, signal, maxCachedCalls) {
     checkStopped(signal);
     const checkouts = await worktrees(dir);
     // $HOME may end in a slash or be a link, while git prints the resolved path.
@@ -93,10 +99,7 @@ async function count(env, dir, rules, signal, maxCachedCalls) {
     const folders = repository ? checkouts : [dir];
     const projects = join(env.claudeDir, "projects");
     const storeNames = await listDir(projects);
-    const taken = new Set();
-    const calls = [];
-    const counted = new Set();
-    let sessions = 0;
+    const tally = { taken: new Set(), calls: [], sessions: 0 };
     for (const folder of folders) {
         const own = storeDirName(folder);
         // Sessions started in a subfolder or a nested worktree have their own store, named with the
@@ -107,27 +110,15 @@ async function count(env, dir, rules, signal, maxCachedCalls) {
         for (const name of stores) {
             const store = join(projects, name);
             const files = await transcriptsIn(store);
-            for (const [file, session] of files) {
-                if (taken.has(file))
-                    continue;
-                // A subagent's session decides; one whose session file is gone goes by its own start.
-                const start = (await transcript(env, session, signal))?.startCwd ??
-                    (await transcript(env, file, signal))?.startCwd;
-                if (start ? !isWithin(folder, start) : name !== own)
-                    continue;
-                taken.add(file);
-                counted.add(file);
-                calls.push(...((await transcript(env, file, signal))?.calls ?? []));
-                if (file === session)
-                    sessions++;
-            }
+            await countStore(transcripts, env, signal, tally, folder, files, name === own);
             checkStopped(signal);
             for (const path of transcripts.keys())
                 if (path.startsWith(store + sep) && !files.has(path))
                     transcripts.delete(path);
         }
     }
-    trimCache(counted, maxCachedCalls);
+    const { calls, sessions } = tally;
+    trimCache(transcripts, tally.taken, maxCachedCalls);
     return {
         sessions,
         repository,
@@ -137,8 +128,27 @@ async function count(env, dir, rules, signal, maxCachedCalls) {
         matches: Object.fromEntries(rules.map((r) => [r.rule, matchCount(r, calls)])),
     };
 }
+/**
+ * Adds the transcripts in one store whose session started in `folder`. A subagent's session
+ * decides; one whose session file is gone goes by its own start, or, without one, by whether the
+ * store is the folder's own.
+ */
+async function countStore(transcripts, env, signal, tally, folder, files, ownStore) {
+    for (const [file, session] of files) {
+        if (tally.taken.has(file))
+            continue;
+        const start = (await transcript(transcripts, env, session, signal))?.startCwd ??
+            (await transcript(transcripts, env, file, signal))?.startCwd;
+        if (start ? !isWithin(folder, start) : !ownStore)
+            continue;
+        tally.taken.add(file);
+        tally.calls.push(...((await transcript(transcripts, env, file, signal))?.calls ?? []));
+        if (file === session)
+            tally.sessions++;
+    }
+}
 /** Drops the least recently counted transcripts over the limit, keeping those just counted. */
-function trimCache(counted, maxCalls) {
+function trimCache(transcripts, counted, maxCalls) {
     let total = 0;
     for (const known of transcripts.values())
         total += known.calls.length;
@@ -166,7 +176,7 @@ async function transcriptsIn(store) {
  * One transcript, read up to its end; one that cannot be read keeps what was read before, and one
  * whose count stops keeps the whole lines read so far.
  */
-async function transcript(env, file, signal) {
+async function transcript(transcripts, env, file, signal) {
     if (await isCredentials(env, file))
         return null;
     const info = await stat(file).catch(() => null);
@@ -182,7 +192,7 @@ async function transcript(env, file, signal) {
     if (known.size === info.size && known.mtimeMs === info.mtimeMs)
         return known;
     try {
-        await readFrom(file, known, info.size, signal);
+        await readFrom(env, file, known, info.size, signal);
         known.size = info.size;
         known.mtimeMs = info.mtimeMs;
     }
@@ -194,8 +204,11 @@ async function transcript(env, file, signal) {
     return known;
 }
 /** Reads whole lines from the offset up to `size`; a line still being written is read next time. */
-async function readFrom(file, known, size, signal) {
-    const handle = await open(file, "r");
+async function readFrom(env, file, known, size, signal) {
+    // Checked again on the open file, so one swapped for the credentials file after transcript()'s check is not read.
+    const handle = await openUnlessCredentials(env, file);
+    if (!handle)
+        return;
     try {
         let carried = Buffer.alloc(0);
         let position = known.offset;
@@ -220,10 +233,10 @@ async function readFrom(file, known, size, signal) {
     }
 }
 /** Takes the tool calls from an assistant line and your answers from a tool result line. */
-function read(line, transcript) {
+function read(line, into) {
     const hasCall = line.includes('"tool_use"');
     const hasDecision = line.includes('"permissionDecision"');
-    const hasStart = !transcript.startCwd && line.includes('"cwd"');
+    const hasStart = !into.startCwd && line.includes('"cwd"');
     if (!hasCall && !hasDecision && !hasStart)
         return;
     let record;
@@ -235,35 +248,42 @@ function read(line, transcript) {
     }
     if (!isRecord(record))
         return;
-    if (!transcript.startCwd && typeof record.cwd === "string")
-        transcript.startCwd = record.cwd;
+    if (!into.startCwd && typeof record.cwd === "string")
+        into.startCwd = record.cwd;
     if (!isRecord(record.message))
         return;
     const content = record.message.content;
     if (!Array.isArray(content))
         return;
+    if (record.type === "assistant")
+        readCalls(record, content, into);
+    else if (record.type === "user")
+        readDecision(record, content, into);
+}
+/** The tool calls in an assistant line. */
+function readCalls(record, content, into) {
     const at = typeof record.timestamp === "string" ? record.timestamp : "";
-    if (record.type === "assistant") {
-        for (const block of content) {
-            if (!isRecord(block) || block.type !== "tool_use")
-                continue;
-            if (typeof block.id !== "string" || typeof block.name !== "string")
-                continue;
-            const call = callOf(block.name, isRecord(block.input) ? block.input : {}, at);
-            transcript.calls.push(call);
-            transcript.byId.set(block.id, call);
-        }
-        return;
+    for (const block of content) {
+        if (!isRecord(block) || block.type !== "tool_use")
+            continue;
+        if (typeof block.id !== "string" || typeof block.name !== "string")
+            continue;
+        const call = callOf(block.name, isRecord(block.input) ? block.input : {}, at);
+        into.calls.push(call);
+        into.byId.set(block.id, call);
     }
+}
+/** Your answer to the calls a tool result line answers, when you gave it by hand. */
+function readDecision(record, content, into) {
     const decision = record.permissionDecision;
-    if (record.type !== "user" || !isRecord(decision))
+    if (!isRecord(decision))
         return;
     if (typeof decision.source !== "string" || !decision.source.startsWith("user"))
         return;
     for (const block of content) {
         if (!isRecord(block) || block.type !== "tool_result")
             continue;
-        const call = typeof block.tool_use_id === "string" && transcript.byId.get(block.tool_use_id);
+        const call = typeof block.tool_use_id === "string" && into.byId.get(block.tool_use_id);
         if (call)
             call.byYou = decision.decision === "accept";
     }
@@ -312,8 +332,13 @@ function approvals(calls, rules) {
     for (const c of calls) {
         if (c.byYou !== true)
             continue;
-        if (c.rule)
-            groups.set(c.rule, [...(groups.get(c.rule) ?? []), c]);
+        if (!c.rule)
+            continue;
+        const group = groups.get(c.rule);
+        if (group)
+            group.push(c);
+        else
+            groups.set(c.rule, [c]);
     }
     const refused = calls.filter((c) => c.byYou === false);
     const out = [];

package/dist/core/schema.d.ts

@@ -0,0 +1,8 @@
+import { type Validator } from "typebox/compile";
+/**
+ * What `validator` found wrong with `value`, each led by where: `label` and the path inside it,
+ * such as `sandbox.network`.
+ */
+export declare function schemaErrors(validator: Validator, value: unknown, label: string): string[];
+/** The first thing wrong with a request body, such as "add.list must be string". */
+export declare function firstError(validator: Validator, value: unknown): string;

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,45 @@
+/**
+ * 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 hidden end of one whose start is shown (`--token=value`,
+ * `Authorization: Bearer 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,207 @@
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { FRONTMATTER, isRecord, parseJson } 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`, `--api-key`, `--client-secret` or `--auth-token`. */
+const SECRET_FLAG = /^--([\w-]*[-_])?(token|api[-_]?key|apikey|password|secret|auth\w*|key)$/i;
+/** A flag whose value is an HTTP header, as mcp-remote takes `--header "Authorization: Bearer …"`. */
+const HEADER_FLAG = /^(--header|-H)$/;
+/** An argument that is itself a credential header or an Authorization value. */
+const SECRET_HEADER = /^([\w-]*(authorization|api-key|token|cookie)\s*:|(bearer|basic)\s+\S)/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 header as ccdesk shows it: the name and the `Bearer` or `Basic` scheme stay, the rest is hidden. */
+function shownHeader(header) {
+    const kept = /^([^:]*:\s*)?((bearer|basic)\s+)?/i.exec(header)?.[0] ?? "";
+    return `${kept}•••`;
+}
+/**
+ * A server's command-line arguments as ccdesk shows them: the value after a secret flag, given as
+ * `--token value` or `--token=value`, a header's value after `--header` or `-H`, a credential
+ * header or Authorization value on its own, a value that starts like a known key, and the
+ * credentials in a URL are hidden.
+ */
+function shownArgs(args) {
+    return args.map((arg, i) => (typeof arg === "string" ? shownArg(arg, args[i - 1]) : arg));
+}
+/** One argument as ccdesk shows it, given the one before it. */
+function shownArg(arg, previous) {
+    if (typeof previous === "string" && !arg.startsWith("-")) {
+        if (SECRET_FLAG.test(previous))
+            return "•••";
+        if (HEADER_FLAG.test(previous))
+            return shownHeader(arg);
+    }
+    const equals = arg.indexOf("=");
+    if (equals > 0) {
+        const name = arg.slice(0, equals);
+        const value = arg.slice(equals + 1);
+        if (HEADER_FLAG.test(name))
+            return `${name}=${shownHeader(value)}`;
+        if (SECRET_FLAG.test(name) || KEY_PREFIX.test(value))
+            return `${name}=•••`;
+    }
+    if (SECRET_HEADER.test(arg))
+        return shownHeader(arg);
+    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 = parseJson(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 {
+        parseJson(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 : parseJson(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 hidden end of one whose start is shown (`--token=value`,
+ * `Authorization: Bearer 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];
+        // The start was kept, as in `--token=•••` or `Authorization: Bearer •••`: the rest is the secret.
+        if (typeof hidden === "string" && hidden.endsWith("•••") && raw.startsWith(hidden.slice(0, -3)))
+            return [raw.slice(hidden.length - 3)];
+        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);
+}