@sanity/workflow-cli 0.8.1 → 0.10.0

package/dist/commands/diagnose.d.ts

@@ -1,5 +1,20 @@
-import { Command } from '@oclif/core';
-import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation } from '@sanity/workflow-engine';
+import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation, type WorkflowEvaluation } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
+/** The `--json` transitions payload: raw derived state (atom GROQ, negation,
+ *  pivotality, solvable requirement) — structure for scripts, never baked
+ *  English. Pure so the shape is a testable contract. */
+export declare function rawTransitionProjection(evaluation: WorkflowEvaluation): {
+    name: string;
+    to: string;
+    filterSatisfied: boolean;
+    unevaluable: boolean;
+    blockedBy: {
+        requirement?: import("@sanity/groq-condition-describe").AtomRequirement;
+        groq: string;
+        negated: boolean;
+        pivotal: boolean;
+    }[];
+}[];
 /**
  * The diagnosis body: the verdict line, the current stage's activities +
  * transitions as evidence (for any in-flight state), and the cause block with
@@ -8,12 +23,15 @@ import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation } from '@
  * {@link SuggestedRemediation}s rather than re-deriving them, so the rendered
  * fix block and the `--json` output stay one computation.
  */
-export declare function renderDiagnosis({ diagnosis, input, remediations, }: {
+export declare function renderDiagnosis({ diagnosis, input, remediations, explanations, }: {
     diagnosis: Diagnosis;
     input: DiagnoseInput;
     remediations: SuggestedRemediation[];
+    /** Insight summaries per unsatisfied transition name — rendered under the
+     *  transition line so "stuck" reads as "stuck until X". */
+    explanations?: ReadonlyMap<string, string> | undefined;
 }): string[];
-export default class Diagnose extends Command {
+export default class Diagnose extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/diagnose.js

@@ -1,11 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
-import { diagnoseInputFromEvaluation, workflow, } from '@sanity/workflow-engine';
+import { Args } from '@oclif/core';
+import { diagnoseInputFromEvaluation, workflow, unsatisfiedTransitionSummaries, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../lib/client.js";
-import { loadWorkflowConfig } from "../lib/config.js";
-import { fail } from "../lib/fail.js";
-import { tagFlags } from "../lib/flags.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { resolveInstanceContext } from "../lib/context.js";
+import { fail, failureDetail } from "../lib/fail.js";
+import { jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs } from "../lib/operation-args.js";
 import { formatTimestamp, sectionHeader, activityIcon } from "../lib/ui.js";
 import { instanceHeader } from "./show.js";
 function formatAssignee(a) {
@@ -17,11 +18,12 @@ function activityLine(t, assignees) {
         : '';
     return `  ${activityIcon[t.status]} ${t.activity.name} ${styleText('dim', `[${t.status}]`)}${who}`;
 }
-function transitionLine(tr) {
+function transitionLine(tr, explanation) {
     const mark = tr.filterSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
-    return `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    return explanation !== undefined ? `${line}\n      ${styleText('dim', `↳ ${explanation}`)}` : line;
 }
-function currentStageLines(input) {
+function currentStageLines(input, explanations) {
     const lines = [
         `${sectionHeader('Stage')} ${input.instance.currentStage}`,
         sectionHeader('Activities'),
@@ -32,7 +34,7 @@ function currentStageLines(input) {
     if (input.transitions.length > 0) {
         lines.push('', sectionHeader('Exit transitions'));
         for (const tr of input.transitions) {
-            lines.push(transitionLine(tr));
+            lines.push(transitionLine(tr, explanations?.get(tr.transition.name)));
         }
     }
     return lines;
@@ -108,11 +110,6 @@ function noTransitionDetail() {
         ],
     };
 }
-/** An unevaluable exit filter is a *recoverable* hold, not a dead end: it
- *  clears itself once the operand becomes readable, and no engine verb
- *  unsticks it (so the engine emits no remediation). The "what to do" —
- *  make the operand readable — lives here in the why, since there is no
- *  runnable fix to render. */
 function transitionUnevaluableDetail(transitions) {
     return {
         headline: `an exit transition's filter could not be evaluated`,
@@ -121,23 +118,12 @@ function transitionUnevaluableDetail(transitions) {
             `that is missing or unreadable (GROQ null), so routing is held rather than`,
             `falling through. Make the data the filter reads readable — publish the`,
             `subject (or fill the field) — and the instance advances on its own; no`,
-            `move-stage needed.`,
+            `set-stage needed.`,
         ],
     };
 }
-const REMEDIATION_LABEL = {
-    'retry-effect': 'retry-effect',
-    'drain-effects': 're-run the effect drainer',
-    'reset-activity': 'reset-activity',
-    'set-stage': 'move-stage',
-    abort: 'abort',
-};
-/** Render the engine's structured remediations as the "suggested fix" block.
- *  Only the runnable ones reach here — {@link renderDiagnosis} filters out
- *  verbs the CLI can't yet perform so it never advertises a fix you can't run
- *  (the full set, planned verbs included, still rides `--json`). */
 function remediationLines(remediations) {
-    return remediations.map((r) => `  • ${REMEDIATION_LABEL[r.verb]} — ${r.rationale}`);
+    return remediations.map((r) => `  • ${r.verb} — ${r.rationale}`);
 }
 function causeDetail(cause) {
     switch (cause.kind) {
@@ -153,6 +139,11 @@ function causeDetail(cause) {
             return transitionUnevaluableDetail(cause.transitions);
     }
 }
+function liveChildrenTail(diagnosis) {
+    if (diagnosis.liveChildren === undefined)
+        return '';
+    return ` ${styleText('yellow', `${diagnosis.liveChildren} spawned child workflow(s) still running.`)}`;
+}
 function statusLine(diagnosis) {
     switch (diagnosis.state) {
         case 'progressing':
@@ -162,31 +153,37 @@ function statusLine(diagnosis) {
         case 'blocked':
             return `${logSymbols.info} ${styleText('cyan', 'blocked')} — ${blockedHeadline(diagnosis)}`;
         case 'completed':
-            return `${logSymbols.success} ${styleText('green', 'completed')} at ${formatTimestamp(diagnosis.at)}.`;
+            return `${logSymbols.success} ${styleText('green', 'completed')} at ${formatTimestamp(diagnosis.at)}.${liveChildrenTail(diagnosis)}`;
         case 'aborted': {
             const tail = diagnosis.reason !== undefined ? ` — ${diagnosis.reason}` : '';
-            return `${logSymbols.info} ${styleText('dim', 'aborted')} at ${formatTimestamp(diagnosis.at)}${tail}.`;
+            return `${logSymbols.info} ${styleText('dim', 'aborted')} at ${formatTimestamp(diagnosis.at)}${tail}.${liveChildrenTail(diagnosis)}`;
         }
         case 'stuck':
             return `${logSymbols.warning} ${styleText('yellow', 'STUCK')} — ${causeDetail(diagnosis.cause).headline}`;
     }
 }
-/**
- * The diagnosis body: the verdict line, the current stage's activities +
- * transitions as evidence (for any in-flight state), and the cause block with
- * the engine's suggested fix when stuck. Pure so every verdict permutation is
- * assertable without driving a live evaluation. Takes the engine's
- * {@link SuggestedRemediation}s rather than re-deriving them, so the rendered
- * fix block and the `--json` output stay one computation.
- */
-export function renderDiagnosis({ diagnosis, input, remediations, }) {
+export function rawTransitionProjection(evaluation) {
+    return evaluation.currentStage.transitions.map((t) => ({
+        name: t.transition.name,
+        to: t.transition.to,
+        filterSatisfied: t.filterSatisfied,
+        unevaluable: t.unevaluable,
+        blockedBy: t.insight.blockedBy.map((atom) => ({
+            groq: atom.atom.groq,
+            negated: atom.atom.negated,
+            pivotal: atom.pivotal,
+            ...(atom.requirement !== undefined ? { requirement: atom.requirement } : {}),
+        })),
+    }));
+}
+export function renderDiagnosis({ diagnosis, input, remediations, explanations, }) {
     const lines = [statusLine(diagnosis)];
     const inFlight = diagnosis.state === 'progressing' ||
         diagnosis.state === 'waiting' ||
         diagnosis.state === 'blocked' ||
         diagnosis.state === 'stuck';
     if (inFlight) {
-        lines.push('', ...currentStageLines(input));
+        lines.push('', ...currentStageLines(input, explanations));
     }
     if (diagnosis.state === 'waiting') {
         lines.push('', ...waitingLines(diagnosis));
@@ -198,16 +195,13 @@ export function renderDiagnosis({ diagnosis, input, remediations, }) {
         const detail = causeDetail(diagnosis.cause);
         const runnable = remediations.filter((r) => r.available);
         lines.push('', sectionHeader("Why it's stuck"), ...detail.why);
-        // A recoverable hold (e.g. an unevaluable transition filter) has no
-        // runnable remediation — its "what to do" is in the why above, so skip
-        // the empty fix header rather than dangle it.
         if (runnable.length > 0) {
             lines.push('', sectionHeader('Suggested fix'), ...remediationLines(runnable));
         }
     }
     return lines;
 }
-export default class Diagnose extends Command {
+export default class Diagnose extends WorkflowCommand {
     static description = "Explain why a workflow instance is or isn't progressing, and what would unstick it.";
     static examples = [
         '<%= config.bin %> diagnose wf-instance.abc123',
@@ -219,30 +213,18 @@ export default class Diagnose extends Command {
     };
     static flags = {
         ...tagFlags,
-        json: Flags.boolean({
-            description: 'Emit the structured diagnosis as JSON instead of rendered output.',
-            default: false,
-        }),
+        ...jsonFlags,
     };
     async run() {
         const { args, flags } = await this.parse(Diagnose);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
         const { evaluation, diagnosis, remediations } = await workflow
             .diagnose({
             client,
-            tag: config.tag,
-            workflowResource: config.workflowResource,
+            ...baseEngineArgs(scope),
             instanceId: args.instanceId,
-            // Token-auth CLI can't hit /users/me; pin the same system actor the
-            // write verbs use. Transition filters and activity status are actor-
-            // independent. A requirement that reads $actor/$assigned/$can is the
-            // exception — it's evaluated against this system actor, so a `blocked`
-            // verdict on such a requirement reflects the engine's view, not a
-            // specific assignee's.
-            access: { actor: { kind: 'system', id: 'workflow-cli' } },
         })
-            .catch((error) => fail('diagnose failed:', error instanceof Error ? error.message : String(error)));
+            .catch((error) => fail('diagnose failed:', failureDetail(error)));
         const input = diagnoseInputFromEvaluation(evaluation);
         if (flags.json) {
             this.log(JSON.stringify({
@@ -250,12 +232,14 @@ export default class Diagnose extends Command {
                 stage: evaluation.instance.currentStage,
                 diagnosis,
                 remediations,
+                transitions: rawTransitionProjection(evaluation),
             }, null, 2));
             return;
         }
         this.log(instanceHeader(evaluation.instance));
         this.log('');
-        for (const line of renderDiagnosis({ diagnosis, input, remediations })) {
+        const explanations = new Map(unsatisfiedTransitionSummaries(evaluation).map((entry) => [entry.transition, entry.summary]));
+        for (const line of renderDiagnosis({ diagnosis, input, remediations, explanations })) {
             this.log(line);
         }
     }

package/dist/commands/fire-action.d.ts

@@ -1,13 +1,6 @@
-import { Command } from '@oclif/core';
 import { type AvailableAction } from '@sanity/workflow-engine';
-import { type RanOp } from '../lib/ops-report.ts';
-/**
- * Parse repeated `--param key=value` flags into a params object. Each
- * value is JSON-parsed so numbers/booleans/objects type correctly,
- * falling back to the raw string. The engine validates the result against
- * the action's declared param types.
- */
-export declare function parseParams(pairs: string[]): Record<string, unknown>;
+import { WorkflowCommand } from '../lib/base-command.ts';
+import { type WriteOutcome, type WriteReport } from '../lib/ops-report.ts';
 /**
  * The list-mode body: every action on the current stage's activities, marked
  * fireable or not (with the disabling reason), plus a hint showing the
@@ -19,53 +12,37 @@ export declare function renderAvailableActions({ actions, stage, instanceId, }:
     stage: string;
     instanceId: string;
 }): string[];
-interface FireOutcome {
-    fired: boolean;
-    cascaded: number;
-    instance: {
-        currentStage: string;
-    };
-    ranOps?: RanOp[];
-}
 /** The `--json` payload for a fired action — the structured counterpart of
  *  {@link fireActionReport}. Pure so its shape is asserted directly. */
-export declare function fireResultJson(result: FireOutcome, ids: {
+export declare function fireResultJson(result: WriteOutcome, ids: {
     instanceId: string;
     activity: string;
     action: string;
 }): Record<string, unknown>;
-export interface FireActionReport {
-    fired: boolean;
-    message: string;
-    opsLines: string[];
-}
 /**
  * Turn a `fireAction` result into the spinner message + ops block. Pure so
  * the fired / no-op / cascaded / ops permutations assert without a live
  * fire.
  */
 export declare function fireActionReport({ result, activity, action, }: {
-    result: FireOutcome;
+    result: WriteOutcome;
     activity: string;
     action: string;
-}): FireActionReport;
-export default class FireAction extends Command {
+}): WriteReport;
+export default class FireAction extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         activity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         action: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         param: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
-        as: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'as-role': import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
-        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     private listActions;
     private fireOne;
 }
-export {};

package/dist/commands/fire-action.js

@@ -1,60 +1,20 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
-import { workflow, } from '@sanity/workflow-engine';
+import { Args, Flags } from '@oclif/core';
+import { actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import ora from 'ora';
-import { loadClient } from "../lib/client.js";
-import { loadWorkflowConfig } from "../lib/config.js";
-import { fail, failOnThrow } from "../lib/fail.js";
-import { tagFlags } from "../lib/flags.js";
-import { resolveActor } from "../lib/operation-args.js";
-import { emitWriteReport, opsAppliedLines } from "../lib/ops-report.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { resolveInstanceContext } from "../lib/context.js";
+import { fail, failOnThrow, failureDetail } from "../lib/fail.js";
+import { jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs } from "../lib/operation-args.js";
+import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../lib/ops-report.js";
+import { parseParams } from "../lib/params.js";
 import { instanceHeader } from "./show.js";
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function coerceParamValue(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        // Not valid JSON — treat it as a plain string so `--param note=hi`
-        // needs no quoting. The engine validates against the action's
-        // declared param type either way.
-        return raw;
-    }
-}
-function parseParam(pair) {
-    const eq = pair.indexOf('=');
-    if (eq < 1) {
-        throw new Error(`expected key=value, got "${pair}"`);
-    }
-    return [pair.slice(0, eq), coerceParamValue(pair.slice(eq + 1))];
-}
-/**
- * Parse repeated `--param key=value` flags into a params object. Each
- * value is JSON-parsed so numbers/booleans/objects type correctly,
- * falling back to the raw string. The engine validates the result against
- * the action's declared param types.
- */
-export function parseParams(pairs) {
-    return Object.fromEntries(pairs.map(parseParam));
-}
 function reasonText(reason) {
-    switch (reason.kind) {
-        case 'filter-failed':
-            return `action filter not satisfied${reason.detail ? ` (${reason.detail})` : ''}`;
-        case 'activity-not-active':
-            return `activity is ${reason.status}`;
-        case 'stage-terminal':
-            return `stage '${reason.stage}' is terminal`;
-        case 'mutation-guard-denied':
-            return `blocked by mutation guard(s) ${reason.guardIds.join(', ')}${reason.detail ? ` (${reason.detail})` : ''}`;
-        case 'instance-completed':
-            return `instance completed at ${reason.completedAt}`;
-        case 'requirements-unmet':
-            return `unmet requirement(s): ${reason.unmetRequirements.join(', ')}`;
+    if (reason.kind === 'mutation-guard-denied') {
+        return `blocked by mutation guard(s) ${deniedGuardLabels(reason.denied).join(', ')}`;
     }
+    return actionDisabledDetail(reason);
 }
 function paramLabel(p) {
     return `${p.name}${p.required === true ? '' : '?'}:${p.type}`;
@@ -73,12 +33,6 @@ function actionLines(a) {
     }
     return lines;
 }
-/**
- * The list-mode body: every action on the current stage's activities, marked
- * fireable or not (with the disabling reason), plus a hint showing the
- * flags to fire one. Pure so the populated/empty permutations assert
- * without a live evaluation.
- */
 export function renderAvailableActions({ actions, stage, instanceId, }) {
     if (actions.length === 0) {
         return [`No actions on the activities of the current stage ('${stage}').`];
@@ -90,46 +44,37 @@ export function renderAvailableActions({ actions, stage, instanceId, }) {
     lines.push('', styleText('dim', 'Fire one with:'), styleText('dim', `  fire-action ${instanceId} --activity <activity> --action <action>`));
     return lines;
 }
-/** The `--json` payload for a fired action — the structured counterpart of
- *  {@link fireActionReport}. Pure so its shape is asserted directly. */
 export function fireResultJson(result, ids) {
     return {
         instanceId: ids.instanceId,
         activity: ids.activity,
         action: ids.action,
-        fired: result.fired,
+        changed: result.changed,
         cascaded: result.cascaded,
         currentStage: result.instance.currentStage,
         ...(result.ranOps !== undefined ? { ranOps: result.ranOps } : {}),
     };
 }
-/**
- * Turn a `fireAction` result into the spinner message + ops block. Pure so
- * the fired / no-op / cascaded / ops permutations assert without a live
- * fire.
- */
 export function fireActionReport({ result, activity, action, }) {
     const stage = styleText('bold', result.instance.currentStage);
-    if (!result.fired) {
+    if (!result.changed) {
         return {
-            fired: false,
+            changed: false,
             message: `fireAction returned without firing — activity '${activity}' is no longer active`,
             opsLines: [],
         };
     }
-    const tail = result.cascaded > 0 ? `, then cascaded ${result.cascaded} auto-transition(s)` : '';
     return {
-        fired: true,
-        message: `Fired ${styleText('bold', action)} on ${styleText('bold', activity)} — now at ${stage}${tail}`,
+        changed: true,
+        message: `Fired ${styleText('bold', action)} on ${styleText('bold', activity)} — now at ${stage}${cascadeTail(result.cascaded)}`,
         opsLines: opsAppliedLines(result.ranOps),
     };
 }
-export default class FireAction extends Command {
-    static description = "Fire an action on an instance — act on a user's behalf to unstick a waiting activity. Omit --action to list what can be fired.";
+export default class FireAction extends WorkflowCommand {
+    static description = 'Fire an action on an instance to unstick a waiting activity — the write acts as the configured token. Omit --action to list what can be fired.';
     static examples = [
         '<%= config.bin %> fire-action wf-instance.abc123',
         '<%= config.bin %> fire-action wf-instance.abc123 --activity approve --action approve',
-        '<%= config.bin %> fire-action wf-instance.abc123 --activity approve --action approve --as user.xyz --as-role editor',
         '<%= config.bin %> fire-action wf-instance.abc123 --activity publish --action publish --param note=shipping',
     ];
     static args = {
@@ -148,26 +93,18 @@ export default class FireAction extends Command {
             multiple: true,
             default: [],
         }),
-        as: Flags.string({
-            description: 'Attribute the fire to this Sanity user id (default: a workflow-cli system actor).',
-        }),
-        'as-role': Flags.string({
-            description: 'Role to attribute to the --as user (repeatable), so role-gated filters pass.',
-            multiple: true,
-            default: [],
-        }),
-        json: Flags.boolean({
-            description: 'Emit structured JSON instead of rendered output.',
-            default: false,
-        }),
+        ...jsonFlags,
     };
     async run() {
         const { args, flags } = await this.parse(FireAction);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
-        const actor = failOnThrow('fire-action usage error:', () => resolveActor(flags.as, flags['as-role']));
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
         if (flags.action === undefined) {
-            await this.listActions({ client, config, instanceId: args.instanceId, actor, json: flags.json });
+            await this.listActions({
+                client,
+                scope,
+                instanceId: args.instanceId,
+                json: flags.json,
+            });
             return;
         }
         if (flags.activity === undefined) {
@@ -175,25 +112,22 @@ export default class FireAction extends Command {
         }
         await this.fireOne({
             client,
-            config,
+            scope,
             instanceId: args.instanceId,
-            actor,
             activity: flags.activity,
             action: flags.action,
             params: flags.param,
             json: flags.json,
         });
     }
-    async listActions({ client, config, instanceId, actor, json, }) {
+    async listActions({ client, scope, instanceId, json, }) {
         const { evaluation, actions } = await workflow
             .availableActions({
             client,
-            tag: config.tag,
-            workflowResource: config.workflowResource,
+            ...baseEngineArgs(scope),
             instanceId,
-            access: { actor },
         })
-            .catch((error) => fail('fire-action failed:', errorMessage(error)));
+            .catch((error) => fail('fire-action failed:', failureDetail(error)));
         const stage = evaluation.instance.currentStage;
         if (json) {
             this.log(JSON.stringify({ instanceId, stage, actions }, null, 2));
@@ -206,37 +140,30 @@ export default class FireAction extends Command {
         }
     }
     async fireOne(opts) {
-        const { client, config, instanceId, actor, activity, action, json } = opts;
+        const { client, scope, instanceId, activity, action, json } = opts;
         const params = failOnThrow('Invalid --param:', () => parseParams(opts.params));
         const fireArgs = {
             client,
-            tag: config.tag,
-            workflowResource: config.workflowResource,
+            ...baseEngineArgs(scope),
             instanceId,
             activity,
             action,
-            access: { actor },
             params,
         };
         if (json) {
             const result = await workflow
                 .fireAction(fireArgs)
-                .catch((error) => fail('fireAction error:', errorMessage(error)));
+                .catch((error) => fail('fire-action error:', failureDetail(error)));
             this.log(JSON.stringify(fireResultJson(result, { instanceId, activity, action }), null, 2));
             return;
         }
-        const spinner = ora(`Firing ${action} on ${activity}…`).start();
-        try {
-            const result = await workflow.fireAction(fireArgs);
-            emitWriteReport({
-                spinner,
-                report: fireActionReport({ result, activity, action }),
-                log: (line) => this.log(line),
-            });
-        }
-        catch (error) {
-            spinner.fail('Action rejected');
-            fail('fireAction error:', errorMessage(error));
-        }
+        await runWriteVerb({
+            startLabel: `Firing ${action} on ${activity}…`,
+            failLabel: 'Action rejected',
+            failHeadline: 'fire-action error:',
+            run: () => workflow.fireAction(fireArgs),
+            report: (result) => fireActionReport({ result, activity, action }),
+            log: (line) => this.log(line),
+        });
     }
 }

package/dist/commands/list.d.ts

@@ -1,18 +1,18 @@
-import { Command } from '@oclif/core';
+import { type TerminalState } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
 interface InstanceRow {
     _id: string;
     definition: string;
     tag: string;
     currentStage: string;
-    completedAt?: string;
-    abortedAt?: string;
+    completedAt?: string | null;
+    abortedAt?: string | null;
     lastChangedAt: string;
 }
-type InstanceStatus = 'aborted' | 'completed' | 'in-flight';
 interface ListFlags {
     'in-flight': boolean;
     failed: boolean;
-    'workflow-name'?: string | undefined;
+    definition?: string | undefined;
     tag?: string | undefined;
     limit: number;
 }
@@ -25,23 +25,22 @@ export declare function buildListQuery(flags: ListFlags): {
     groq: string;
     params: Record<string, unknown>;
 };
-/** Map a queried instance to its display row (derives the status column).
- *  Pure — status is the semantic value; the table colors it at render. */
+/** Map a queried instance to its display row (derives the status column). */
 export declare function instanceRow(r: InstanceRow): {
     _id: string;
     definition: string;
     tag: string;
     currentStage: string;
-    status: InstanceStatus;
+    status: TerminalState;
     lastChangedAt: string;
 };
-export default class List extends Command {
+export default class List extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
         'in-flight': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         failed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        definition: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };