@sanity/workflow-cli 0.7.0 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@ Command-line tool for deploying, inspecting, and administering Sanity workflow
 definitions and instances.
 
 > [!WARNING]
-> Early access, restricted. `retry-task` and `set-stage` are still stubs —
+> Early access, restricted. `retry-activity` and `set-stage` are still stubs —
 > they print their parsed input and exit non-zero. The "wired" commands below
 > talk to a real Sanity dataset using `SANITY_*` env vars.
 
@@ -75,25 +75,25 @@ built or standalone CLI instead resolves the package's compiled `dist`.
 
 ## Command status
 
-| Command                                    | Status                                                                                    |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `deploy`                                   | wired — calls `workflow.deployDefinitions` over the `WORKFLOW_DEFS` module                |
-| `deploy --check`                           | wired — runs `validateDefinition` over the local batch + a duplicate-id check             |
-| `deploy --dry-run`                         | wired — fetches existing docs and renders a coloured JSON diff per change                 |
-| `deploy --only <id>`                       | wired — filters deploy/check/dry-run to one `definition`                                  |
-| `list`                                     | wired — `client.fetch` over `workflow.instance` documents                                 |
-| `show <instance-id>`                       | wired — `client.getDocument`                                                              |
-| `diagnose <instance-id>`                   | wired — one `workflow.evaluate` call, classifies why the instance is/isn't progressing    |
-| `tail <instance-id>`                       | wired — `client.listen()` over the instance, prints new history entries                   |
-| `abort <instance-id>`                      | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards) |
-| `retry-task <instance-id> <task-id>`       | stub                                                                                      |
-| `move-stage <instance-id> --to <stage-id>` | wired — calls `workflow.setStage` (runs guards + onEnter effects)                         |
-| `fire-action <instance-id>`                | wired — `workflow.evaluate` lists actions; `workflow.fireAction` fires one                |
-| `set-stage <instance-id> --to <stage-id>`  | stub (engine has no guard-bypass path yet)                                                |
-| `definition list`                          | wired — `client.fetch` over `workflow.definition` documents                               |
-| `definition show <id>`                     | wired — `client.fetch`, latest version unless `--version`                                 |
-| `definition diff <id>`                     | wired — diffs the in-code definition against the deployed latest (`--version` to pin)     |
-| `definition delete <name>`                 | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)  |
+| Command                                      | Status                                                                                    |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `deploy`                                     | wired — calls `workflow.deployDefinitions` over the `WORKFLOW_DEFS` module                |
+| `deploy --check`                             | wired — runs `validateDefinition` over the local batch + a duplicate-id check             |
+| `deploy --dry-run`                           | wired — fetches existing docs and renders a coloured JSON diff per change                 |
+| `deploy --only <id>`                         | wired — filters deploy/check/dry-run to one `definition`                                  |
+| `list`                                       | wired — `client.fetch` over `workflow.instance` documents                                 |
+| `show <instance-id>`                         | wired — `client.getDocument`                                                              |
+| `diagnose <instance-id>`                     | wired — one `workflow.evaluate` call, classifies why the instance is/isn't progressing    |
+| `tail <instance-id>`                         | wired — `client.listen()` over the instance, prints new history entries                   |
+| `abort <instance-id>`                        | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards) |
+| `retry-activity <instance-id> <activity-id>` | stub                                                                                      |
+| `move-stage <instance-id> --to <stage-id>`   | wired — calls `workflow.setStage` (runs guards + onEnter effects)                         |
+| `fire-action <instance-id>`                  | wired — `workflow.evaluate` lists actions; `workflow.fireAction` fires one                |
+| `set-stage <instance-id> --to <stage-id>`    | stub (engine has no guard-bypass path yet)                                                |
+| `definition list`                            | wired — `client.fetch` over `workflow.definition` documents                               |
+| `definition show <id>`                       | wired — `client.fetch`, latest version unless `--version`                                 |
+| `definition diff <id>`                       | wired — diffs the in-code definition against the deployed latest (`--version` to pin)     |
+| `definition delete <name>`                   | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)  |
 
 ## Known gaps
 

package/dist/commands/definition/diff.js

