artshelf 0.10.0 → 0.10.2

package/dist/src/commands/shared.js

@@ -0,0 +1,160 @@
+import { existsSync } from "node:fs";
+import { dueEntries, previewCleanupPlan, readLedger, validateLedger } from "../ledger.js";
+import { listRegisteredLedgers } from "../registry.js";
+import { printJson } from "../renderers/json.js";
+export function registeredLedgersOrThrow(registryPath) {
+    const ledgers = listRegisteredLedgers(registryPath);
+    if (ledgers.length === 0)
+        throw new Error("No registered Artshelf ledgers. Run `artshelf ledgers add --ledger <path>` first.");
+    return ledgers;
+}
+export function validateRegisteredLedgersOrThrow(registryPath) {
+    const results = registeredLedgersOrThrow(registryPath).map((ledger) => ({ ledger, result: validateRegisteredLedger(ledger) }));
+    return { ok: results.every((entry) => entry.result.ok), results };
+}
+export function printRegisteredLedgerValidation(registryPath, results, json) {
+    if (json) {
+        printJson({ ok: false, registryPath, ledgers: results });
+        return 1;
+    }
+    for (const entry of results.filter((item) => !item.result.ok)) {
+        process.stdout.write(`invalid ${entry.ledger.name}: ${entry.result.errors.join("; ")}\nledger: ${entry.ledger.path}\n`);
+    }
+    process.stdout.write(`registry: ${registryPath}\n`);
+    return 1;
+}
+export function validateRegisteredLedger(ledger) {
+    if (!existsSync(ledger.path)) {
+        return {
+            ok: false,
+            errors: [`registered ledger is missing: ${ledger.path}`],
+            warnings: [],
+            entries: 0
+        };
+    }
+    return validateLedger(ledger.path);
+}
+export function reviewLedger(ledger, registered = true) {
+    const validate = registered ? validateRegisteredLedger(ledger) : validateLedger(ledger.path);
+    const ledgerExists = existsSync(ledger.path);
+    if (!validate.ok) {
+        return {
+            ledger,
+            ledgerExists,
+            validate,
+            due: [],
+            plan: emptyReviewPlan(ledger.path)
+        };
+    }
+    return {
+        ledger,
+        ledgerExists,
+        validate,
+        due: dueEntries(readLedger(ledger.path)),
+        plan: previewCleanupPlan(ledger.path)
+    };
+}
+export function reviewJsonResult(result) {
+    const { ledgerExists: _ledgerExists, ...jsonResult } = result;
+    return jsonResult;
+}
+export function emptyReviewPlan(ledgerPath) {
+    return {
+        planId: "not-created",
+        generatedAt: "",
+        ledgerPath,
+        entries: [],
+        skipped: [],
+        planPath: null
+    };
+}
+export function printLedgerEntries(results, status) {
+    const total = results.reduce((count, result) => count + result.entries.length, 0);
+    if (total === 0) {
+        process.stdout.write(`no artshelf entries${status ? ` with status ${status}` : ""}\n`);
+        return;
+    }
+    for (const result of results) {
+        if (result.entries.length === 0)
+            continue;
+        process.stdout.write(`\n[${result.ledger.name}] ${result.ledger.path}\n`);
+        for (const record of result.entries) {
+            process.stdout.write(`${record.id} ${record.kind} ${record.status} ${record.cleanup} ${record.path} :: ${record.reason}\n`);
+        }
+    }
+}
+export function printDueEntries(results) {
+    const visible = results.flatMap((result) => result.entries.filter((entry) => entry.dueStatus !== "kept").map((entry) => ({ ledger: result.ledger, entry })));
+    if (visible.length === 0) {
+        process.stdout.write("nothing due\n");
+        return;
+    }
+    for (const item of visible) {
+        process.stdout.write(`${item.entry.dueStatus} ${item.entry.id} ${item.entry.cleanup} ${item.entry.path} :: ${item.entry.reason}\nledger: ${item.ledger.path}\n`);
+    }
+}
+export function printPlans(results) {
+    for (const result of results) {
+        process.stdout.write(`plan ${result.plan.planId} [${result.ledger.name}]: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped\n`);
+        process.stdout.write(`plan: ${result.plan.planPath ?? "not created"}\nledger: ${result.ledger.path}\n`);
+    }
+}
+export function printPlan(plan, ledgerPath) {
+    process.stdout.write(`plan ${plan.planId}: ${plan.entries.length} entries, ${plan.skipped.length} skipped\n`);
+    process.stdout.write(`plan: ${plan.planPath ?? "not created"}\nledger: ${ledgerPath}\n`);
+}
+export function printTrashListEntries(results) {
+    const total = results.reduce((count, result) => count + result.entries.length, 0);
+    if (total === 0) {
+        process.stdout.write("no trashed records\n");
+        return;
+    }
+    for (const result of results) {
+        if (result.entries.length === 0)
+            continue;
+        process.stdout.write(`\n[${result.ledger.name}] ${result.ledger.path}\n`);
+        for (const entry of result.entries) {
+            process.stdout.write(`trash ${entry.id} ${entry.age} ${entry.cleanedAt} ${entry.targetPath} -> ${entry.receiptPath} (${entry.cleanupPlanId})\n`);
+        }
+    }
+}
+export function summarizeReview(results) {
+    const summary = {
+        ledgers: results.length,
+        ok: 0,
+        invalid: 0,
+        stale: 0,
+        affected: 0,
+        due: 0,
+        manualReview: 0,
+        missingPath: 0,
+        executable: 0,
+        skipped: 0,
+        previewPlanIds: []
+    };
+    for (const result of results) {
+        if (result.validate.ok) {
+            summary.ok += 1;
+        }
+        else if (result.ledgerExists) {
+            summary.invalid += 1;
+        }
+        else {
+            summary.stale += 1;
+        }
+        const due = result.due.filter((entry) => entry.dueStatus === "due").length;
+        const manualReview = result.due.filter((entry) => entry.dueStatus === "manual-review").length;
+        const missingPath = result.due.filter((entry) => entry.dueStatus === "missing-path").length;
+        summary.due += due;
+        summary.manualReview += manualReview;
+        summary.missingPath += missingPath;
+        summary.executable += result.plan.entries.length;
+        summary.skipped += result.plan.skipped.length;
+        if (result.plan.planId !== "not-created")
+            summary.previewPlanIds.push(result.plan.planId);
+        if (!result.validate.ok || due + manualReview + missingPath > 0 || result.plan.entries.length > 0) {
+            summary.affected += 1;
+        }
+    }
+    return summary;
+}

