ushman-ledger 1.3.0 → 1.3.1

package/README.md

@@ -145,14 +145,18 @@ ushman-ledger record --workspace=<ws> --kind=change-log --subkind=semantic-clean
 ushman-ledger note regression --workspace=<ws> --phase=cleanup --summary="runtime drift" --body=/tmp/note.md
 ushman-ledger note cleanup-wave --workspace=<ws> --phase=cleanup --summary="wave 1" --body=/tmp/narrative.md
 ushman-ledger list --workspace=<ws> --json
+ushman-ledger list --workspace=<ws> --json --progress
 ushman-ledger render --workspace=<ws> --to=retro
 ushman-ledger render --workspace=<ws> --to=migration-log-md
 ushman-ledger render --workspace=<ws> --to=workspace-narrative-md
+ushman-ledger render --workspace=<ws> --to=retro --out=/tmp/retro.md --quiet
 ushman-ledger render --workspace=<ws> --to=jsonl --out=/tmp/ledger.jsonl
 ushman-ledger render --workspace=<ws> --to=dependency-graph --out=/tmp/ledger.mmd
 ushman-ledger archive --workspace=<ws> --out=/tmp/ledger.tgz
+ushman-ledger archive --workspace=<ws> --out=/tmp/ledger.tgz --progress
 ushman-ledger doctor --workspace=<ws>
 ushman-ledger doctor --workspace=<ws> --json
+ushman-ledger doctor --workspace=<ws> --quiet
 ```
 
 Valid record kinds: `tool-invocation`, `stage-write`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `change-log`
@@ -184,6 +188,12 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 `render()` still returns a string for in-memory callers. `renderTo()` is the bounded-output alternative for large ledgers and can write to a callback or the canonical render file on disk.
 `renderTo()` writers receive sequential chunks, can return synchronously or asynchronously, and should throw only when the render should abort.
 
+## CLI quiet and progress modes
+
+- `--progress` writes concise progress lines to stderr for long-running `list`, `render`, `archive`, and `doctor` CLI operations. Stdout remains reserved for the command result, so `list --json --progress` still emits parseable JSON.
+- `--quiet` suppresses verbose human output on those commands. `doctor --quiet` prints `ok` or one finding code per line; `archive --quiet` and `render --quiet` print `ok` on success; `list --quiet` prints one entry id per line for non-JSON output.
+- `--quiet` takes precedence over `--progress`. For render targets without a canonical ledger render file, such as `jsonl` and `dependency-graph`, `render --quiet` requires `--out`.
+
 ## Workspace prerequisite
 
 `openLedger()` and the CLI expect a valid ushman v4 workspace with `.lab/lab.json` already present.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA6DA,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;AAsjCF,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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmEA,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;AAomCF,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

@@ -15,7 +15,7 @@ import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const DEFAULT_GIT_DIFF_TIMEOUT_MS = 30_000;
-const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json']);
+const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json', 'progress', 'quiet']);
 const GIT_DIFF_FORMAT_ARGS = ['--no-color', '--no-ext-diff', '--src-prefix=a/', '--dst-prefix=b/'];
 const RENDER_TARGETS = [
     'retro',
@@ -25,6 +25,12 @@ const RENDER_TARGETS = [
     'migration-log-md',
     'workspace-narrative-md',
 ];
+const CANONICAL_RENDER_TARGETS = new Set([
+    'migration-log-md',
+    'retro',
+    'timeline-html',
+    'workspace-narrative-md',
+]);
 const GIT_DIFF_FLAG_NAMES = ['git-diff-max-buffer-bytes', 'git-diff-timeout-ms', 'git-paths'];
 const CHANGE_LOG_RECORD_ONLY_FLAGS = [
     'commands',
@@ -75,12 +81,12 @@ const renderHelp = (commandName) => `${commandName}
 Commands:
   ${renderRecordUsage(commandName)}
   ${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} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json] [--quiet] [--progress]
   ${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|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
-  ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
-  ${commandName} doctor [--workspace=<ws>] [--json]
+  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>] [--quiet] [--progress]
+  ${commandName} archive [--workspace=<ws>] --out=<file.tgz> [--quiet] [--progress]
+  ${commandName} doctor [--workspace=<ws>] [--json] [--quiet] [--progress]
   ${commandName} --version
 
 ${renderValidValues()}
