artshelf 0.7.0 → 0.9.0

package/dist/src/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { appendPreparedRecord, createCleanupPlan, createTrashPurgePlan, dueEntries, executeCleanupPlan, executeTrashPurgePlan, filterRecordsByStatus, findRecords, getRecord, listTrashedRecords, normalizeLedgerPath, prepareRecord, previewCleanupPlan, readLedger, resolveRecord, validateLedger } from "./ledger.js";
 import { listRegisteredLedgers, normalizeRegistryPath, registerLedger } from "./registry.js";
 const VERSION = readPackageVersion();
+const PACKAGE_NAME = "artshelf";
+const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
@@ -29,56 +35,83 @@ function readPackageVersion() {
     }
     return packageJson.version;
 }
-function main(argv) {
+async function main(argv) {
     try {
         const parsed = parseArgs(argv);
+        let status = 0;
+        let shouldCheckForUpdate = true;
         if (parsed.command === "--version" || parsed.command === "-v" || boolFlag(parsed, "version")) {
             process.stdout.write(`artshelf ${VERSION}\n`);
-            return 0;
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         if (parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || boolFlag(parsed, "help")) {
-            printHelp(parsed.command === "help" ? parsed.positionals[0] : parsed.command);
-            return 0;
+            printHelp(resolveHelpKey(parsed));
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         switch (parsed.command) {
             case "put":
-                return handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "ledgers":
-                return handleLedgers(parsed, boolFlag(parsed, "json"));
+                status = handleLedgers(parsed, boolFlag(parsed, "json"));
+                break;
             case "list":
-                return handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "find":
-                return handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "get":
-                return handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "due":
-                return handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "validate":
-                return handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "cleanup":
-                return handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "trash":
-                return handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "review":
-                return handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "doctor":
-                return handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "status":
-                return handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "resolve":
-                return handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
+            case "update":
+                shouldCheckForUpdate = false;
+                status = await handleUpdate(parsed, boolFlag(parsed, "json"));
+                break;
             case undefined:
                 printHelp();
-                return 0;
+                status = 0;
+                break;
             default:
                 throw new Error(`Unknown command: ${parsed.command}`);
         }
+        if (!shouldCheckForUpdate)
+            return status;
+        return maybeNotifyUpdateAndReturn(status, parsed);
     }
     catch (error) {
         process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
         return 1;
     }
 }
+async function maybeNotifyUpdateAndReturn(status, parsed) {
+    await maybeNotifyAvailableUpdate(parsed);
+    return status;
+}
 function handlePut(parsed, ledgerPath, json) {
     const path = parsed.positionals[0];
     if (!path)
@@ -114,6 +147,10 @@ function handlePut(parsed, ledgerPath, json) {
 function handleLedgers(parsed, json) {
     const action = parsed.positionals[0] ?? "list";
     const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
+    if (action === "help") {
+        printHelp("ledgers");
+        return 0;
+    }
     if (action === "add") {
         const ledgerPath = normalizeLedgerPath(requiredStringFlag(parsed, "ledger"));
         if (!existsSync(ledgerPath))
@@ -726,6 +763,189 @@ function printStatusSingle(ledger) {
             process.stdout.write(`error: ${message}\n`);
     }
 }
+async function handleUpdate(parsed, json) {
+    if (parsed.positionals.length > 0)
+        throw new Error("update does not accept positional arguments");
+    const info = await getUpdateInfo({ force: true });
+    if (!info)
+        throw new Error("Could not check npm for the latest Artshelf version");
+    if (!info.updateAvailable) {
+        if (json)
+            return printJson({ ok: true, updated: false, current: info.current, latest: info.latest });
+        process.stdout.write(`artshelf is already up to date: v${info.current}\n`);
+        return 0;
+    }
+    if (process.env.ARTSHELF_UPDATE_DRY_RUN === "1") {
+        if (json) {
+            return printJson({
+                ok: true,
+                updated: false,
+                dryRun: true,
+                current: info.current,
+                latest: info.latest,
+                command: ["npm", "install", "-g", `${PACKAGE_NAME}@latest`]
+            });
+        }
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Dry run: would run "npm install -g ${PACKAGE_NAME}@latest"\n`);
+        return 0;
+    }
+    if (!json) {
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Updating with "npm install -g ${PACKAGE_NAME}@latest"...\n`);
+    }
+    const result = json
+        ? spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { encoding: "utf8" })
+        : spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { stdio: "inherit" });
+    const status = result.status ?? 1;
+    const spawnError = result.error instanceof Error ? result.error.message : "";
+    if (json) {
+        const stderr = typeof result.stderr === "string" ? result.stderr : "";
+        printJson({
+            ok: status === 0,
+            updated: status === 0,
+            current: info.current,
+            latest: info.latest,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: appendOutputMessage(stderr, spawnError)
+        });
+        return status;
+    }
+    if (spawnError)
+        process.stderr.write(`Update failed: ${spawnError}\n`);
+    if (status === 0)
+        process.stdout.write(`artshelf updated to v${info.latest}\n`);
+    return status;
+}
+function appendOutputMessage(output, message) {
+    if (!message)
+        return output;
+    if (!output)
+        return message;
+    return `${output}${output.endsWith("\n") ? "" : "\n"}${message}`;
+}
+async function maybeNotifyAvailableUpdate(parsed) {
+    if (process.env.ARTSHELF_NO_UPDATE_CHECK === "1")
+        return;
+    if (parsed.command === "update")
+        return;
+    const info = await getUpdateInfo({ force: false });
+    if (!info?.updateAvailable)
+        return;
+    process.stderr.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+    process.stderr.write(`Run "artshelf update" to update npm installs\n`);
+}
+async function getUpdateInfo(options) {
+    const latest = await getLatestVersion(options);
+    if (!latest)
+        return null;
+    return {
+        current: VERSION,
+        latest,
+        updateAvailable: compareVersions(latest, VERSION) > 0
+    };
+}
+async function getLatestVersion(options) {
+    const override = process.env.ARTSHELF_LATEST_VERSION;
+    if (override)
+        return normalizeVersion(override);
+    if (!options.force) {
+        const cached = readUpdateCache();
+        if (cached)
+            return cached.latest;
+    }
+    const latest = await fetchLatestNpmVersion();
+    writeUpdateCache(latest);
+    return latest;
+}
+function readUpdateCache() {
+    const ttl = Number(process.env.ARTSHELF_UPDATE_CHECK_TTL_MS ?? UPDATE_CHECK_TTL_MS);
+    if (ttl < 0)
+        return null;
+    const cachePath = updateCachePath();
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (cache.latest !== null && typeof cache.latest !== "string")
+            return null;
+        if (typeof cache.checkedAt !== "number")
+            return null;
+        if (Date.now() - cache.checkedAt > ttl)
+            return null;
+        return { latest: cache.latest === null ? null : normalizeVersion(cache.latest) };
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateCache(latest) {
+    try {
+        const cachePath = updateCachePath();
+        const dir = dirname(cachePath);
+        if (dir) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(cachePath, `${JSON.stringify({ latest, checkedAt: Date.now() }, null, 2)}\n`);
+        }
+    }
+    catch {
+        // Update checks should never affect normal CLI behavior.
+    }
+}
+async function fetchLatestNpmVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 750);
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": `artshelf/${VERSION}` }
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (!body || typeof body !== "object" || typeof body.version !== "string")
+            return null;
+        return normalizeVersion(body.version);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function updateCachePath() {
+    return process.env.ARTSHELF_UPDATE_CACHE ?? join(homedir(), ".artshelf", "update-check.json");
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/i, "");
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < Math.max(a.numbers.length, b.numbers.length); index += 1) {
+        const diff = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function parseVersion(version) {
+    const [main = "", prerelease = ""] = normalizeVersion(version).split("-", 2);
+    return {
+        numbers: main.split(".").map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }),
+        prerelease
+    };
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = new Map();
@@ -734,6 +954,14 @@ function parseArgs(argv) {
         const arg = rest[index];
         if (!arg)
             continue;
+        if (arg === "-h") {
+            flags.set("help", true);
+            continue;
+        }
+        if (arg === "-v") {
+            flags.set("version", true);
+            continue;
+        }
         if (!arg.startsWith("--")) {
             positionals.push(arg);
             continue;
@@ -958,7 +1186,93 @@ function printReview(results) {
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function printHelp(command) {
+const COMMAND_GROUPS = [
+    {
+        group: "Create",
+        commands: [{ name: "put", summary: "Record an artifact with a reason and retention" }]
+    },
+    {
+        group: "Inspect",
+        commands: [
+            { name: "list", summary: "List ledger records" },
+            { name: "find", summary: "Find records by path, owner, label, or status" },
+            { name: "get", summary: "Show one record by id" },
+            { name: "due", summary: "Show due, manual-review, and missing-path records" },
+            { name: "status", summary: "Summarize ledger and registry counts" }
+        ]
+    },
+    {
+        group: "Review",
+        commands: [
+            { name: "validate", summary: "Check ledger shape and report warnings" },
+            { name: "review", summary: "Preview validate, due, and cleanup plans (read-only)" }
+        ]
+    },
+    {
+        group: "Clean",
+        commands: [
+            { name: "cleanup", summary: "Plan and execute approved cleanups" },
+            { name: "trash", summary: "Inspect and purge Artshelf trash" },
+            { name: "resolve", summary: "Mark a record manually resolved" }
+        ]
+    },
+    {
+        group: "System",
+        commands: [
+            { name: "ledgers", summary: "Manage the ledger registry" },
+            { name: "doctor", summary: "Report Artshelf health on this machine" },
+            { name: "update", summary: "Update the Artshelf CLI" }
+        ]
+    }
+];
+// Commands with subcommands that carry their own focused help. Used to route
+// `artshelf <command> <subcommand> --help` to a nested help key.
+const NESTED_HELP = new Map([
+    ["trash", new Set(["list", "purge"])],
+    ["ledgers", new Set(["list", "add"])]
+]);
+function resolveHelpKey(parsed) {
+    // `artshelf help [command [subcommand]]`
+    if (parsed.command === "help") {
+        return joinHelpKey(parsed.positionals[0], parsed.positionals[1]);
+    }
+    // `artshelf [--help|-h]` with no command resolves to the top-level help.
+    if (!parsed.command || parsed.command === "--help" || parsed.command === "-h") {
+        return "";
+    }
+    // `artshelf <command> [subcommand] --help`
+    return joinHelpKey(parsed.command, parsed.positionals[0]);
+}
+function joinHelpKey(command, subcommand) {
+    if (!command)
+        return "";
+    const subcommands = NESTED_HELP.get(command);
+    if (subcommands && subcommand && subcommands.has(subcommand)) {
+        return `${command} ${subcommand}`;
+    }
+    return command;
+}
+function renderTopLevelHelp() {
+    const names = COMMAND_GROUPS.flatMap((entry) => entry.commands.map((command) => command.name));
+    const width = Math.max(...names.map((name) => name.length)) + 2;
+    const lines = [
+        `Artshelf ${VERSION} — approval-first retention for the temporary files agents leave behind.`,
+        "",
+        "Usage:",
+        "  artshelf <command> [options]",
+        "",
+        "Available Commands:"
+    ];
+    for (const { group, commands } of COMMAND_GROUPS) {
+        lines.push(`  ${group}`);
+        for (const command of commands) {
+            lines.push(`    ${command.name.padEnd(width)}${command.summary}`);
+        }
+    }
+    lines.push("", "Global Options:", "  -h, --help     Show help for artshelf or a specific command", "  -v, --version  Show the Artshelf version", "", "Output:", "  --json       Emit machine-readable JSON on commands that return data", "", "Scope (command-specific):", "  --ledger <path>     Target an explicit JSONL ledger", "  --registry <path>   Target an explicit ledger registry", "  --all               Read every registered ledger (on commands that support it)", "", `Use "artshelf <command> --help" for more information about a command.`, "");
+    return lines.join("\n");
+}
+function printHelp(command = "") {
     if (command === "put") {
         process.stdout.write(`Usage:
   artshelf put <path> --reason <text> (--ttl <ttl>|--retain-until <date>|--manual-review) [options]
@@ -992,30 +1306,36 @@ Global --all mode is dry-run only.
         return;
     }
     if (command === "trash") {
-        process.stdout.write(`Usage:
-  artshelf trash list [--ledger <path>] [--all] [--json]
-  artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
-  artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
+        process.stdout.write(`Inspect and purge Artshelf trash.
+
+Usage:
+  artshelf trash [command]
+
+Available Commands:
+  list      List records currently held in Artshelf trash
+  purge     Plan or execute approved permanent trash deletion
 
-Trash is approval-first. Use list to inspect what is currently in Artshelf trash and
-dry-run purge to generate a reviewed plan id for age-based deletion. Purge
-requires either --dry-run or --execute. Execute requires a reviewed plan id, and
-trash purge is always scoped to one --ledger; --all is not supported for purge
-(only for trash list).
-Trash receipt artifacts are registered when purge executes. Completed receipts are
-refused on repeat execute; started receipts from interrupted purges may be resumed
-and reconciled. Purged records are resolved and no longer reappear as trashed.
+Flags:
+  -h, --help   help for trash
+
+Use "artshelf trash <command> --help" for more information about a command.
 `);
         return;
     }
     if (command === "ledgers") {
-        process.stdout.write(`Usage:
-  artshelf ledgers list [--plain] [--registry <path>] [--json]
-  artshelf ledgers add --ledger <path> [--name <name>] [--scope repo|user|other] [--registry <path>] [--json]
+        process.stdout.write(`Manage the ledger registry.
+
+Usage:
+  artshelf ledgers [command]
+
+Available Commands:
+  list      List and validate registered ledgers
+  add       Register an existing ledger file
 
-The ledger registry is a global index of known ledgers. It gives Artshelf one read-only entry point without moving project records into one global ledger.
-By default \`list\` validates each registered ledger and reports ok/missing/invalid status, entry counts, and warning/error counts so agents can spot stale registry entries without a separate validate pass; it exits non-zero when the registry or any registered ledger is broken.
-Use \`--plain\` for the fast path that lists registered ledgers without reading them.
+Flags:
+  -h, --help   help for ledgers
+
+Use "artshelf ledgers <command> --help" for more information about a command.
 `);
         return;
     }
@@ -1110,48 +1430,120 @@ or receipts and never mutates records. A healthy selected ledger exits 0; with
 `);
         return;
     }
-    process.stdout.write(`Artshelf ${VERSION}
+    if (command === "update") {
+        process.stdout.write(`Usage:
+  artshelf update [--json]
 
-Usage:
-  artshelf put <path> --reason <text> (--ttl <ttl>|--retain-until <date>|--manual-review)
-  artshelf ledgers list [--plain] [--json]
-  artshelf ledgers add --ledger <path> [--name <name>] [--json]
-  artshelf list [--json]
-  artshelf list --all [--json]
-  artshelf list --status active [--json]
-  artshelf find --path <path> [--json]
-  artshelf find --all --owner <name> [--json]
-  artshelf get <id> [--json]
-  artshelf get <id> --all [--json]
-  artshelf due [--json]
-  artshelf due --all [--json]
-  artshelf validate [--json]
-  artshelf validate --all [--json]
-  artshelf review [--json]
-  artshelf review --all [--json]
-  artshelf doctor [--json]
-  artshelf status [--json]
-  artshelf status --all [--json]
-  artshelf cleanup --dry-run [--json]
-  artshelf cleanup --dry-run --all [--json]
-  artshelf cleanup --execute --plan-id <id> [--json]
-  artshelf trash list [--all] [--ledger <path>] [--json]
+Update checks compare the current CLI version with the latest published npm
+version. Normal commands may print a non-blocking update notice to stderr when a
+newer version is available. Run update to upgrade npm global installs only:
+
+  npm install -g artshelf@latest
+
+pnpm global installs should update with pnpm add -g artshelf@latest; source
+installs should update by pulling, rebuilding, and linking the checkout.
+`);
+        return;
+    }
+    if (command === "due") {
+        process.stdout.write(`Usage:
+  artshelf due [--ledger <path>] [--json]
+  artshelf due --all [--registry <path>] [--json]
+
+Due lists records whose retention has elapsed or that need attention: due,
+manual-review, and missing-path entries. Kept entries are hidden in human output.
+Due is read-only and never moves files or writes plans.
+`);
+        return;
+    }
+    if (command === "validate") {
+        process.stdout.write(`Usage:
+  artshelf validate [--ledger <path>] [--json]
+  artshelf validate --all [--registry <path>] [--json]
+
+Validate checks ledger shape and reports errors and warnings, such as records
+that point at missing artifact paths, without changing anything. A clean ledger
+exits 0; shape errors exit non-zero. With --all it validates every registered
+ledger.
+`);
+        return;
+    }
+    if (command === "trash list") {
+        process.stdout.write(`Usage:
+  artshelf trash list [--ledger <path>] [--all] [--registry <path>] [--json]
+
+Options:
+  --ledger <path>          Use a specific ledger file
+  --all                     Include records from all registered ledgers
+  --registry <path>         Registry path used with --all
+  --json                    Emit machine-readable output
+
+Trash list shows records currently held in Artshelf trash without deleting anything.
+With --all it reports trashed records across every registered ledger.
+`);
+        return;
+    }
+    if (command === "trash purge") {
+        process.stdout.write(`Usage:
   artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
   artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
-  artshelf resolve <id> --status resolved --reason <text> [--json]
 
-Global options:
-  --ledger <path>        Use an explicit JSONL ledger
-  --registry <path>      Use an explicit ledger registry
-  --all                  Read all registered ledgers for supported commands
-  --json                 Emit machine-readable JSON
-  --help                 Show help
-  --version              Show version
+Options:
+  --older-than <ttl>        Purge trashed records older than this duration
+  --dry-run                 Build a reviewed purge plan and output a plan id
+  --execute                 Execute a reviewed purge plan
+  --plan-id <id>            Execute only this reviewed purge plan
+  --ledger <path>           Target one specific ledger
+  --json                    Emit machine-readable output
+
+Trash purge permanently deletes aged trash from a reviewed plan. --dry-run turns
+--older-than into a reviewed purge plan id; --execute deletes only that one reviewed
+plan id. Purge is always scoped to one --ledger; --all is not supported for purge.
+Completed receipts are refused on repeat execute; an interrupted purge may be resumed
+and reconciled.
+`);
+        return;
+    }
+    if (command === "ledgers list") {
+        process.stdout.write(`Usage:
+  artshelf ledgers list [--plain] [--registry <path>] [--json]
+
+Options:
+  --plain                  Skip ledger validation and list registrations directly
+  --registry <path>        Registry path to use
+  --json                   Emit machine-readable output
 
-Examples:
-  artshelf put tmp/run-output --reason "debug parser output" --ttl 3d --kind scratch
-  artshelf cleanup --dry-run --json
-  artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
+Ledgers list validates every registered ledger and reports ok/missing/invalid
+status, entry counts, and warnings so agents can spot stale registry entries
+without a separate validate pass. Use --plain for the fast path that lists
+registered ledgers without reading them. It exits non-zero when the registry or
+any registered ledger is broken.
 `);
+        return;
+    }
+    if (command === "ledgers add") {
+        process.stdout.write(`Usage:
+  artshelf ledgers add --ledger <path> [--name <name>] [--scope repo|user|other] [--registry <path>] [--json]
+
+Options:
+  --ledger <path>          Register this ledger file
+  --name <name>            Override the ledger display name
+  --scope <scope>          Registry scope: repo, user, or other
+  --registry <path>        Registry path to update
+  --json                   Emit machine-readable output
+
+Ledgers add registers an existing ledger file in the global registry so --all
+commands and the registry index can find it. The ledger file must already exist.
+`);
+        return;
+    }
+    process.stdout.write(renderTopLevelHelp());
 }
-process.exitCode = main(process.argv.slice(2));
+main(process.argv.slice(2))
+    .then((status) => {
+    process.exitCode = status;
+})
+    .catch((error) => {
+    process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
+    process.exitCode = 1;
+});