package/dist/src/commands/status.js

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import { dueEntries, previewCleanupPlan, readLedger, validateLedger } from "../ledger.js";
+import { listRegisteredLedgers, normalizeRegistryPath } from "../registry.js";
+import { printCompactJson, printJson } from "../renderers/json.js";
+import { buildStatusAgentPacketAll, buildStatusAgentPacketSingle, emptyStatusCounts, printStatusAll, printStatusSingle, sumStatusCounts } from "../renderers/status.js";
+import { boolFlag, stringFlag } from "../shared/flags.js";
+import { validateRegisteredLedger } from "./shared.js";
+export function handleStatus(parsed, ledgerPath, json) {
+    const agent = boolFlag(parsed, "agent");
+    if (boolFlag(parsed, "all")) {
+        const report = buildStatusReport(normalizeRegistryPath(stringFlag(parsed, "registry")));
+        if (agent) {
+            printCompactJson(buildStatusAgentPacketAll(report));
+            return report.ok ? 0 : 1;
+        }
+        if (json) {
+            printJson(report);
+            return report.ok ? 0 : 1;
+        }
+        printStatusAll(report);
+        return report.ok ? 0 : 1;
+    }
+    const ledger = statusLedger({ name: "current", path: ledgerPath, scope: "other", createdAt: "", updatedAt: "" }, false);
+    if (agent) {
+        printCompactJson(buildStatusAgentPacketSingle(ledger, ledgerPath));
+        return ledger.ok ? 0 : 1;
+    }
+    if (json) {
+        printJson({ ok: ledger.ok, ledger });
+        return ledger.ok ? 0 : 1;
+    }
+    printStatusSingle(ledger);
+    return ledger.ok ? 0 : 1;
+}
+function buildStatusReport(registryPath) {
+    let registryOk = true;
+    let registryError = null;
+    let entries = [];
+    try {
+        entries = listRegisteredLedgers(registryPath);
+    }
+    catch (error) {
+        registryOk = false;
+        registryError = error.message;
+    }
+    const ledgers = entries.map((entry) => statusLedger(entry));
+    const totals = {
+        ledgers: ledgers.length,
+        ok: ledgers.filter((ledger) => ledger.status === "ok").length,
+        stale: ledgers.filter((ledger) => ledger.status === "missing").length,
+        invalid: ledgers.filter((ledger) => ledger.status === "invalid").length,
+        active: sumStatusCounts(ledgers, "active"),
+        due: sumStatusCounts(ledgers, "due"),
+        manualReview: sumStatusCounts(ledgers, "manualReview"),
+        missingPath: sumStatusCounts(ledgers, "missingPath"),
+        kept: sumStatusCounts(ledgers, "kept"),
+        pendingCleanup: sumStatusCounts(ledgers, "pendingCleanup")
+    };
+    return {
+        ok: registryOk && totals.stale === 0 && totals.invalid === 0,
+        registryPath,
+        registryExists: existsSync(registryPath),
+        registryOk,
+        registryError,
+        ledgers,
+        totals
+    };
+}
+function statusLedger(ledger, registered = true) {
+    const validate = registered ? validateRegisteredLedger(ledger) : validateLedger(ledger.path);
+    if (!validate.ok) {
+        return {
+            name: ledger.name,
+            path: ledger.path,
+            scope: ledger.scope,
+            status: existsSync(ledger.path) ? "invalid" : "missing",
+            ok: false,
+            counts: emptyStatusCounts(),
+            errors: validate.errors
+        };
+    }
+    const records = readLedger(ledger.path);
+    const due = dueEntries(records);
+    const counts = {
+        active: records.filter((record) => record.status === "active").length,
+        due: due.filter((entry) => entry.dueStatus === "due").length,
+        manualReview: due.filter((entry) => entry.dueStatus === "manual-review").length,
+        missingPath: due.filter((entry) => entry.dueStatus === "missing-path").length,
+        kept: due.filter((entry) => entry.dueStatus === "kept").length,
+        pendingCleanup: previewCleanupPlan(ledger.path).entries.length
+    };
+    return {
+        name: ledger.name,
+        path: ledger.path,
+        scope: ledger.scope,
+        status: "ok",
+        ok: true,
+        counts,
+        errors: []
+    };
+}

