ccdesk 0.2.2 → 0.2.4

package/dist/{server → core}/write.js

@@ -1,9 +1,12 @@
 import { randomBytes } from "node:crypto";
 import { chmod, link, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import {} from "../shared/types.js";
+import { Type } from "typebox";
+import { BACKUP_KINDS } from "../shared/types.js";
+import { isRecord, parseJson } from "./scan/data.js";
 import {} from "./scan/env.js";
 import { isCredentials, isSecretPath, revisionOf } from "./scan/files.js";
+import { jsonSyntaxError } from "./secrets.js";
 /** A change ccdesk refuses on purpose; the server answers 409 with the message. */
 export class RefusedError extends Error {
 }
@@ -12,15 +15,30 @@ export class StaleError extends RefusedError {
 }
 const CREDENTIALS = "ccdesk does not read or change Claude Code's credentials.";
 const STATE_FILE = "ccdesk does not change ~/.claude.json; Claude Code rewrites it all the time.";
-let queue = Promise.resolve();
+/** A new, empty queue of changes. Each core has its own. */
+export function changeQueue() {
+    let queue = Promise.resolve();
+    return (change) => {
+        const run = queue.then(change);
+        queue = run.catch(() => undefined);
+        return run;
+    };
+}
 /**
- * Runs changes one at a time, so two of them can never both pass a revision check before either
- * writes. Every exported change goes through here; helpers it calls must not.
+ * Plans a change again and makes it, but only when it has no errors and everything it was worked
+ * out from is as reviewed; `changed` is the refusal otherwise. Planning and saving share one turn
+ * of the queue, so no other change lands between the check and the write.
  */
-export function serially(change) {
-    const run = queue.then(change);
-    queue = run.catch(() => undefined);
-    return run;
+export function saveReviewed(queue, plan, expectedRevision, changed) {
+    return queue(async () => {
+        const { preview, save } = await plan();
+        const errors = preview.errors ?? [];
+        if (errors.length > 0)
+            throw new RefusedError(errors.join("; "));
+        if (preview.revision !== expectedRevision)
+            throw new RefusedError(changed);
+        return save();
+    });
 }
 export function backupRoot(env) {
     return join(env.claudeDir, "backups", "ccdesk");
@@ -60,6 +78,26 @@ export async function readIfExists(env, path) {
         throw error;
     }
 }
+/**
+ * A JSON file that holds an object, as ccdesk edits it: missing or empty is `{}`, anything else
+ * that is not an object is refused. `reformats` says whether writing it back as 2-space JSON
+ * changes more than the edit, since its diff is rendered from the parsed file.
+ */
+export async function readJsonObject(env, path) {
+    const raw = await readIfExists(env, path);
+    if (raw === null || raw.trim() === "")
+        return { raw, data: {}, reformats: false };
+    let parsed;
+    try {
+        parsed = parseJson(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, reformats: raw !== `${JSON.stringify(parsed, null, 2)}\n` };
+}
 /**
  * Replaces a file's content, but only while it still has `expected` revision. The new text is
  * written to a temporary file first and the revision is checked again just before the rename, so
@@ -132,6 +170,21 @@ export async function removeExactly(path, expected) {
     await rm(aside);
     return false;
 }
+/** What a backup folder records about its change, in its manifest. */
+export const BackupManifestSchema = Type.Object({
+    kind: Type.Enum(BACKUP_KINDS),
+    /** The file that changed (for a deleted memory: the memory file). */
+    target: Type.String(),
+    createdAt: Type.String(),
+    /** Revision of the target before the change; "missing" when ccdesk created it. */
+    before: Type.String(),
+    /** Revision of the target right after the change; "pending" while it runs, "partial" when it failed halfway. */
+    after: Type.String(),
+    /** For a deleted memory: the MEMORY.md lines removed with it. */
+    removedIndexLines: Type.Optional(Type.Array(Type.String())),
+    /** For a change made through `claude mcp`: the commands that put it back, values hidden. */
+    undoCommands: Type.Optional(Type.Array(Type.String())),
+});
 export const MANIFEST = "ccdesk-backup.json";
 /** Takes a change out of Recent changes, for one whose effect was undone again right away. */
 export function forgetChange(env, id) {

package/dist/server/args.d.ts

@@ -0,0 +1,32 @@
+export declare const HELP = "ccdesk: see and change what Claude Code loads on this machine\n\nUsage:\n  npx ccdesk [options]                     Open the page in your browser\n  npx ccdesk scan [dir] --json             Print what Claude Code loads in dir, as JSON\n  npx ccdesk explain <file> [--dir <dir>]  Print what loads once Claude reads or edits file\n\nOptions:\n  --port <n>            Port to listen on (default: a free port)\n  --no-open             Print the URL instead of opening a browser\n  --config-dir <path>   Claude folder to read, as CLAUDE_CONFIG_DIR sets it for Claude Code\n                        (wins over $CLAUDE_CONFIG_DIR)\n  --dir <dir>           For explain: the folder the session starts in (default: the current one)\n  -h, --help            Show this help\n\nccdesk reads ~/.claude (or --config-dir, or $CLAUDE_CONFIG_DIR). The page opens on the directory\nyou run ccdesk from and listens on 127.0.0.1 only. dir and file are relative to that directory.\nscan and explain write nothing and print no value the page hides.";
+/** The port `--dev` listens on, which `pnpm dev:ui` proxies to. */
+export declare const DEV_PORT = 4319;
+/** What `ccdesk` was asked to do. */
+export type Command = {
+    command: "help";
+} | {
+    command: "serve";
+    port: number;
+    configDir: string | undefined;
+    open: boolean;
+    /** Serve the API only, on DEV_PORT with a fixed token, for the Vite dev server. */
+    dev: boolean;
+}
+/** Print the DirectoryView of `dir` (default: the current one) as JSON. */
+ | {
+    command: "scan";
+    dir: string | undefined;
+    configDir: string | undefined;
+}
+/** Print what loads once Claude touches `file` in a session started in `dir`. */
+ | {
+    command: "explain";
+    file: string;
+    dir: string | undefined;
+    configDir: string | undefined;
+};
+/** Arguments ccdesk cannot run with; the message is what to print. */
+export declare class UsageError extends Error {
+}
+/** Reads the arguments after `ccdesk`, without touching the file system. */
+export declare function parse(argv: string[]): Command;

package/dist/server/args.js

@@ -0,0 +1,106 @@
+import { parseArgs } from "node:util";
+export const HELP = `ccdesk: see and change what Claude Code loads on this machine
+
+Usage:
+  npx ccdesk [options]                     Open the page in your browser
+  npx ccdesk scan [dir] --json             Print what Claude Code loads in dir, as JSON
+  npx ccdesk explain <file> [--dir <dir>]  Print what loads once Claude reads or edits file
+
+Options:
+  --port <n>            Port to listen on (default: a free port)
+  --no-open             Print the URL instead of opening a browser
+  --config-dir <path>   Claude folder to read, as CLAUDE_CONFIG_DIR sets it for Claude Code
+                        (wins over $CLAUDE_CONFIG_DIR)
+  --dir <dir>           For explain: the folder the session starts in (default: the current one)
+  -h, --help            Show this help
+
+ccdesk reads ~/.claude (or --config-dir, or $CLAUDE_CONFIG_DIR). The page opens on the directory
+you run ccdesk from and listens on 127.0.0.1 only. dir and file are relative to that directory.
+scan and explain write nothing and print no value the page hides.`;
+/** The port `--dev` listens on, which `pnpm dev:ui` proxies to. */
+export const DEV_PORT = 4319;
+/** Arguments ccdesk cannot run with; the message is what to print. */
+export class UsageError extends Error {
+}
+/** The flags each command takes; --help goes with any. */
+const FLAGS = {
+    serve: ["port", "open", "dev", "config-dir"],
+    scan: ["json", "config-dir"],
+    explain: ["dir", "config-dir"],
+};
+/** Reads the arguments after `ccdesk`, without touching the file system. */
+export function parse(argv) {
+    let parsed;
+    try {
+        parsed = options(argv);
+    }
+    catch (error) {
+        throw usage(error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help)
+        return { command: "help" };
+    const [first, ...rest] = positionals;
+    const name = commandOf(first);
+    for (const flag of Object.keys(values))
+        if (!FLAGS[name].includes(flag))
+            throw usage(`--${flag} does not go with ${name === "serve" ? "the page" : name}`);
+    const configDir = values["config-dir"];
+    if (name === "scan") {
+        if (rest.length > 1)
+            throw usage("scan takes one dir");
+        if (!values.json)
+            throw usage("scan prints JSON; pass --json");
+        return { command: "scan", dir: rest[0], configDir };
+    }
+    if (name === "explain") {
+        const [file, ...extra] = rest;
+        if (file === undefined || extra.length > 0)
+            throw usage("explain takes one file");
+        return { command: "explain", file, dir: values.dir, configDir };
+    }
+    return {
+        command: "serve",
+        port: portOf(values),
+        configDir,
+        open: values.open ?? true,
+        dev: values.dev ?? false,
+    };
+}
+/** The command the first word names; without one, the page. */
+function commandOf(first) {
+    if (first === undefined)
+        return "serve";
+    if (first === "scan" || first === "explain")
+        return first;
+    throw usage(`unknown command ${first}`);
+}
+/** The port to serve on: --port, the dev server's with --dev, or else any free one. */
+function portOf(values) {
+    if (!values.port)
+        return values.dev ? DEV_PORT : 0;
+    const port = Number(values.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw usage(`invalid --port ${values.port}`);
+    return port;
+}
+function usage(message) {
+    return new UsageError(`ccdesk: ${message}\n\n${HELP}`);
+}
+/** The flags as given: one left out is absent, so each command can refuse the others' flags. */
+function options(args) {
+    return parseArgs({
+        args,
+        options: {
+            port: { type: "string" },
+            "config-dir": { type: "string" },
+            open: { type: "boolean" },
+            dev: { type: "boolean" },
+            json: { type: "boolean" },
+            dir: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        allowNegative: true,
+    });
+}

package/dist/server/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server/cli.js

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

package/dist/server/commands.d.ts

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

package/dist/server/commands.js

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

package/dist/server/server.d.ts

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