ccdesk 0.2.1 → 0.2.3

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

@@ -1,11 +1,13 @@
 import { watch } from "node:fs";
 import { stat } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { storeDirName } from "../shared/memory.js";
 import {} from "../shared/types.js";
 import {} from "./scan/env.js";
-import { isNetworkPath, mainWorktreeRoot } from "./scan/files.js";
+import { isDir, isFile, isNetworkPath } from "./scan/files.js";
+import { mainWorktreeRoot } from "./scan/git.js";
 import { scanDirectory } from "./scan/index.js";
+import { loadPlugin, manifestCommandMap, manifestPaths } from "./scan/plugins.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. */
@@ -31,7 +33,8 @@ async function targets(env, dir, extra) {
     const memoryKey = (await mainWorktreeRoot(dir)) ?? dir;
     const out = [
         ...claude(env.claudeDir),
-        { path: join(env.claudeDir, "plugins"), recursive: false },
+        // Only the install list: Windows reports a write deep in a plugin as a change to `cache`.
+        { path: join(env.claudeDir, "plugins"), recursive: false, names: ["installed_plugins.json"] },
         { path: join(env.claudeDir, "projects", storeDirName(memoryKey), "memory"), recursive: false },
         { path: env.managedDir, recursive: false },
         { path: join(env.managedDir, "managed-settings.d"), recursive: false },
@@ -53,11 +56,15 @@ async function targets(env, dir, extra) {
         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) {
+/**
+ * Files a scan read that the fixed list does not cover: a custom memory folder, imports, installed
+ * plugins. A missing import is watched too, so creating it shows up, even when its folder is missing
+ * as well.
+ */
+async function dependencies(env, view) {
     const files = view.instructions.flatMap((i) => [
         i.realPath ?? i.path,
-        ...i.imports.filter((r) => r.exists).map((r) => r.resolved),
+        ...i.imports.map((r) => r.resolved),
     ]);
     const byFolder = new Map();
     for (const file of files) {
@@ -65,19 +72,80 @@ export function dependencies(view) {
         names.add(basename(file));
         byFolder.set(dirname(file), names);
     }
+    const plugins = await Promise.all(view.inventory.plugins.map((p) => pluginTargets(env, view, p)));
     return [
         ...[...byFolder].map(([path, names]) => ({ path, recursive: false, names: [...names] })),
         ...(view.memory ? [{ path: view.memory.dir, recursive: false }] : []),
+        ...plugins.flat(),
+    ];
+}
+/** A plugin's folders the scan reads from, when they are not named in its manifest. */
+const PLUGIN_FOLDERS = ["agents", "skills", "commands", "output-styles", "hooks"];
+/** Manifest keys that name files or folders inside the plugin. */
+const PLUGIN_KEYS = ["agents", "skills", "commands", "outputStyles", "hooks", "mcpServers"];
+/**
+ * What the scan reads in a plugin: its manifest, .mcp.json, a skill at its root, its component
+ * folders and the paths its manifest names. Not the whole plugin, which can hold an MCP server's
+ * node_modules and files the server writes while it runs.
+ */
+async function pluginTargets(env, view, plugin) {
+    const root = plugin.installPath;
+    // A path from installed_plugins.json that is not absolute names no folder Claude Code would load.
+    if (!isAbsolute(root))
+        return [];
+    // The scan reports a manifest that does not parse; here it only names paths to watch.
+    const loaded = await loadPlugin(env, plugin, []);
+    const named = await Promise.all(PLUGIN_KEYS.map((key) => manifestPaths(loaded, key)));
+    const commands = await manifestCommandMap(loaded);
+    // Without a skills folder, each folder at the root holding SKILL.md is a skill.
+    const rootSkills = view.inventory.skills
+        .filter((s) => s.plugin === plugin.id && s.folder && dirname(s.folder) === root)
+        .map((s) => s.folder);
+    const paths = [
+        ...PLUGIN_FOLDERS.map((name) => join(root, name)),
+        ...named.flatMap((list) => list ?? []),
+        ...commands.map((c) => c.path),
+        ...rootSkills,
+    ];
+    const out = [
+        {
+            path: root,
+            recursive: false,
+            names: [".claude-plugin", ".mcp.json", "SKILL.md", ...PLUGIN_FOLDERS],
+        },
+        { path: join(root, ".claude-plugin"), recursive: false, names: ["plugin.json"] },
     ];
+    for (const path of new Set(paths)) {
+        if (await isDir(path))
+            out.push({ path, recursive: true });
+        else if (await isFile(path))
+            out.push({ path: dirname(path), recursive: false, names: [basename(path)] });
+    }
+    return out;
+}
+/**
+ * `target`, or when it does not exist yet, the nearest folder above it that does, watched for the
+ * next missing name only. Watching needs a folder that exists, and the watchers are rebuilt after
+ * every change, so each folder that appears moves the watch one level closer.
+ */
+async function nearestWatchable(target) {
+    if (isNetworkPath(target.path) || (await stat(target.path).catch(() => null)))
+        return target;
+    for (let missing = target.path; dirname(missing) !== missing; missing = dirname(missing)) {
+        const parent = dirname(missing);
+        if (await stat(parent).catch(() => null))
+            return { path: parent, recursive: false, names: [basename(missing)] };
+    }
+    return target;
 }
 /** One set of file watchers per directory a page is looking at, shared by its requests. */
 export class Watcher {
-    env;
-    scanOf;
     subscriptions = new Map();
     /** What the latest scan of each directory read, kept for a watch that starts after the scan. */
     scanned = new Map();
     latest = new Map();
+    env;
+    scanOf;
     constructor(env, scanOf = scanDirectory) {
         this.env = env;
         this.scanOf = scanOf;
@@ -91,11 +159,11 @@ export class Watcher {
         // Only a watched directory's view can be known to be current later.
         if (subscription)
             this.latest.set(view.path, { view, startedAt, stateFile });
-        const extra = dependencies(view);
+        const extra = await dependencies(this.env, view);
         this.scanned.set(view.path, extra);
         if (subscription && JSON.stringify(extra) !== JSON.stringify(subscription.extra)) {
             subscription.extra = extra;
-            void this.rewatch(view.path, subscription);
+            subscription.ready = this.rewatch(view.path, subscription);
         }
         return view;
     }
@@ -126,10 +194,12 @@ export class Watcher {
      * the last change time, whichever comes first.
      */
     async wait(dir, since, signal, timeoutMs = WAIT_MS) {
-        const subscription = await this.subscribe(dir);
+        const subscription = await this.watching(dir);
         clearTimeout(subscription.idle);
+        // Closed while its watchers were starting: there is nothing left to wait on.
+        const closed = this.subscriptions.get(dir) !== subscription;
         try {
-            if (subscription.changedAt <= since && !signal.aborted)
+            if (!closed && subscription.changedAt <= since && !signal.aborted)
                 await new Promise((resolve) => {
                     const done = () => {
                         clearTimeout(timer);
@@ -143,29 +213,63 @@ export class Watcher {
                 });
         }
         finally {
-            if (subscription.waiters.size === 0)
-                subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+            this.release(dir, subscription);
         }
         return { changed: subscription.changedAt > since, at: subscription.changedAt };
     }
+    /**
+     * 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.
+     */
+    async subscribe(dir, onChange) {
+        const subscription = await this.watching(dir);
+        // Closed while its watchers were starting: nothing will change.
+        if (this.subscriptions.get(dir) !== subscription)
+            return () => {
+                // Nothing was subscribed, so there is nothing to stop.
+            };
+        clearTimeout(subscription.idle);
+        // A function of its own, so the same onChange subscribed twice is unsubscribed twice.
+        const listener = () => onChange();
+        subscription.listeners.add(listener);
+        return () => {
+            if (subscription.listeners.delete(listener))
+                this.release(dir, subscription);
+        };
+    }
+    /** Drops the watchers of `dir` after a while once no one waits or listens for changes. */
+    release(dir, subscription) {
+        // A dropped subscription has nothing left to clean up later.
+        if (subscription.waiters.size === 0 &&
+            subscription.listeners.size === 0 &&
+            this.subscriptions.get(dir) === subscription)
+            subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+    }
     close() {
         for (const dir of [...this.subscriptions.keys()])
             this.drop(dir);
     }
-    async subscribe(dir) {
+    async watching(dir) {
         const existing = this.subscriptions.get(dir);
-        if (existing)
+        if (existing) {
+            // Watchers moving to a new target after a change are not watching it yet.
+            await existing.ready;
             return existing;
+        }
         const subscription = {
             watchers: [],
+            ready: Promise.resolve(),
             changedAt: 0,
             touchedAt: 0,
             watchingSince: Number.POSITIVE_INFINITY,
             waiters: new Set(),
+            listeners: new Set(),
             extra: this.scanned.get(dir) ?? [],
         };
         this.subscriptions.set(dir, subscription);
-        await this.rewatch(dir, subscription);
+        subscription.ready = this.rewatch(dir, subscription);
+        await subscription.ready;
         return subscription;
     }
     drop(dir) {
@@ -178,10 +282,14 @@ export class Watcher {
             w.close();
         this.subscriptions.delete(dir);
         this.latest.delete(dir);
+        // Pages still waiting are answered now, so no timer outlives the watcher.
+        for (const wake of [...subscription.waiters])
+            wake();
     }
     /** (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);
+        const extra = await Promise.all(subscription.extra.map(nearestWatchable));
+        const list = await targets(this.env, dir, extra);
         for (const w of subscription.watchers)
             w.close();
         subscription.watchers = [];
@@ -197,9 +305,10 @@ export class Watcher {
                     clearTimeout(subscription.settle);
                     subscription.settle = setTimeout(() => {
                         subscription.changedAt = Date.now();
-                        for (const wake of [...subscription.waiters])
+                        // First, so a subscriber that throws cannot leave the old watchers in place.
+                        subscription.ready = this.rewatch(dir, subscription);
+                        for (const wake of [...subscription.waiters, ...subscription.listeners])
                             wake();
-                        void this.rewatch(dir, subscription);
                     }, SETTLE_MS);
                 });
                 watcher.on("error", () => watcher.close());

package/dist/core/write.d.ts

@@ -0,0 +1,119 @@
+import { type Static, Type } from "typebox";
+import { type BackupKind } from "../shared/types.ts";
+import { type ScanEnv } from "./scan/env.ts";
+/** A change ccdesk refuses on purpose; the server answers 409 with the message. */
+export declare class RefusedError extends Error {
+}
+/** A write refused because its file changed after review: nothing was written. */
+export declare class StaleError extends RefusedError {
+}
+/**
+ * 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 one; helpers it calls must not.
+ */
+export type Serially = <T>(change: () => Promise<T>) => Promise<T>;
+/** A new, empty queue of changes. Each core has its own. */
+export declare function changeQueue(): Serially;
+/** The queue the save functions use when they are called without a core's. */
+export declare const serially: Serially;
+/** What every change's review has: the revision it was worked out from and why it cannot be saved. */
+interface Review {
+    /** Fingerprint of everything the change was worked out from. */
+    revision: string;
+    /** When there are any, nothing is saved. */
+    errors?: string[];
+}
+/** A change worked out from disk as it is now: what it shows for review, and how to make it. */
+export interface Planned<Preview extends Review, T> {
+    preview: Preview;
+    save: () => Promise<T>;
+}
+/**
+ * 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 declare function saveReviewed<T>(queue: Serially, plan: () => Promise<Planned<Review, T>>, expectedRevision: string, changed: string): Promise<T>;
+export declare function backupRoot(env: ScanEnv): string;
+/** The file's text, or null when it does not exist. Any other read error is thrown, not hidden. */
+export declare function readIfExists(env: ScanEnv, path: string): Promise<string | null>;
+/**
+ * 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 declare function readJsonObject(env: ScanEnv, path: string): Promise<{
+    raw: string | null;
+    data: Record<string, unknown>;
+    reformats: boolean;
+}>;
+/**
+ * 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
+ * an edit made elsewhere while ccdesk was saving is kept and the save refused. A symlink is written
+ * through, so links into a dotfiles repository survive; the temporary file is new, unguessable and
+ * created exclusively, so nothing planted beside the target can redirect the write. A file with
+ * other hard links is refused, since the rename would leave them on the old text.
+ */
+export declare function writeAtomic(env: ScanEnv, path: string, content: string, expected: string): Promise<void>;
+/**
+ * Deletes a file only while it still has `expected` revision, and says whether it did. The file is
+ * renamed aside first, so what is removed is exactly what was checked; one that differs is put
+ * back, unless a new file took its place meanwhile, which ccdesk then refuses to overwrite.
+ */
+export declare function removeExactly(path: string, expected: string): Promise<boolean>;
+/** What a backup folder records about its change, in its manifest. */
+export declare const BackupManifestSchema: Type.TObject<{
+    kind: Type.TEnum<["settings", "mcp", "agent", "memory-index", "memory-delete", "memory-restore", "mcp-claude"]>;
+    /** The file that changed (for a deleted memory: the memory file). */
+    target: Type.TString;
+    createdAt: Type.TString;
+    /** Revision of the target before the change; "missing" when ccdesk created it. */
+    before: Type.TString;
+    /** Revision of the target right after the change; "pending" while it runs, "partial" when it failed halfway. */
+    after: Type.TString;
+    /** For a deleted memory: the MEMORY.md lines removed with it. */
+    removedIndexLines: Type.TOptional<Type.TArray<Type.TString>>;
+    /** For a change made through `claude mcp`: the commands that put it back, values hidden. */
+    undoCommands: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export type BackupManifest = Static<typeof BackupManifestSchema>;
+export declare const MANIFEST = "ccdesk-backup.json";
+/** Takes a change out of Recent changes, for one whose effect was undone again right away. */
+export declare function forgetChange(env: ScanEnv, id: string): Promise<void>;
+/** The copy of the target inside a backup folder. */
+export declare const SNAPSHOT = "before";
+/** For a change made through `claude mcp`: the affected servers after it, values hidden. */
+export declare const SHOWN_AFTER = "after";
+/**
+ * Lists a change Claude Code made through `claude mcp` in Recent changes. ccdesk cannot undo it,
+ * so it keeps only the affected servers before and after as the page shows them, secrets hidden,
+ * and the commands that would put them back; never a value the page does not show.
+ */
+export declare function recordClaudeMcpChange(env: ScanEnv, record: {
+    target: string;
+    shownBefore: string;
+    shownAfter: string;
+    undoCommands: string[];
+}): Promise<void>;
+/**
+ * Makes a change and records it in Recent changes. The file's previous text and a manifest are put
+ * in a new backup folder first, so a change interrupted halfway can still be restored; the manifest
+ * gets the new revision once the change is made. A change that fails is removed from Recent changes
+ * when its first write was refused as stale, or when `unchanged` confirms nothing on disk moved;
+ * otherwise it stays, marked partial, so it can be put back. Backups can hold settings with secrets, so only the user can read them.
+ */
+export declare function recordChange<T extends {
+    revision: string;
+}>(env: ScanEnv, record: {
+    kind: BackupKind;
+    target: string;
+    before: string | null;
+    removedIndexLines?: string[];
+    /** Whether disk is still as before the change; by default, whether the target is. */
+    unchanged?: () => Promise<boolean>;
+}, change: () => Promise<T>): Promise<T & {
+    id: string;
+    created: boolean;
+}>;
+export {};

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 } 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,32 @@ 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;
+    };
+}
+/** The queue the save functions use when they are called without a core's. */
+export const serially = changeQueue();
 /**
- * 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 +80,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 = 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, 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 +172,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 {};