ushman-ledger 0.3.0

package/dist/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"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"}

package/dist/builders.js

@@ -0,0 +1,73 @@
+import { AgentPatchRecordSchema, CorrectionRecordSchema, DescopeBriefRecordSchema, MergeReturnRecordSchema, MergeReturnRejectedRecordSchema, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, OperatorPatchRecordSchema, PatchPayloadWriteSchema, RevertRecordSchema, ReworkTestRetiredRecordSchema, RollbackRecordSchema, StageTransitionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
+import { generateUuidV7 } from "./uuid.js";
+/** Build an `agent-patch` record, deriving structured payload fields later if only `diffPath` is supplied. */
+export const buildAgentPatchRecord = (input) => AgentPatchRecordSchema.parse({
+    ...input,
+    kind: 'agent-patch',
+    payload: input.payload ? PatchPayloadWriteSchema.parse(input.payload) : undefined,
+});
+/** Build an `operator-patch` record, deriving structured payload fields later if only `diffPath` is supplied. */
+export const buildOperatorPatchRecord = (input) => OperatorPatchRecordSchema.parse({
+    ...input,
+    kind: 'operator-patch',
+    payload: input.payload ? PatchPayloadWriteSchema.parse(input.payload) : undefined,
+});
+/** Build a `stage-transition` record with a validated structured payload. */
+export const buildStageTransitionRecord = (input) => StageTransitionRecordSchema.parse({
+    ...input,
+    kind: 'stage-transition',
+});
+/** Build an `operator-decision` record using the required structured payload shape. */
+export const buildOperatorDecisionRecord = (input) => OperatorDecisionRecordSchema.parse({
+    ...input,
+    kind: 'operator-decision',
+    payload: OperatorDecisionPayloadSchema.parse(input.payload),
+});
+/** Build a `validator-result` record and synthesize `payload.id` only when the caller omits it. */
+export const buildValidatorResultRecord = (input) => ValidatorResultRecordSchema.parse({
+    ...input,
+    kind: 'validator-result',
+    payload: {
+        id: input.payload?.id ?? generateUuidV7(),
+    },
+});
+/** Build a `correction` record with validated linkage fields. */
+export const buildCorrectionRecord = (input) => CorrectionRecordSchema.parse({
+    ...input,
+    kind: 'correction',
+});
+/** Build a `strip-decision-reverted` record. */
+export const buildStripDecisionRevertedRecord = (input) => StripDecisionRevertedRecordSchema.parse({
+    ...input,
+    kind: 'strip-decision-reverted',
+});
+/** Build a `descope-brief` record. */
+export const buildDescopeBriefRecord = (input) => DescopeBriefRecordSchema.parse({
+    ...input,
+    kind: 'descope-brief',
+});
+/** Build a `merge-return` record. */
+export const buildMergeReturnRecord = (input) => MergeReturnRecordSchema.parse({
+    ...input,
+    kind: 'merge-return',
+});
+/** Build a `merge-return-rejected` record. */
+export const buildMergeReturnRejectedRecord = (input) => MergeReturnRejectedRecordSchema.parse({
+    ...input,
+    kind: 'merge-return-rejected',
+});
+/** Build a `revert` record. */
+export const buildRevertRecord = (input) => RevertRecordSchema.parse({
+    ...input,
+    kind: 'revert',
+});
+/** Build a `rollback` record. */
+export const buildRollbackRecord = (input) => RollbackRecordSchema.parse({
+    ...input,
+    kind: 'rollback',
+});
+/** Build a `rework.test_retired` record. */
+export const buildReworkTestRetiredRecord = (input) => ReworkTestRetiredRecordSchema.parse({
+    ...input,
+    kind: 'rework.test_retired',
+});

package/dist/candidate-paths.d.ts

@@ -0,0 +1,3 @@
+export declare const CANDIDATE_FILE_GLOBS: readonly ["src/**/*", "public/**/*", "index.html", "vite.config.ts", "vite.config.js", "package.json", "tsconfig.json"];
+export declare const CANDIDATE_EXCLUDE_GLOBS: readonly ["node_modules/**", "dist/**", ".vite/**", ".lab/**", "asl/**"];
+//# sourceMappingURL=candidate-paths.d.ts.map

package/dist/candidate-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-paths.d.ts","sourceRoot":"","sources":["../src/candidate-paths.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,oBAAoB,yHAQvB,CAAC;AAEX,eAAO,MAAM,uBAAuB,0EAA2E,CAAC"}

package/dist/candidate-paths.js

@@ -0,0 +1,11 @@
+// PLACEHOLDER — replace with import from @ushman/lab-types after ushman M1 lands.
+export const CANDIDATE_FILE_GLOBS = [
+    'src/**/*',
+    'public/**/*',
+    'index.html',
+    'vite.config.ts',
+    'vite.config.js',
+    'package.json',
+    'tsconfig.json',
+];
+export const CANDIDATE_EXCLUDE_GLOBS = ['node_modules/**', 'dist/**', '.vite/**', '.lab/**', 'asl/**'];

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+type CliContext = {
+    readonly commandName: string;
+    readonly defaultEmitter: {
+        readonly tool: string;
+        readonly version: string;
+    };
+    readonly stdin: NodeJS.ReadableStream & AsyncIterable<Uint8Array | string>;
+    readonly stderr: NodeJS.WritableStream;
+    readonly stdout: NodeJS.WritableStream;
+};
+export declare const runLedgerCli: (argv: readonly string[], context?: Partial<CliContext>) => Promise<number>;
+export declare const main: (argv?: readonly string[]) => Promise<number>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoBA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AA2jBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}