package/dist/src/commands/trash.js

@@ -0,0 +1,78 @@
+import { createTrashPurgePlan, executeTrashPurgePlan, listTrashedRecords } from "../ledger.js";
+import { normalizeRegistryPath } from "../registry.js";
+import { printJson } from "../renderers/json.js";
+import { boolFlag, requiredStringFlag, stringFlag } from "../shared/flags.js";
+import { TRASH_HELP } from "../shared/help-text.js";
+import { printRegisteredLedgerValidation, printTrashListEntries, validateRegisteredLedgersOrThrow } from "./shared.js";
+export function handleTrash(parsed, ledgerPath, json) {
+    const action = parsed.positionals[0];
+    if (!action)
+        throw new Error("trash requires a subcommand: list or purge");
+    if (action === "list") {
+        return handleTrashList(parsed, ledgerPath, json);
+    }
+    if (action === "purge") {
+        return handleTrashPurge(parsed, ledgerPath, json);
+    }
+    if (action === "help") {
+        process.stdout.write(TRASH_HELP);
+        return 0;
+    }
+    throw new Error(`Unknown trash subcommand: ${action}`);
+}
+export function handleTrashList(parsed, ledgerPath, json) {
+    if (boolFlag(parsed, "all")) {
+        const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
+        const validation = validateRegisteredLedgersOrThrow(registryPath);
+        if (!validation.ok)
+            return printRegisteredLedgerValidation(registryPath, validation.results, json);
+        const results = validation.results.map(({ ledger }) => ({ ledger, entries: listTrashedRecords(ledger.path) }));
+        if (json)
+            return printJson({ ok: true, registryPath, ledgers: results });
+        printTrashListEntries(results);
+        process.stdout.write(`registry: ${registryPath}\n`);
+        return 0;
+    }
+    const entries = listTrashedRecords(ledgerPath);
+    if (json)
+        return printJson({ ok: true, ledgerPath, entries });
+    if (entries.length === 0) {
+        process.stdout.write(`no trashed records\nledger: ${ledgerPath}\n`);
+        return 0;
+    }
+    for (const entry of entries) {
+        process.stdout.write(`${entry.id} age ${entry.age} target ${entry.targetPath} cleaned ${entry.cleanedAt} receipt ${entry.receiptPath} plan ${entry.cleanupPlanId}\n`);
+    }
+    process.stdout.write(`ledger: ${ledgerPath}\n`);
+    return 0;
+}
+export function handleTrashPurge(parsed, ledgerPath, json) {
+    const execute = boolFlag(parsed, "execute");
+    const dryRun = boolFlag(parsed, "dry-run");
+    if (dryRun && execute)
+        throw new Error("trash purge accepts either --dry-run or --execute, not both");
+    if (boolFlag(parsed, "all")) {
+        throw new Error("trash purge --all is not supported; scope the purge to one --ledger and review the plan id before execute");
+    }
+    if (!dryRun && !execute)
+        throw new Error("trash purge requires either --dry-run or --execute");
+    if (execute) {
+        const planId = requiredStringFlag(parsed, "plan-id");
+        const receipt = executeTrashPurgePlan(ledgerPath, planId);
+        if (json)
+            return printJson({ ok: true, receipt });
+        process.stdout.write(`trash receipt ${receipt.purgePlanId}: ${receipt.results.length} results\nreceipt: ${receipt.receiptPath}\nledger: ${ledgerPath}\n`);
+        return 0;
+    }
+    const olderThan = requiredStringFlag(parsed, "older-than");
+    const plan = createTrashPurgePlan(ledgerPath, olderThan);
+    if (json)
+        return printJson({ ok: true, plan });
+    if (plan.entries.length === 0) {
+        process.stdout.write(`trash purge plan ${plan.purgePlanId}: no matching trashed records\nledger: ${ledgerPath}\n`);
+        return 0;
+    }
+    process.stdout.write(`trash purge plan ${plan.purgePlanId}: ${plan.entries.length} entries, ${plan.skipped.length} skipped\n`);
+    process.stdout.write(`plan: ${plan.planPath ?? "not-created"}\nledger: ${ledgerPath}\n`);
+    return 0;
+}

