@sanity/workflow-cli 0.8.1 → 0.10.0

package/dist/commands/list.js

@@ -1,23 +1,17 @@
-import { styleText } from 'node:util';
-import { Command, Flags } from '@oclif/core';
-import { WORKFLOW_INSTANCE_TYPE, tagScopeFilter } from '@sanity/workflow-engine';
-import { Table } from 'console-table-printer';
+import { Flags } from '@oclif/core';
+import { WORKFLOW_INSTANCE_TYPE, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../lib/client.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { resolveReadTargets } from "../lib/context.js";
 import { tagFlags } from "../lib/flags.js";
-import { formatAge } from "../lib/ui.js";
-/**
- * Build the GROQ query + params for `list` from its flags. Pure so the
- * filter combinations can be asserted without a live dataset. `--tag` is an
- * optional filter: omit it and the listing spans every partition.
- */
+import { runReadAcrossTargets } from "../lib/read-fanout.js";
+import { clipToLimit, formatAge, formatTable } from "../lib/ui.js";
 export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
     if (flags['in-flight'])
         filters.push('!defined(completedAt)');
-    if (flags['workflow-name'])
+    if (flags.definition)
         filters.push('definition == $definition');
-    // Cheap approximation of --failed: any activity in any stage with status "failed".
     if (flags.failed)
         filters.push('count(stages[].activities[status == "failed"]) > 0');
     if (flags.tag)
@@ -31,44 +25,32 @@ export function buildListQuery(flags) {
       abortedAt,
       lastChangedAt
     }`;
-    const params = { limit: flags.limit };
-    if (flags['workflow-name'])
-        params['definition'] = flags['workflow-name'];
+    const params = { limit: flags.limit + 1 };
+    if (flags.definition)
+        params['definition'] = flags.definition;
     if (flags.tag)
         params['tag'] = flags.tag;
     return { groq, params };
 }
-/** Aborted instances also carry `completedAt`, so check `abortedAt` first. */
-function deriveStatus(r) {
-    if (r.abortedAt)
-        return 'aborted';
-    if (r.completedAt)
-        return 'completed';
-    return 'in-flight';
-}
-/** Map a queried instance to its display row (derives the status column).
- *  Pure — status is the semantic value; the table colors it at render. */
 export function instanceRow(r) {
     return {
         _id: r._id,
         definition: r.definition,
         tag: r.tag,
         currentStage: r.currentStage,
-        status: deriveStatus(r),
+        status: terminalState({
+            ...(r.completedAt != null ? { completedAt: r.completedAt } : {}),
+            ...(r.abortedAt != null ? { abortedAt: r.abortedAt } : {}),
+        }),
         lastChangedAt: r.lastChangedAt,
     };
 }
-const STATUS_COLOR = {
-    completed: 'green',
-    aborted: 'dim',
-    'in-flight': 'cyan',
-};
-export default class List extends Command {
+export default class List extends WorkflowCommand {
     static description = 'List workflow instances in the configured dataset.';
     static examples = [
         '<%= config.bin %> list',
         '<%= config.bin %> list --in-flight',
-        '<%= config.bin %> list --workflow-name productLaunch',
+        '<%= config.bin %> list --definition productLaunch',
         '<%= config.bin %> list --tag prod',
     ];
     static flags = {
@@ -81,8 +63,8 @@ export default class List extends Command {
             description: 'Only instances with at least one failed activity.',
             default: false,
         }),
-        'workflow-name': Flags.string({
-            description: 'Filter by workflow definition name.',
+        definition: Flags.string({
+            description: "Only instances of this workflow definition (its `name`; the instance's `definition` field).",
         }),
         limit: Flags.integer({
             description: 'Maximum rows to return.',
@@ -91,34 +73,39 @@ export default class List extends Command {
     };
     async run() {
         const { flags } = await this.parse(List);
+        const targets = await resolveReadTargets(flags);
         const { groq, params } = buildListQuery(flags);
-        const client = loadClient();
-        const rows = await client.fetch(groq, params);
-        if (rows.length === 0) {
-            this.log(`${logSymbols.info} no instances match`);
-            return;
-        }
-        const table = new Table({
-            columns: [
-                { name: '_id', title: 'Instance', alignment: 'left' },
-                { name: 'definition', title: 'Workflow', alignment: 'left' },
-                { name: 'tag', title: 'Tag', alignment: 'left' },
-                { name: 'currentStage', title: 'Stage', alignment: 'left' },
-                { name: 'status', title: 'Status', alignment: 'left' },
-                { name: 'updated', title: 'Updated', alignment: 'left' },
-            ],
+        const failures = await runReadAcrossTargets({
+            targets,
+            log: (line) => this.log(line),
+            run: async ({ client }) => {
+                const fetched = await client.fetch(groq, params, { tag: 'list' });
+                if (fetched.length === 0) {
+                    this.log(`${logSymbols.info} no instances match`);
+                    return;
+                }
+                const { rows, note } = clipToLimit(fetched, flags.limit);
+                const lines = formatTable(['instance', 'workflow', 'tag', 'stage', 'status', 'updated'], rows.map((r) => {
+                    const row = instanceRow(r);
+                    return [
+                        row._id,
+                        row.definition,
+                        row.tag,
+                        row.currentStage,
+                        row.status,
+                        formatAge(row.lastChangedAt),
+                    ];
+                }));
+                for (const line of lines) {
+                    this.log(line);
+                }
+                if (note) {
+                    this.log(note);
+                }
+            },
         });
-        for (const r of rows) {
-            const row = instanceRow(r);
-            table.addRow({
-                _id: row._id,
-                definition: row.definition,
-                tag: row.tag,
-                currentStage: row.currentStage,
-                status: styleText(STATUS_COLOR[row.status], row.status),
-                updated: formatAge(row.lastChangedAt),
-            });
+        if (failures.length > 0) {
+            this.exit(1);
         }
-        table.printTable();
     }
 }

package/dist/commands/{retry-activity.d.ts → reset-activity.d.ts}

@@ -1,5 +1,5 @@
 import { StubCommand } from '../lib/stub.ts';
-export default class RetryActivity extends StubCommand {
+export default class ResetActivity extends StubCommand {
     static hidden: boolean;
     static description: string;
     static args: {

package/dist/commands/{retry-activity.js → reset-activity.js}

@@ -1,9 +1,8 @@
 import { Args } from '@oclif/core';
 import { StubCommand } from "../lib/stub.js";
-export default class RetryActivity extends StubCommand {
-    // Stubbed, so kept off the help + published surface until it's wired.
+export default class ResetActivity extends StubCommand {
     static hidden = true;
-    static description = 'Re-invoke a failed activity on an in-flight instance.';
+    static description = 'Reset a failed activity on an in-flight instance — back to pending (re-run) or to skipped (bypass).';
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
         activity: Args.string({ required: true, description: 'Activity name within the current stage.' }),

package/dist/commands/set-stage.d.ts

@@ -1,12 +1,36 @@
-import { StubCommand } from '../lib/stub.ts';
-export default class SetStage extends StubCommand {
-    static hidden: boolean;
+import { type SetStageArgs, type WorkflowInstance } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
+import { type EngineScope } from '../lib/operation-args.ts';
+import { type WriteOutcome, type WriteReport } from '../lib/ops-report.ts';
+export default class SetStage extends WorkflowCommand {
     static description: string;
+    static examples: string[];
     static args: {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
         to: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
+    run(): Promise<void>;
 }
+/** The shared operation args ({@link buildOperationArgs}) plus the
+ *  setStage-specific target. */
+export declare function buildSetStageArgs({ scope, instanceId, targetStage, reason, }: {
+    scope: EngineScope;
+    instanceId: string;
+    targetStage: string;
+    reason: string | undefined;
+}): SetStageArgs & EngineScope;
+/** {@link WriteOutcome} with the terminal stamp the no-op copy reads. */
+interface SetStageOutcome extends WriteOutcome {
+    instance: Pick<WorkflowInstance, 'currentStage' | 'completedAt'>;
+}
+/**
+ * Turn a `setStage` result into the spinner message + ops block. Pure so
+ * the changed / terminal / already-at-target / cascaded / ops permutations
+ * can be asserted without driving a real move.
+ */
+export declare function setStageReport(result: SetStageOutcome, to: string): WriteReport;
+export {};

package/dist/commands/set-stage.js

@@ -1,18 +1,69 @@
+import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { StubCommand } from "../lib/stub.js";
-export default class SetStage extends StubCommand {
-    // Stubbed, so kept off the help + published surface until it's wired.
-    static hidden = true;
-    // Engine note: workflow.setStage currently always runs guards + stage
-    // entry (activity activation, effects). A "manual override" that bypasses
-    // them is engine work that hasn't landed; this command stub captures
-    // the intended surface only.
-    static description = "Force-set an instance's current stage, bypassing guards + effects (manual override).";
+import { workflow } from '@sanity/workflow-engine';
+import { WorkflowCommand } from "../lib/base-command.js";
+import { resolveInstanceContext } from "../lib/context.js";
+import { tagFlags } from "../lib/flags.js";
+import { buildOperationArgs } from "../lib/operation-args.js";
+import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../lib/ops-report.js";
+export default class SetStage extends WorkflowCommand {
+    static description = "Force an instance into a stage, regardless of its declared transitions and filters — the engine's setStage admin override. The target stage's enter lifecycle still runs (auto-activities start, stage guards reconcile), and the post-move cascade can immediately auto-transition the instance onward.";
+    static examples = [
+        '<%= config.bin %> set-stage wf-instance.abc123 --to ready',
+        "<%= config.bin %> set-stage wf-instance.abc123 --to ready --reason 'unblock for demo'",
+    ];
     static args = {
-        instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
+        instanceId: Args.string({
+            required: true,
+            description: 'Workflow instance id to move.',
+        }),
     };
     static flags = {
-        to: Flags.string({ required: true, description: 'Target stage name.' }),
-        reason: Flags.string({ description: 'Reason for the manual override.' }),
+        ...tagFlags,
+        to: Flags.string({
+            required: true,
+            description: 'Target stage name.',
+        }),
+        reason: Flags.string({
+            description: 'Free-text reason — recorded on the history entry for audit.',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SetStage);
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
+        await runWriteVerb({
+            startLabel: `Setting ${args.instanceId} → ${flags.to}…`,
+            failLabel: 'Stage move rejected',
+            failHeadline: 'set-stage error:',
+            run: () => workflow.setStage({
+                client,
+                ...buildSetStageArgs({
+                    scope,
+                    instanceId: args.instanceId,
+                    targetStage: flags.to,
+                    reason: flags.reason,
+                }),
+            }),
+            report: (result) => setStageReport(result, flags.to),
+            log: (line) => this.log(line),
+        });
+    }
+}
+export function buildSetStageArgs({ scope, instanceId, targetStage, reason, }) {
+    return { ...buildOperationArgs({ scope, instanceId, reason }), targetStage };
+}
+export function setStageReport(result, to) {
+    const stage = styleText('bold', result.instance.currentStage);
+    if (!result.changed) {
+        const { completedAt } = result.instance;
+        const message = completedAt !== undefined
+            ? `setStage changed nothing — instance is terminal (at ${stage} since ${completedAt})`
+            : `setStage changed nothing — instance is already at ${stage}`;
+        return { changed: false, message, opsLines: [] };
+    }
+    return {
+        changed: true,
+        message: `Now at ${stage} (was → ${to}${cascadeTail(result.cascaded)})`,
+        opsLines: opsAppliedLines(result.ranOps),
     };
 }

package/dist/commands/show.d.ts

@@ -1,6 +1,6 @@
-import { Command } from '@oclif/core';
 import { type WorkflowInstance } from '@sanity/workflow-engine';
-export default class Show extends Command {
+import { WorkflowCommand } from '../lib/base-command.ts';
+export default class Show extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
@@ -8,6 +8,7 @@ export default class Show extends Command {
     };
     static flags: {
         include: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/show.js

@@ -1,10 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
-import { abortReason } from '@sanity/workflow-engine';
+import { Args, Flags } from '@oclif/core';
+import { abortReason, displayTitle, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../lib/client.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { findInstance, resolveReadTargets } from "../lib/context.js";
+import { tagFlags } from "../lib/flags.js";
 import { formatKeyValue, formatTimestamp, sectionHeader, activityIcon } from "../lib/ui.js";
-export default class Show extends Command {
+export default class Show extends WorkflowCommand {
     static description = 'Show the state, activities, and effects of a workflow instance.';
     static examples = [
         '<%= config.bin %> show wf-instance.abc123',
@@ -17,6 +19,7 @@ export default class Show extends Command {
         }),
     };
     static flags = {
+        ...tagFlags,
         include: Flags.string({
             description: 'Optional sections to include in output.',
             options: ['history'],
@@ -26,11 +29,12 @@ export default class Show extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Show);
-        const client = loadClient();
-        const instance = await client.getDocument(args.instanceId);
-        if (!instance) {
+        const targets = await resolveReadTargets(flags);
+        const hit = await findInstance({ targets, instanceId: args.instanceId, requestTag: 'show' });
+        if (!hit) {
             this.error(`${logSymbols.error} no instance with id "${args.instanceId}"`, { exit: 1 });
         }
+        const { instance } = hit;
         this.log(instanceHeader(instance));
         this.log('');
         for (const line of describeInstance(instance, {
@@ -40,19 +44,14 @@ export default class Show extends Command {
         }
     }
 }
-const HEADER_PAD = 9; // "Completed" — the longest label in the block
-/** The summary block at the top of `show` (and reused by `diagnose` /
- *  `fire-action`): a bold workflow + id title, then aligned detail rows. */
+const HEADER_PAD = 9;
 export function instanceHeader(instance) {
     const title = `${styleText('bold', `${instance.definition} v${instance.pinnedVersion}`)}  ${styleText('cyan', instance._id)}`;
     const rows = [
         formatKeyValue({ key: 'Stage', value: instance.currentStage, padTo: HEADER_PAD }),
         formatKeyValue({ key: 'Started', value: formatTimestamp(instance.startedAt), padTo: HEADER_PAD }),
     ];
-    // Aborted instances also carry a completedAt stamped at the abort, so the
-    // abort line stands in for completion — showing a green "Completed" too would
-    // misread as success.
-    if (instance.abortedAt) {
+    if (terminalState(instance) === 'aborted' && instance.abortedAt !== undefined) {
         const reason = abortReason(instance);
         const tail = reason ? ` — ${reason}` : '';
         const value = styleText('yellow', `${formatTimestamp(instance.abortedAt)}${tail}`);
@@ -67,11 +66,6 @@ export function instanceHeader(instance) {
     rows.push(formatKeyValue({ key: 'Tag', value: instance.tag, padTo: HEADER_PAD }));
     return [title, ...rows].join('\n');
 }
-/**
- * The per-instance body lines: every stage with its activities, any pending
- * effects, and (optionally) the history log. Pure so it can be asserted
- * without driving the oclif command.
- */
 export function describeInstance(instance, options) {
     const lines = [sectionHeader('Stages')];
     for (const stage of instance.stages) {
@@ -79,7 +73,7 @@ export function describeInstance(instance, options) {
             ? styleText('dim', ` (exited ${formatTimestamp(stage.exitedAt)})`)
             : styleText('cyan', ' (current)');
         lines.push(`  • ${stage.name}${marker}`);
-        for (const activity of stage.activities) {
+        for (const activity of stage.activities ?? []) {
             lines.push(`      ${activityIcon[activity.status]} ${activity.name}  ${styleText('dim', `[${activity.status}]`)}`);
         }
     }
@@ -92,7 +86,7 @@ export function describeInstance(instance, options) {
     if (options.includeHistory) {
         lines.push('', sectionHeader('History'));
         for (const entry of instance.history) {
-            lines.push(`  ${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${entry._type}`);
+            lines.push(`  ${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${displayTitle(entry._type)}`);
         }
     }
     return lines;

package/dist/commands/start.d.ts

@@ -0,0 +1,56 @@
+import { type FieldEntry, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance, type WorkflowLifecycle } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
+import { type EngineScope } from '../lib/operation-args.ts';
+export default class Start extends WorkflowCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        field: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * Why a definition can't be started standalone, or `undefined` when it can.
+ * Advisory, mirroring the Startable column in `definition list` — the engine
+ * itself does not refuse ({@link isStartableDefinition}), but the CLI has no
+ * way to supply the parent context a spawn-only child expects.
+ */
+export declare function startRefusal(definition: {
+    lifecycle?: WorkflowLifecycle | undefined;
+}): string | undefined;
+/**
+ * Type each `--field name=value` against the workflow's declared field
+ * entries — the engine takes typed {@link InitialFieldValue}s, and a value's
+ * type IS its declared entry's kind. Only `input`-sourced entries read
+ * caller values (the engine silently ignores the rest), so anything else
+ * fails here, naming the fields that ARE settable; value validation stays
+ * in the engine.
+ */
+export declare function buildInitialFields({ declared, values, }: {
+    declared: Pick<FieldEntry, 'type' | 'name' | 'initialValue'>[];
+    values: Record<string, unknown>;
+}): InitialFieldValue[];
+/**
+ * The shared engine args ({@link baseEngineArgs}) plus the start-specific
+ * fields. Optionals spread conditionally because the engine's optional args
+ * reject an explicit `undefined` under `exactOptionalPropertyTypes`.
+ */
+export declare function buildStartArgs({ scope, name, version, initialFields, }: {
+    scope: EngineScope;
+    name: string;
+    version: number | undefined;
+    initialFields: InitialFieldValue[];
+}): StartInstanceArgs & EngineScope;
+/** The success spinner message. Pure so the in-flight / immediately-terminal
+ *  permutations can be asserted without driving a real start. */
+export declare function startReport(instance: Pick<WorkflowInstance, '_id' | 'currentStage' | 'completedAt'>): string;
+/** The `--json` payload. Keys follow the CLI's `--json` vocabulary (matching
+ *  `fire-action`): `instanceId` carries the document `_id`, `version` the
+ *  pinned definition version; the rest mirror the instance fields. */
+export declare function startResultJson(instance: Pick<WorkflowInstance, '_id' | 'definition' | 'pinnedVersion' | 'currentStage' | 'completedAt'>): Record<string, unknown>;

package/dist/commands/start.js

@@ -0,0 +1,133 @@
+import { styleText } from 'node:util';
+import { Args, Flags } from '@oclif/core';
+import { isStartableDefinition, workflow, } from '@sanity/workflow-engine';
+import { WorkflowCommand } from "../lib/base-command.js";
+import { resolveContext } from "../lib/context.js";
+import { fetchDeployedDefinition } from "../lib/definitions.js";
+import { fail, failOnThrow, failureDetail } from "../lib/fail.js";
+import { jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs } from "../lib/operation-args.js";
+import { runWriteVerb } from "../lib/ops-report.js";
+import { parseParams } from "../lib/params.js";
+export default class Start extends WorkflowCommand {
+    static description = 'Start a workflow instance from a deployed definition. Supply values for the ' +
+        "workflow's input-sourced fields with --field (e.g. the subject document ref).";
+    static examples = [
+        '<%= config.bin %> start productLaunch',
+        '<%= config.bin %> start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
+        '<%= config.bin %> start productLaunch --version 2 --tag prod',
+    ];
+    static args = {
+        name: Args.string({ required: true, description: 'Workflow definition name.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        version: Flags.integer({
+            description: 'Definition version to start from (default: highest deployed).',
+        }),
+        field: Flags.string({
+            description: 'Initial value for a declared input-sourced field, as name=value (repeatable). Values ' +
+                'are JSON-parsed, falling back to a string; ref kinds take a JSON object with a GDR ' +
+                '`id` and doc `type`.',
+            multiple: true,
+            default: [],
+        }),
+        ...jsonFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Start);
+        const { deployment, client } = await resolveContext(flags);
+        const values = failOnThrow('Invalid --field:', () => parseParams(flags.field));
+        const initialFields = await resolveStartInputs({
+            client,
+            name: args.name,
+            tag: deployment.tag,
+            version: flags.version,
+            values,
+        });
+        const startArgs = {
+            client,
+            ...buildStartArgs({
+                scope: deployment,
+                name: args.name,
+                version: flags.version,
+                initialFields,
+            }),
+        };
+        if (flags.json) {
+            const result = await workflow
+                .startInstance(startArgs)
+                .catch((error) => fail('start error:', failureDetail(error)));
+            this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            return;
+        }
+        await runWriteVerb({
+            startLabel: `Starting ${args.name}…`,
+            failLabel: 'Start rejected',
+            failHeadline: 'start error:',
+            run: () => workflow.startInstance(startArgs),
+            report: (result) => ({ changed: true, message: startReport(result.instance) }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+async function resolveStartInputs({ client, name, tag, version, values, }) {
+    const deployed = await fetchDeployedDefinition({ client, name, tag, version });
+    if (deployed === undefined) {
+        fail(`No deployed definition "${name}".`);
+    }
+    const refusal = startRefusal(deployed);
+    if (refusal !== undefined) {
+        fail('start error:', refusal);
+    }
+    return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
+}
+export function startRefusal(definition) {
+    if (isStartableDefinition(definition)) {
+        return undefined;
+    }
+    return "definition is spawn-only (lifecycle: 'child') — instances of it are spawned by a parent workflow's activity, not started standalone";
+}
+export function buildInitialFields({ declared, values, }) {
+    const settable = declared.filter((f) => f.initialValue?.type === 'input');
+    const settableNames = settable.map((f) => f.name).join(', ');
+    return Object.entries(values).map(([name, value]) => {
+        const entry = declared.find((f) => f.name === name);
+        if (entry === undefined) {
+            throw new Error(settable.length > 0
+                ? `workflow declares no field "${name}" — input fields: ${settableNames}`
+                : `workflow declares no field "${name}" — it declares no input fields at all`);
+        }
+        if (entry.initialValue?.type !== 'input') {
+            throw new Error(`field "${name}" is not input-sourced — the engine would silently ignore the value. ` +
+                (settable.length > 0
+                    ? `Input fields: ${settableNames}`
+                    : 'This workflow has no input fields.'));
+        }
+        return { type: entry.type, name, value };
+    });
+}
+export function buildStartArgs({ scope, name, version, initialFields, }) {
+    return {
+        ...baseEngineArgs(scope),
+        definition: name,
+        ...(version !== undefined ? { version } : {}),
+        ...(initialFields.length > 0 ? { initialFields } : {}),
+    };
+}
+export function startReport(instance) {
+    const id = styleText('bold', instance._id);
+    const stage = styleText('bold', instance.currentStage);
+    return instance.completedAt !== undefined
+        ? `Started ${id} — completed immediately at ${stage}`
+        : `Started ${id} — now at ${stage}`;
+}
+export function startResultJson(instance) {
+    return {
+        instanceId: instance._id,
+        definition: instance.definition,
+        version: instance.pinnedVersion,
+        currentStage: instance.currentStage,
+        ...(instance.completedAt !== undefined ? { completedAt: instance.completedAt } : {}),
+    };
+}

package/dist/commands/tail.d.ts

@@ -1,10 +1,13 @@
-import { Command } from '@oclif/core';
-export default class Tail extends Command {
+import { WorkflowCommand } from '../lib/base-command.ts';
+export default class Tail extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
+    static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
     run(): Promise<void>;
     /**
      * Fetch the current instance state, print history entries past the