@sanity/workflow-cli 0.8.0 → 0.9.0

package/dist/commands/fire-action.js

@@ -1,45 +1,15 @@
 import { styleText } from 'node:util';
 import { Args, Command, Flags } from '@oclif/core';
-import { workflow, } from '@sanity/workflow-engine';
+import { 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 { resolveInstanceContext } from "../lib/context.js";
+import { errorMessage, fail, failOnThrow } from "../lib/fail.js";
+import { actorFlags, jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs, resolveActor } from "../lib/operation-args.js";
+import { emitWriteReport, opsAppliedLines, } 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':
@@ -49,7 +19,7 @@ function reasonText(reason) {
         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})` : ''}`;
+            return `blocked by mutation guard(s) ${deniedGuardLabels(reason.denied).join(', ')}`;
         case 'instance-completed':
             return `instance completed at ${reason.completedAt}`;
         case 'requirements-unmet':
@@ -79,7 +49,7 @@ function actionLines(a) {
  * flags to fire one. Pure so the populated/empty permutations assert
  * without a live evaluation.
  */
-export function renderAvailableActions(actions, stage, instanceId) {
+export function renderAvailableActions({ actions, stage, instanceId, }) {
     if (actions.length === 0) {
         return [`No actions on the activities of the current stage ('${stage}').`];
     }
@@ -97,7 +67,7 @@ export function fireResultJson(result, ids) {
         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 } : {}),
@@ -108,18 +78,18 @@ export function fireResultJson(result, ids) {
  * the fired / no-op / cascaded / ops permutations assert without a live
  * fire.
  */
-export function fireActionReport(result, activity, action) {
+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,
+        changed: true,
         message: `Fired ${styleText('bold', action)} on ${styleText('bold', activity)} — now at ${stage}${tail}`,
         opsLines: opsAppliedLines(result.ranOps),
     };
@@ -148,26 +118,21 @@ 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,
-        }),
+        ...actorFlags,
+        ...jsonFlags,
     };
     async run() {
         const { args, flags } = await this.parse(FireAction);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
         const actor = failOnThrow('fire-action usage error:', () => resolveActor(flags.as, flags['as-role']));
         if (flags.action === undefined) {
-            await this.listActions(client, config, args.instanceId, actor, flags.json);
+            await this.listActions({
+                client,
+                scope,
+                instanceId: args.instanceId,
+                actor,
+                json: flags.json,
+            });
             return;
         }
         if (flags.activity === undefined) {
@@ -175,7 +140,7 @@ export default class FireAction extends Command {
         }
         await this.fireOne({
             client,
-            config,
+            scope,
             instanceId: args.instanceId,
             actor,
             activity: flags.activity,
@@ -184,14 +149,12 @@ export default class FireAction extends Command {
             json: flags.json,
         });
     }
-    async listActions(client, config, instanceId, actor, json) {
+    async listActions({ client, scope, instanceId, actor, json, }) {
         const { evaluation, actions } = await workflow
             .availableActions({
             client,
-            tag: config.tag,
-            workflowResource: config.workflowResource,
+            ...baseEngineArgs(scope, actor),
             instanceId,
-            access: { actor },
         })
             .catch((error) => fail('fire-action failed:', errorMessage(error)));
         const stage = evaluation.instance.currentStage;
@@ -201,38 +164,40 @@ export default class FireAction extends Command {
         }
         this.log(instanceHeader(evaluation.instance));
         this.log('');
-        for (const line of renderAvailableActions(actions, stage, instanceId)) {
+        for (const line of renderAvailableActions({ actions, stage, instanceId })) {
             this.log(line);
         }
     }
     async fireOne(opts) {
-        const { client, config, instanceId, actor, activity, action, json } = opts;
+        const { client, scope, instanceId, actor, activity, action, json } = opts;
         const params = failOnThrow('Invalid --param:', () => parseParams(opts.params));
         const fireArgs = {
             client,
-            tag: config.tag,
-            workflowResource: config.workflowResource,
+            ...baseEngineArgs(scope, actor),
             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:', errorMessage(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, fireActionReport(result, activity, action), (line) => this.log(line));
+            emitWriteReport({
+                spinner,
+                report: fireActionReport({ result, activity, action }),
+                log: (line) => this.log(line),
+            });
         }
         catch (error) {
             spinner.fail('Action rejected');
-            fail('fireAction error:', errorMessage(error));
+            fail('fire-action error:', errorMessage(error));
         }
     }
 }

package/dist/commands/list.d.ts

@@ -12,7 +12,7 @@ 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;
 }
@@ -41,7 +41,7 @@ export default class List extends Command {
     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>;
     };

package/dist/commands/list.js

@@ -3,7 +3,7 @@ import { Command, Flags } from '@oclif/core';
 import { WORKFLOW_INSTANCE_TYPE, tagScopeFilter } from '@sanity/workflow-engine';
 import { Table } from 'console-table-printer';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../lib/client.js";
+import { resolveReadContext } from "../lib/context.js";
 import { tagFlags } from "../lib/flags.js";
 import { formatAge } from "../lib/ui.js";
 /**
@@ -15,7 +15,7 @@ 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)
@@ -32,8 +32,8 @@ export function buildListQuery(flags) {
       lastChangedAt
     }`;
     const params = { limit: flags.limit };
-    if (flags['workflow-name'])
-        params['definition'] = flags['workflow-name'];
+    if (flags.definition)
+        params['definition'] = flags.definition;
     if (flags.tag)
         params['tag'] = flags.tag;
     return { groq, params };
@@ -68,7 +68,7 @@ export default class List extends Command {
     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 +81,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,8 +91,8 @@ export default class List extends Command {
     };
     async run() {
         const { flags } = await this.parse(List);
+        const { client } = await resolveReadContext(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`);

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,9 @@
 import { Args } from '@oclif/core';
 import { StubCommand } from "../lib/stub.js";
-export default class RetryActivity extends StubCommand {
+export default class ResetActivity extends StubCommand {
     // Stubbed, so kept off the help + published surface until it's wired.
     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 { Command } from '@oclif/core';
+import { type SetStageArgs, type WorkflowInstance } from '@sanity/workflow-engine';
+import { type EngineScope } from '../lib/operation-args.ts';
+import { type WriteOutcome, type WriteReport } from '../lib/ops-report.ts';
+export default class SetStage extends Command {
     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,85 @@
-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 { styleText } from 'node:util';
+import { Args, Command, Flags } from '@oclif/core';
+import { workflow } from '@sanity/workflow-engine';
+import ora from 'ora';
+import { resolveInstanceContext } from "../lib/context.js";
+import { errorMessage, fail } from "../lib/fail.js";
+import { tagFlags } from "../lib/flags.js";
+import { buildOperationArgs } from "../lib/operation-args.js";
+import { emitWriteReport, opsAppliedLines, } from "../lib/ops-report.js";
+export default class SetStage extends Command {
+    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);
+        const spinner = ora(`Setting ${args.instanceId} → ${flags.to}…`).start();
+        try {
+            const result = await workflow.setStage({
+                client,
+                ...buildSetStageArgs({
+                    scope,
+                    instanceId: args.instanceId,
+                    targetStage: flags.to,
+                    reason: flags.reason,
+                }),
+            });
+            emitWriteReport({
+                spinner,
+                report: setStageReport(result, flags.to),
+                log: (line) => this.log(line),
+            });
+        }
+        catch (error) {
+            spinner.fail('Stage move rejected');
+            fail('set-stage error:', errorMessage(error));
+        }
+    }
+}
+/** The shared operation args ({@link buildOperationArgs}) plus the
+ *  setStage-specific target. */
+export function buildSetStageArgs({ scope, instanceId, targetStage, reason, }) {
+    return { ...buildOperationArgs({ scope, instanceId, reason }), targetStage };
+}
+/**
+ * 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 function setStageReport(result, to) {
+    const stage = styleText('bold', result.instance.currentStage);
+    if (!result.changed) {
+        // The engine no-ops in two distinct cases: a terminal instance never
+        // moves again, and a same-stage move has nothing to do.
+        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: [] };
+    }
+    const tail = result.cascaded > 0 ? `, then cascaded ${result.cascaded} auto-transition(s)` : '';
+    return {
+        changed: true,
+        message: `Now at ${stage} (was → ${to}${tail})`,
+        opsLines: opsAppliedLines(result.ranOps),
     };
 }

package/dist/commands/show.d.ts

@@ -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

@@ -2,7 +2,8 @@ import { styleText } from 'node:util';
 import { Args, Command, Flags } from '@oclif/core';
 import { abortReason } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../lib/client.js";
+import { resolveReadContext } 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 {
     static description = 'Show the state, activities, and effects of a workflow instance.';
@@ -17,6 +18,7 @@ export default class Show extends Command {
         }),
     };
     static flags = {
+        ...tagFlags,
         include: Flags.string({
             description: 'Optional sections to include in output.',
             options: ['history'],
@@ -26,7 +28,7 @@ export default class Show extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Show);
-        const client = loadClient();
+        const { client } = await resolveReadContext(flags);
         const instance = await client.getDocument(args.instanceId);
         if (!instance) {
             this.error(`${logSymbols.error} no instance with id "${args.instanceId}"`, { exit: 1 });
@@ -46,8 +48,8 @@ const HEADER_PAD = 9; // "Completed" — the longest label in the block
 export function instanceHeader(instance) {
     const title = `${styleText('bold', `${instance.definition} v${instance.pinnedVersion}`)}  ${styleText('cyan', instance._id)}`;
     const rows = [
-        formatKeyValue('Stage', instance.currentStage, { padTo: HEADER_PAD }),
-        formatKeyValue('Started', formatTimestamp(instance.startedAt), { padTo: HEADER_PAD }),
+        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
@@ -56,15 +58,15 @@ export function instanceHeader(instance) {
         const reason = abortReason(instance);
         const tail = reason ? ` — ${reason}` : '';
         const value = styleText('yellow', `${formatTimestamp(instance.abortedAt)}${tail}`);
-        rows.push(formatKeyValue('Aborted', value, { padTo: HEADER_PAD }));
+        rows.push(formatKeyValue({ key: 'Aborted', value, padTo: HEADER_PAD }));
     }
     else {
         const completed = instance.completedAt
             ? styleText('green', formatTimestamp(instance.completedAt))
             : styleText('dim', '—');
-        rows.push(formatKeyValue('Completed', completed, { padTo: HEADER_PAD }));
+        rows.push(formatKeyValue({ key: 'Completed', value: completed, padTo: HEADER_PAD }));
     }
-    rows.push(formatKeyValue('Tag', instance.tag, { padTo: HEADER_PAD }));
+    rows.push(formatKeyValue({ key: 'Tag', value: instance.tag, padTo: HEADER_PAD }));
     return [title, ...rows].join('\n');
 }
 /**
@@ -79,7 +81,11 @@ 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) {
+        // A persisted stage may carry no activities array — an activity-less stage,
+        // or an older-shape document — so treat an absent list as none rather than
+        // crash. This renders whatever is in the lake, not only freshly-stamped
+        // instances; it does not reconstruct activity state from history.
+        for (const activity of stage.activities ?? []) {
             lines.push(`      ${activityIcon[activity.status]} ${activity.name}  ${styleText('dim', `[${activity.status}]`)}`);
         }
     }

package/dist/commands/start.d.ts

@@ -0,0 +1,59 @@
+import { Command } from '@oclif/core';
+import { type Actor, type FieldEntry, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance, type WorkflowLifecycle } from '@sanity/workflow-engine';
+import { type EngineScope } from '../lib/operation-args.ts';
+export default class Start extends Command {
+    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>;
+        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>;
+        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, actor, }: {
+    scope: EngineScope;
+    name: string;
+    version: number | undefined;
+    initialFields: InitialFieldValue[];
+    actor: Actor;
+}): 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>;