@sanity/workflow-cli 0.8.0 → 0.9.0

package/dist/lib/select-deployment.js

@@ -0,0 +1,58 @@
+import { resourceAliasesToMap, } from '@sanity/workflow-engine';
+import { fail } from "./fail.js";
+/**
+ * Pick the deployment for the requested `--tag`. Tags are unique across a
+ * config (enforced by defineWorkflowConfig), so a tag names at most one
+ * deployment.
+ *
+ * With no tag: fall back to the sole deployment when there's exactly one
+ * (the common single-environment case), otherwise fail asking for `--tag` —
+ * a multi-deployment config is ambiguous without it. `orAlternative` extends
+ * that ambiguity message for callers with another way out (deploy's `--all-tags`).
+ */
+export function selectDeployment(config, { tag, orAlternative = '' }) {
+    if (tag === undefined) {
+        if (config.deployments.length > 1) {
+            fail(`Multiple deployments configured — pass --tag${orAlternative}.`, availableTags(config));
+        }
+        const [sole] = config.deployments;
+        if (sole === undefined) {
+            fail('No deployments configured.');
+        }
+        return sole;
+    }
+    const deployment = config.deployments.find((candidate) => candidate.tag === tag);
+    if (deployment === undefined) {
+        fail(`No deployment for tag "${tag}".`, availableTags(config));
+    }
+    return deployment;
+}
+/**
+ * The deployments a `deploy` run acts on: every one with `--all-tags`,
+ * otherwise a single target via {@link selectDeployment} and its failure
+ * modes. Deploying everything is an explicit opt-in — never a default — so an
+ * ambiguous bare `deploy` can't fan a write out across environments.
+ */
+export function selectDeployments(config, { tag, allTags }) {
+    if (allTags) {
+        return config.deployments;
+    }
+    return [
+        selectDeployment(config, { tag, orAlternative: ', or --all-tags to deploy every deployment' }),
+    ];
+}
+function availableTags(config) {
+    return `Available tags: ${config.deployments.map((candidate) => candidate.tag).join(', ')}`;
+}
+/**
+ * Project a deployment into the engine's {@link DeployTarget} — the shape the
+ * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)
+ * consume — expanding its handle bindings into the alias map in the same step.
+ */
+export function deploymentToTarget(deployment) {
+    return {
+        tag: deployment.tag,
+        workflowResource: deployment.workflowResource,
+        resourceAliases: resourceAliasesToMap(deployment.resourceAliases),
+    };
+}

package/dist/lib/ui.d.ts