@@ -30,7 +30,7 @@ export default class DefinitionDiff extends Command {
         let deployed;
         try {
             deployed = await fetchDeployedDefinition(client, args.definition, config, flags.version);
-            spinner.succeed(`Diffed ${args.definition} v${def.version}`);
+            spinner.succeed(`Diffed ${args.definition}`);
         }
         catch (error) {
             spinner.fail('Diff failed');

package/dist/commands/definition/list.d.ts

@@ -2,7 +2,7 @@ import { Command } from '@oclif/core';
 import { type WorkflowRole } from '@sanity/workflow-engine';
 interface DefinitionListFlags {
     tag?: string | undefined;
-    'workflow-id'?: string | undefined;
+    'workflow-name'?: string | undefined;
     limit: number;
 }
 export interface DefinitionListRow {
@@ -24,7 +24,7 @@ export default class DefinitionList extends Command {
     static examples: string[];
     static flags: {
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-        'workflow-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': 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>;

package/dist/commands/definition/list.js

@@ -21,8 +21,8 @@ export function buildDefinitionListQuery(flags) {
         params.tag = flags.tag;
         filters.push(tagScopeFilter());
     }
-    if (flags['workflow-id']) {
-        params.name = flags['workflow-id'];
+    if (flags['workflow-name']) {
+        params.name = flags['workflow-name'];
         filters.push('name == $name');
     }
     const instanceMatch = instanceFilters.join(' && ');
@@ -50,7 +50,7 @@ export default class DefinitionList extends Command {
             description: 'The maximum number of definitions to return.',
             default: 100,
         }),
-        'workflow-id': Flags.string({
+        'workflow-name': Flags.string({
             description: 'Filter to a single workflow definition name (e.g. product-launch)',
         }),
     };

package/dist/commands/definition/show.d.ts

@@ -24,10 +24,12 @@ export default class DefinitionShow extends Command {
  *  title, then the human title, description, and deploy `tag` as aligned
  *  detail rows. `tag` is deployment metadata (the partition), not part of the
  *  authored definition, so it's passed separately and omitted when unknown. */
-export declare function definitionHeader(def: WorkflowDefinition, tag?: string): string;
+export declare function definitionHeader(def: WorkflowDefinition & {
+    version: number;
+}, tag?: string): string;
 /**
- * The body lines for `definition show`: every stage with its tasks and each
- * task's actions. Pure so it can be asserted without driving the oclif command.
+ * The body lines for `definition show`: every stage with its activities and each
+ * activity's actions. Pure so it can be asserted without driving the oclif command.
  */
 export declare function describeDefinition(def: WorkflowDefinition): string[];
 export {};

package/dist/commands/definition/show.js

@@ -36,8 +36,8 @@ export default class DefinitionShow extends Command {
             version: flags.version,
         });
         const client = loadClient();
-        // The authored {@link WorkflowDefinition} carries no `tag` — it's the
-        // partition the document was deployed into, stamped on the stored doc.
+        // A deployed document: the authored {@link WorkflowDefinition} plus the
+        // deploy-stamped envelope (`version`, `contentHash`, `tag`).
         const def = await client.fetch(groq, params);
         if (!def) {
             const at = flags.version ? `v${flags.version}` : 'latest';
@@ -71,24 +71,24 @@ function actionLine(action) {
     const status = statusOp ? styleText('dim', ` → ${statusOp.status}`) : '';
     return `          · ${action.name}${status}`;
 }
-/** A `- task` line followed by one line per action it exposes. */
-function taskBlock(task) {
-    const title = task.title ? styleText('dim', ` — ${task.title}`) : '';
-    return [`      - ${task.name}${title}`, ...(task.actions ?? []).map(actionLine)];
+/** A `- activity` line followed by one line per action it exposes. */
+function activityBlock(activity) {
+    const title = activity.title ? styleText('dim', ` — ${activity.title}`) : '';
+    return [`      - ${activity.name}${title}`, ...(activity.actions ?? []).map(actionLine)];
 }
-/** A `• stage` line (with initial/terminal markers) followed by its task blocks. */
+/** A `• stage` line (with initial/terminal markers) followed by its activity blocks. */
 function stageBlock(stage, initialStage) {
     const title = stage.title ? styleText('dim', ` — ${stage.title}`) : '';
     const terminal = isTerminalStage(stage) ? styleText('dim', ' (terminal)') : '';
     const initial = stage.name === initialStage ? styleText('cyan', '  [initial]') : '';
     return [
         `  • ${stage.name}${title}${terminal}${initial}`,
-        ...(stage.tasks ?? []).flatMap(taskBlock),
+        ...(stage.activities ?? []).flatMap(activityBlock),
     ];
 }
 /**
- * The body lines for `definition show`: every stage with its tasks and each
- * task's actions. Pure so it can be asserted without driving the oclif command.
+ * The body lines for `definition show`: every stage with its activities and each
+ * activity's actions. Pure so it can be asserted without driving the oclif command.
  */
 export function describeDefinition(def) {
     return [

package/dist/commands/deploy.js

@@ -88,7 +88,6 @@ export function validateModeFlags(check, dryRun) {
 export function deployResultLines(results) {
     const symbols = {
         created: logSymbols.success,
-        updated: logSymbols.info,
     };
     return results.map((r) => {
         const symbol = symbols[r.status] ?? logSymbols.warning;

package/dist/commands/diagnose.d.ts

@@ -1,7 +1,7 @@
 import { Command } from '@oclif/core';
 import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation } from '@sanity/workflow-engine';
 /**
- * The diagnosis body: the verdict line, the current stage's tasks +
+ * 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

package/dist/commands/diagnose.js

@@ -6,25 +6,28 @@ 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 { formatTimestamp, sectionHeader, taskIcon } from "../lib/ui.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}`;
 }
-function taskLine(t, assignees) {
+function activityLine(t, assignees) {
     const who = assignees.length > 0
         ? styleText('dim', `  assigned → ${assignees.map(formatAssignee).join(', ')}`)
         : '';
-    return `  ${taskIcon[t.status]} ${t.task.name} ${styleText('dim', `[${t.status}]`)}${who}`;
+    return `  ${activityIcon[t.status]} ${t.activity.name} ${styleText('dim', `[${t.status}]`)}${who}`;
 }
 function transitionLine(tr) {
     const mark = tr.filterSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
     return `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
 }
 function currentStageLines(input) {
-    const lines = [`${sectionHeader('Stage')} ${input.instance.currentStage}`, sectionHeader('Tasks')];
-    for (const t of input.tasks) {
-        lines.push(taskLine(t, input.assignees[t.task.name] ?? []));
+    const lines = [
+        `${sectionHeader('Stage')} ${input.instance.currentStage}`,
+        sectionHeader('Activities'),
+    ];
+    for (const t of input.activities) {
+        lines.push(activityLine(t, input.assignees[t.activity.name] ?? []));
     }
     if (input.transitions.length > 0) {
         lines.push('', sectionHeader('Exit transitions'));
@@ -37,14 +40,14 @@ function currentStageLines(input) {
 function failedEffectDetail(effect) {
     const ran = effect.durationMs !== undefined ? ` (after ${effect.durationMs}ms)` : '';
     return {
-        headline: `a failed effect is blocking task '${effect.origin.name}'`,
+        headline: `a failed effect is blocking activity '${effect.origin.name}'`,
         why: [
             styleText('red', `${logSymbols.error} failed effect: ${effect.name}`),
-            `  queued by task '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
+            `  queued by activity '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
             ...(effect.error !== undefined ? [`  error: ${effect.error.message}`] : []),
             '',
-            `Task '${effect.origin.name}' is waiting on this effect. It failed against an`,
-            `external system, so the task never completes and the stage can't advance.`,
+            `Activity '${effect.origin.name}' is waiting on this effect. It failed against an`,
+            `external system, so the activity never completes and the stage can't advance.`,
         ],
     };
 }
@@ -58,12 +61,12 @@ function hungEffectDetail(effect) {
         ],
     };
 }
-function failedTaskDetail(task) {
+function failedActivityDetail(activity) {
     return {
-        headline: `task '${task}' failed`,
+        headline: `activity '${activity}' failed`,
         why: [
-            styleText('red', `${logSymbols.error} task '${task}' is in a terminal failed state.`),
-            `Any exit transition gated on '${task}' being done can never fire.`,
+            styleText('red', `${logSymbols.error} activity '${activity}' is in a terminal failed state.`),
+            `Any exit transition gated on '${activity}' being done can never fire.`,
         ],
     };
 }
@@ -76,31 +79,31 @@ function waitingLines(w) {
         ? `assigned to ${w.assignees.map(formatAssignee).join(', ')}`
         : 'unassigned — anyone with permission can act';
     return [
-        `${logSymbols.info} task '${w.task}' is active (${who}),`,
+        `${logSymbols.info} activity '${w.activity}' is active (${who}),`,
         `waiting for action: ${w.actions.join(' or ')}. This is the normal in-flight`,
         `state — it advances when someone acts.`,
     ];
 }
 function blockedHeadline(b) {
     const who = b.assignees.length > 0 ? ` for ${b.assignees.map(formatAssignee).join(', ')}` : '';
-    return `task '${b.task}'${who} is not yet ready — unmet requirement(s): ${b.requirements.join(', ')}`;
+    return `activity '${b.activity}'${who} is not yet ready — unmet requirement(s): ${b.requirements.join(', ')}`;
 }
 function blockedLines(b) {
     const who = b.assignees.length > 0
         ? `assigned to ${b.assignees.map(formatAssignee).join(', ')}`
         : 'unassigned';
     return [
-        `${logSymbols.info} task '${b.task}' is visible but not yet executable (${who}).`,
+        `${logSymbols.info} activity '${b.activity}' is visible but not yet executable (${who}).`,
         `Unmet requirement(s): ${b.requirements.join(', ')}. It can't be acted on until`,
         `those preconditions are met — check what would satisfy them (a prerequisite`,
-        `task completing, required content landing). It will not advance on its own.`,
+        `activity completing, required content landing). It will not advance on its own.`,
     ];
 }
 function noTransitionDetail() {
     return {
         headline: `no exit transition's filter is satisfied`,
         why: [
-            `${logSymbols.info} every task is resolved, but no exit transition's filter is true.`,
+            `${logSymbols.info} every activity is resolved, but no exit transition's filter is true.`,
             `Likely a routing state value a filter reads never got written.`,
         ],
     };
@@ -114,7 +117,7 @@ function transitionUnevaluableDetail(transitions) {
     return {
         headline: `an exit transition's filter could not be evaluated`,
         why: [
-            `${logSymbols.info} every task is resolved, but ${transitions.join(', ')} reads an operand`,
+            `${logSymbols.info} every activity is resolved, but ${transitions.join(', ')} reads an operand`,
             `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`,
@@ -125,7 +128,7 @@ function transitionUnevaluableDetail(transitions) {
 const REMEDIATION_LABEL = {
     'retry-effect': 'retry-effect',
     'drain-effects': 're-run the effect drainer',
-    'reset-task': 'reset-task',
+    'reset-activity': 'reset-activity',
     'set-stage': 'move-stage',
     abort: 'abort',
 };
@@ -142,8 +145,8 @@ function causeDetail(cause) {
             return failedEffectDetail(cause.effect);
         case 'hung-effect':
             return hungEffectDetail(cause.effect);
-        case 'failed-task':
-            return failedTaskDetail(cause.task);
+        case 'failed-activity':
+            return failedActivityDetail(cause.activity);
         case 'no-transition-fires':
             return noTransitionDetail();
         case 'transition-unevaluable':
@@ -169,7 +172,7 @@ function statusLine(diagnosis) {
     }
 }
 /**
- * The diagnosis body: the verdict line, the current stage's tasks +
+ * 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
@@ -232,7 +235,7 @@ export default class Diagnose extends Command {
             workflowResource: config.workflowResource,
             instanceId: args.instanceId,
             // Token-auth CLI can't hit /users/me; pin the same system actor the
-            // write verbs use. Transition filters and task status are actor-
+            // 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

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

@@ -9,7 +9,7 @@ import { type RanOp } from '../lib/ops-report.ts';
  */
 export declare function parseParams(pairs: string[]): Record<string, unknown>;
 /**
- * The list-mode body: every action on the current stage's tasks, marked
+ * 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.
@@ -27,7 +27,7 @@ interface FireOutcome {
  *  {@link fireActionReport}. Pure so its shape is asserted directly. */
 export declare function fireResultJson(result: FireOutcome, ids: {
     instanceId: string;
-    task: string;
+    activity: string;
     action: string;
 }): Record<string, unknown>;
 export interface FireActionReport {
@@ -40,7 +40,7 @@ export interface FireActionReport {
  * the fired / no-op / cascaded / ops permutations assert without a live
  * fire.
  */
-export declare function fireActionReport(result: FireOutcome, task: string, action: string): FireActionReport;
+export declare function fireActionReport(result: FireOutcome, activity: string, action: string): FireActionReport;
 export default class FireAction extends Command {
     static description: string;
     static examples: string[];
@@ -48,7 +48,7 @@ export default class FireAction extends Command {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
-        task: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        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>;

package/dist/commands/fire-action.js

@@ -44,8 +44,8 @@ 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 'activity-not-active':
+            return `activity is ${reason.status}`;
         case 'stage-terminal':
             return `stage '${reason.stage}' is terminal`;
         case 'mutation-guard-denied':
@@ -63,7 +63,7 @@ function actionLines(a) {
     const mark = a.allowed ? logSymbols.success : logSymbols.error;
     const title = a.title !== undefined ? styleText('dim', `  (${a.title})`) : '';
     const lines = [
-        `  ${mark} ${a.task} → ${a.action}${title} ${styleText('dim', `[task ${a.taskStatus}]`)}`,
+        `  ${mark} ${a.activity} → ${a.action}${title} ${styleText('dim', `[activity ${a.activityStatus}]`)}`,
     ];
     if (a.params.length > 0) {
         lines.push(styleText('dim', `      params: ${a.params.map(paramLabel).join(', ')}`));
@@ -74,20 +74,20 @@ function actionLines(a) {
     return lines;
 }
 /**
- * The list-mode body: every action on the current stage's tasks, marked
+ * 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 tasks of the current stage ('${stage}').`];
+        return [`No actions on the activities of the current stage ('${stage}').`];
     }
     const lines = [styleText('bold', `Actions on stage '${stage}':`), ''];
     for (const a of actions) {
         lines.push(...actionLines(a));
     }
-    lines.push('', styleText('dim', 'Fire one with:'), styleText('dim', `  fire-action ${instanceId} --task <task> --action <action>`));
+    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
@@ -95,7 +95,7 @@ export function renderAvailableActions(actions, stage, instanceId) {
 export function fireResultJson(result, ids) {
     return {
         instanceId: ids.instanceId,
-        task: ids.task,
+        activity: ids.activity,
         action: ids.action,
         fired: result.fired,
         cascaded: result.cascaded,
@@ -108,37 +108,37 @@ export function fireResultJson(result, ids) {
  * the fired / no-op / cascaded / ops permutations assert without a live
  * fire.
  */
-export function fireActionReport(result, task, action) {
+export function fireActionReport(result, activity, action) {
     const stage = styleText('bold', result.instance.currentStage);
     if (!result.fired) {
         return {
             fired: false,
-            message: `fireAction returned without firing — task '${task}' is no longer active`,
+            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', task)} — now at ${stage}${tail}`,
+        message: `Fired ${styleText('bold', action)} on ${styleText('bold', activity)} — 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 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.";
     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',
+        '<%= 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 = {
         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.',
+        activity: Flags.string({
+            description: 'Activity 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.',
@@ -170,15 +170,15 @@ export default class FireAction extends Command {
             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)');
+        if (flags.activity === undefined) {
+            fail('fire-action usage error:', 'specify --activity for the action (or omit --action to list what can be fired)');
         }
         await this.fireOne({
             client,
             config,
             instanceId: args.instanceId,
             actor,
-            task: flags.task,
+            activity: flags.activity,
             action: flags.action,
             params: flags.param,
             json: flags.json,
@@ -206,14 +206,14 @@ export default class FireAction extends Command {
         }
     }
     async fireOne(opts) {
-        const { client, config, instanceId, actor, task, action, json } = opts;
+        const { client, config, instanceId, actor, activity, action, json } = opts;
         const params = failOnThrow('Invalid --param:', () => parseParams(opts.params));
         const fireArgs = {
             client,
             tag: config.tag,
             workflowResource: config.workflowResource,
             instanceId,
-            task,
+            activity,
             action,
             access: { actor },
             params,
@@ -222,13 +222,13 @@ export default class FireAction extends Command {
             const result = await workflow
                 .fireAction(fireArgs)
                 .catch((error) => fail('fireAction error:', errorMessage(error)));
-            this.log(JSON.stringify(fireResultJson(result, { instanceId, task, action }), null, 2));
+            this.log(JSON.stringify(fireResultJson(result, { instanceId, activity, action }), null, 2));
             return;
         }
-        const spinner = ora(`Firing ${action} on ${task}…`).start();
+        const spinner = ora(`Firing ${action} on ${activity}…`).start();
         try {
             const result = await workflow.fireAction(fireArgs);
-            emitWriteReport(spinner, fireActionReport(result, task, action), (line) => this.log(line));
+            emitWriteReport(spinner, fireActionReport(result, activity, action), (line) => this.log(line));
         }
         catch (error) {
             spinner.fail('Action rejected');

package/dist/commands/list.d.ts

@@ -12,7 +12,7 @@ type InstanceStatus = 'aborted' | 'completed' | 'in-flight';
 interface ListFlags {
     'in-flight': boolean;
     failed: boolean;
-    'workflow-id'?: string | undefined;
+    'workflow-name'?: 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-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': 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

@@ -15,11 +15,11 @@ export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
     if (flags['in-flight'])
         filters.push('!defined(completedAt)');
-    if (flags['workflow-id'])
+    if (flags['workflow-name'])
         filters.push('definition == $definition');
-    // Cheap approximation of --failed: any task in any stage with status "failed".
+    // Cheap approximation of --failed: any activity in any stage with status "failed".
     if (flags.failed)
-        filters.push('count(stages[].tasks[status == "failed"]) > 0');
+        filters.push('count(stages[].activities[status == "failed"]) > 0');
     if (flags.tag)
         filters.push(tagScopeFilter());
     const groq = `*[${filters.join(' && ')}] | order(lastChangedAt desc) [0...$limit]{
@@ -32,8 +32,8 @@ export function buildListQuery(flags) {
       lastChangedAt
     }`;
     const params = { limit: flags.limit };
-    if (flags['workflow-id'])
-        params['definition'] = flags['workflow-id'];
+    if (flags['workflow-name'])
+        params['definition'] = flags['workflow-name'];
     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-id productLaunch',
+        '<%= config.bin %> list --workflow-name productLaunch',
         '<%= config.bin %> list --tag prod',
     ];
     static flags = {
@@ -78,10 +78,10 @@ export default class List extends Command {
             default: false,
         }),
         failed: Flags.boolean({
-            description: 'Only instances with at least one failed task.',
+            description: 'Only instances with at least one failed activity.',
             default: false,
         }),
-        'workflow-id': Flags.string({
+        'workflow-name': Flags.string({
             description: 'Filter by workflow definition name.',
         }),
         limit: Flags.integer({

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

@@ -1,9 +1,9 @@
 import { StubCommand } from '../lib/stub.ts';
-export default class RetryTask extends StubCommand {
+export default class RetryActivity 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>>;
+        activity: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
 }

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

@@ -1,11 +1,11 @@
 import { Args } from '@oclif/core';
 import { StubCommand } from "../lib/stub.js";
-export default class RetryTask extends StubCommand {
+export default class RetryActivity 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 description = 'Re-invoke a failed activity 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.' }),
+        activity: Args.string({ required: true, description: 'Activity name within the current stage.' }),
     };
 }

package/dist/commands/set-stage.js

@@ -4,7 +4,7 @@ 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
+    // 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).";

package/dist/commands/show.d.ts

@@ -15,7 +15,7 @@ export default class Show extends Command {
  *  `fire-action`): a bold workflow + id title, then aligned detail rows. */
 export declare function instanceHeader(instance: WorkflowInstance): string;
 /**
- * The per-instance body lines: every stage with its tasks, any pending
+ * The per-instance body lines: every stage with its activities, any pending
  * effects, and (optionally) the history log. Pure so it can be asserted
  * without driving the oclif command.
  */

package/dist/commands/show.js

@@ -3,9 +3,9 @@ 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 { formatKeyValue, formatTimestamp, sectionHeader, taskIcon } from "../lib/ui.js";
+import { formatKeyValue, formatTimestamp, sectionHeader, activityIcon } from "../lib/ui.js";
 export default class Show extends Command {
-    static description = 'Show the state, tasks, and effects of a workflow instance.';
+    static description = 'Show the state, activities, and effects of a workflow instance.';
     static examples = [
         '<%= config.bin %> show wf-instance.abc123',
         '<%= config.bin %> show wf-instance.abc123 --include history',
@@ -68,7 +68,7 @@ export function instanceHeader(instance) {
     return [title, ...rows].join('\n');
 }
 /**
- * The per-instance body lines: every stage with its tasks, any pending
+ * The per-instance body lines: every stage with its activities, any pending
  * effects, and (optionally) the history log. Pure so it can be asserted
  * without driving the oclif command.
  */
@@ -79,8 +79,8 @@ export function describeInstance(instance, options) {
             ? styleText('dim', ` (exited ${formatTimestamp(stage.exitedAt)})`)
             : styleText('cyan', ' (current)');
         lines.push(`  • ${stage.name}${marker}`);
-        for (const task of stage.tasks) {
-            lines.push(`      ${taskIcon[task.status]} ${task.name}  ${styleText('dim', `[${task.status}]`)}`);
+        for (const activity of stage.activities) {
+            lines.push(`      ${activityIcon[activity.status]} ${activity.name}  ${styleText('dim', `[${activity.status}]`)}`);
         }
     }
     if (instance.pendingEffects.length > 0) {

package/dist/lib/definitions.js

@@ -115,7 +115,7 @@ export function collectValidationErrors(defs) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            errors.push(`  · ${d.name} v${d.version}: ${message}`);
+            errors.push(`  · ${d.name}: ${message}`);
         }
     }
     return errors;

package/dist/lib/diff.d.ts

@@ -1,5 +1,6 @@
 import type { DiffEntry } from '@sanity/workflow-engine';
-/** One summary line per diff entry, tagged create / update / unchanged. */
+/** One summary line per diff entry, tagged create / unchanged. Definitions are
+ *  immutable, so a content change is a new version (`create`), never an update. */
 export declare function summaryLines(entries: DiffEntry[]): string[];
 /** Render a JSON diff of `oldObj` → `newObj` as `+`/`-`/context lines. */
 export declare function diffLines(oldObj: object, newObj: object): string[];

package/dist/lib/diff.js

@@ -2,11 +2,11 @@ import { styleText } from 'node:util';
 import { diffJson } from 'diff';
 import logSymbols from 'log-symbols';
 import { sectionHeader } from "./ui.js";
-/** One summary line per diff entry, tagged create / update / unchanged. */
+/** One summary line per diff entry, tagged create / unchanged. Definitions are
+ *  immutable, so a content change is a new version (`create`), never an update. */
 export function summaryLines(entries) {
     const tags = {
         create: styleText('green', '+ create   '),
-        update: styleText('yellow', '~ update   '),
         unchanged: styleText('dim', '  unchanged'),
     };
     return entries.map((e) => {

package/dist/lib/ui.d.ts

@@ -1,4 +1,4 @@
-import type { TaskStatus } from '@sanity/workflow-engine';
+import type { ActivityStatus } from '@sanity/workflow-engine';
 /**
  * A bold `Title:` section heading. Mirrors the Sanity CLI's `sectionHeader`
  * (name + shape) so it folds into the shared helper when this CLI merges in.
@@ -13,9 +13,9 @@ export declare function formatKeyValue(key: string, value: string, options?: {
     indent?: number;
     padTo?: number;
 }): string;
-/** Status glyph per task state. log-symbols ship pre-colored (green ✔, red ✖),
+/** Status glyph per activity state. log-symbols ship pre-colored (green ✔, red ✖),
  *  so those need no extra wrap; the rest carry their own state color. */
-export declare const taskIcon: Record<TaskStatus, string>;
+export declare const activityIcon: Record<ActivityStatus, string>;
 /** An engine ISO-8601 timestamp as an absolute `yyyy-MM-dd HH:mm:ss` — the
  *  Sanity CLI's audit-log format (see `backups/list`). For detail views. */
 export declare function formatTimestamp(iso: string): string;

package/dist/lib/ui.js

@@ -21,9 +21,9 @@ export function formatKeyValue(key, value, options) {
     const paddedKey = `${key}:`.padEnd(padTo > 0 ? padTo + 1 : key.length + 1);
     return `${' '.repeat(indent)}${styleText('dim', paddedKey)} ${value}`;
 }
-/** Status glyph per task state. log-symbols ship pre-colored (green ✔, red ✖),
+/** Status glyph per activity state. log-symbols ship pre-colored (green ✔, red ✖),
  *  so those need no extra wrap; the rest carry their own state color. */
-export const taskIcon = {
+export const activityIcon = {
     done: logSymbols.success,
     active: styleText('cyan', '●'),
     pending: styleText('dim', '○'),

package/oclif.manifest.json

@@ -152,12 +152,12 @@
           "required": true
         }
       },
-      "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.",
+      "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.",
       "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"
+        "<%= 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"
       ],
       "flags": {
         "tag": {
@@ -167,9 +167,9 @@
           "multiple": false,
           "type": "option"
         },
-        "task": {
-          "description": "Task the action belongs to. Required to fire; omit --action to list.",
-          "name": "task",
+        "activity": {
+          "description": "Activity the action belongs to. Required to fire; omit --action to list.",
+          "name": "activity",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -233,7 +233,7 @@
       "examples": [
         "<%= config.bin %> list",
         "<%= config.bin %> list --in-flight",
-        "<%= config.bin %> list --workflow-id productLaunch",
+        "<%= config.bin %> list --workflow-name productLaunch",
         "<%= config.bin %> list --tag prod"
       ],
       "flags": {
@@ -251,14 +251,14 @@
           "type": "boolean"
         },
         "failed": {
-          "description": "Only instances with at least one failed task.",
+          "description": "Only instances with at least one failed activity.",
           "name": "failed",
           "allowNo": false,
           "type": "boolean"
         },
-        "workflow-id": {
+        "workflow-name": {
           "description": "Filter by workflow definition name.",
-          "name": "workflow-id",
+          "name": "workflow-name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -340,7 +340,7 @@
         "move-stage.js"
       ]
     },
-    "retry-task": {
+    "retry-activity": {
       "aliases": [],
       "args": {
         "instanceId": {
@@ -348,18 +348,18 @@
           "name": "instanceId",
           "required": true
         },
-        "task": {
-          "description": "Task name within the current stage.",
-          "name": "task",
+        "activity": {
+          "description": "Activity name within the current stage.",
+          "name": "activity",
           "required": true
         }
       },
-      "description": "Re-invoke a failed task on an in-flight instance.",
+      "description": "Re-invoke a failed activity on an in-flight instance.",
       "flags": {},
       "hasDynamicHelp": false,
       "hidden": true,
       "hiddenAliases": [],
-      "id": "retry-task",
+      "id": "retry-activity",
       "pluginAlias": "@sanity/workflow-cli",
       "pluginName": "@sanity/workflow-cli",
       "pluginType": "core",
@@ -368,7 +368,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "retry-task.js"
+        "retry-activity.js"
       ]
     },
     "set-stage": {
@@ -422,7 +422,7 @@
           "required": true
         }
       },
-      "description": "Show the state, tasks, and effects of a workflow instance.",
+      "description": "Show the state, activities, and effects of a workflow instance.",
       "examples": [
         "<%= config.bin %> show wf-instance.abc123",
         "<%= config.bin %> show wf-instance.abc123 --include history"
@@ -614,9 +614,9 @@
           "multiple": false,
           "type": "option"
         },
-        "workflow-id": {
+        "workflow-name": {
           "description": "Filter to a single workflow definition name (e.g. product-launch)",
-          "name": "workflow-id",
+          "name": "workflow-name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -681,5 +681,5 @@
       ]
     }
   },
-  "version": "0.7.0"
+  "version": "0.8.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -53,15 +53,15 @@
     "diff": "^9.0.0",
     "log-symbols": "^7.0.1",
     "ora": "^9.4.0",
-    "@sanity/workflow-engine": "0.10.0"
+    "@sanity/workflow-engine": "0.12.0"
   },
   "devDependencies": {
     "@types/diff": "^8.0.0",
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine-test": "0.6.0",
-    "@sanity/workflow-examples": "0.1.6"
+    "@sanity/workflow-engine-test": "0.7.0",
+    "@sanity/workflow-examples": "0.2.0"
   },
   "oclif": {
     "bin": "sanity-workflows",