artshelf 0.10.0 → 0.10.2

package/dist/src/renderers/review.js

@@ -0,0 +1,159 @@
+import { attentionGlyph } from "./attention.js";
+import { statusCommand } from "./status.js";
+const REVIEW_SAFETY = {
+    dryRunOnly: true,
+    executeAllRefused: true,
+    noExecuteRan: true,
+    noResolveRan: true,
+    noDeleteRan: true
+};
+export function reviewNextAction(summary, scope, ledgerPath) {
+    const broken = summary.invalid + summary.stale;
+    const review = statusCommand(scope, "review", ledgerPath);
+    if (broken > 0) {
+        const repair = scope === "all" ? "re-register or fix the file" : "fix the file";
+        return `repair ${broken} broken ledger(s) above (${repair}), then re-run \`${review}\``;
+    }
+    if (summary.executable > 0) {
+        const dryRun = scope === "all" ? "artshelf cleanup --dry-run --all" : `artshelf cleanup --dry-run${ledgerPath ? ` --ledger ${ledgerPath}` : ""}`;
+        return `run \`${dryRun}\` to generate plans, then \`artshelf cleanup --execute --plan-id <id> --ledger <path>\` for each reviewed plan`;
+    }
+    if (summary.missingPath > 0) {
+        return "inspect missing-path entries and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+    }
+    return "nothing to do — no broken ledgers and no due, manual-review, missing-path, or executable cleanup entries";
+}
+export function printReviewAll(results, summary, nextAction, registryPath) {
+    const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath > 0;
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
+    process.stdout.write(`registry: ${registryPath} — ${summary.ledgers} ledgers (${summary.ok} ok, ${summary.invalid} invalid, ${summary.stale} stale)\n`);
+    printReview(results);
+    process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped}\n`);
+    process.stdout.write(`next: ${nextAction}\n`);
+}
+export function printReview(results) {
+    for (const result of results) {
+        const visibleDue = result.due.filter((entry) => entry.dueStatus !== "kept");
+        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0;
+        process.stdout.write(`${attentionGlyph(needsAttention)} [${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
+        process.stdout.write(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped\n`);
+        process.stdout.write(`ledger: ${result.ledger.path}\n`);
+    }
+}
+function buildReviewDecisions(results, scope) {
+    const readyForApproval = [];
+    const needsReviewFirst = [];
+    const blocked = [];
+    const review = scope === "all" ? "artshelf review --all" : "artshelf review";
+    for (const result of results) {
+        const { ledger, validate, due } = result;
+        if (!validate.ok) {
+            const status = result.ledgerExists ? "invalid" : "missing";
+            const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
+            blocked.push({
+                label: `Repair ${ledger.name} ledger (${status})`,
+                itemIds: [],
+                actionType: "fix-registry",
+                approvalTarget: null,
+                reason: validate.errors[0] ?? `${scope === "all" ? "registered ledger" : "ledger"} is ${status}`,
+                nextStep: `${repair}, then re-run \`${review}\``
+            });
+            continue;
+        }
+        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path");
+        const trashSafe = due.filter((entry) => entry.dueStatus === "due" && entry.cleanup === "trash");
+        const inspectItems = due.filter((entry) => entry.dueStatus === "manual-review" ||
+            (entry.dueStatus === "due" && (entry.cleanup === "review" || entry.cleanup === "delete")));
+        if (missingPath.length > 0) {
+            const ids = missingPath.map((entry) => entry.id).sort();
+            readyForApproval.push({
+                label: `Resolve ${ids.length} missing-path record(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "resolve-missing",
+                approvalTarget: `approve artshelf resolve missing ledger ${ledger.path} ids ${ids.join(" ")}`,
+                reason: "the recorded path is already missing",
+                nextStep: "confirm the artifact is no longer needed, then approve the ledger-only resolve"
+            });
+        }
+        if (trashSafe.length > 0) {
+            const ids = trashSafe.map((entry) => entry.id).sort();
+            needsReviewFirst.push({
+                label: `Plan cleanup for ${ids.length} trash-eligible artifact(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "cleanup",
+                approvalTarget: null,
+                reason: "disposable artifacts are due but no reviewed cleanup plan exists yet",
+                nextStep: `run \`artshelf cleanup --dry-run --ledger ${ledger.path} --json\`, then approve \`approve artshelf cleanup ledger ${ledger.path} plan <plan-id>\``
+            });
+        }
+        if (inspectItems.length > 0) {
+            const ids = inspectItems.map((entry) => entry.id).sort();
+            const hasDelete = inspectItems.some((entry) => entry.cleanup === "delete");
+            needsReviewFirst.push({
+                label: `Inspect ${ids.length} record(s) in ${ledger.name} before cleanup`,
+                itemIds: ids,
+                actionType: "inspect",
+                approvalTarget: null,
+                reason: hasDelete
+                    ? "records need manual review; cleanup=delete is refused and never deletes files"
+                    : "records are held for manual review before any cleanup",
+                nextStep: "inspect each path, then keep, change retention, resolve, or set cleanup=trash and plan a cleanup"
+            });
+        }
+    }
+    return { readyForApproval, needsReviewFirst, blocked };
+}
+function reviewCounts(summary) {
+    return {
+        due: summary.due,
+        manualReview: summary.manualReview,
+        missingPath: summary.missingPath,
+        executable: summary.executable,
+        skipped: summary.skipped
+    };
+}
+export function buildReviewAgentPacketAll(results, summary, registry) {
+    const groups = buildReviewDecisions(results, "all");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "all",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        registry,
+        ledgers: { total: summary.ledgers, ok: summary.ok, stale: summary.stale, invalid: summary.invalid },
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "all"),
+        verification: `artshelf review --all --agent --registry ${registry.path}`
+    };
+}
+export function buildReviewAgentPacketSingle(result, summary, ledgerPath) {
+    const groups = buildReviewDecisions([result], "single");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "single",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        ledgerPath,
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "single", ledgerPath),
+        verification: `artshelf review --agent --ledger ${ledgerPath}`
+    };
+}

package/dist/src/renderers/status.js

@@ -0,0 +1,112 @@
+import { attentionGlyph } from "./attention.js";
+const STATUS_ATTENTION_CATEGORIES = ["due", "manualReview", "missingPath", "pendingCleanup"];
+export function emptyStatusCounts() {
+    return { active: 0, due: 0, manualReview: 0, missingPath: 0, kept: 0, pendingCleanup: 0 };
+}
+export function sumStatusCounts(ledgers, key) {
+    return ledgers.reduce((total, ledger) => total + ledger.counts[key], 0);
+}
+export function statusAttention(counts) {
+    return STATUS_ATTENTION_CATEGORIES.filter((key) => counts[key] > 0);
+}
+export function statusCommand(scope, command, ledgerPath) {
+    if (scope === "all")
+        return `artshelf ${command} --all`;
+    return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
+}
+function statusNextAction(blockers, counts, scope, ledgerPath) {
+    if (blockers.length > 0) {
+        const verify = statusCommand(scope, "status", ledgerPath);
+        return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
+    }
+    const review = statusCommand(scope, "review", ledgerPath);
+    if (counts.pendingCleanup > 0 || counts.due > 0) {
+        return `run \`${review}\` to preview cleanup plans; nothing is auto-executed`;
+    }
+    if (counts.manualReview > 0) {
+        return `run \`${review}\` to inspect manual-review records; nothing is auto-executed`;
+    }
+    if (counts.missingPath > 0) {
+        return "inspect missing-path records and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+    }
+    return "nothing due — no broken ledgers and no due, manual-review, missing-path, or pending cleanup entries";
+}
+export function buildStatusAgentPacketAll(report) {
+    const blockers = [];
+    if (report.registryError)
+        blockers.push(`registry unreadable: ${report.registryError}`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status !== "ok") {
+            blockers.push(`${ledger.name} ${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`);
+        }
+    }
+    const counts = {
+        active: report.totals.active,
+        due: report.totals.due,
+        manualReview: report.totals.manualReview,
+        missingPath: report.totals.missingPath,
+        kept: report.totals.kept,
+        pendingCleanup: report.totals.pendingCleanup
+    };
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "all",
+        health: report.ok ? "ok" : "attention",
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: { total: report.totals.ledgers, ok: report.totals.ok, stale: report.totals.stale, invalid: report.totals.invalid },
+        counts,
+        attention: statusAttention(counts),
+        blockers,
+        nextAction: statusNextAction(blockers, counts, "all"),
+        verification: `artshelf status --all --agent --registry ${report.registryPath}`
+    };
+}
+export function buildStatusAgentPacketSingle(ledger, ledgerPath) {
+    const blockers = ledger.ok
+        ? []
+        : [`${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`];
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "single",
+        health: ledger.ok ? "ok" : "attention",
+        ledgerPath,
+        counts: ledger.counts,
+        attention: statusAttention(ledger.counts),
+        blockers,
+        nextAction: statusNextAction(blockers, ledger.counts, "single", ledgerPath),
+        verification: `artshelf status --agent --ledger ${ledgerPath}`
+    };
+}
+export function printStatusAll(report) {
+    const anyActionable = report.ledgers.some((ledger) => statusAttention(ledger.counts).length > 0);
+    process.stdout.write(`${attentionGlyph(!report.ok || anyActionable)} artshelf status: ${report.ok ? "ok" : "needs attention"}\n`);
+    process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"} — ${report.totals.ledgers} ledgers (${report.totals.ok} ok, ${report.totals.stale} stale, ${report.totals.invalid} invalid)\n`);
+    if (report.registryError)
+        process.stdout.write(`registry error: ${report.registryError}\n`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status === "ok") {
+            process.stdout.write(`${attentionGlyph(statusAttention(ledger.counts).length > 0)} [${ledger.name}] ${formatStatusCounts(ledger.counts)}\n`);
+        }
+        else {
+            process.stdout.write(`⚠ [${ledger.name}] ${ledger.status}: ${ledger.errors.join("; ")}\n`);
+        }
+    }
+    process.stdout.write(`total: ${formatStatusCounts(report.totals)}\n`);
+}
+export function printStatusSingle(ledger) {
+    const needsAttention = !ledger.ok || statusAttention(ledger.counts).length > 0;
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf status: ${ledger.ok ? "ok" : ledger.status}\n`);
+    process.stdout.write(`ledger: ${ledger.path}\n`);
+    if (ledger.ok) {
+        process.stdout.write(`${formatStatusCounts(ledger.counts)}\n`);
+    }
+    else {
+        for (const message of ledger.errors)
+            process.stdout.write(`error: ${message}\n`);
+    }
+}
+function formatStatusCounts(counts) {
+    return `active ${counts.active} · due ${counts.due} · manual-review ${counts.manualReview} · missing ${counts.missingPath} · kept ${counts.kept} · pending ${counts.pendingCleanup}`;
+}

package/dist/src/shared/cli-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/shared/errors.js

@@ -0,0 +1,4 @@
+export function formatCliError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `artshelf: ${message}\nRun \`artshelf help\` for usage.\n`;
+}

package/dist/src/shared/flags.js

@@ -0,0 +1,41 @@
+export const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
+export const VALUE_FLAGS = new Set([
+    "cleanup",
+    "kind",
+    "label",
+    "ledger",
+    "name",
+    "owner",
+    "path",
+    "plan-id",
+    "older-than",
+    "registry",
+    "reason",
+    "retain-until",
+    "scope",
+    "status",
+    "ttl"
+]);
+export function requiredStringFlag(parsed, name) {
+    const value = stringFlag(parsed, name);
+    if (!value)
+        throw new Error(`Missing required --${name}`);
+    return value;
+}
+export function stringFlag(parsed, name) {
+    const value = parsed.flags.get(name);
+    if (Array.isArray(value))
+        return value[value.length - 1];
+    return typeof value === "string" ? value : undefined;
+}
+export function boolFlag(parsed, name) {
+    return parsed.flags.get(name) === true;
+}
+export function arrayFlag(parsed, name) {
+    const value = parsed.flags.get(name);
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return [];
+}

package/dist/src/shared/help-text.js

@@ -0,0 +1,355 @@
+export const LEDGERS_HELP = `Manage the ledger registry.
+
+Usage:
+  artshelf ledgers [command]
+
+Available Commands:
+  list      List and validate registered ledgers
+  add       Register an existing ledger file
+
+Flags:
+  -h, --help   help for ledgers
+
+Use "artshelf ledgers <command> --help" for more information about a command.
+`;
+export const TRASH_HELP = `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
+
+Flags:
+  -h, --help   help for trash
+
+Use "artshelf trash <command> --help" for more information about a 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" }
+        ]
+    }
+];
+const NESTED_HELP = new Map([
+    ["trash", new Set(["list", "purge"])],
+    ["ledgers", new Set(["list", "add"])]
+]);
+export function resolveHelpKey(parsed) {
+    if (parsed.command === "help") {
+        return joinHelpKey(parsed.positionals[0], parsed.positionals[1]);
+    }
+    if (!parsed.command || parsed.command === "--help" || parsed.command === "-h") {
+        return "";
+    }
+    return joinHelpKey(parsed.command, parsed.positionals[0]);
+}
+export function renderHelp(command, version) {
+    if (command === "put") {
+        return `Usage:
+  artshelf put <path> --reason <text> (--ttl <ttl>|--retain-until <date>|--manual-review) [options]
+
+Options:
+  --kind scratch|backup|run-artifact|evidence|cache|quarantine|other
+  --cleanup trash|review|delete  (cleanup=delete is refused; trash purge needs a reviewed plan)
+  --owner <name>
+  --label <label>        Repeatable
+  --ledger <path>
+  --registry <path>
+  --json
+`;
+    }
+    if (command === "cleanup") {
+        return `Usage:
+  artshelf cleanup --dry-run [--ledger <path>] [--json]
+  artshelf cleanup --dry-run --all [--registry <path>] [--json]
+  artshelf cleanup --execute --plan-id <id> [--ledger <path>] [--json]
+
+Cleanup execution is approval-only. There is no daemon, no auto-execute, and no
+global execute path: review a dry-run plan, then execute that one reviewed plan id.
+Cleanup is ledger-first. Execute never computes a fresh live set; it only uses a reviewed plan id.
+cleanup=delete records cleanup-refused instead of deleting files; physical trash purge needs a separate reviewed plan.
+Dry-run writes and registers a plan only when executable cleanup entries exist; no-op dry-runs report not-created.
+Matching dry-runs reuse the existing plan id and refresh its Artshelf-owned plan artifact.
+Execute writes and registers an Artshelf-owned receipt artifact.
+Global --all mode is dry-run only.
+`;
+    }
+    if (command === "trash")
+        return TRASH_HELP;
+    if (command === "ledgers")
+        return LEDGERS_HELP;
+    if (command === "list") {
+        return `Usage:
+  artshelf list [--status <status>] [--ledger <path>] [--json]
+  artshelf list --all [--status <status>] [--registry <path>] [--json]
+
+Statuses:
+  active, review-required, trashed, cleanup-refused, resolved
+`;
+    }
+    if (command === "find") {
+        return `Usage:
+  artshelf find (--path <path>|--owner <name>|--label <label>|--status <status>) [options]
+  artshelf find --all (--path <path>|--owner <name>|--label <label>|--status <status>) [options]
+
+Options:
+  --path <path>          Match an exact artifact path after path normalization
+  --owner <name>
+  --label <label>        Repeatable; all labels must match
+  --status <status>
+  --ledger <path>
+  --registry <path>
+  --json
+
+Find is read-only. Use it before put when an integration needs idempotent artifact registration.
+`;
+    }
+    if (command === "get") {
+        return `Usage:
+  artshelf get <id> [--ledger <path>] [--json]
+  artshelf get <id> --all [--registry <path>] [--json]
+
+Get is read-only and returns one ledger record by Artshelf id.
+`;
+    }
+    if (command === "resolve") {
+        return `Usage:
+  artshelf resolve <id> --status resolved --reason <text> [--ledger <path>] [--json]
+
+Resolve marks a handled, missing, or no-longer-needed record as manually resolved.
+Resolved records stay in the audit trail but no longer participate in due or cleanup planning.
+`;
+    }
+    if (command === "review") {
+        return `Usage:
+  artshelf review [--ledger <path>] [--json|--agent]
+  artshelf review --all [--registry <path>] [--json|--agent]
+
+Review runs validate, due, and cleanup plan preview without moving files or
+writing a plan. With --all, review adds aggregate triage counts and the next
+safe action.
+
+Render modes:
+  (default)  Human summary of validation, triage counts, and the next safe action.
+  --json     Full read-only audit report (backward-compatible).
+  --agent    Compact single-line JSON decision packet for agents: health, triage
+             counts, and classified decision groups (ready for approval, needs
+             review first, blocked) with exact approval targets where they are
+             safe. Review is read-only, so cleanup approval targets are minted by
+             \`cleanup --dry-run\`, never leaked from a preview plan id.
+             Token-efficient; --agent takes precedence over --json.
+`;
+    }
+    if (command === "doctor") {
+        return `Usage:
+  artshelf doctor [--registry <path>] [--ledger <path>] [--json|--agent]
+
+Doctor reports whether Artshelf is healthy on this machine: CLI version, selected
+or default ledger path, selected or global registry path, registered ledger health
+(stale/missing/invalid), and the cleanup safety posture. Execute is scoped to one
+selected or default ledger and still requires a reviewed plan id; --all execute
+and cleanup=delete are refused, while physical trash purge requires a separate
+reviewed purge plan.
+
+Render modes:
+  (default)  Human summary of machine health and cleanup safety.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, registry
+             and registered-ledger health, blockers, cleanup-safety posture, next
+             action, and a verify command. Token-efficient; --agent takes
+             precedence over --json.
+
+Run it after install, when --all commands behave unexpectedly, or on a schedule to
+catch stale registry entries. Doctor is read-only. A healthy machine exits 0; a
+broken registry or registered ledger exits non-zero with actionable errors.
+`;
+    }
+    if (command === "status") {
+        return `Usage:
+  artshelf status [--ledger <path>] [--json|--agent]
+  artshelf status --all [--registry <path>] [--json|--agent]
+
+Status is the lightweight daily "what is going on?" view. Without --all, it
+reports counts for the selected or default ledger only. With --all, it adds
+registry health, total ledgers, and aggregated counts across registered ledgers.
+Counts include active artifacts, kept, due, manual-review, missing-path, and
+pending cleanup entries.
+
+Render modes:
+  (default)  Human summary, short enough to paste into a chat.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, counts,
+             attention categories, blockers, next action, and a verify command.
+             Token-efficient; --agent takes precedence over --json.
+
+Status is read-only: it never creates plans or receipts and never mutates
+records. A healthy selected ledger exits 0; with --all, a broken registry or any
+stale or invalid registered ledger exits non-zero.
+`;
+    }
+    if (command === "update") {
+        return `Usage:
+  artshelf update [--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.
+`;
+    }
+    if (command === "due") {
+        return `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.
+`;
+    }
+    if (command === "validate") {
+        return `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.
+`;
+    }
+    if (command === "trash list") {
+        return `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.
+`;
+    }
+    if (command === "trash purge") {
+        return `Usage:
+  artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
+  artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
+
+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.
+`;
+    }
+    if (command === "ledgers list") {
+        return `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
+
+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.
+`;
+    }
+    if (command === "ledgers add") {
+        return `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 renderTopLevelHelp(version);
+}
+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(version) {
+    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");
+}