@@ -9,7 +9,9 @@ export declare function sectionHeader(title: string): string;
  * the Sanity CLI's `formatKeyValue` so it folds into the shared helper on
  * merge; pass `padTo` (the longest key's length) to align a block of rows.
  */
-export declare function formatKeyValue(key: string, value: string, options?: {
+export declare function formatKeyValue({ key, value, indent, padTo, }: {
+    key: string;
+    value: string;
     indent?: number;
     padTo?: number;
 }): string;

package/dist/lib/ui.js

@@ -15,9 +15,7 @@ export function sectionHeader(title) {
  * the Sanity CLI's `formatKeyValue` so it folds into the shared helper on
  * merge; pass `padTo` (the longest key's length) to align a block of rows.
  */
-export function formatKeyValue(key, value, options) {
-    const indent = options?.indent ?? 2;
-    const padTo = options?.padTo ?? 0;
+export function formatKeyValue({ key, value, indent = 2, padTo = 0, }) {
     const paddedKey = `${key}:`.padEnd(padTo > 0 ? padTo + 1 : key.length + 1);
     return `${' '.repeat(indent)}${styleText('dim', paddedKey)} ${value}`;
 }

package/oclif.manifest.json

@@ -16,7 +16,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -48,21 +48,31 @@
     "deploy": {
       "aliases": [],
       "args": {},
-      "description": "Validate, diff, and deploy workflow definitions to the configured dataset.",
+      "description": "Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.",
       "examples": [
-        "<%= config.bin %> deploy",
+        "<%= config.bin %> deploy --tag prod",
+        "<%= config.bin %> deploy --all-tags",
         "<%= config.bin %> deploy --check",
         "<%= config.bin %> deploy --dry-run",
         "<%= config.bin %> deploy --only productLaunch"
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "all-tags": {
+          "description": "Deploy every deployment in the config, not just one tag.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "all-tags",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "dry-run": {
           "description": "Validate + diff against the deployed version; do not write.",
           "name": "dry-run",
@@ -76,7 +86,7 @@
           "type": "boolean"
         },
         "only": {
-          "description": "Limit deploy/check/diff to a single workflow definition by name.",
+          "description": "Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.",
           "name": "only",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -115,14 +125,14 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "json": {
-          "description": "Emit the structured diagnosis as JSON instead of rendered output.",
+          "description": "Emit structured JSON instead of rendered output.",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -161,7 +171,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -190,7 +200,7 @@
           "type": "option"
         },
         "as": {
-          "description": "Attribute the fire to this Sanity user id (default: a workflow-cli system actor).",
+          "description": "Attribute the write to this Sanity user id (default: a workflow-cli system actor).",
           "name": "as",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -233,12 +243,12 @@
       "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"
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -256,9 +266,9 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "workflow-name": {
-          "description": "Filter by workflow definition name.",
-          "name": "workflow-name",
+        "definition": {
+          "description": "Only instances of this workflow definition (its `name`; the instance's `definition` field).",
+          "name": "definition",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -287,60 +297,7 @@
         "list.js"
       ]
     },
-    "move-stage": {
-      "aliases": [],
-      "args": {
-        "instanceId": {
-          "description": "Workflow instance id to move.",
-          "name": "instanceId",
-          "required": true
-        }
-      },
-      "description": "Move an instance to a new stage. Guards + transition effects run as if the transition fired normally.",
-      "examples": [
-        "<%= config.bin %> move-stage wf-instance.abc123 --to ready",
-        "<%= config.bin %> move-stage wf-instance.abc123 --to ready --reason 'unblock for demo'"
-      ],
-      "flags": {
-        "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
-          "name": "tag",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "to": {
-          "description": "Target stage name.",
-          "name": "to",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "reason": {
-          "description": "Free-text reason — recorded on the history entry for audit.",
-          "name": "reason",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "move-stage",
-      "pluginAlias": "@sanity/workflow-cli",
-      "pluginName": "@sanity/workflow-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "move-stage.js"
-      ]
-    },
-    "retry-activity": {
+    "reset-activity": {
       "aliases": [],
       "args": {
         "instanceId": {
@@ -354,12 +311,12 @@
           "required": true
         }
       },
-      "description": "Re-invoke a failed activity on an in-flight instance.",
+      "description": "Reset a failed activity on an in-flight instance — back to pending (re-run) or to skipped (bypass).",
       "flags": {},
       "hasDynamicHelp": false,
       "hidden": true,
       "hiddenAliases": [],
-      "id": "retry-activity",
+      "id": "reset-activity",
       "pluginAlias": "@sanity/workflow-cli",
       "pluginName": "@sanity/workflow-cli",
       "pluginType": "core",
@@ -368,20 +325,31 @@
       "relativePath": [
         "dist",
         "commands",
-        "retry-activity.js"
+        "reset-activity.js"
       ]
     },
     "set-stage": {
       "aliases": [],
       "args": {
         "instanceId": {
-          "description": "Workflow instance id.",
+          "description": "Workflow instance id to move.",
           "name": "instanceId",
           "required": true
         }
       },
-      "description": "Force-set an instance's current stage, bypassing guards + effects (manual override).",
+      "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.",
+      "examples": [
+        "<%= config.bin %> set-stage wf-instance.abc123 --to ready",
+        "<%= config.bin %> set-stage wf-instance.abc123 --to ready --reason 'unblock for demo'"
+      ],
       "flags": {
+        "tag": {
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "name": "tag",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "to": {
           "description": "Target stage name.",
           "name": "to",
@@ -391,7 +359,7 @@
           "type": "option"
         },
         "reason": {
-          "description": "Reason for the manual override.",
+          "description": "Free-text reason — recorded on the history entry for audit.",
           "name": "reason",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -399,13 +367,13 @@
         }
       },
       "hasDynamicHelp": false,
-      "hidden": true,
       "hiddenAliases": [],
       "id": "set-stage",
       "pluginAlias": "@sanity/workflow-cli",
       "pluginName": "@sanity/workflow-cli",
       "pluginType": "core",
       "strict": true,
+      "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -428,6 +396,13 @@
         "<%= config.bin %> show wf-instance.abc123 --include history"
       ],
       "flags": {
+        "tag": {
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "name": "tag",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "include": {
           "description": "Optional sections to include in output.",
           "name": "include",
@@ -455,6 +430,82 @@
         "show.js"
       ]
     },
+    "start": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "description": "Workflow definition name.",
+          "name": "name",
+          "required": true
+        }
+      },
+      "description": "Start a workflow instance from a deployed definition. Supply values for the workflow's input-sourced fields with --field (e.g. the subject document ref).",
+      "examples": [
+        "<%= config.bin %> start productLaunch",
+        "<%= config.bin %> start article-review --field subject='{\"id\":\"dataset:proj:ds:article-1\",\"type\":\"article\"}'",
+        "<%= config.bin %> start article-review --as user.xyz --as-role editor",
+        "<%= config.bin %> start productLaunch --version 2 --tag prod"
+      ],
+      "flags": {
+        "tag": {
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "name": "tag",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "version": {
+          "description": "Definition version to start from (default: highest deployed).",
+          "name": "version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "field": {
+          "description": "Initial value for a declared input-sourced field, as name=value (repeatable). Values are JSON-parsed, falling back to a string; ref kinds take a JSON object with a GDR `id` and doc `type`.",
+          "name": "field",
+          "default": [],
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "as": {
+          "description": "Attribute the write to this Sanity user id (default: a workflow-cli system actor).",
+          "name": "as",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "as-role": {
+          "description": "Role to attribute to the --as user (repeatable), so role-gated filters pass.",
+          "name": "as-role",
+          "default": [],
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "json": {
+          "description": "Emit structured JSON instead of rendered output.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "start",
+      "pluginAlias": "@sanity/workflow-cli",
+      "pluginName": "@sanity/workflow-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "start.js"
+      ]
+    },
     "tail": {
       "aliases": [],
       "args": {
@@ -468,7 +519,15 @@
       "examples": [
         "<%= config.bin %> tail wf-instance.abc123"
       ],
-      "flags": {},
+      "flags": {
+        "tag": {
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "name": "tag",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
       "id": "tail",
@@ -501,7 +560,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -547,9 +606,9 @@
     "definition:diff": {
       "aliases": [],
       "args": {
-        "definition": {
+        "name": {
           "description": "Workflow definition name.",
-          "name": "definition",
+          "name": "name",
           "required": true
         }
       },
@@ -560,7 +619,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -600,7 +659,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -614,9 +673,9 @@
           "multiple": false,
           "type": "option"
         },
-        "workflow-name": {
-          "description": "Filter to a single workflow definition name (e.g. product-launch)",
-          "name": "workflow-name",
+        "name": {
+          "description": "Filter to a single workflow definition name (e.g. product-launch).",
+          "name": "name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -650,7 +709,7 @@
       "description": "Show a deployed workflow definition.",
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.",
+          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -681,5 +740,5 @@
       ]
     }
   },
-  "version": "0.8.0"
+  "version": "0.9.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -46,22 +46,24 @@
   "dependencies": {
     "@oclif/core": "^4.11.4",
     "@oclif/plugin-help": "^6.2.50",
+    "@sanity/cli-core": "^2.1.1",
     "@sanity/client": "^7.22.1",
     "boxen": "^8.0.1",
     "console-table-printer": "^2.16.0",
     "date-fns": "^4.4.0",
     "diff": "^9.0.0",
+    "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
     "ora": "^9.4.0",
-    "@sanity/workflow-engine": "0.12.0"
+    "@sanity/workflow-engine": "0.14.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.7.0",
-    "@sanity/workflow-examples": "0.2.0"
+    "@sanity/workflow-engine-test": "0.9.0",
+    "@sanity/workflow-examples": "0.4.0"
   },
   "oclif": {
     "bin": "sanity-workflows",

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

@@ -1,47 +0,0 @@
-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

@@ -1,77 +0,0 @@
-import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
-import { workflow } from '@sanity/workflow-engine';
-import ora from 'ora';
-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 = styleText('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),
-    };
-}