@sanity/workflow-cli 0.8.1 → 0.10.0

package/README.md

@@ -4,9 +4,9 @@ Command-line tool for deploying, inspecting, and administering Sanity workflow
 definitions and instances.
 
 > [!WARNING]
-> 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.
+> Early access, restricted. The commands below talk to a real Sanity dataset,
+> configured by a `sanity.workflow.ts` file and authenticated with
+> `sanity login`.
 
 ## Run
 
@@ -20,39 +20,82 @@ pnpm --filter @sanity/workflow-cli dev list --in-flight
 pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
 ```
 
-Copy the template and fill it in first: `cp ../../.env.example ../../.env`
-(from the repo root, `cp .env.example .env`). Env vars are read from
-the root `.env` (`SANITY_PROJECT_ID`, `SANITY_DATASET`,
-`SANITY_AUTH_TOKEN`). The dev script loads them via `tsx --env-file`.
-
-### Workflow target (resource + tags)
-
-The CLI targets one engine "resource" (a dataset, canvas, media
-library, or dashboard) tagged with one or more engine tags. Defaults
-match the bench fixtures the rest of this repo uses.
-
-| Env var                  | Default      | Allowed values                                          |
-| ------------------------ | ------------ | ------------------------------------------------------- |
-| `WORKFLOW_RESOURCE_TYPE` | `dataset`    | `dataset` / `canvas` / `media-library` / `dashboard`    |
-| `WORKFLOW_RESOURCE_ID`   | `test.test`  | any string                                              |
-| `WORKFLOW_TAG`           | _(required)_ | single environment tag, e.g. `prod` (`--tag` overrides) |
-| `WORKFLOW_DEFS`          | _(required)_ | module path or package exporting `allDefinitions`       |
-
-Invalid values fail with a clean error before the command runs.
-
-`WORKFLOW_DEFS` has no default — `deploy` is agnostic about which
-definitions it ships, so it must be told where to find them. Point it at a
-module (a path like `./src/workflows.ts`, or a package name) whose
-`allDefinitions` export is a `WorkflowDefinition[]`. This repo's own demo
-set lives in `@sanity/workflow-examples`, so `WORKFLOW_DEFS=@sanity/workflow-examples`
-deploys it.
+Authenticate once with `sanity login` (the CLI reads that session token); for
+CI, set `SANITY_AUTH_TOKEN` instead. Then create a `sanity.workflow.ts` in the
+directory you run from — see [Configuration](#configuration).
+
+The token must span **every resource the workflow references**, not just the
+workflow resource. Runtime commands build one client from the deployment
+descriptor; when a workflow's subject or `doc.ref` fields point into other
+datasets (or a canvas / media library), the engine reaches them through
+sibling clients derived from that same token. A `sanity login` session or an
+org-capable token covers this out of the box; a token scoped to a single
+project will fail on cross-resource reads.
+
+## Configuration
+
+The CLI is configured by a `sanity.workflow.ts` (or `.js`/`.mjs`) discovered in
+the directory you run from. It exports a config built with
+`defineWorkflowConfig`, declaring one **deployment** per environment:
+
+```ts
+import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
+
+import {articleReview, urlDraft} from './src/workflows.ts'
+
+export default defineWorkflowConfig({
+  deployments: [
+    {
+      name: 'production',
+      tag: 'prod', // the environment partition the engine's docs are scoped to
+      workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
+      resourceAliases: [
+        // binds each `@<handle>:` a definition references to a physical resource
+        // in a DIFFERENT dataset from `workflowResource` (same-resource content
+        // needs no alias — see below)
+        {name: 'content', resource: {type: 'dataset', id: 'acme.content'}},
+        {name: 'assets', resource: {type: 'dataset', id: 'acme.assets'}},
+      ],
+      definitions: [articleReview, urlDraft], // the batch this deployment ships
+    },
+  ],
+})
+```
 
-Run through the `dev` / `cli` scripts and this loads straight from
-TypeScript source — no build step between editing a definition and
-deploying it. Those scripts set `NODE_OPTIONS='--conditions=development'`
-and run under `tsx`, so a package specifier resolves to its `src/` via the
-`development` export condition and the `.ts` is transpiled on the fly. A
-built or standalone CLI instead resolves the package's compiled `dist`.
+Pick a deployment with `--tag <tag>`; with a single deployment configured you
+can omit it, and with several configured a bare `deploy` fails asking for
+`--tag` or `--all-tags`. `--all-tags` deploys every deployment in the config in
+one run: a failure in one doesn't stop the rest — the run continues, prints a
+summary of what failed, and exits non-zero. The client's project + dataset are derived
+from the deployment's `workflowResource`, and `deploy` expands each
+definition's `@<handle>:` reference to the bound physical resource. An invalid
+config fails with a clean, path-prefixed error before the command runs.
+
+`resourceAliases` is only for content that lives in a _different_ resource from
+`workflowResource`. A definition can reference a document in the **same**
+resource by bare id, no alias needed — bare ids root at `workflowResource` at
+runtime. Rule of thumb: **different resource → bind an alias and reference it as
+`@<handle>:<id>`; same resource → use a bare id and omit `resourceAliases`
+entirely.** So the simplest single-dataset setup is just a `workflowResource`
+and `definitions`, with no `resourceAliases` at all.
+
+| Var                 | Purpose                                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `SANITY_AUTH_TOKEN` | Explicit token for CI / scripted use — wins over the `sanity login` session (editor role for writes) |
+| `SANITY_API_HOST`   | Optional API host override (defaults to the prod API)                                                |
+
+Run through the `dev` / `cli` scripts and the CLI itself and your
+`sanity.workflow.ts` load straight from TypeScript source: the scripts set
+`NODE_OPTIONS='--conditions=development'` under `tsx`, and the config file is
+transpiled on the fly by `jiti`. Definitions you author **inline** in the
+config, or import by **relative path**, transpile the same way — no build step.
+
+One caveat: a definition imported from a _separate workspace package_ (e.g.
+`@sanity/workflow-examples`) resolves to that package's built `dist/`. `jiti`
+applies its own module resolution and does **not** honour
+`--conditions=development`, so it never picks up a package's `src/` export
+condition — rebuild that package after editing it, or the config loads its
+stale compiled output.
 
 > [!NOTE]
 > pnpm intercepts a handful of its own flag names (`--check`,
@@ -75,25 +118,58 @@ 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-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`)  |
+| Command                                | Status                                                                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                       |
+| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                     |
+| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                             |
+| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                   |
+| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                            |
+| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                         |
+| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                          |
+| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                |
+| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, 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)                                   |
+| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run) |
+| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                          |
+| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                          |
+| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                   |
+| `definition diff <name>`               | 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`)                                    |
+
+## Telemetry
+
+The CLI collects usage telemetry through Sanity's standard pipeline: a
+per-command trace (`Editorial Workflows CLI Command Executed` — the command id, the
+names of declared flags used, never their values, and a success flag) plus
+the engine's adoption events from the operations it drives. Consent is the
+account-wide status managed by `npx sanity telemetry enable|disable|status`;
+CI and trueish `DO_NOT_TRACK` suppress everything, and a session that isn't
+logged in sends nothing. A one-time notice on stderr discloses collection on
+first use.
+
+One extension point: supply your own logger as `telemetry` in
+`sanity.workflow.ts` and the built-in pipeline is not constructed at all —
+every event flows to your implementation unconditionally (CI included), and
+consent, suppression, and destination become its business.
+
+## Definition sharing
+
+Separate from telemetry, `deploy --share-definitions-with-sanity` donates the
+definition documents the deploy newly created to Sanity — verbatim (structure,
+names, titles, GROQ filters, effect configuration, seeded values), plus their
+deployment coordinates (project and dataset, or resource id) — never content
+documents, instances, or your auth token. The documents go to Sanity's
+first-party definition-feedback endpoint, not the telemetry pipeline;
+telemetry carries only a content-free marker (content hash plus structural
+counts) per shared definition.
+
+Sharing is opt-in by the flag alone, per invocation: the CLI never prompts
+and nothing persists. An interactive deploy that created new definition
+versions without the flag logs a one-line stderr hint pointing at it — CI /
+non-TTY runs stay silent. Telemetry consent and `DO_NOT_TRACK` play no part:
+sharing is its own explicit consent, given per deploy.
 
 ## Known gaps
 
@@ -101,15 +177,21 @@ built or standalone CLI instead resolves the package's compiled `dist`.
   Sanity CLI as a plugin host. The package publishes as a standalone
   `sanity-workflows` binary today; plugging into `sanity` as an oclif
   plugin is a separate piece of work.
-- **`set-stage` manual override.** The engine's `workflow.setStage`
-  always runs guards + effects; the proposal's "bypass" semantics
-  need engine work before this command can do anything useful.
-- **Actor identity.** Write paths default the actor to
-  `{ kind: "system", id: "workflow-cli" }` rather than resolving the real
-  user via `/users/me` (which a token-only CLI can't reach). `fire-action`
-  takes `--as <userId>` / `--as-role <role>` to attribute a fire to a real
-  user, so assignee- and role-gated action filters pass. Once we host inside
-  the Sanity CLI's auth flow, the real user can flow through everywhere.
+- **No true bypass.** `set-stage` is the engine's `setStage` admin
+  override: it skips the definition's declared transitions and filters, but
+  the target stage's enter lifecycle and the post-move cascade still run. A
+  true force-set that also bypasses guards + enter effects does not exist
+  yet — it needs engine work that hasn't landed.
+
+## Identity
+
+Identity is the token behind the configured client: the engine resolves the
+acting user (and their roles) from `/users/me`, so every write is attributed
+to whoever the token authenticates — there is no identity injection and no
+`--as` impersonation. Alongside that "who", the CLI declares an advisory
+"via what": every verb carries
+`executionContext: { kind: "cli", id: "workflow-cli" }`, stamped on history
+entries as provenance.
 
 ## Tech stack
 

package/bin/run.js

@@ -1,8 +1,4 @@
 #!/usr/bin/env node
-// Production entry for the published package: loads the compiled commands
-// from ./dist/commands (per the `oclif.commands` field). The dev counterpart,
-// bin/dev.js, passes `development: true` to load TS sources instead.
-
 import {execute} from '@oclif/core'
 
 await execute({dir: import.meta.url})

package/dist/commands/abort.d.ts

@@ -1,5 +1,7 @@
-import { Command } from '@oclif/core';
-export default class Abort extends Command {
+import { type WorkflowInstance } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
+import { type WriteReport } from '../lib/ops-report.ts';
+export default class Abort extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
@@ -12,19 +14,13 @@ export default class Abort extends Command {
     run(): Promise<void>;
 }
 interface AbortOutcome {
-    fired: boolean;
-    instance: {
-        currentStage: string;
-        completedAt?: string | undefined;
-    };
+    changed: boolean;
+    instance: Pick<WorkflowInstance, 'currentStage' | 'completedAt'>;
 }
 /**
  * Turn an `abortInstance` result into the spinner message. Pure so the
- * fired / already-terminal permutations can be asserted without driving
+ * aborted / already-terminal permutations can be asserted without driving
  * a real abort.
  */
-export declare function abortReport(result: AbortOutcome): {
-    fired: boolean;
-    message: string;
-};
+export declare function abortReport(result: AbortOutcome): WriteReport;
 export {};

package/dist/commands/abort.js

@@ -1,13 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, 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 { WorkflowCommand } from "../lib/base-command.js";
+import { resolveInstanceContext } from "../lib/context.js";
 import { tagFlags } from "../lib/flags.js";
 import { buildOperationArgs } from "../lib/operation-args.js";
-export default class Abort extends Command {
+import { runWriteVerb } from "../lib/ops-report.js";
+export default class Abort extends WorkflowCommand {
     static description = 'Abort an in-flight workflow instance — a hard stop: pending effects are cancelled, stage guards lifted, and the instance is marked terminal where it stands.';
     static examples = [
         '<%= config.bin %> abort wf-instance.abc123',
@@ -22,41 +21,32 @@ export default class Abort extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Abort);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
-        const spinner = ora(`Aborting ${args.instanceId}…`).start();
-        try {
-            const result = await workflow.abortInstance({
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
+        await runWriteVerb({
+            startLabel: `Aborting ${args.instanceId}…`,
+            failLabel: 'Abort rejected',
+            failHeadline: 'abort error:',
+            run: () => workflow.abortInstance({
                 client,
-                ...buildOperationArgs({ config, instanceId: args.instanceId, reason: flags.reason }),
-            });
-            const report = abortReport(result);
-            if (!report.fired) {
-                spinner.warn(report.message);
-                return;
-            }
-            spinner.succeed(report.message);
-        }
-        catch (error) {
-            spinner.fail('Abort rejected');
-            const message = error instanceof Error ? error.message : String(error);
-            fail('abortInstance error:', message);
-        }
+                ...buildOperationArgs({
+                    scope,
+                    instanceId: args.instanceId,
+                    reason: flags.reason,
+                }),
+            }),
+            report: abortReport,
+            log: (line) => this.log(line),
+        });
     }
 }
-/**
- * Turn an `abortInstance` result into the spinner message. Pure so the
- * fired / already-terminal permutations can be asserted without driving
- * a real abort.
- */
 export function abortReport(result) {
     const stage = styleText('bold', result.instance.currentStage);
-    if (!result.fired) {
+    if (!result.changed) {
         const at = result.instance.completedAt ?? 'unknown';
         return {
-            fired: false,
-            message: `abortInstance returned without firing — instance is already terminal (at ${stage} since ${at})`,
+            changed: false,
+            message: `abortInstance changed nothing — instance is already terminal (at ${stage} since ${at})`,
         };
     }
-    return { fired: true, message: `Aborted — instance hard-stopped at ${stage}` };
+    return { changed: true, message: `Aborted — instance hard-stopped at ${stage}` };
 }

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

@@ -1,7 +1,7 @@
-import { Command } from '@oclif/core';
 import { type DeleteDefinitionArgs, type DeleteDefinitionResult } from '@sanity/workflow-engine';
-import { type WorkflowConfig } from '../../lib/config.ts';
-export default class DefinitionDelete extends Command {
+import { WorkflowCommand } from '../../lib/base-command.ts';
+import { type EngineScope } from '../../lib/operation-args.ts';
+export default class DefinitionDelete extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
@@ -21,15 +21,15 @@ export default class DefinitionDelete extends Command {
  * engine's optionals reject an explicit `undefined` under
  * `exactOptionalPropertyTypes`.
  */
-export declare function buildDeleteArgs({ config, name, flags, }: {
-    config: WorkflowConfig;
+export declare function buildDeleteArgs({ scope, name, flags, }: {
+    scope: EngineScope;
     name: string;
     flags: {
         version?: number | undefined;
         cascade: boolean;
         reason?: string | undefined;
     };
-}): Omit<DeleteDefinitionArgs, 'client'>;
+}): DeleteDefinitionArgs & EngineScope;
 /** What the spinner names: the workflow, or one pinned version of it. */
 export declare function deleteTargetLabel(args: Pick<DeleteDefinitionArgs, 'definition' | 'version'>): string;
 /**

package/dist/commands/definition/delete.js

@@ -1,13 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, 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 { WorkflowCommand } from "../../lib/base-command.js";
+import { resolveContext } from "../../lib/context.js";
 import { tagFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
-export default class DefinitionDelete extends Command {
+import { runWriteVerb } from "../../lib/ops-report.js";
+export default class DefinitionDelete extends WorkflowCommand {
     static description = 'Delete a deployed workflow definition (every version, or one via --version). ' +
         'Refuses while non-terminal instances exist unless --cascade aborts them first — ' +
         'instances are aborted in place, never deleted.';
@@ -34,45 +33,30 @@ export default class DefinitionDelete extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(DefinitionDelete);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
-        const deleteArgs = buildDeleteArgs({ config, name: args.name, flags });
-        const spinner = ora(`Deleting definition ${deleteTargetLabel(deleteArgs)}…`).start();
-        try {
-            const result = await workflow.deleteDefinition({ client, ...deleteArgs });
-            spinner.succeed(deleteReport(result));
-        }
-        catch (error) {
-            spinner.fail('Delete rejected');
-            const message = error instanceof Error ? error.message : String(error);
-            fail('deleteDefinition error:', message);
-        }
+        const { deployment, client } = await resolveContext(flags);
+        const deleteArgs = buildDeleteArgs({ scope: deployment, name: args.name, flags });
+        await runWriteVerb({
+            startLabel: `Deleting definition ${deleteTargetLabel(deleteArgs)}…`,
+            failLabel: 'Delete rejected',
+            failHeadline: 'definition delete error:',
+            run: () => workflow.deleteDefinition({ client, ...deleteArgs }),
+            report: (result) => ({ changed: true, message: deleteReport(result) }),
+            log: (line) => this.log(line),
+        });
     }
 }
-/**
- * The shared engine args ({@link baseEngineArgs}) plus the delete-specific
- * targeting. `version` and `reason` spread conditionally because the
- * engine's optionals reject an explicit `undefined` under
- * `exactOptionalPropertyTypes`.
- */
-export function buildDeleteArgs({ config, name, flags, }) {
+export function buildDeleteArgs({ scope, name, flags, }) {
     return {
-        ...baseEngineArgs(config),
+        ...baseEngineArgs(scope),
         definition: name,
         cascade: flags.cascade,
         ...(flags.version !== undefined ? { version: flags.version } : {}),
         ...(flags.reason !== undefined ? { reason: flags.reason } : {}),
     };
 }
-/** What the spinner names: the workflow, or one pinned version of it. */
 export function deleteTargetLabel(args) {
     return args.version === undefined ? args.definition : `${args.definition} v${args.version}`;
 }
-/**
- * Turn a `deleteDefinition` result into the spinner message. Pure so the
- * version / cascade / guard permutations can be asserted without driving
- * a real delete.
- */
 export function deleteReport(result) {
     const versions = result.deletedVersions.map((v) => `v${v}`).join(', ');
     const parts = [`Deleted ${styleText('bold', result.name)} ${versions}`];

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

@@ -1,9 +1,10 @@
-import { Command } from '@oclif/core';
-export default class DefinitionDiff extends Command {
+import { type WorkflowDefinition } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
+export default class DefinitionDiff extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
-        definition: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -11,3 +12,9 @@ export default class DefinitionDiff extends Command {
     };
     run(): Promise<void>;
 }
+/**
+ * Pick the single definition to diff by name and validate it, failing cleanly
+ * when it's missing from the deployment or doesn't pass validation. Extracted
+ * from `run` so the command's orchestration stays thin and this stays testable.
+ */
+export declare function selectDefinitionToDiff(definitions: WorkflowDefinition[], name: string): WorkflowDefinition;

package/dist/commands/definition/diff.js

@@ -1,21 +1,20 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { diffEntry } from '@sanity/workflow-engine';
 import ora from 'ora';
-import { loadClient } from "../../lib/client.js";
-import { loadWorkflowConfig } from "../../lib/config.js";
-import { loadValidatedDefinition } from "../../lib/definitions.js";
+import { WorkflowCommand } from "../../lib/base-command.js";
+import { resolveContext } from "../../lib/context.js";
+import { fetchDeployedDefinition, selectDefinitions, validateOrFail } from "../../lib/definitions.js";
 import { diffReport } from "../../lib/diff.js";
-import { fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { buildDefinitionShowQuery } from "./show.js";
-export default class DefinitionDiff extends Command {
+import { deploymentToTarget } from "../../lib/select-deployment.js";
+export default class DefinitionDiff extends WorkflowCommand {
     static description = 'Diff an in-code definition against the deployed version (latest by default).';
     static examples = [
         '<%= config.bin %> definition diff productLaunch',
         '<%= config.bin %> definition diff productLaunch --version 2',
     ];
     static args = {
-        definition: Args.string({ required: true, description: 'Workflow definition name.' }),
+        name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
         ...tagFlags,
@@ -23,40 +22,33 @@ export default class DefinitionDiff extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(DefinitionDiff);
-        const config = loadWorkflowConfig(flags.tag);
-        const def = await loadValidatedDefinition(args.definition);
-        const client = loadClient();
-        const spinner = ora(`Diffing ${args.definition} against deployed…`).start();
+        const { deployment, client } = await resolveContext(flags);
+        const def = selectDefinitionToDiff(deployment.definitions, args.name);
+        const target = deploymentToTarget(deployment);
+        const spinner = ora(`Diffing ${args.name} against deployed…`).start();
         let deployed;
         try {
             deployed = await fetchDeployedDefinition({
                 client,
-                name: args.definition,
-                config,
+                name: args.name,
+                tag: target.tag,
                 version: flags.version,
             });
-            spinner.succeed(`Diffed ${args.definition}`);
+            spinner.succeed(`Diffed ${args.name}`);
         }
         catch (error) {
             spinner.fail('Diff failed');
             throw error;
         }
-        for (const line of diffReport([diffEntry({ def, latestRaw: deployed, target: config })]))
+        for (const line of diffReport([diffEntry({ def, latestRaw: deployed, target })]))
             this.log(line);
     }
 }
-/**
- * Fetch the deployed document to compare against. Unlike `deploy
- * --dry-run` (which looks up the exact docId, so a version bump always
- * reads as "create"), diff targets the deployed version that would be
- * superseded — latest unless pinned via `version`. An absent latest is a
- * legitimate "create" diff, but an absent *pinned* version is an error.
- */
-async function fetchDeployedDefinition({ client, name, config, version, }) {
-    const { groq, params } = buildDefinitionShowQuery({ name, tag: config.tag, version });
-    const deployed = await client.fetch(groq, params);
-    if (deployed === null && version !== undefined) {
-        fail(`No deployed definition "${name}" v${version}.`);
+export function selectDefinitionToDiff(definitions, name) {
+    const [def] = selectDefinitions(definitions, { only: name });
+    if (def === undefined) {
+        throw new Error(`selectDefinitions returned no match for "${name}"`);
     }
-    return deployed ?? undefined;
+    validateOrFail([def]);
+    return def;
 }

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

@@ -1,8 +1,7 @@
-import { Command } from '@oclif/core';
-import { type WorkflowRole } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 interface DefinitionListFlags {
     tag?: string | undefined;
-    'workflow-name'?: string | undefined;
+    name?: string | undefined;
     limit: number;
 }
 export interface DefinitionListRow {
@@ -10,21 +9,21 @@ export interface DefinitionListRow {
     version: number;
     title: string;
     tag: string;
-    role?: WorkflowRole;
     stageCount: number;
     inFlightCount: number;
     totalInstances: number;
+    _createdAt: string;
 }
 export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
     groq: string;
     params: Record<string, unknown>;
 };
-export default class DefinitionList extends Command {
+export default class DefinitionList extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        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>;