@sanity/workflow-cli 0.11.0 → 0.13.0

package/dist/commands/{diagnose.js → editorial-workflows/diagnose.js}

@@ -2,12 +2,12 @@ import { styleText } from 'node:util';
 import { Args } from '@oclif/core';
 import { diagnoseInputFromEvaluation, workflow, unsatisfiedTransitionSummaries, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-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 { 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) {
     return a.type === 'user' ? `user:${a.id}` : `role:${a.role}`;
@@ -212,6 +212,7 @@ export function renderDiagnosis({ diagnosis, input, remediations, explanations,
     return lines;
 }
 export default class Diagnose extends WorkflowCommand {
+    static aliases = ['diagnose'];
     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',

package/dist/commands/{fire-action.d.ts → editorial-workflows/fire-action.d.ts}

@@ -1,6 +1,6 @@
 import { type AvailableAction } from '@sanity/workflow-engine';
-import { WorkflowCommand } from '../lib/base-command.ts';
-import { type WriteOutcome, type WriteReport } from '../lib/ops-report.ts';
+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
@@ -30,6 +30,7 @@ export declare function fireActionReport({ result, activity, action, }: {
     action: string;
 }): WriteReport;
 export default class FireAction extends WorkflowCommand {
+    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{fire-action.js → editorial-workflows/fire-action.js}

@@ -2,13 +2,13 @@ import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
 import { actionRendering, actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-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 { 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 reasonText(reason) {
     if (reason.kind === 'mutation-guard-denied') {
@@ -82,6 +82,7 @@ export function fireActionReport({ result, activity, action, }) {
     };
 }
 export default class FireAction extends WorkflowCommand {
+    static aliases = ['fire-action'];
     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',

package/dist/commands/{list.d.ts → editorial-workflows/list.d.ts}

@@ -1,5 +1,5 @@
 import { type TerminalState } from '@sanity/workflow-engine';
-import { WorkflowCommand } from '../lib/base-command.ts';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 interface InstanceRow {
     _id: string;
     definition: string;
@@ -8,6 +8,8 @@ interface InstanceRow {
     completedAt?: string | null;
     abortedAt?: string | null;
     lastChangedAt: string;
+    modelVersion?: number | null;
+    minReaderModel?: number | null;
 }
 interface ListFlags {
     'include-completed': boolean;
@@ -43,6 +45,7 @@ export declare function instanceRow(r: InstanceRow): {
     lastChangedAt: string;
 };
 export default class List extends WorkflowCommand {
+    static aliases: string[];
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/{list.js → editorial-workflows/list.js}

@@ -1,12 +1,12 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_INSTANCE_TYPE, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
+import { WORKFLOW_INSTANCE_TYPE, assertReadableModel, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { WorkflowCommand } from "../lib/base-command.js";
-import { resolveReadTargets } from "../lib/context.js";
-import { failOnThrow } from "../lib/fail.js";
-import { tagFlags } from "../lib/flags.js";
-import { runReadAcrossTargets } from "../lib/read-fanout.js";
-import { clipToLimit, formatAge, formatTable } from "../lib/ui.js";
+import { WorkflowCommand } from "../../lib/base-command.js";
+import { resolveReadTargets } from "../../lib/context.js";
+import { failOnThrow } from "../../lib/fail.js";
+import { tagFlags } from "../../lib/flags.js";
+import { runReadAcrossTargets } from "../../lib/read-fanout.js";
+import { formatAge, logClippedTable } from "../../lib/ui.js";
 export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
     const params = {};
@@ -36,7 +36,9 @@ export function buildListQuery(flags) {
       currentStage,
       completedAt,
       abortedAt,
-      lastChangedAt
+      lastChangedAt,
+      modelVersion,
+      minReaderModel
     }`;
     return { groq, params };
 }
@@ -54,6 +56,7 @@ export function instanceRow(r) {
     };
 }
 export default class List extends WorkflowCommand {
+    static aliases = ['list'];
     static description = 'List workflow instances in the configured dataset (in-flight by default).';
     static examples = [
         '<%= config.bin %> list',
@@ -98,24 +101,23 @@ export default class List extends WorkflowCommand {
                     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);
-                }
+                logClippedTable({
+                    rows: fetched,
+                    limit: flags.limit,
+                    headers: ['instance', 'workflow', 'tag', 'stage', 'status', 'updated'],
+                    toCells: (r) => {
+                        const row = instanceRow(r);
+                        return [
+                            row._id,
+                            row.definition,
+                            row.tag,
+                            row.currentStage,
+                            row.status,
+                            formatAge(row.lastChangedAt),
+                        ];
+                    },
+                    log: (line) => this.log(line),
+                });
             },
         });
         if (failures.length > 0) {
@@ -125,8 +127,11 @@ export default class List extends WorkflowCommand {
 }
 async function fetchRows({ client, groq, params, document, }) {
     if (document === undefined) {
-        return client.fetch(groq, params, { tag: 'list' });
+        const rows = await client.fetch(groq, params, { tag: 'list' });
+        return rows.map(assertReadableModel);
     }
     const candidates = await client.fetch(groq, params, { tag: 'list' });
-    return candidates.filter((instance) => instanceWatchesDocument(instance, document));
+    return candidates
+        .map(assertReadableModel)
+        .filter((instance) => instanceWatchesDocument(instance, document));
 }

package/dist/commands/editorial-workflows/nuke.d.ts

@@ -0,0 +1,12 @@
+import { WorkflowCommand } from '../../lib/base-command.ts';
+export default class Nuke extends WorkflowCommand {
+    static aliases: string[];
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/editorial-workflows/nuke.js

@@ -0,0 +1,77 @@
+import { Flags } from '@oclif/core';
+import { input } from '@sanity/cli-core/ux';
+import { resourceGdr } from '@sanity/workflow-engine';
+import logSymbols from 'log-symbols';
+import { WorkflowCommand } from "../../lib/base-command.js";
+import { clientFor, resolveApiHost, resolveTokenOrFail } from "../../lib/client.js";
+import { dedupeResources } from "../../lib/context.js";
+import { fail } from "../../lib/fail.js";
+import { loadWorkflowConfig } from "../../lib/load-config.js";
+import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, renderNukePlan, resolveNukePlan, } from "../../lib/nuke.js";
+import { runWriteVerb } from "../../lib/ops-report.js";
+import { canPromptOnStderr } from "../../lib/prompt.js";
+import { selectDeployment } from "../../lib/select-deployment.js";
+export default class Nuke extends WorkflowCommand {
+    static aliases = ['nuke'];
+    static summary = 'Delete every engine-owned document for a deployment tag — the dev-period big red button.';
+    static description = 'The reset for a dataset holding engine documents the versioned upgrade framework cannot yet ' +
+        "migrate: deletes the tag's instances, definitions, and guards (across every alias-bound " +
+        'resource). Content documents are never touched. Prints a dry-run plan, then requires you to ' +
+        'type back every involved dataset (--force skips the prompt; the plan still prints).';
+    static examples = [
+        '<%= config.bin %> nuke --tag plugin-dev',
+        '<%= config.bin %> nuke --tag plugin-dev --force',
+    ];
+    static flags = {
+        tag: Flags.string({
+            description: 'The deployment tag to reset. Required — a destructive reset never guesses the environment.',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Nuke);
+        const config = await loadWorkflowConfig();
+        const deployment = selectDeployment(config, { tag: flags.tag });
+        const targets = buildTargets(deployment, await resolveTokenOrFail());
+        const plan = await resolveNukePlan({ tag: deployment.tag, targets });
+        const apiHost = resolveApiHost() ?? 'https://api.sanity.io (production default)';
+        renderNukePlan(plan, apiHost).forEach((line) => this.log(line));
+        const counts = planCounts(plan);
+        if (counts.total === 0) {
+            this.log(`${logSymbols.info} Nothing to nuke for tag "${deployment.tag}".`);
+            return;
+        }
+        if (!flags.force)
+            await confirmOrFail(involvedTargets(plan));
+        await runWriteVerb({
+            startLabel: 'Nuking…',
+            failLabel: 'Nuke failed',
+            failHeadline: 'workflow nuke error:',
+            run: () => executeNuke(plan),
+            report: () => ({ changed: true, message: formatNukeSummary(deployment.tag, counts) }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+function buildTargets(deployment, token) {
+    const engineResource = deployment.workflowResource;
+    const aliasResources = (deployment.resourceAliases ?? []).map((binding) => binding.resource);
+    return dedupeResources([engineResource, ...aliasResources]).map((resource) => ({
+        resource,
+        client: clientFor(resource, token),
+        holdsEngineDocs: resourceGdr(resource) === resourceGdr(engineResource),
+    }));
+}
+async function confirmOrFail(targets) {
+    if (!canPromptOnStderr()) {
+        fail('Refusing to nuke without confirmation in a non-interactive shell.', 'Re-run with --force to skip the prompt.');
+    }
+    const answer = await input({ message: `Type every target to confirm deletion (space-separated):\n  ${targets.join(' ')}\n` }, { output: process.stderr });
+    if (!confirmationMatches(answer, targets)) {
+        fail('Confirmation did not match — nothing was deleted.', `Expected: ${targets.join(' ')}`);
+    }
+}

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

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

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

@@ -1,6 +1,7 @@
 import { Args } from '@oclif/core';
-import { StubCommand } from "../lib/stub.js";
+import { StubCommand } from "../../lib/stub.js";
 export default class ResetActivity extends StubCommand {
+    static hiddenAliases = ['reset-activity'];
     static hidden = true;
     static description = 'Reset a failed activity on an in-flight instance — back to pending (re-run) or to skipped (bypass).';
     static args = {

package/dist/commands/{set-stage.d.ts → editorial-workflows/set-stage.d.ts}

@@ -1,8 +1,9 @@
 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';
+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 aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{set-stage.js → editorial-workflows/set-stage.js}

@@ -1,12 +1,13 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
 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";
+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 aliases = ['set-stage'];
     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',

package/dist/commands/{show.d.ts → editorial-workflows/show.d.ts}

@@ -1,6 +1,7 @@
 import { type WorkflowInstance } from '@sanity/workflow-engine';
-import { WorkflowCommand } from '../lib/base-command.ts';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Show extends WorkflowCommand {
+    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{show.js → editorial-workflows/show.js}

@@ -2,11 +2,12 @@ import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
 import { abortReason, displayTitle, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-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";
+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 WorkflowCommand {
+    static aliases = ['show'];
     static description = 'Show the state, activities, and effects of a workflow instance.';
     static examples = [
         '<%= config.bin %> show wf-instance.abc123',
@@ -67,27 +68,40 @@ export function instanceHeader(instance) {
     return [title, ...rows].join('\n');
 }
 export function describeInstance(instance, options) {
-    const lines = [sectionHeader('Stages')];
-    for (const stage of instance.stages) {
-        const marker = stage.exitedAt
-            ? styleText('dim', ` (exited ${formatTimestamp(stage.exitedAt)})`)
-            : styleText('cyan', ' (current)');
-        lines.push(`  • ${stage.name}${marker}`);
-        for (const activity of stage.activities ?? []) {
-            lines.push(`      ${activityIcon[activity.status]} ${activity.name}  ${styleText('dim', `[${activity.status}]`)}`);
-        }
-    }
-    if (instance.pendingEffects.length > 0) {
-        lines.push('', sectionHeader('Pending effects'));
-        for (const eff of instance.pendingEffects) {
-            lines.push(`  • ${eff.name}  ${styleText('dim', `(key=${eff._key})`)}`);
-        }
-    }
-    if (options.includeHistory) {
-        lines.push('', sectionHeader('History'));
-        for (const entry of instance.history) {
-            lines.push(`  ${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${displayTitle(entry._type)}`);
-        }
+    return [
+        ...stageLines(instance),
+        ...pendingEffectLines(instance),
+        ...(options.includeHistory ? historyLines(instance) : []),
+    ];
+}
+function stageLines(instance) {
+    return [
+        sectionHeader('Stages'),
+        ...instance.stages.flatMap((stage) => [
+            `  • ${stage.name}${stageMarker(stage)}`,
+            ...(stage.activities ?? []).map((activity) => `      ${activityIcon[activity.status]} ${activity.name}  ${styleText('dim', `[${activity.status}]`)}`),
+        ]),
+    ];
+}
+function stageMarker(stage) {
+    return stage.exitedAt
+        ? styleText('dim', ` (exited ${formatTimestamp(stage.exitedAt)})`)
+        : styleText('cyan', ' (current)');
+}
+function pendingEffectLines(instance) {
+    if (instance.pendingEffects.length === 0) {
+        return [];
     }
-    return lines;
+    return [
+        '',
+        sectionHeader('Pending effects'),
+        ...instance.pendingEffects.map((eff) => `  • ${eff.name}  ${styleText('dim', `(key=${eff._key})`)}`),
+    ];
+}
+function historyLines(instance) {
+    return [
+        '',
+        sectionHeader('History'),
+        ...instance.history.map((entry) => `  ${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${displayTitle(entry._type)}`),
+    ];
 }

package/dist/commands/{start.d.ts → editorial-workflows/start.d.ts}

@@ -1,7 +1,8 @@
-import { type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } from '@sanity/workflow-engine';
-import { WorkflowCommand } from '../lib/base-command.ts';
-import { type EngineScope } from '../lib/operation-args.ts';
+import { StartNotSettledError, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } 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 aliases: string[];
     static description: string;
     static examples: string[];
     static args: {
@@ -11,20 +12,35 @@ export default class Start extends WorkflowCommand {
         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>;
+        'instance-id': 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>;
 }
+/** A created-but-unprimed failure is resumable — the engine message names
+ *  the id and the generic remediation; operators need the CLI's own retry
+ *  spelling appended. Every other error passes through untouched. */
+export declare function withRetryHint(error: unknown): unknown;
+/** The spinner message for a start whose first cascade failed after the
+ *  instance was created and primed: the run exists — say so, name the cause,
+ *  and point at the retry rail instead of reporting a rejection. */
+export declare function startNotSettledReport(error: StartNotSettledError): string;
+/** The `--json` payload for a not-settled start — same `instanceId` key as
+ *  the success payload so scripts can pick up the retry id either way. */
+export declare function startNotSettledJson(error: StartNotSettledError): Record<string, unknown>;
 /**
  * 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, }: {
+export declare function buildStartArgs({ scope, name, version, initialFields, instanceId, }: {
     scope: EngineScope;
     name: string;
     version: number | undefined;
     initialFields: InitialFieldValue[];
+    /** The start's idempotency key (`--instance-id`) — a retry carrying it
+     *  resumes the earlier attempt instead of creating a duplicate. */
+    instanceId?: string | undefined;
 }): StartInstanceArgs & EngineScope;
 /** The success spinner message. Pure so the in-flight / immediately-terminal
  *  permutations can be asserted without driving a real start. */

package/dist/commands/{start.js → editorial-workflows/start.js}

@@ -1,21 +1,23 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { buildInitialFields, startRefusal, 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";
+import { buildInitialFields, errorMessage, StartNotPrimedError, StartNotSettledError, startRefusal, 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 aliases = ['start'];
     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',
+        '<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6',
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
@@ -32,6 +34,12 @@ export default class Start extends WorkflowCommand {
             multiple: true,
             default: [],
         }),
+        'instance-id': Flags.string({
+            description: "Start under this instance id — for retries. The id is the start's idempotency key: " +
+                'pass the id of a start that failed partway and the engine resumes it instead of ' +
+                'creating a duplicate (an already-settled start replays as a no-op). Omit to mint ' +
+                'a fresh id.',
+        }),
         ...jsonFlags,
     };
     async run() {
@@ -52,25 +60,58 @@ export default class Start extends WorkflowCommand {
                 name: args.name,
                 version: flags.version,
                 initialFields,
+                instanceId: flags['instance-id'],
             }),
         };
         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));
+            const result = await workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError) {
+                    this.log(JSON.stringify(startNotSettledJson(error), null, 2));
+                    return undefined;
+                }
+                fail('start error:', failureDetail(withRetryHint(error)));
+            });
+            if (result !== undefined) {
+                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) }),
+            run: () => workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError)
+                    return error;
+                throw withRetryHint(error);
+            }),
+            report: (result) => result instanceof StartNotSettledError
+                ? { changed: false, message: startNotSettledReport(result) }
+                : { changed: true, message: startReport(result.instance) },
             log: (line) => this.log(line),
         });
     }
 }
+export function withRetryHint(error) {
+    return error instanceof StartNotPrimedError
+        ? new Error(`${errorMessage(error)} (--instance-id ${error.instanceId})`)
+        : error;
+}
+export function startNotSettledReport(error) {
+    const id = styleText('bold', error.instanceId);
+    return (`Started ${id} — but its first auto-advance failed: ${errorMessage(error.cause)}. ` +
+        `It settles on the next tick, or retry with --instance-id ${error.instanceId}.`);
+}
+export function startNotSettledJson(error) {
+    return {
+        instanceId: error.instanceId,
+        notSettled: true,
+        detail: errorMessage(error.cause),
+        ...(error.instance !== undefined
+            ? { currentStage: error.instance.currentStage, definition: error.instance.definition }
+            : {}),
+    };
+}
 async function resolveStartInputs({ client, name, tag, version, values, }) {
     const deployed = await fetchDeployedDefinition({ client, name, tag, version });
     if (deployed === undefined) {
@@ -82,12 +123,13 @@ async function resolveStartInputs({ client, name, tag, version, values, }) {
     }
     return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
 }
-export function buildStartArgs({ scope, name, version, initialFields, }) {
+export function buildStartArgs({ scope, name, version, initialFields, instanceId, }) {
     return {
         ...baseEngineArgs(scope),
         definition: name,
         ...(version !== undefined ? { version } : {}),
         ...(initialFields.length > 0 ? { initialFields } : {}),
+        ...(instanceId !== undefined ? { instanceId } : {}),
     };
 }
 export function startReport(instance) {

package/dist/commands/{tail.d.ts → editorial-workflows/tail.d.ts}

@@ -1,5 +1,6 @@
-import { WorkflowCommand } from '../lib/base-command.ts';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Tail extends WorkflowCommand {
+    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {