@sanity/workflow-cli 0.5.1

package/dist/commands/fire-action.js

@@ -0,0 +1,241 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { workflow, } from '@sanity/workflow-engine';
+import boxen from 'boxen';
+import logSymbols from 'log-symbols';
+import ora from 'ora';
+import pc from 'picocolors';
+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 { 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 'task-not-active':
+            return `task 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(', ')}`;
+    }
+}
+function paramLabel(p) {
+    return `${p.name}${p.required === true ? '' : '?'}:${p.type}`;
+}
+function actionLines(a) {
+    const mark = a.allowed ? pc.green(logSymbols.success) : pc.red(logSymbols.error);
+    const title = a.title !== undefined ? pc.dim(`  (${a.title})`) : '';
+    const lines = [`  ${mark} ${a.task} → ${a.action}${title} ${pc.dim(`[task ${a.taskStatus}]`)}`];
+    if (a.params.length > 0) {
+        lines.push(pc.dim(`      params: ${a.params.map(paramLabel).join(', ')}`));
+    }
+    if (!a.allowed && a.disabledReason !== undefined) {
+        lines.push(pc.dim(`      disabled: ${reasonText(a.disabledReason)}`));
+    }
+    return lines;
+}
+/**
+ * The list-mode body: every action on the current stage's tasks, 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 tasks of the current stage ('${stage}').`];
+    }
+    const lines = [pc.bold(`actions on stage '${stage}':`), ''];
+    for (const a of actions) {
+        lines.push(...actionLines(a));
+    }
+    lines.push('', pc.dim('fire one with:'), pc.dim(`  fire-action ${instanceId} --task <task> --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,
+        task: ids.task,
+        action: ids.action,
+        fired: result.fired,
+        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, task, action) {
+    const stage = pc.bold(result.instance.currentStage);
+    if (!result.fired) {
+        return {
+            fired: false,
+            message: `fireAction returned without firing — task '${task}' is no longer active`,
+            opsLines: [],
+        };
+    }
+    const tail = result.cascaded > 0 ? `, then cascaded ${result.cascaded} auto-transition(s)` : '';
+    return {
+        fired: true,
+        message: `Fired ${pc.bold(action)} on ${pc.bold(task)} — now at ${stage}${tail}`,
+        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 task. Omit --action to list what can be fired.";
+    static examples = [
+        '<%= config.bin %> fire-action wf-instance.abc123',
+        '<%= config.bin %> fire-action wf-instance.abc123 --task approve --action approve',
+        '<%= config.bin %> fire-action wf-instance.abc123 --task approve --action approve --as user.xyz --as-role editor',
+        '<%= config.bin %> fire-action wf-instance.abc123 --task publish --action publish --param note=shipping',
+    ];
+    static args = {
+        instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        task: Flags.string({
+            description: 'Task the action belongs to. Required to fire; omit --action to list.',
+        }),
+        action: Flags.string({
+            description: 'Action to fire. Omit to list the actions available on the instance.',
+        }),
+        param: Flags.string({
+            description: 'Action param as key=value (repeatable). Values are JSON-parsed, falling back to a string.',
+            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,
+        }),
+    };
+    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']));
+        if (flags.action === undefined) {
+            await this.listActions(client, config, args.instanceId, actor, flags.json);
+            return;
+        }
+        if (flags.task === undefined) {
+            fail('fire-action usage error:', 'specify --task for the action (or omit --action to list what can be fired)');
+        }
+        await this.fireOne({
+            client,
+            config,
+            instanceId: args.instanceId,
+            actor,
+            task: flags.task,
+            action: flags.action,
+            params: flags.param,
+            json: flags.json,
+        });
+    }
+    async listActions(client, config, instanceId, actor, json) {
+        const { evaluation, actions } = await workflow
+            .availableActions({
+            client,
+            tag: config.tag,
+            workflowResource: config.workflowResource,
+            instanceId,
+            access: { actor },
+        })
+            .catch((error) => fail('fire-action failed:', errorMessage(error)));
+        const stage = evaluation.instance.currentStage;
+        if (json) {
+            this.log(JSON.stringify({ instanceId, stage, actions }, null, 2));
+            return;
+        }
+        this.log(boxen(instanceHeader(evaluation.instance), {
+            padding: 1,
+            borderStyle: 'round',
+            title: 'fire-action',
+        }));
+        this.log('');
+        for (const line of renderAvailableActions(actions, stage, instanceId)) {
+            this.log(line);
+        }
+    }
+    async fireOne(opts) {
+        const { client, config, instanceId, actor, task, action, json } = opts;
+        const params = failOnThrow('Invalid --param:', () => parseParams(opts.params));
+        const fireArgs = {
+            client,
+            tag: config.tag,
+            workflowResource: config.workflowResource,
+            instanceId,
+            task,
+            action,
+            access: { actor },
+            params,
+        };
+        if (json) {
+            const result = await workflow
+                .fireAction(fireArgs)
+                .catch((error) => fail('fireAction error:', errorMessage(error)));
+            this.log(JSON.stringify(fireResultJson(result, { instanceId, task, action }), null, 2));
+            return;
+        }
+        const spinner = ora(`Firing ${action} on ${task}…`).start();
+        try {
+            const result = await workflow.fireAction(fireArgs);
+            emitWriteReport(spinner, fireActionReport(result, task, action), (line) => this.log(line));
+        }
+        catch (error) {
+            spinner.fail('Action rejected');
+            fail('fireAction error:', errorMessage(error));
+        }
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,46 @@
+import { Command } from '@oclif/core';
+interface InstanceRow {
+    _id: string;
+    definition: string;
+    currentStage: string;
+    startedAt: string;
+    completedAt?: string;
+    abortedAt?: string;
+    failedTaskCount: number;
+}
+interface ListFlags {
+    'in-flight': boolean;
+    failed: boolean;
+    'workflow-id'?: string | undefined;
+    limit: number;
+}
+/**
+ * Build the GROQ query + params for `list` from its flags. Pure so the
+ * filter combinations can be asserted without a live dataset.
+ */
+export declare function buildListQuery(flags: ListFlags): {
+    groq: string;
+    params: Record<string, unknown>;
+};
+/** Map a queried instance to its display row (derives the status column). */
+export declare function instanceRow(r: InstanceRow): {
+    _id: string;
+    definition: string;
+    currentStage: string;
+    startedAt: string;
+    status: 'aborted' | 'completed' | 'in-flight';
+    failedTaskCount: number;
+};
+export default class List extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'in-flight': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        failed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'workflow-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        subject: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+export {};

package/dist/commands/list.js

@@ -0,0 +1,106 @@
+import { Command, Flags } from '@oclif/core';
+import { WORKFLOW_INSTANCE_TYPE } from '@sanity/workflow-engine';
+import { Table } from 'console-table-printer';
+import logSymbols from 'log-symbols';
+import { loadClient } from "../lib/client.js";
+/**
+ * Build the GROQ query + params for `list` from its flags. Pure so the
+ * filter combinations can be asserted without a live dataset.
+ */
+export function buildListQuery(flags) {
+    const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
+    if (flags['in-flight'])
+        filters.push('!defined(completedAt)');
+    if (flags['workflow-id'])
+        filters.push('definition == $definition');
+    // Cheap approximation of --failed: any task in any stage with status "failed".
+    if (flags.failed)
+        filters.push('count(stages[].tasks[status == "failed"]) > 0');
+    const groq = `*[${filters.join(' && ')}] | order(startedAt desc) [0...$limit]{
+      _id,
+      definition,
+      currentStage,
+      startedAt,
+      completedAt,
+      abortedAt,
+      "failedTaskCount": count(stages[].tasks[status == "failed"])
+    }`;
+    const params = { limit: flags.limit };
+    if (flags['workflow-id'])
+        params['definition'] = flags['workflow-id'];
+    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). */
+export function instanceRow(r) {
+    return {
+        _id: r._id,
+        definition: r.definition,
+        currentStage: r.currentStage,
+        startedAt: r.startedAt,
+        status: deriveStatus(r),
+        failedTaskCount: r.failedTaskCount,
+    };
+}
+export default class List extends Command {
+    static description = 'List workflow instances in the configured dataset.';
+    static examples = [
+        '<%= config.bin %> list',
+        '<%= config.bin %> list --in-flight',
+        '<%= config.bin %> list --workflow-id productLaunch',
+    ];
+    static flags = {
+        'in-flight': Flags.boolean({
+            description: 'Only instances that have not completed.',
+            default: false,
+        }),
+        failed: Flags.boolean({
+            description: 'Only instances with at least one failed task.',
+            default: false,
+        }),
+        'workflow-id': Flags.string({
+            description: 'Filter by workflow definition name.',
+        }),
+        subject: Flags.string({
+            description: 'Filter by subject document id. (not yet implemented)',
+        }),
+        limit: Flags.integer({
+            description: 'Maximum rows to return.',
+            default: 50,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(List);
+        if (flags.subject) {
+            this.warn('--subject is parsed but not yet implemented; ignoring.');
+        }
+        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: 'currentStage', title: 'stage', alignment: 'left' },
+                { name: 'startedAt', title: 'started', alignment: 'left' },
+                { name: 'status', title: 'status', alignment: 'left' },
+                { name: 'failedTaskCount', title: 'failed', alignment: 'right' },
+            ],
+        });
+        for (const r of rows) {
+            table.addRow(instanceRow(r));
+        }
+        table.printTable();
+    }
+}

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

@@ -0,0 +1,47 @@
+import { Command } from '@oclif/core';
+import { type SetStageArgs } from '@sanity/workflow-engine';
+import { type WorkflowConfig } from '../lib/config.ts';
+import { type RanOp } from '../lib/ops-report.ts';
+export default class MoveStage 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(config: WorkflowConfig, instanceId: string, targetStage: string, reason: string | undefined): Omit<SetStageArgs, 'client'>;
+interface SetStageOutcome {
+    fired: boolean;
+    cascaded: number;
+    instance: {
+        currentStage: string;
+    };
+    ranOps?: RanOp[];
+}
+export interface MoveStageReport {
+    fired: boolean;
+    /** Spinner message — warn copy when not fired, success copy otherwise. */
+    message: string;
+    /**
+     * The full "ops applied" block to print after the spinner — a blank
+     * line, the header, and one line per op. Empty when nothing ran (or
+     * when the transition didn't fire), so the caller can print it
+     * unconditionally.
+     */
+    opsLines: string[];
+}
+/**
+ * Turn a `setStage` result into the spinner message + ops block. Pure so
+ * the fired / not-fired / cascaded / ops permutations can be asserted
+ * without driving a real transition.
+ */
+export declare function moveStageReport(result: SetStageOutcome, to: string): MoveStageReport;
+export {};