package/dist/src/commands/update.js

@@ -0,0 +1,75 @@
+import { PACKAGE_NAME } from "../config/package.js";
+import { updateCheckDisabled, updateDryRunEnabled } from "../config/env.js";
+import { installGlobalNpmPackage } from "../adapters/process.js";
+import { printJson } from "../renderers/json.js";
+import { getUpdateInfo } from "../adapters/update.js";
+export 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 (updateDryRunEnabled()) {
+        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 = installGlobalNpmPackage(`${PACKAGE_NAME}@latest`, json ? "pipe" : "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}`;
+}
+export async function maybeNotifyAvailableUpdate(parsed) {
+    if (updateCheckDisabled())
+        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`);
+}

package/dist/src/commands/validate.js

@@ -0,0 +1,35 @@
+import { validateLedger } from "../ledger.js";
+import { normalizeRegistryPath } from "../registry.js";
+import { printJson } from "../renderers/json.js";
+import { boolFlag, stringFlag } from "../shared/flags.js";
+import { registeredLedgersOrThrow, validateRegisteredLedger } from "./shared.js";
+export function handleValidate(parsed, ledgerPath, json) {
+    if (boolFlag(parsed, "all")) {
+        const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
+        const results = registeredLedgersOrThrow(registryPath).map((ledger) => ({ ledger, result: validateRegisteredLedger(ledger) }));
+        const ok = results.every((entry) => entry.result.ok);
+        if (json) {
+            printJson({ ok, registryPath, ledgers: results });
+            return ok ? 0 : 1;
+        }
+        for (const entry of results) {
+            process.stdout.write(`${entry.result.ok ? "ok" : "invalid"} ${entry.ledger.name}: ${entry.result.entries} entries, ${entry.result.errors.length} errors, ${entry.result.warnings.length} warnings\nledger: ${entry.ledger.path}\n`);
+            for (const error of entry.result.errors)
+                process.stdout.write(`error: ${error}\n`);
+            for (const warning of entry.result.warnings)
+                process.stdout.write(`warning: ${warning}\n`);
+        }
+        process.stdout.write(`registry: ${registryPath}\n`);
+        return ok ? 0 : 1;
+    }
+    const result = validateLedger(ledgerPath);
+    if (json)
+        return printJson({ ledgerPath, ...result });
+    process.stdout.write(`${result.ok ? "ok" : "invalid"}: ${result.entries} entries, ${result.errors.length} errors, ${result.warnings.length} warnings\n`);
+    for (const error of result.errors)
+        process.stdout.write(`error: ${error}\n`);
+    for (const warning of result.warnings)
+        process.stdout.write(`warning: ${warning}\n`);
+    process.stdout.write(`ledger: ${ledgerPath}\n`);
+    return result.ok ? 0 : 1;
+}

package/dist/src/config/env.js

@@ -0,0 +1,24 @@
+export function latestVersionOverride(env = process.env) {
+    return env.ARTSHELF_LATEST_VERSION;
+}
+export function npmRegistryUrlFromEnv(packageName, env = process.env) {
+    return env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${packageName}/latest`;
+}
+export function updateCheckDisabled(env = process.env) {
+    return env.ARTSHELF_NO_UPDATE_CHECK === "1";
+}
+export function updateDryRunEnabled(env = process.env) {
+    return env.ARTSHELF_UPDATE_DRY_RUN === "1";
+}
+export function updateCheckTtlMs(env, fallback) {
+    return resolveTtlMs(env.ARTSHELF_UPDATE_CHECK_TTL_MS, fallback);
+}
+export function noUpdateCheckTtlMs(env, fallback) {
+    return resolveTtlMs(env.ARTSHELF_NO_UPDATE_CHECK_TTL_MS ?? env.ARTSHELF_UPDATE_CHECK_TTL_MS, fallback);
+}
+function resolveTtlMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}

