@sensigo/realm-cli 0.19.0 → 0.20.0

package/dist/commands/gc.d.ts

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+export interface SweepOrphansOptions {
+    /** Minimum age (ms) a `.tmp` must have to be reaped. Rejected below `FLOOR_MS` — see above. */
+    olderThanMs: number;
+    /** true (default caller behavior): report only, never unlink. */
+    dryRun: boolean;
+    /** Injected clock for deterministic age math in tests; defaults to `new Date()`. */
+    now?: Date;
+}
+export interface SweepOrphansResult {
+    /** Reaped (force mode) or would-be-reaped (dry-run) `.tmp` paths. */
+    reaped: string[];
+    /** A candidate vanished on its own (lstat or unlink hit ENOENT) — benign, never a failure. */
+    already_gone: string[];
+    /** A candidate lstat'd to something other than ENOENT/regular-file/symlink (e.g. a directory
+     *  unexpectedly named `*.tmp`), or a genuine unlink error (permissions, I/O). Loud on purpose —
+     *  a type mismatch is never silently swallowed, in either dry-run or force mode. */
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Reaps orphaned atomic-write `.tmp` files older than `options.olderThanMs`. `FLOOR_MS` is
+ * checked FIRST, before any filesystem access, so no caller — CLI action, test, or future
+ * consumer — can reach a delete without crossing it.
+ *
+ * Per-candidate rule (uses `lstat`, never `readdir({ withFileTypes: true })` — on WSL/9p
+ * `Dirent.d_type` can be `DT_UNKNOWN`, which would make every type check false and the sweep
+ * reap nothing):
+ *  - `lstat` ENOENT (vanished before we could even examine it, or during the later `unlink`) →
+ *    `already_gone`, in either mode — a benign race, never a failure.
+ *  - a **symlink** → skipped silently (appears in no bucket). Never `unlink`ed, never followed.
+ *  - anything else that is **not a regular file** (a directory unexpectedly named `*.tmp`, a
+ *    socket, …) → `failed`, loud, in either mode — a type mismatch is never an ENOENT-style
+ *    silent swallow, because it signals something anomalous in `runsDir` worth surfacing even
+ *    from a dry-run.
+ *  - a **future mtime** (negative age — clock skew) → skipped silently, never reaped.
+ *  - a regular file younger than `olderThanMs` → skipped silently (almost certainly an in-flight
+ *    write's temp).
+ *  - a regular file older than `olderThanMs` → a reap candidate: in dry-run, its path lands in
+ *    `reaped` (interpreted as "would reap") without any filesystem mutation; in force mode, it is
+ *    `unlink`ed — success → `reaped`; ENOENT → `already_gone`; anything else → `failed`.
+ */
+export declare function sweepOrphans(runsDir: string, options: SweepOrphansOptions): Promise<SweepOrphansResult>;
+export declare const gcCommand: Command;
+//# sourceMappingURL=gc.d.ts.map

package/dist/commands/gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,MAAM,WAAW,mBAAmB;IAClC,+FAA+F;IAC/F,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,oFAAoF;IACpF,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8FAA8F;IAC9F,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;wFAEoF;IACpF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AA+DD,eAAO,MAAM,SAAS,SAwDlB,CAAC"}

package/dist/commands/gc.js

@@ -0,0 +1,240 @@
+// gc command — sweep orphaned atomic-write temps (issue #160, Phase 1: .tmp only).
+//
+// atomicWriteFile (packages/core/src/store/atomic-write.ts) writes a unique sibling temp
+// (`${path}.<pid>.<counter>.tmp`) then POSIX-renames it over the target. A process dying between
+// the write and the rename orphans that temp forever — it is not runId-keyed for the key-pointer
+// case (`keys/<hash>.json.<pid>.*.tmp`), so `realm run purge` (#107), which acts by runId, can
+// never reach it. Temps are invisible to `list()` (no `.json` suffix) but accumulate on disk
+// regardless. Windows never produces a temp at all (`atomicWriteFile` falls back to plain
+// `writeFile` on win32) — this sweep is a documented no-op there, not a design driver.
+//
+// Reaping a `.tmp` is unconditionally safe: if the sweep unlinks a temp mid-rename, the pending
+// `rename` gets ENOENT, `atomicWriteFile`'s own catch best-effort-unlinks its temp + rethrows — the
+// TARGET file is never touched (worst case: a spurious write error surfaces to the writer, never a
+// torn file). Combined with the 1h floor below, an in-flight write's temp (age ≪ floor) is never
+// even selected.
+//
+// Phase 1 = `.tmp` only. `.lock` reaping is deliberately split to #164 (deferred — proper-lockfile
+// self-heals a live-path lock; only a purged-target's lock lingers, which is negligible). Run-less
+// `trace-buffer-*.jsonl` WAL cleanup is #163. Neither is this command's job — see the report footer.
+import { readdir, lstat, unlink, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { WorkflowError } from '@sensigo/realm';
+import { parseDuration } from '../lib/parse-duration.js';
+/**
+ * Minimum `--older-than` the sweep will ever honor (1 hour) — a conservative floor for hygiene of
+ * non-urgent crash residue, and, forward-consistency-wise, the safety guard the deferred `.lock`
+ * reaping (#164) will also require; enforcing it here means #164 inherits an already-tested guard.
+ * Temps themselves are safe to reap at any age past a few seconds (see the module doc above) — this
+ * floor is conservatism, not the temp-safety mechanism. Module-private: the only way to reach a
+ * delete is through `sweepOrphans`, which checks this FIRST, before any filesystem access.
+ */
+const FLOOR_MS = 3_600_000;
+/**
+ * Every top-level `*.tmp` in `runsDir`, plus one level of recursion into `runsDir/keys/*.tmp` —
+ * `keys/` is the ONLY subdirectory any store ever creates in `runsDir` (verified: `JsonFileStore`'s
+ * `keysDir()`/`mkdir` calls are the only subdirectory creation anywhere in this codebase's
+ * `runsDir` usage). A plain `readdir(runsDir)` sees the `keys` entry itself (no `.json`/`.tmp`
+ * suffix, so it's filtered out) but NOT what's inside it — hence the explicit second `readdir`.
+ * Nothing else is recursed into; nothing else is globbed (no `*.lock` — that's #164).
+ * Tolerates a missing `runsDir` or a missing `keys/` (a fresh install, or one that never wrote a
+ * keyed run, legitimately lacks either) — a missing directory yields zero candidates, not a throw.
+ */
+async function findTempCandidates(runsDir) {
+    const topLevel = await readdir(runsDir).catch(() => []);
+    const paths = topLevel.filter((f) => f.endsWith('.tmp')).map((f) => join(runsDir, f));
+    const keysDir = join(runsDir, 'keys');
+    const keysEntries = await readdir(keysDir).catch(() => []);
+    paths.push(...keysEntries.filter((f) => f.endsWith('.tmp')).map((f) => join(keysDir, f)));
+    return paths;
+}
+/**
+ * Reaps orphaned atomic-write `.tmp` files older than `options.olderThanMs`. `FLOOR_MS` is
+ * checked FIRST, before any filesystem access, so no caller — CLI action, test, or future
+ * consumer — can reach a delete without crossing it.
+ *
+ * Per-candidate rule (uses `lstat`, never `readdir({ withFileTypes: true })` — on WSL/9p
+ * `Dirent.d_type` can be `DT_UNKNOWN`, which would make every type check false and the sweep
+ * reap nothing):
+ *  - `lstat` ENOENT (vanished before we could even examine it, or during the later `unlink`) →
+ *    `already_gone`, in either mode — a benign race, never a failure.
+ *  - a **symlink** → skipped silently (appears in no bucket). Never `unlink`ed, never followed.
+ *  - anything else that is **not a regular file** (a directory unexpectedly named `*.tmp`, a
+ *    socket, …) → `failed`, loud, in either mode — a type mismatch is never an ENOENT-style
+ *    silent swallow, because it signals something anomalous in `runsDir` worth surfacing even
+ *    from a dry-run.
+ *  - a **future mtime** (negative age — clock skew) → skipped silently, never reaped.
+ *  - a regular file younger than `olderThanMs` → skipped silently (almost certainly an in-flight
+ *    write's temp).
+ *  - a regular file older than `olderThanMs` → a reap candidate: in dry-run, its path lands in
+ *    `reaped` (interpreted as "would reap") without any filesystem mutation; in force mode, it is
+ *    `unlink`ed — success → `reaped`; ENOENT → `already_gone`; anything else → `failed`.
+ */
+export async function sweepOrphans(runsDir, options) {
+    if (options.olderThanMs < FLOOR_MS) {
+        throw new WorkflowError(`--older-than must resolve to at least 1h (got ${options.olderThanMs}ms) — gc refuses to ` +
+            `reap crash residue younger than that, even with --force.`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { olderThanMs: options.olderThanMs, floorMs: FLOOR_MS },
+        });
+    }
+    const now = options.now ?? new Date();
+    const candidatePaths = await findTempCandidates(runsDir);
+    const result = { reaped: [], already_gone: [], failed: [] };
+    const toReap = [];
+    for (const path of candidatePaths) {
+        let info;
+        try {
+            info = await lstat(path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                result.already_gone.push(path); // vanished between readdir and lstat
+            }
+            else {
+                result.failed.push({ path, error: err instanceof Error ? err.message : String(err) });
+            }
+            continue;
+        }
+        if (info.isSymbolicLink())
+            continue; // never unlink or follow a symlink — silent skip
+        if (!info.isFile()) {
+            result.failed.push({
+                path,
+                error: 'expected a regular file but found a different type (unexpected for a *.tmp name)',
+            });
+            continue;
+        }
+        const ageMs = now.getTime() - info.mtime.getTime();
+        if (ageMs < 0)
+            continue; // future mtime (clock skew) — skip, never reap
+        if (ageMs <= options.olderThanMs)
+            continue; // too fresh — most likely an in-flight write's temp
+        toReap.push(path);
+    }
+    if (options.dryRun) {
+        result.reaped = toReap;
+        return result;
+    }
+    for (const path of toReap) {
+        try {
+            await unlink(path);
+            result.reaped.push(path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                result.already_gone.push(path); // vanished between lstat and unlink
+            }
+            else {
+                result.failed.push({ path, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+    }
+    return result;
+}
+/** Best-effort total bytes for a known list of paths — reporting-only, never gates reaping.
+ *  Called against a fresh dry-run preview, so the paths are still on disk when stat'd. */
+async function statPathBytes(paths) {
+    let total = 0;
+    await Promise.all(paths.map(async (p) => {
+        try {
+            const info = await stat(p);
+            total += info.size;
+        }
+        catch {
+            // vanished between the preview pass and this stat — best-effort, ignore.
+        }
+    }));
+    return total;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** So an operator doesn't distrust the tool when `runsDir` still holds residue gc deliberately
+ *  does not touch — printed on every report, dry-run or force, empty or not. */
+const NOT_REAPED_FOOTER = 'gc does NOT reap orphaned .lock dirs (deferred — issue #164) or run-less trace-buffer-*.jsonl ' +
+    'WAL files (issue #163). Their presence in runsDir is expected and not a sign gc is broken.';
+/** Prints the dry-run / force report shared by both code paths. `previewBytes` always comes from
+ *  the initial (always non-destructive) preview pass — see the action below for why. */
+function printGcReport(result, previewBytes, dryRun) {
+    const nothingToReport = result.reaped.length === 0 && result.already_gone.length === 0 && result.failed.length === 0;
+    if (nothingToReport) {
+        console.log('No orphaned .tmp files found to reap.');
+    }
+    else if (dryRun) {
+        console.log(`${result.reaped.length} orphaned .tmp file(s) WOULD be reaped (${formatBytes(previewBytes)} to free):`);
+        for (const p of result.reaped)
+            console.log(`  • ${p}`);
+        if (result.already_gone.length > 0) {
+            console.log(`(${result.already_gone.length} candidate(s) already vanished on their own.)`);
+        }
+    }
+    else {
+        console.log(`Reaped ${result.reaped.length} orphaned .tmp file(s) (${formatBytes(previewBytes)} freed). ` +
+            `${result.already_gone.length} already gone, ${result.failed.length} failed.`);
+    }
+    for (const f of result.failed) {
+        console.error(`  ✗ ${f.path}: ${f.error}`);
+    }
+    if (dryRun && !nothingToReport) {
+        console.log('\nRe-run with --force to actually delete.');
+    }
+    console.log(`\n${NOT_REAPED_FOOTER}`);
+}
+export const gcCommand = new Command('gc')
+    .description('Sweep orphaned atomic-write .tmp files — crash residue from a process that died mid-write (dry-run by default)')
+    .requiredOption('--older-than <duration>', 'Reap temps idle at least this long (minimum 1h; e.g. 1h, 6h, 30d)')
+    .option('--force', 'Actually delete (without this, gc only reports what WOULD be reaped)')
+    .action(async (opts) => {
+    let olderThanMs;
+    try {
+        olderThanMs = parseDuration(opts.olderThan);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+        return;
+    }
+    // Defense-in-depth over sweepOrphans's own floor check — reject before touching the
+    // filesystem at all, with a CLI-friendly message naming the flag the operator just typed.
+    if (olderThanMs < FLOOR_MS) {
+        console.error(`--older-than must be at least 1h (got '${opts.olderThan}'). gc refuses to reap crash ` +
+            `residue younger than that, even with --force.`);
+        process.exit(1);
+        return;
+    }
+    const { JsonFileStore } = await import('@sensigo/realm');
+    const runsDir = new JsonFileStore().runsDirPath;
+    const now = new Date();
+    try {
+        // Always preview first — this NEVER mutates, in either mode — because it is the only
+        // reliable moment to `stat()` the candidates for the report's byte total: a force-mode
+        // reap deletes the files before sweepOrphans returns, so statting them afterward is
+        // impossible. The preview and the (optional) real pass share the same olderThanMs/now, so
+        // the candidate set is consistent bar a narrow, benign concurrent-activity window — which
+        // already_gone exists to absorb.
+        const preview = await sweepOrphans(runsDir, { olderThanMs, dryRun: true, now });
+        const bytes = await statPathBytes(preview.reaped);
+        if (opts.force !== true) {
+            printGcReport(preview, bytes, true);
+            return;
+        }
+        const result = await sweepOrphans(runsDir, { olderThanMs, dryRun: false, now });
+        printGcReport(result, bytes, false);
+        if (result.failed.length > 0)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=gc.js.map

package/dist/commands/gc.js.map

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

package/dist/commands-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AA4BA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAavB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}
+{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AA6BA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAcvB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}

package/dist/commands-registry.js

@@ -9,6 +9,7 @@ import { abandonCommand } from './commands/abandon.js';
 import { reclaimCommand } from './commands/reclaim.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { purgeCommand } from './commands/purge.js';
+import { gcCommand } from './commands/gc.js';
 import { reconcileCommand } from './commands/reconcile.js';
 import { attemptsCommand } from './commands/attempts.js';
 import { respondCommand } from './commands/respond.js';
@@ -47,6 +48,7 @@ export const runCommands = [
     respondCommand,
     cleanupCommand,
     purgeCommand,
+    gcCommand,
     reconcileCommand,
     attemptsCommand,
 ];

package/dist/commands-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands-registry.js","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,eAAe;IACf,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;IACX,cAAc;CACf,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,gBAAgB;IAChB,eAAe;CAChB,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,aAAa;CACd,CAAC"}
+{"version":3,"file":"commands-registry.js","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,eAAe;IACf,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;IACX,cAAc;CACf,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,SAAS;IACT,gBAAgB;IAChB,eAAe;CAChB,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,aAAa;CACd,CAAC"}

package/dist/index.js

@@ -4,7 +4,7 @@ import 'dotenv/config';
 import { Command } from 'commander';
 import { workflowCommands, runCommands, topLevelCommands } from './commands-registry.js';
 const program = new Command();
-program.name('realm').description('Realm workflow engine CLI').version('0.19.0');
+program.name('realm').description('Realm workflow engine CLI').version('0.20.0');
 // realm workflow — operations on workflow definitions
 const workflowCmd = new Command('workflow').description('Manage workflow definitions');
 for (const cmd of workflowCommands)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensigo/realm-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,9 +61,9 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@sensigo/realm": "^0.19.0",
-    "@sensigo/realm-mcp": "^0.19.0",
-    "@sensigo/realm-testing": "^0.19.0",
+    "@sensigo/realm": "^0.20.0",
+    "@sensigo/realm-mcp": "^0.20.0",
+    "@sensigo/realm-testing": "^0.20.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "chalk": "^5.0.0",
     "commander": "^14.0.3",