package/dist/commands/move-stage.js

@@ -0,0 +1,77 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { workflow } from '@sanity/workflow-engine';
+import ora from 'ora';
+import pc from 'picocolors';
+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 { buildOperationArgs } from "../lib/operation-args.js";
+import { emitWriteReport, opsAppliedLines } from "../lib/ops-report.js";
+export default class MoveStage extends Command {
+    static description = 'Move an instance to a new stage. Guards + transition effects run as if the transition fired normally.';
+    static examples = [
+        '<%= config.bin %> move-stage wf-instance.abc123 --to ready',
+        "<%= config.bin %> move-stage wf-instance.abc123 --to ready --reason 'unblock for demo'",
+    ];
+    static args = {
+        instanceId: Args.string({
+            required: true,
+            description: 'Workflow instance id to move.',
+        }),
+    };
+    static flags = {
+        ...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(MoveStage);
+        const config = loadWorkflowConfig(flags.tag);
+        const client = loadClient();
+        const spinner = ora(`Moving ${args.instanceId} → ${flags.to}…`).start();
+        try {
+            const result = await workflow.setStage({
+                client,
+                ...buildSetStageArgs(config, args.instanceId, flags.to, flags.reason),
+            });
+            emitWriteReport(spinner, moveStageReport(result, flags.to), (line) => this.log(line));
+        }
+        catch (error) {
+            spinner.fail('Move rejected');
+            const message = error instanceof Error ? error.message : String(error);
+            fail('setStage error:', message);
+        }
+    }
+}
+/** The shared operation args ({@link buildOperationArgs}) plus the
+ *  setStage-specific target. */
+export function buildSetStageArgs(config, instanceId, targetStage, reason) {
+    return { ...buildOperationArgs(config, instanceId, reason), targetStage };
+}
+/**
+ * Turn a `setStage` result into the spinner message + ops block. Pure so
+ * the fired / not-fired / cascaded / ops permutations can be asserted
+ * without driving a real transition.
+ */
+export function moveStageReport(result, to) {
+    const stage = pc.bold(result.instance.currentStage);
+    if (!result.fired) {
+        return {
+            fired: false,
+            message: `setStage returned without firing — instance is already at ${stage}`,
+            opsLines: [],
+        };
+    }
+    const tail = result.cascaded > 0 ? `, then cascaded ${result.cascaded} auto-transition(s)` : '';
+    return {
+        fired: true,
+        message: `Now at ${stage} (was → ${to}${tail})`,
+        opsLines: opsAppliedLines(result.ranOps),
+    };
+}

package/dist/commands/retry-task.d.ts

@@ -0,0 +1,9 @@
+import { StubCommand } from '../lib/stub.ts';
+export default class RetryTask extends StubCommand {
+    static hidden: boolean;
+    static description: string;
+    static args: {
+        instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        task: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+}

package/dist/commands/retry-task.js

@@ -0,0 +1,11 @@
+import { Args } from '@oclif/core';
+import { StubCommand } from "../lib/stub.js";
+export default class RetryTask extends StubCommand {
+    // Stubbed, so kept off the help + published surface until it's wired.
+    static hidden = true;
+    static description = 'Re-invoke a failed task on an in-flight instance.';
+    static args = {
+        instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
+        task: Args.string({ required: true, description: 'Task name within the current stage.' }),
+    };
+}

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

@@ -0,0 +1,12 @@
+import { StubCommand } from '../lib/stub.ts';
+export default class SetStage extends StubCommand {
+    static hidden: boolean;
+    static description: 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>;
+    };
+}

package/dist/commands/set-stage.js

@@ -0,0 +1,18 @@
+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 (task 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).";
+    static args = {
+        instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
+    };
+    static flags = {
+        to: Flags.string({ required: true, description: 'Target stage name.' }),
+        reason: Flags.string({ description: 'Reason for the manual override.' }),
+    };
+}

package/dist/commands/show.d.ts

@@ -0,0 +1,23 @@
+import { Command } from '@oclif/core';
+import { type WorkflowInstance } from '@sanity/workflow-engine';
+export default class Show extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        include: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/** The boxed summary block at the top of `show` output. */
+export declare function instanceHeader(instance: WorkflowInstance): string;
+/**
+ * The per-instance body lines: every stage with its tasks, any pending
+ * effects, and (optionally) the history log. Pure so it can be asserted
+ * without driving the oclif command.
+ */
+export declare function describeInstance(instance: WorkflowInstance, options: {
+    includeHistory: boolean;
+}): string[];