package/dist/src/config/package.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { npmRegistryUrlFromEnv } from "./env.js";
+export const PACKAGE_NAME = "artshelf";
+export const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+export const NO_UPDATE_CHECK_TTL_MS = 60 * 60 * 1000;
+export const VERSION = readPackageVersion();
+export function npmRegistryUrl() {
+    return npmRegistryUrlFromEnv(PACKAGE_NAME);
+}
+export function readPackageVersion() {
+    const packageJsonPath = decodeURIComponent(new URL("../../../package.json", import.meta.url).pathname);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (typeof packageJson.version !== "string") {
+        throw new Error("package.json version must be a string");
+    }
+    return packageJson.version;
+}

package/dist/src/config/paths.js

@@ -0,0 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function updateCachePath(env = process.env) {
+    return env.ARTSHELF_UPDATE_CACHE ?? join(homedir(), ".artshelf", "update-check.json");
+}

package/dist/src/renderers/attention.js

@@ -0,0 +1,3 @@
+export function attentionGlyph(needsAttention) {
+    return needsAttention ? "⚠" : "✓";
+}

package/dist/src/renderers/doctor.js

@@ -0,0 +1,64 @@
+import { attentionGlyph } from "./attention.js";
+const DOCTOR_ATTENTION_CATEGORIES = ["stale", "invalid", "warnings"];
+function doctorAttention(summary) {
+    return DOCTOR_ATTENTION_CATEGORIES.filter((key) => summary[key] > 0);
+}
+function doctorNextAction(blockers, summary) {
+    if (blockers.length > 0) {
+        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+    }
+    if (summary.warnings > 0) {
+        return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf validate --all\` to inspect; nothing is auto-executed`;
+    }
+    return "artshelf is healthy on this machine — cleanup safety enforced; no action needed";
+}
+export function buildDoctorAgentPacket(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]}` : ""}`);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        command: "doctor",
+        health: report.ok ? "ok" : "attention",
+        version: report.version,
+        node: report.node,
+        ledgerPath: report.ledgerPath,
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: {
+            total: report.summary.ledgers,
+            ok: report.summary.ok,
+            stale: report.summary.stale,
+            invalid: report.summary.invalid,
+            warnings: report.summary.warnings
+        },
+        attention: doctorAttention(report.summary),
+        blockers,
+        cleanupSafety: report.cleanupSafety,
+        nextAction: doctorNextAction(blockers, report.summary),
+        verification: `artshelf doctor --agent --registry ${report.registryPath}`
+    };
+}
+export function printDoctor(report) {
+    process.stdout.write(`artshelf ${report.version} (node ${report.node})\n`);
+    process.stdout.write(`${attentionGlyph(!report.ok)} health: ${report.ok ? "ok" : "needs attention"}\n`);
+    process.stdout.write(`ledger: ${report.ledgerPath}${report.ledgerExists ? "" : " (absent)"}\n`);
+    process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"}\n`);
+    if (report.registryError)
+        process.stdout.write(`registry error: ${report.registryError}\n`);
+    process.stdout.write(`registered ledgers: ${report.summary.ledgers} (${report.summary.ok} ok, ${report.summary.stale} stale, ${report.summary.invalid} invalid)\n`);
+    for (const ledger of report.ledgers) {
+        process.stdout.write(`  ${attentionGlyph(ledger.status !== "ok")} ${ledger.status} ${ledger.name} ${ledger.path}\n`);
+        for (const message of ledger.errors)
+            process.stdout.write(`    error: ${message}\n`);
+    }
+    process.stdout.write("cleanup safety: execute requires a reviewed plan id against a single ledger; --all execute is refused; cleanup=delete is refused; physical trash purge requires a separate reviewed purge plan\n");
+    if (!report.ok) {
+        for (const message of report.errors)
+            process.stdout.write(`error: ${message}\n`);
+    }
+}

package/dist/src/renderers/json.js

@@ -0,0 +1,10 @@
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    return 0;
+}
+// Agent/compact surface: a single minified JSON line. The default `--json`
+// stays pretty-printed for audit/debug; agent packets optimize for tokens.
+export function printCompactJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    return 0;
+}