@sensigo/realm-cli 0.38.0 → 0.39.0

package/dist/commands/run-migrate.js

@@ -0,0 +1,303 @@
+// run-migrate.ts — `realm run migrate --stamp-seals` (issue #367, part 3).
+//
+// The vehicle the shipped `gc --heal` note promises operators. It walks every terminal run and
+// gives each one the seal arm it has always meant, WITHOUT touching the retention clock — which is
+// the whole reason it exists rather than letting `--heal` rewrite the same population and reset
+// `updated_at` on all of it.
+//
+// The sweep is TWO-ARMED, and that is load-bearing. An unstamped-only filter would leave the
+// `incoherent` bucket with no population at all: the records it exists to surface are precisely
+// the STAMPED ones whose arm disagrees with their own prose or markers, and the store boundary
+// deliberately abstains on the abandon-marker case, so nothing else in the system can see them.
+//
+// It writes only through `RunStore.stampSeal`. It never rewrites a record it cannot classify, and
+// never auto-corrects one it finds incoherent — an operator adjudicates those.
+import { Command } from 'commander';
+import { classifyLegacySeal, armToPhase } from '@sensigo/realm';
+function emptyBuckets() {
+    return {
+        stamped: [],
+        already_stamped: [],
+        unclassifiable: [],
+        incoherent: [],
+        skipped_conflict: [],
+        failed: [],
+    };
+}
+/**
+ * Why a record could not be classified — phrased for an operator, and deliberately phrased to
+ * avoid the terminal-writer census's own token: a printed diagnostic must never look like source
+ * code that writes a seal.
+ */
+function whyUnclassifiable(run) {
+    if (run.terminal_reason === undefined) {
+        return 'no terminal reason recorded and no marker to read';
+    }
+    return `terminal reason "${run.terminal_reason.slice(0, 80)}" matches no known seal shape`;
+}
+/**
+ * The exit taxonomy, aligned with the house rule every other sweep command follows (`gc`'s own,
+ * gc.ts): **exit 1 means THIS COMMAND failed to do its job.** A write that errored is that. A
+ * record nobody can classify is not — the command did exactly what it should, and said so loudly.
+ *
+ * That distinction matters more here than usual, because residue is CHRONIC: an unclassifiable
+ * record stays unclassifiable, so a nonzero exit on residue would make every scheduled run of this
+ * command fail forever, and the first thing an operator does with a chronic alarm is silence it.
+ *
+ * Automation that genuinely wants to gate on residue opts in with `--detailed-exitcode`, which
+ * turns the two outcomes into a three-way: 0 clean · 1 the command failed · 2 succeeded, residue
+ * remains. Same shape as `grep`, `git diff --exit-code` and Terraform's `-detailed-exitcode` — a
+ * machine-readable answer that needs no prose parsing, and that naive pipelines never inherit.
+ */
+export function migrateExitCode(buckets, options = {}) {
+    if (buckets.failed.length > 0)
+        return 1;
+    if (options.detailed === true &&
+        (buckets.unclassifiable.length > 0 || buckets.incoherent.length > 0)) {
+        return 2;
+    }
+    return 0;
+}
+/**
+ * The sweep. Pure over its injected store, so the acceptance suite drives it directly.
+ *
+ * `not_terminal` refusals from `stampSeal` are STATED-UNREACHABLE here rather than bucketed: this
+ * loop only offers terminal records, and any terminal→live flip bumps `version`, so the CAS
+ * refuses first and the record lands in `skipped_conflict`.
+ */
+export async function migrateStampSeals(runStore, options = {}) {
+    if (runStore.stampSeal === undefined) {
+        throw new Error('This store does not implement stampSeal, so `realm run migrate --stamp-seals` cannot ' +
+            'write to it. Records stay readable and correct without migrating — the read path ' +
+            'recovers a legacy arm wherever one is recoverable, and the rest still derive correctly from ' +
+            'the legacy ladder. To materialise the arms, use the tooling that owns ' +
+            'this store.');
+    }
+    const buckets = emptyBuckets();
+    const all = await runStore.list();
+    for (const run of all) {
+        if (!run.terminal_state)
+            continue;
+        // ARM 2 — already stamped: audit the arm against the record's own evidence.
+        if (run.sealed_by !== undefined) {
+            // A ruled record is done. An operator looked at it and said what it is, which outranks
+            // anything the classifier can infer from prose — and re-examining it every sweep is exactly
+            // the loop the ruling was made to end.
+            if (run.sealed_by.adjudicated !== undefined) {
+                buckets.already_stamped.push({ id: run.id, verified: true, ruled: true });
+                continue;
+            }
+            // The FULL markers-first classifier, deliberately: the store boundary's comparator abstains
+            // on abandon-marker records, and those are exactly the stale arms nothing else observes.
+            const classified = classifyLegacySeal(run);
+            // PHASE level, not arm level. The classifier can only ever recover `complete` from a
+            // completed run's prose, so comparing arms would report every `gate_resolution_complete` and
+            // `guard_pass_complete` stamp as a disagreement.
+            if (classified === undefined) {
+                // Abstained: nothing to compare against. The arm stands, unverified.
+                buckets.already_stamped.push({ id: run.id, verified: false });
+            }
+            else if (armToPhase(classified) === armToPhase(run.sealed_by.arm)) {
+                buckets.already_stamped.push({ id: run.id, verified: true });
+            }
+            else {
+                buckets.incoherent.push({
+                    id: run.id,
+                    arm: run.sealed_by.arm,
+                    classified,
+                    arm_phase: armToPhase(run.sealed_by.arm),
+                    classified_phase: armToPhase(classified),
+                });
+            }
+            continue;
+        }
+        // ARM 1 — unstamped: classify, then stamp.
+        const arm = classifyLegacySeal(run);
+        if (arm === undefined) {
+            buckets.unclassifiable.push({ id: run.id, why: whyUnclassifiable(run) });
+            continue;
+        }
+        const phaseBefore = run.run_phase;
+        const phaseAfter = armToPhase(arm);
+        if (options.force !== true) {
+            buckets.stamped.push({ id: run.id, arm, phase_before: phaseBefore, phase_after: phaseAfter });
+            continue;
+        }
+        try {
+            // `classified: true` marks this stamp as CLASSIFIER-minted, forever distinguishable from a
+            // writer's own assertion. `step` is never fabricated.
+            const result = await runStore.stampSeal(run.id, { arm, classified: true }, run.version);
+            if (result.stamped) {
+                buckets.stamped.push({
+                    id: run.id,
+                    arm,
+                    phase_before: phaseBefore,
+                    phase_after: result.run.run_phase,
+                });
+            }
+            else {
+                // The record gained an arm between the sweep's read and this write; nothing to verify.
+                buckets.already_stamped.push({ id: run.id, verified: false });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'STATE_SNAPSHOT_MISMATCH') {
+                buckets.skipped_conflict.push(run.id);
+            }
+            else {
+                buckets.failed.push({
+                    id: run.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    return buckets;
+}
+/**
+ * `armToPhase` is total over `SEAL_ARMS`, and returns JS `undefined` for anything else — so an arm
+ * written by a NEWER binary interpolated straight into a report line as "phase undefined", which
+ * reads like a bug in this command rather than a record it cannot interpret.
+ */
+function phaseLabel(phase) {
+    return phase === undefined
+        ? 'phase unknown to this binary (written by a newer version?)'
+        : `phase ${phase}`;
+}
+/** The ordering instruction, live since the vehicle exists. */
+export const ORDERING_LINE = 'Run `realm run migrate --stamp-seals` BEFORE `realm run gc --heal` after upgrading across ' +
+    '#367 if retention clocks matter: heal rewrites the same records and resets updated_at, which ' +
+    'this command deliberately preserves.';
+/** Renders the report. Returned as lines so the output cells can read it without capturing stdout. */
+export function renderMigrateReport(buckets, options = {}) {
+    const force = options.force === true;
+    const lines = [];
+    const nothing = buckets.stamped.length === 0 &&
+        buckets.already_stamped.length === 0 &&
+        buckets.unclassifiable.length === 0 &&
+        buckets.incoherent.length === 0 &&
+        buckets.skipped_conflict.length === 0 &&
+        buckets.failed.length === 0;
+    // "every terminal run already carries its seal arm" is a UNIVERSAL claim, and four different
+    // buckets can each falsify it: a record nobody could classify, one whose write failed, one whose
+    // arm contradicts itself, and one a concurrent writer moved. It may only be appended when all
+    // four are empty. It shipped appended unconditionally, printed directly above the very records
+    // that disprove it.
+    const everyRunArmed = buckets.unclassifiable.length === 0 &&
+        buckets.incoherent.length === 0 &&
+        buckets.failed.length === 0 &&
+        buckets.skipped_conflict.length === 0;
+    if (nothing) {
+        lines.push('No terminal runs found to migrate.');
+    }
+    else if (buckets.stamped.length > 0) {
+        lines.push(force
+            ? `Stamped ${buckets.stamped.length} run(s) with their seal arm.`
+            : `${buckets.stamped.length} run(s) WOULD be stamped:`);
+        for (const e of buckets.stamped) {
+            const phase = e.phase_before === e.phase_after ? e.phase_after : `${e.phase_before} → ${e.phase_after}`;
+            lines.push(`  • ${e.id}: ${e.arm} (phase ${phase})`);
+        }
+    }
+    else if (force) {
+        lines.push(everyRunArmed
+            ? 'Nothing to stamp — every terminal run already carries its seal arm.'
+            : 'Nothing was stamped.');
+    }
+    else {
+        lines.push(everyRunArmed
+            ? 'Nothing would be stamped — every terminal run already carries its seal arm.'
+            : 'Nothing would be stamped.');
+    }
+    if (buckets.already_stamped.length > 0) {
+        // "Coherent" is a finding, and the audit cannot make it when the classifier abstains — a
+        // record whose own evidence places it nowhere has an arm that stands UNVERIFIED, not one that
+        // has been checked and agreed with.
+        // Three disjoint groups, and the arithmetic is pinned by a cell: X + R + U = N.
+        const ruled = buckets.already_stamped.filter((e) => e.ruled === true).length;
+        const checked = buckets.already_stamped.filter((e) => e.verified && e.ruled !== true).length;
+        const unverified = buckets.already_stamped.filter((e) => !e.verified).length;
+        if (ruled === 0 && unverified === 0) {
+            lines.push(`${buckets.already_stamped.length} run(s) already stamped, and their arms agree with the record.`);
+        }
+        else {
+            // "Their arms agree with the record" would be FALSE for a ruled record whose prose still
+            // disagrees — the ruling stands over that disagreement rather than resolving it. So any
+            // ruled record forces the split form, and the ruled segment always shows when there is one.
+            const segments = [];
+            if (checked > 0)
+                segments.push(`${checked} checked against the record`);
+            if (ruled > 0)
+                segments.push(`${ruled} ruled by an operator — the ruling stands`);
+            if (unverified > 0) {
+                segments.push(`${unverified} unverifiable — nothing in the record to check the arm against`);
+            }
+            lines.push(`${buckets.already_stamped.length} run(s) already stamped (${segments.join(', ')}).`);
+        }
+    }
+    if (buckets.unclassifiable.length > 0) {
+        lines.push(`${buckets.unclassifiable.length} run(s) could NOT be classified and were left untouched:`);
+        for (const e of buckets.unclassifiable)
+            lines.push(`  • ${e.id}: ${e.why}`);
+    }
+    if (buckets.incoherent.length > 0) {
+        lines.push(`${buckets.incoherent.length} run(s) carry an arm that disagrees with their own record — ` +
+            `adjudicate these yourself; nothing was rewritten:`);
+        for (const e of buckets.incoherent) {
+            lines.push(`  • ${e.id}: recorded arm '${e.arm}' (${phaseLabel(e.arm_phase)}), but the record's own ` +
+                `markers/prose read as '${e.classified}' (${phaseLabel(e.classified_phase)})`);
+        }
+    }
+    if (buckets.skipped_conflict.length > 0) {
+        lines.push(`${buckets.skipped_conflict.length} run(s) skipped — a concurrent writer moved them; ` +
+            `their own next write path owns them.`);
+        for (const id of buckets.skipped_conflict)
+            lines.push(`  • ${id}  (skipped — concurrent write)`);
+    }
+    if (buckets.failed.length > 0) {
+        lines.push(`${buckets.failed.length} run(s) FAILED to stamp and still have no seal arm:`);
+        for (const f of buckets.failed)
+            lines.push(`  ✗ ${f.id}: ${f.error}`);
+    }
+    // Only offer the next step when there IS one: on a corpus of nothing but unclassifiable records,
+    // `--force` stamps exactly nothing, and inviting the operator to run it is a wasted round trip.
+    if (!force && buckets.stamped.length > 0)
+        lines.push('Re-run with --force to actually stamp.');
+    // RESIDUE = terminal runs that will still have no recorded arm when this run ends. A failed
+    // write leaves the record armless just as surely as an unclassifiable one does — omitting it
+    // printed "Residue: 0" directly above a record that had failed to stamp. In a dry run nothing is
+    // written, so the would-be-stamped records still count.
+    const residue = buckets.unclassifiable.length + buckets.failed.length + (force ? 0 : buckets.stamped.length);
+    const skipped = buckets.skipped_conflict.length > 0
+        ? ` (+${buckets.skipped_conflict.length} skipped — arm state unknown until their own writer settles)`
+        : '';
+    lines.push(`Residue: ${residue} terminal run(s) still without a recorded seal arm.${skipped}`);
+    lines.push(ORDERING_LINE);
+    return lines;
+}
+export const runMigrateCommand = new Command('migrate')
+    .description('Materialise recorded seal arms on legacy terminal runs (issue #367)')
+    .requiredOption('--stamp-seals', 'Stamp each terminal run with the seal arm it has always meant')
+    .option('--force', 'Actually write the stamps (without this, the sweep is a dry run)')
+    .option('--detailed-exitcode', 'Three-way exit for automation: 0 clean, 1 the command failed, 2 succeeded but residue ' +
+    'remains (the shape grep, `git diff --exit-code` and Terraform use). Opt-in, so a naive ' +
+    'pipeline never inherits a chronic alarm from records that can never be classified.')
+    .action(async (opts) => {
+    const { JsonFileStore } = await import('@sensigo/realm');
+    const runStore = new JsonFileStore();
+    try {
+        const buckets = await migrateStampSeals(runStore, { force: opts.force ?? false });
+        for (const line of renderMigrateReport(buckets, { force: opts.force ?? false })) {
+            console.log(line);
+        }
+        process.exitCode = migrateExitCode(buckets, { detailed: opts.detailedExitcode ?? false });
+    }
+    catch (err) {
+        // The batch never started, or stopped before writing — say so, rather than emitting a bare
+        // errno an operator has to guess the scope of.
+        console.error(`migrate ABORTED before writing anything: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=run-migrate.js.map

package/dist/commands/run-migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-migrate.js","sourceRoot":"","sources":["../../src/commands/run-migrate.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":"AA+BA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAgBvB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}
+{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAkCA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAiBvB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}

package/dist/commands-registry.js

@@ -25,6 +25,9 @@ import { listCommand } from './commands/list.js';
 import { mcpCommand } from './commands/mcp.js';
 import { serveCommand } from './commands/serve.js';
 import { migrateCommand } from './commands/migrate.js';
+// issue #367 (part 3): the run-scoped sibling of `realm workflow migrate` — different group, no
+// collision.
+import { runMigrateCommand } from './commands/run-migrate.js';
 import { agentCommand } from './commands/agent.js';
 import { webhookCommand } from './commands/webhook.js';
 import { listenCommand } from './commands/listen.js';
@@ -55,6 +58,7 @@ export const runCommands = [
     reconcileCommand,
     attemptsCommand,
     drainCommand,
+    runMigrateCommand,
 ];
 /** Top-level commands not nested under a subgroup. */
 export const topLevelCommands = [

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,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,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,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,YAAY;CACb,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,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,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,gGAAgG;AAChG,aAAa;AACb,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,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,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,YAAY;IACZ,iBAAiB;CAClB,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.38.0');
+program.name('realm').description('Realm workflow engine CLI').version('0.39.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.38.0",
+  "version": "0.39.0",
   "publishConfig": {
     "access": "public"
   },
@@ -63,9 +63,9 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@sensigo/realm": "^0.38.0",
-    "@sensigo/realm-mcp": "^0.38.0",
-    "@sensigo/realm-testing": "^0.38.0",
+    "@sensigo/realm": "^0.39.0",
+    "@sensigo/realm-mcp": "^0.39.0",
+    "@sensigo/realm-testing": "^0.39.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "chalk": "^5.0.0",
     "commander": "^15.0.0",