package/dist/cli.js

@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { ZodError } from 'zod';
+import { openLedger } from "./handle.js";
+import { LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord } from "./schema/entry.js";
+import { NoteSubkindSchema } from "./schema/note.js";
+import { LEDGER_LIBRARY_VERSION } from "./version.js";
+const execFileAsync = promisify(execFile);
+const GIT_DIFF_TIMEOUT_MS = 30_000;
+const RENDER_TARGETS = ['retro', 'jsonl', 'timeline-html', 'dependency-graph', 'analytics-summary'];
+class CliUsageError extends Error {
+}
+const DEFAULT_CONTEXT = {
+    commandName: 'ushman-ledger',
+    defaultEmitter: {
+        tool: 'ushman-ledger',
+        version: LEDGER_LIBRARY_VERSION,
+    },
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+};
+const renderValidValues = () => `Valid values:
+  kinds: ${LEDGER_KINDS.join(', ')}
+  phases: ${LEDGER_PHASES.join(', ')}
+  note subkinds: ${NoteSubkindSchema.options.join(', ')}
+  render targets: ${RENDER_TARGETS.join(', ')}
+`;
+const renderHelp = (commandName) => `${commandName}
+
+Commands:
+  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+  ${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
+  ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
+  ${commandName} show [--workspace=<ws>] <entry-id>
+  ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
+  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|analytics-summary] [--phase=<phase>] [--out=<file>] [--fresh] [--json]
+  ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
+  ${commandName} doctor [--workspace=<ws>]
+  ${commandName} --version
+
+${renderValidValues()}`;
+const renderCommandHelp = (commandName, command) => {
+    switch (command) {
+        case 'record':
+            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+
+${renderValidValues()}`;
+        case 'note':
+            return `${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
+
+${renderValidValues()}`;
+        case 'list':
+            return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
+
+${renderValidValues()}`;
+        case 'render':
+            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--out=<file>] [--fresh] [--json]
+
+Use \`--fresh\` to bypass the cached analytics summary. \`--json\` remains a compatibility alias for the same behavior.
+
+${renderValidValues()}`;
+        default:
+            return renderHelp(commandName);
+    }
+};
+const parseArgv = (argv) => {
+    const flags = {};
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token) {
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const body = token.slice(2);
+        const equalsIndex = body.indexOf('=');
+        const name = equalsIndex !== -1 ? body.slice(0, equalsIndex) : body;
+        if (equalsIndex !== -1) {
+            const inlineValue = body.slice(equalsIndex + 1);
+            flags[name] = inlineValue;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next || next.startsWith('--')) {
+            flags[name] = true;
+            continue;
+        }
+        flags[name] = next;
+        index += 1;
+    }
+    return { flags, positionals };
+};
+const getFlag = (flags, name) => {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+};
+const hasFlag = (flags, name) => flags[name] === true || typeof flags[name] === 'string';
+const readStdinText = async (stdin) => {
+    const readableStdin = stdin;
+    if (readableStdin.isTTY) {
+        throw new CliUsageError('--from-stdin requires piped input.');
+    }
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    }
+    return chunks.join('');
+};
+const getWorkspaceRoot = (flags) => path.resolve(getFlag(flags, 'workspace') ?? '.');
+const getRequiredString = (flags, name) => {
+    const value = getFlag(flags, name);
+    if (!value) {
+        throw new CliUsageError(`Missing required --${name}.`);
+    }
+    return value;
+};
+const ensureFileExists = async (filePath, flagName) => {
+    try {
+        const fileStat = await stat(filePath);
+        if (!fileStat.isFile()) {
+            throw new CliUsageError(`${flagName} must point to a file: ${filePath}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new CliUsageError(`${flagName} file not found: ${filePath}`);
+        }
+        throw error;
+    }
+};
+const materializeGitDiff = async (workspaceRoot, gitRef) => {
+    let tempDir;
+    try {
+        const { stdout } = await execFileAsync('git', ['diff', gitRef], {
+            cwd: workspaceRoot,
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: GIT_DIFF_TIMEOUT_MS,
+        });
+        tempDir = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-git-diff-'));
+        const patchPath = path.join(tempDir, 'patch.diff');
+        await writeFile(patchPath, stdout, 'utf8');
+        return { patchPath, tempDir };
+    }
+    catch (error) {
+        if (tempDir) {
+            await rm(tempDir, { force: true, recursive: true });
+        }
+        if (error.code === 'ENOENT') {
+            throw new CliUsageError('git is required for --diff-from-git and was not found in PATH.');
+        }
+        if (error.code === 'ETIMEDOUT') {
+            throw new CliUsageError(`git diff ${gitRef} timed out after ${GIT_DIFF_TIMEOUT_MS}ms. Narrow the diff or run git manually.`);
+        }
+        throw error;
+    }
+};
+const parseJsonInput = (text, sourceLabel) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliUsageError(`Invalid JSON from ${sourceLabel}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const print = (context, text) => {
+    context.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+};
+const parseLimit = (flags) => {
+    const raw = getFlag(flags, 'limit');
+    if (!raw) {
+        return undefined;
+    }
+    if (!/^[1-9]\d*$/u.test(raw)) {
+        throw new CliUsageError(`Invalid --limit value: ${raw}`);
+    }
+    return Number.parseInt(raw, 10);
+};
+const parseOptionalKind = (flags) => {
+    const kind = getFlag(flags, 'kind');
+    if (!kind) {
+        return undefined;
+    }
+    if (!LEDGER_KINDS.includes(kind)) {
+        throw new CliUsageError(`Invalid --kind value: ${kind}. Expected one of: ${LEDGER_KINDS.join(', ')}.`);
+    }
+    return kind;
+};
+const getRequiredKind = (flags) => {
+    const kind = parseOptionalKind(flags);
+    if (!kind) {
+        throw new CliUsageError('Missing required --kind.');
+    }
+    return kind;
+};
+const parseOptionalPhase = (flags) => {
+    const phase = getFlag(flags, 'phase');
+    if (!phase) {
+        return undefined;
+    }
+    if (!LEDGER_PHASES.includes(phase)) {
+        throw new CliUsageError(`Invalid --phase value: ${phase}. Expected one of: ${LEDGER_PHASES.join(', ')}.`);
+    }
+    return phase;
+};
+const getRequiredPhase = (flags) => {
+    const phase = parseOptionalPhase(flags);
+    if (!phase) {
+        throw new CliUsageError('Missing required --phase.');
+    }
+    return phase;
+};
+const parseSince = (flags) => {
+    const since = getFlag(flags, 'since');
+    if (!since) {
+        return undefined;
+    }
+    const parsed = Date.parse(since);
+    if (Number.isNaN(parsed)) {
+        throw new CliUsageError(`Invalid --since value: ${since}. Expected an ISO-8601 timestamp.`);
+    }
+    return new Date(parsed).toISOString();
+};
+const parseRenderTarget = (flags) => {
+    const target = getFlag(flags, 'to') ?? 'retro';
+    if (!RENDER_TARGETS.includes(target)) {
+        throw new CliUsageError(`Invalid --to value: ${target}. Expected one of: ${RENDER_TARGETS.join(', ')}.`);
+    }
+    return target;
+};
+const validateRecordStdinFlags = (flags) => {
+    const conflictingFlags = [
+        'agent',
+        'action',
+        'check-id',
+        'diff',
+        'diff-from-git',
+        'idempotency-key',
+        'kind',
+        'operator',
+        'phase',
+        'rationale',
+        'summary',
+    ].filter((flagName) => hasFlag(flags, flagName));
+    if (conflictingFlags.length === 0) {
+        return;
+    }
+    throw new CliUsageError(`--from-stdin cannot be combined with record field flags: ${conflictingFlags
+        .map((flagName) => `--${flagName}`)
+        .join(', ')}. When using --from-stdin, provide all record fields in the JSON input.`);
+};
+const buildBaseRecordFromFlags = (parsed, context) => {
+    const kind = getRequiredKind(parsed.flags);
+    const record = {
+        emitter: {
+            tool: context.defaultEmitter.tool,
+            version: context.defaultEmitter.version,
+        },
+        kind,
+        phase: getRequiredPhase(parsed.flags),
+        summary: getRequiredString(parsed.flags, 'summary'),
+    };
+    const rationale = getFlag(parsed.flags, 'rationale');
+    if (rationale) {
+        if (kind !== 'agent-patch' &&
+            kind !== 'operator-patch' &&
+            kind !== 'operator-decision' &&
+            kind !== 'correction') {
+            throw new CliUsageError('--rationale is only supported for patch, operator-decision, and correction records.');
+        }
+        if (kind !== 'operator-decision') {
+            record.rationale = rationale;
+        }
+    }
+    if (kind === 'agent-patch') {
+        record.agent = {
+            name: getFlag(parsed.flags, 'agent') ?? context.defaultEmitter.tool,
+        };
+    }
+    if (kind === 'operator-patch') {
+        record.operator = {
+            name: getFlag(parsed.flags, 'operator') ?? context.defaultEmitter.tool,
+        };
+    }
+    if (kind === 'operator-decision') {
+        const action = getRequiredString(parsed.flags, 'action');
+        record.payload = {
+            action,
+            checkId: getFlag(parsed.flags, 'check-id'),
+            rationale: rationale ?? '',
+        };
+    }
+    const idempotencyKey = getFlag(parsed.flags, 'idempotency-key');
+    if (idempotencyKey) {
+        record.idempotencyKey = idempotencyKey;
+    }
+    return { kind, record };
+};
+const applyPatchInputToRecord = async ({ kind, record, workspaceRoot, parsed, }) => {
+    const diffPath = getFlag(parsed.flags, 'diff');
+    if (diffPath) {
+        if (kind !== 'agent-patch' && kind !== 'operator-patch') {
+            throw new CliUsageError('--diff is only supported for patch records.');
+        }
+        await ensureFileExists(path.resolve(diffPath), '--diff');
+        record.diffPath = diffPath;
+    }
+    const diffFromGit = getFlag(parsed.flags, 'diff-from-git');
+    if (!diffFromGit) {
+        return {};
+    }
+    if (kind !== 'agent-patch' && kind !== 'operator-patch') {
+        throw new CliUsageError('--diff-from-git is only supported for patch records.');
+    }
+    if (diffPath) {
+        throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
+    }
+    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit);
+    return {
+        cleanupTempDir: materialized.tempDir,
+        record: {
+            ...record,
+            diffPath: materialized.patchPath,
+            links: {
+                gitRef: diffFromGit,
+            },
+        },
+    };
+};
+const buildRecordFromFlags = async (parsed, context) => {
+    const workspaceRoot = getWorkspaceRoot(parsed.flags);
+    if (hasFlag(parsed.flags, 'from-stdin')) {
+        validateRecordStdinFlags(parsed.flags);
+        const stdinRecord = parseLedgerRecord(parseJsonInput(await readStdinText(context.stdin), 'stdin'));
+        return {
+            record: stdinRecord,
+            workspaceRoot,
+        };
+    }
+    const { kind, record } = buildBaseRecordFromFlags(parsed, context);
+    const patchInput = await applyPatchInputToRecord({
+        kind,
+        parsed,
+        record,
+        workspaceRoot,
+    });
+    return {
+        cleanupTempDir: patchInput.cleanupTempDir,
+        record: patchInput.record ?? record,
+        workspaceRoot,
+    };
+};
+const buildNoteRecord = async (parsed, context) => {
+    const [subkind] = parsed.positionals;
+    if (!subkind) {
+        throw new CliUsageError('Missing note subkind.');
+    }
+    if (!NoteSubkindSchema.options.includes(subkind)) {
+        throw new CliUsageError(`Invalid note subkind: ${subkind}. Expected one of: ${NoteSubkindSchema.options.join(', ')}.`);
+    }
+    const bodyFromFile = getFlag(parsed.flags, 'body');
+    if (bodyFromFile) {
+        await ensureFileExists(path.resolve(bodyFromFile), '--body');
+    }
+    const body = hasFlag(parsed.flags, 'from-stdin')
+        ? await readStdinText(context.stdin)
+        : bodyFromFile
+            ? await readFile(path.resolve(bodyFromFile), 'utf8')
+            : '';
+    const phase = getRequiredString(parsed.flags, 'phase');
+    if (!LEDGER_PHASES.includes(phase)) {
+        throw new CliUsageError(`Invalid --phase value: ${phase}. Expected one of: ${LEDGER_PHASES.join(', ')}.`);
+    }
+    return {
+        record: {
+            body,
+            emitter: {
+                tool: context.defaultEmitter.tool,
+                version: context.defaultEmitter.version,
+            },
+            kind: 'note',
+            phase: phase,
+            subkind: subkind,
+            summary: getRequiredString(parsed.flags, 'summary'),
+        },
+        workspaceRoot: getWorkspaceRoot(parsed.flags),
+    };
+};
+const runRecordCli = async (parsed, context) => {
+    const { cleanupTempDir, record, workspaceRoot } = await buildRecordFromFlags(parsed, context);
+    try {
+        const ledger = await openLedger(workspaceRoot);
+        const result = await ledger.record(record);
+        print(context, result.id);
+        return 0;
+    }
+    finally {
+        if (cleanupTempDir) {
+            await rm(cleanupTempDir, { force: true, recursive: true });
+        }
+    }
+};
+const runNoteCli = async (parsed, context) => {
+    const { record, workspaceRoot } = await buildNoteRecord(parsed, context);
+    const ledger = await openLedger(workspaceRoot);
+    const result = await ledger.record(record);
+    print(context, result.id);
+    return 0;
+};
+const runListCli = async (parsed, context) => {
+    const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    if (hasFlag(parsed.flags, 'json')) {
+        const entries = [];
+        for await (const entry of ledger.list({
+            kind: parseOptionalKind(parsed.flags),
+            limit: parseLimit(parsed.flags),
+            phase: parseOptionalPhase(parsed.flags),
+            since: parseSince(parsed.flags),
+        })) {
+            entries.push(entry);
+        }
+        print(context, JSON.stringify(entries, null, 2));
+        return 0;
+    }
+    for await (const entry of ledger.list({
+        kind: parseOptionalKind(parsed.flags),
+        limit: parseLimit(parsed.flags),
+        phase: parseOptionalPhase(parsed.flags),
+        since: parseSince(parsed.flags),
+    })) {
+        print(context, `${entry.id} ${entry.phase} ${entry.kind} ${entry.summary}`);
+    }
+    return 0;
+};
+const runShowCli = async (parsed, context) => {
+    const entryId = parsed.positionals[0];
+    if (!entryId) {
+        throw new CliUsageError('Missing entry id.');
+    }
+    const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    const entry = await ledger.show(entryId);
+    if (!entry) {
+        throw new Error(`Ledger entry not found: ${entryId}`);
+    }
+    print(context, JSON.stringify(entry, null, 2));
+    return 0;
+};
+const runTailCli = async (parsed, context) => runListCli({
+    ...parsed,
+    flags: {
+        ...parsed.flags,
+        limit: getFlag(parsed.flags, 'limit') ?? '10',
+    },
+}, context);
+const runRenderCli = async (parsed, context) => {
+    const target = parseRenderTarget(parsed.flags);
+    const wantsFresh = hasFlag(parsed.flags, 'fresh') || hasFlag(parsed.flags, 'json');
+    if (wantsFresh && target !== 'analytics-summary') {
+        throw new CliUsageError('--fresh and --json are only supported for render --to=analytics-summary.');
+    }
+    const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    const content = await ledger.render({
+        fresh: wantsFresh,
+        out: getFlag(parsed.flags, 'out'),
+        phase: parseOptionalPhase(parsed.flags),
+        to: target,
+    });
+    if (!getFlag(parsed.flags, 'out')) {
+        print(context, content);
+    }
+    return 0;
+};
+const runArchiveCli = async (parsed, context) => {
+    const outPath = getRequiredString(parsed.flags, 'out');
+    const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    const result = await ledger.archive(outPath);
+    print(context, result.integrityHash);
+    return 0;
+};
+const runDoctorCli = async (parsed, context) => {
+    const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    const result = await ledger.doctor();
+    if (result.ok) {
+        print(context, 'ok');
+        return 0;
+    }
+    for (const issue of result.issues) {
+        context.stderr.write(`${issue}\n`);
+    }
+    return 1;
+};
+const formatCliError = (error) => {
+    if (error instanceof CliUsageError) {
+        return error.message;
+    }
+    if (error instanceof ZodError) {
+        return error.issues
+            .map((issue) => {
+            const pathLabel = issue.path.length > 0 ? issue.path.join('.') : 'input';
+            return `${pathLabel}: ${issue.message}`;
+        })
+            .join('\n');
+    }
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+};
+export const runLedgerCli = async (argv, context = {}) => {
+    const mergedContext = { ...DEFAULT_CONTEXT, ...context };
+    const [command, ...rest] = argv;
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        print(mergedContext, renderHelp(mergedContext.commandName));
+        return 0;
+    }
+    if (command === '--version' || command === '-v' || command === 'version') {
+        print(mergedContext, LEDGER_LIBRARY_VERSION);
+        return 0;
+    }
+    const parsed = parseArgv(rest);
+    if (hasFlag(parsed.flags, 'help') || rest.includes('-h')) {
+        print(mergedContext, renderCommandHelp(mergedContext.commandName, command));
+        return 0;
+    }
+    switch (command) {
+        case 'record':
+            return runRecordCli(parsed, mergedContext);
+        case 'note':
+            return runNoteCli(parsed, mergedContext);
+        case 'list':
+            return runListCli(parsed, mergedContext);
+        case 'show':
+            return runShowCli(parsed, mergedContext);
+        case 'tail':
+            return runTailCli(parsed, mergedContext);
+        case 'render':
+            return runRenderCli(parsed, mergedContext);
+        case 'archive':
+            return runArchiveCli(parsed, mergedContext);
+        case 'doctor':
+            return runDoctorCli(parsed, mergedContext);
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+};
+export const main = async (argv = process.argv.slice(2)) => {
+    return runLedgerCli(argv);
+};
+const isDirectExecution = () => Boolean(process.argv[1]) && path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+if (isDirectExecution()) {
+    main().then((code) => {
+        process.exit(code);
+    }, (error) => {
+        process.stderr.write(`${formatCliError(error)}\n`);
+        process.exit(error instanceof CliUsageError || error instanceof ZodError ? 1 : 2);
+    });
+}