@@ -98,17 +104,17 @@ ${renderRuntimeTuningHelp()}`;
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'list':
-            return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
+            return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json] [--quiet] [--progress]
 
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'render':
-            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
+            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>] [--quiet] [--progress]
 
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'doctor':
-            return `${commandName} doctor [--workspace=<ws>] [--json]
+            return `${commandName} doctor [--workspace=<ws>] [--json] [--quiet] [--progress]
 
 ${renderRuntimeTuningHelp()}`;
         default:
@@ -307,6 +313,14 @@ const print = (context, text) => {
 const printJson = (context, value) => {
     print(context, JSON.stringify(value, null, 2));
 };
+const isQuiet = (flags) => hasFlag(flags, 'quiet');
+const isProgressEnabled = (flags) => hasFlag(flags, 'progress') && !isQuiet(flags);
+const printProgress = (context, flags, message) => {
+    if (!isProgressEnabled(flags)) {
+        return;
+    }
+    context.stderr.write(`progress ${message}\n`);
+};
 const parseLimit = (flags) => getFlag(flags, 'limit')
     ? parsePositiveIntegerFlag({
         defaultValue: 0,
@@ -791,7 +805,9 @@ const runNoteCli = async (parsed, context) => {
     return 0;
 };
 const runListCli = async (parsed, context) => {
+    printProgress(context, parsed.flags, 'list start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    let entryCount = 0;
     if (hasFlag(parsed.flags, 'json')) {
         let wroteEntry = false;
         context.stdout.write('[\n');
@@ -807,8 +823,10 @@ const runListCli = async (parsed, context) => {
             const renderedEntry = JSON.stringify(entry, null, 2).replaceAll('\n', '\n  ');
             context.stdout.write(`  ${renderedEntry}`);
             wroteEntry = true;
+            entryCount += 1;
         }
         context.stdout.write(wroteEntry ? '\n]\n' : ']\n');
+        printProgress(context, parsed.flags, `list done entries=${entryCount}`);
         return 0;
     }
     for await (const entry of ledger.list({
@@ -817,8 +835,15 @@ const runListCli = async (parsed, context) => {
         phase: parseOptionalPhase(parsed.flags),
         since: parseSince(parsed.flags),
     })) {
-        print(context, `${entry.id} ${entry.phase} ${entry.kind} ${entry.summary}`);
+        entryCount += 1;
+        if (isQuiet(parsed.flags)) {
+            print(context, entry.id);
+        }
+        else {
+            print(context, `${entry.id} ${entry.phase} ${entry.kind} ${entry.summary}`);
+        }
     }
+    printProgress(context, parsed.flags, `list done entries=${entryCount}`);
     return 0;
 };
 const runShowCli = async (parsed, context) => {
@@ -843,6 +868,7 @@ const runTailCli = async (parsed, context) => runListCli({
 }, context);
 const runRenderCli = async (parsed, context) => {
     const target = parseRenderTarget(parsed.flags);
+    printProgress(context, parsed.flags, `render start target=${target}`);
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const renderOptions = {
         limit: parseLimit(parsed.flags),
@@ -851,19 +877,29 @@ const runRenderCli = async (parsed, context) => {
         since: parseSince(parsed.flags),
         to: target,
     };
-    if (renderOptions.out) {
+    if (isQuiet(parsed.flags) && !renderOptions.out && !CANONICAL_RENDER_TARGETS.has(target)) {
+        throw new CliUsageError(`render --quiet requires --out for ${target} output.`);
+    }
+    if (renderOptions.out || isQuiet(parsed.flags)) {
         await ledger.renderTo(renderOptions);
+        if (isQuiet(parsed.flags)) {
+            print(context, 'ok');
+        }
+        printProgress(context, parsed.flags, `render done target=${target}`);
         return 0;
     }
     const content = await ledger.render(renderOptions);
     print(context, content);
+    printProgress(context, parsed.flags, `render done target=${target}`);
     return 0;
 };
 const runArchiveCli = async (parsed, context) => {
     const outPath = getRequiredString(parsed.flags, 'out');
+    printProgress(context, parsed.flags, 'archive start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.archive(outPath);
-    print(context, result.integrityHash);
+    print(context, isQuiet(parsed.flags) ? 'ok' : result.integrityHash);
+    printProgress(context, parsed.flags, 'archive done');
     return 0;
 };
 const formatDoctorFinding = (finding) => [`[${finding.code}] ${finding.message}`, `Next step: ${finding.remediation}`].join('\n');
@@ -878,17 +914,32 @@ const printDoctorFindings = (context, report) => {
     context.stderr.write('\n');
 };
 const runDoctorCli = async (parsed, context) => {
+    printProgress(context, parsed.flags, 'doctor start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.doctor();
     if (hasFlag(parsed.flags, 'json')) {
         printJson(context, result);
+        printProgress(context, parsed.flags, `doctor done issues=${result.issueCount}`);
+        return result.ok ? 0 : 1;
+    }
+    if (isQuiet(parsed.flags)) {
+        if (result.ok) {
+            print(context, 'ok');
+        }
+        else {
+            for (const finding of result.findings) {
+                print(context, finding.code);
+            }
+        }
         return result.ok ? 0 : 1;
     }
     if (result.ok) {
         print(context, 'ok');
+        printProgress(context, parsed.flags, 'doctor done issues=0');
         return 0;
     }
     printDoctorFindings(context, result);
+    printProgress(context, parsed.flags, `doctor done issues=${result.issueCount}`);
     return 1;
 };
 const formatCliError = (error) => {

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB;;;EAuBlC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAU,UAAU,MAAM,EAAE,cAAc,kBAG7D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,kBAAiB,kBAcpE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,KAAK,EACxC,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC7C,QAAQ,MAAM,OAAO,CAAC,KAAK,CAAC,mBAuB/B,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,sBAAsB;;;EAuBlC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAU,UAAU,MAAM,EAAE,cAAc,kBAG7D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,kBAAiB,kBAcpE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,KAAK,EACxC,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC7C,QAAQ,MAAM,OAAO,CAAC,KAAK,CAAC,mBAuB/B,CAAC"}

package/dist/helpers.js

@@ -1,12 +1,13 @@
 import { mkdir, mkdtemp, rm, stat, utimes, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { V4_SCHEMA_VERSION } from 'ushman-lab-types';
 export const createWorkspaceFixture = async () => {
     const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-'));
     await mkdir(path.join(workspaceRoot, '.lab'), { recursive: true });
     await mkdir(path.join(workspaceRoot, 'src'), { recursive: true });
     await writeFile(path.join(workspaceRoot, '.lab', 'lab.json'), `${JSON.stringify({
-        schemaVersion: 'ushman-lab/v4.0',
+        schemaVersion: V4_SCHEMA_VERSION,
         workspaceId: '3d71d4fb-dca0-4d63-9ad6-69d59a2395f4',
     }, null, 2)}\n`, 'utf8');
     return {

package/dist/lab-min.d.ts

@@ -1,7 +1,7 @@
 import * as v from 'valibot';
 export declare const LabManifestMin: v.LooseObjectSchema<{
     readonly createdAt: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    readonly schemaVersion: v.LiteralSchema<"ushman-lab/v4.0", undefined>;
+    readonly schemaVersion: v.LiteralSchema<"shibuk-lab/v4.0", undefined>;
     readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UuidAction<string, undefined>]>;
 }, undefined>;
 export type LabManifestMin = v.InferOutput<typeof LabManifestMin>;

package/dist/lab-min.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lab-min.d.ts","sourceRoot":"","sources":["../src/lab-min.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAE7B,eAAO,MAAM,cAAc;;;;aAIzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAElE,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAWtF,CAAC"}
+{"version":3,"file":"lab-min.d.ts","sourceRoot":"","sources":["../src/lab-min.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAE7B,eAAO,MAAM,cAAc;;;;aAIzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAElE,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAWtF,CAAC"}

package/dist/lab-min.js

@@ -1,9 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { V4_SCHEMA_VERSION } from 'ushman-lab-types';
 import * as v from 'valibot';
 export const LabManifestMin = v.looseObject({
     createdAt: v.optional(v.string()),
-    schemaVersion: v.literal('ushman-lab/v4.0'),
+    schemaVersion: v.literal(V4_SCHEMA_VERSION),
     workspaceId: v.pipe(v.string(), v.uuid()),
 });
 export const readLabManifestMin = async (workspaceRoot) => {

package/package.json

@@ -12,6 +12,7 @@
     "dependencies": {
         "safe-stable-stringify": "^2.5.0",
         "tar": "^7.5.15",
+        "ushman-lab-types": "^0.2.0",
         "valibot": "^1.4.1"
     },
     "description": "Append-only workspace ledger library and CLI for Ushman v4.",
@@ -70,5 +71,5 @@
     },
     "type": "module",
     "types": "dist/index.d.ts",
-    "version": "1.3.0"
+    "version": "1.3.1"
 }