@sanity/workflow-cli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @sanity/workflow-cli
 
+## 0.11.0
+
+### Minor Changes
+
+- e5f5b77: **BREAKING:** rendering and the `--json` diagnose payload follow the engine's actions-only payload model.
+  - `fire-action`'s list mode renders a cascade-fired action as automation (`⚡ … [automation]` with the engine's canonical cascade-fired detail), never as a fireable command; other disabled reasons keep the shared `actionDisabledDetail` rendering.
+  - `diagnose` renders transitions by their `when` trigger (`whenSatisfied` replaces `filterSatisfied` in the `--json` transitions payload), narrates a waiting activity by its caller-fireable actions only (an all-automation activity reads "waiting on automation"), and words failed-effect causes by their action origin.
+  - The activity status glyphs drop `pending` — activities are active from stage entry.
+
+- 7510fd5: **BREAKING:** `list` speaks the engine's filter vocabulary: the `--in-flight` flag (default: list everything) is replaced by `--include-completed` (default: in-flight only) — the same name, polarity, and default the engine and MCP list surfaces use. `list` also gains `--document <gdr-uri>` to list the instances that reference a document.
+
+  Fixes: expected failures (rejected write verbs, validation errors, the 401 arm) now exit by throwing through the oclif lifecycle instead of a raw `process.exit`, so the telemetry `finally` hook still completes the command trace and flushes batched events; `tail` serializes its notification handling (a burst of commits could double-print history entries and regress the high-water mark); and an untagged `definition show` whose name exists in several tag partitions of one dataset now errors listing the partitions — it previously picked the highest version across partitions, which could show a prod operator the dev definition.
+
+- 6e7f42d: **BREAKING:** Definition sharing on `deploy` flips from opt-in to opt-out, and the flag is renamed. `--share-definitions-with-sanity` becomes the negatable `--share-defs` / `--no-share-defs`. A deploy that creates new definition versions now donates them by default; `--no-share-defs` opts out.
+
+  With neither flag, an interactive terminal is asked **once** — a blocking acknowledgement whose answer persists in the Sanity user config, so it never repeats — before anything is sent, since notice must precede the send. Every later flagless deploy prints a one-line reminder of the current state and the flag to change it, so an ongoing donation is never silent. Unattended runs (CI, `DO_NOT_TRACK`, non-TTY) can't prompt and donate nothing by default; opt in per run with `--share-defs`.
+
+  An explicit `--share-defs` also sends that deploy's telemetry regardless of CI / `DO_NOT_TRACK` (a command-line arg beats env vars; account-level `sanity telemetry disable` still applies). Telemetry gains a content-free `Editorial Workflows Definition Sharing Decided` event per invocation — how the decision was reached and what it was (`opt-in` / `opt-out` / `prompt-accepted` / `prompt-declined` / `remembered-share` / `remembered-decline` / `unattended`), whether anything reached the endpoint, and how many versions were eligible — so adoption dashboards can separate explicit opt-outs, prompt declines, and unattended runs and measure the true opt-out rate. The per-definition `Editorial Workflows Definition Shared` marker and the one-POST feedback transport are unchanged.
+
+### Patch Changes
+
+- Updated dependencies [11e2d6f]
+- Updated dependencies [7510fd5]
+- Updated dependencies [01e8042]
+- Updated dependencies [79c54db]
+- Updated dependencies [6a46db1]
+- Updated dependencies [35b9b85]
+- Updated dependencies [e5f5b77]
+- Updated dependencies [01e8042]
+  - @sanity/workflow-engine@0.16.0
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -16,7 +16,7 @@ pnpm --filter @sanity/workflow-cli dev <command> [...args]
 # Examples:
 pnpm --filter @sanity/workflow-cli dev --help
 pnpm --filter @sanity/workflow-cli dev deploy --dry-run
-pnpm --filter @sanity/workflow-cli dev list --in-flight
+pnpm --filter @sanity/workflow-cli dev list --include-completed
 pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
 ```
 
@@ -145,9 +145,10 @@ per-command trace (`Editorial Workflows CLI Command Executed` — the command id
 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.
+CI and trueish `DO_NOT_TRACK` suppress everything (except a `deploy --share-defs`,
+which forces that deploy's telemetry — see [Definition sharing](#definition-sharing)),
+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 —
@@ -156,20 +157,27 @@ 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.
+Separate from telemetry, a `deploy` that creates new definition versions
+donates those documents 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 and a per-invocation decision event.
+
+Sharing is **opt-out**. Pass `--share-defs` to donate without being asked, or
+`--no-share-defs` to decline. With neither flag, an interactive terminal is
+asked **once** — the answer is remembered in your Sanity user config, so the
+prompt never repeats — before anything is sent; notice always precedes the
+send. Every later flagless deploy then prints a one-line reminder of the
+current state (sharing, or not) and the flag to change it, so an ongoing
+donation is never silent. Unattended runs (CI, `DO_NOT_TRACK`, a non-TTY pipe)
+can't prompt: by default they donate nothing (opt in per run with
+`--share-defs`). An explicit `--share-defs` also sends that deploy's telemetry
+regardless of CI / `DO_NOT_TRACK` — a command-line arg beats env vars;
+account-level `sanity telemetry disable` still applies. A failed share only
+warns, never failing a completed deploy.
 
 ## Known gaps
 

package/dist/commands/definition/list.js

@@ -1,5 +1,5 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, inFlightFilter, tagScopeFilter, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets } from "../../lib/context.js";
@@ -31,7 +31,7 @@ export function buildDefinitionListQuery(flags) {
       tag,
       _createdAt,
       "stageCount": count(stages),
-      "inFlightCount": count(*[${instanceMatch} && !defined(completedAt)]),
+      "inFlightCount": count(*[${instanceMatch} && ${inFlightFilter()}]),
       "totalInstances": count(*[${instanceMatch}])
     }`;
     return { groq, params };

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

@@ -12,6 +12,19 @@ export default class DefinitionShow extends WorkflowCommand {
     };
     run(): Promise<void>;
 }
+/**
+ * Resolve the one definition `show` names, refusing every ambiguity: an
+ * untagged name spanning several tag partitions within a dataset
+ * ({@link assertSingleTagPartition}) and a name held by several datasets
+ * ({@link soleHitOrFail}) both error, never pick. `undefined` means nothing
+ * is deployed under the name.
+ */
+export declare function resolveShownDefinition({ targets, name, tag, version, }: {
+    targets: ReadTarget[];
+    name: string;
+    tag: string | undefined;
+    version: number | undefined;
+}): Promise<DeployedDefinition | undefined>;
 /** How a lookup names the version it asked for: `vN` for a pinned
  *  `--version`, `latest` when unpinned. */
 export declare function versionLabel(version: number | undefined): string;

package/dist/commands/definition/show.js

@@ -4,9 +4,10 @@ import { isTerminalStage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets, soleHitOrFail } from "../../lib/context.js";
-import { buildDefinitionShowQuery } from "../../lib/definitions.js";
+import { buildDefinitionShowQuery, buildDefinitionTagsQuery } from "../../lib/definitions.js";
+import { fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { formatKeyValue, sectionHeader } from "../../lib/ui.js";
+import { formatKeyValue, resourceLabel, sectionHeader } from "../../lib/ui.js";
 export default class DefinitionShow extends WorkflowCommand {
     static description = 'Show a deployed workflow definition.';
     static args = {
@@ -19,13 +20,12 @@ export default class DefinitionShow extends WorkflowCommand {
     async run() {
         const { args, flags } = await this.parse(DefinitionShow);
         const targets = await resolveReadTargets(flags);
-        const { groq, params } = buildDefinitionShowQuery({
+        const def = await resolveShownDefinition({
+            targets,
             name: args.name,
             tag: flags.tag,
             version: flags.version,
         });
-        const hits = await fetchDefinitionHits({ targets, groq, params });
-        const def = soleHitOrFail(hits, `Definition "${args.name}"`)?.def;
         if (!def) {
             this.error(`${logSymbols.error} no definition "${args.name}" (${versionLabel(flags.version)})`, {
                 exit: 1,
@@ -38,9 +38,27 @@ export default class DefinitionShow extends WorkflowCommand {
         }
     }
 }
+export async function resolveShownDefinition({ targets, name, tag, version, }) {
+    if (tag === undefined) {
+        await assertSingleTagPartition({ targets, name });
+    }
+    const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
+    const hits = await fetchDefinitionHits({ targets, groq, params });
+    return soleHitOrFail(hits, `Definition "${name}"`)?.def;
+}
 export function versionLabel(version) {
     return version === undefined ? 'latest' : `v${version}`;
 }
+async function assertSingleTagPartition({ targets, name, }) {
+    const { groq, params } = buildDefinitionTagsQuery(name);
+    await Promise.all(targets.map(async (target) => {
+        const tags = await target.client.fetch(groq, params, { tag: 'definition.show' });
+        if (tags.length > 1) {
+            fail(`Definition "${name}" exists in several tag partitions in ` +
+                `${resourceLabel(target.resource)} — pass --tag to choose one.`, tags.toSorted().join('\n'));
+        }
+    }));
+}
 export async function fetchDefinitionHits({ targets, groq, params, }) {
     const probes = await Promise.all(targets.map(async (target) => {
         const def = await target.client.fetch(groq, params, {

package/dist/commands/deploy.d.ts

@@ -18,7 +18,7 @@ export default class Deploy extends WorkflowCommand {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         only: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'share-definitions-with-sanity': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'share-defs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/deploy.js

@@ -41,9 +41,9 @@ export default class Deploy extends WorkflowCommand {
         only: Flags.string({
             description: 'Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.',
         }),
-        'share-definitions-with-sanity': Flags.boolean({
-            description: 'Share the definition documents newly created by this deploy with Sanity — the full document, verbatim (structure, names, filters, effect configuration, seeded values), plus its deployment coordinates (project and dataset, or resource id); never content documents, instances, or your Sanity auth token. Opt-in for this invocation only; the CLI never prompts. Independent of telemetry consent.',
-            default: false,
+        'share-defs': Flags.boolean({
+            allowNo: true,
+            description: 'Share the definition documents newly created by this deploy with Sanity — the full document, verbatim (structure, names, filters, effect configuration, seeded values), plus its deployment coordinates (project and dataset, or resource id); never content documents, instances, or your Sanity auth token. Opt-out: an interactive terminal is asked once (the answer is remembered), while unattended runs (CI / non-TTY / DO_NOT_TRACK) share nothing unless --share-defs is passed. Use --no-share-defs to opt out. An explicit --share-defs also sends telemetry for this deploy regardless of CI / DO_NOT_TRACK.',
         }),
     };
     async run() {
@@ -90,7 +90,7 @@ export default class Deploy extends WorkflowCommand {
             log(line);
         }
         await shareDefinitionsAfterDeploy({
-            flag: flags['share-definitions-with-sanity'],
+            flag: flags['share-defs'],
             candidates,
             warn: (message) => this.warn(message),
         });

package/dist/commands/diagnose.d.ts

@@ -6,7 +6,7 @@ import { WorkflowCommand } from '../lib/base-command.ts';
 export declare function rawTransitionProjection(evaluation: WorkflowEvaluation): {
     name: string;
     to: string;
-    filterSatisfied: boolean;
+    whenSatisfied: boolean;
     unevaluable: boolean;
     blockedBy: {
         requirement?: import("@sanity/groq-condition-describe").AtomRequirement;

package/dist/commands/diagnose.js

@@ -19,8 +19,8 @@ function activityLine(t, assignees) {
     return `  ${activityIcon[t.status]} ${t.activity.name} ${styleText('dim', `[${t.status}]`)}${who}`;
 }
 function transitionLine(tr, explanation) {
-    const mark = tr.filterSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
-    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    const mark = tr.whenSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
+    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.when)}  ${mark}`;
     return explanation !== undefined ? `${line}\n      ${styleText('dim', `↳ ${explanation}`)}` : line;
 }
 function currentStageLines(input, explanations) {
@@ -28,7 +28,7 @@ function currentStageLines(input, explanations) {
         `${sectionHeader('Stage')} ${input.instance.currentStage}`,
         sectionHeader('Activities'),
     ];
-    for (const t of input.activities) {
+    for (const t of input.activities.filter((a) => !a.scopedOut)) {
         lines.push(activityLine(t, input.assignees[t.activity.name] ?? []));
     }
     if (input.transitions.length > 0) {
@@ -42,14 +42,14 @@ function currentStageLines(input, explanations) {
 function failedEffectDetail(effect) {
     const ran = effect.durationMs !== undefined ? ` (after ${effect.durationMs}ms)` : '';
     return {
-        headline: `a failed effect is blocking activity '${effect.origin.name}'`,
+        headline: `a failed effect from action '${effect.origin.name}' is blocking its activity`,
         why: [
             styleText('red', `${logSymbols.error} failed effect: ${effect.name}`),
-            `  queued by activity '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
+            `  queued by action '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
             ...(effect.error !== undefined ? [`  error: ${effect.error.message}`] : []),
             '',
-            `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.`,
+            `The activity that fired '${effect.origin.name}' is waiting on this effect. It failed`,
+            `against an external system, so the activity never resolves and the stage can't advance.`,
         ],
     };
 }
@@ -74,12 +74,22 @@ function failedActivityDetail(activity) {
 }
 function waitingHeadline(w) {
     const who = w.assignees.length > 0 ? ` on ${w.assignees.map(formatAssignee).join(', ')}` : '';
+    if (w.actions.length === 0) {
+        return `waiting${who} on automation — a trigger fires on its own when its condition holds`;
+    }
     return `waiting${who} for action: ${w.actions.join(' or ')}`;
 }
 function waitingLines(w) {
     const who = w.assignees.length > 0
         ? `assigned to ${w.assignees.map(formatAssignee).join(', ')}`
         : 'unassigned — anyone with permission can act';
+    if (w.actions.length === 0) {
+        return [
+            `${logSymbols.info} activity '${w.activity}' is active (${who}),`,
+            `waiting on automation: its cascade-fired action(s) fire on their own when their`,
+            `trigger conditions hold — nothing for a caller to fire.`,
+        ];
+    }
     return [
         `${logSymbols.info} activity '${w.activity}' is active (${who}),`,
         `waiting for action: ${w.actions.join(' or ')}. This is the normal in-flight`,
@@ -103,20 +113,20 @@ function blockedLines(b) {
 }
 function noTransitionDetail() {
     return {
-        headline: `no exit transition's filter is satisfied`,
+        headline: `no exit transition's trigger is satisfied`,
         why: [
-            `${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.`,
+            `${logSymbols.info} every activity is resolved, but no exit transition's \`when\` is true.`,
+            `Likely a routing state value a trigger reads never got written.`,
         ],
     };
 }
 function transitionUnevaluableDetail(transitions) {
     return {
-        headline: `an exit transition's filter could not be evaluated`,
+        headline: `an exit transition's trigger could not be evaluated`,
         why: [
             `${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`,
+            `falling through. Make the data the trigger reads readable — publish the`,
             `subject (or fill the field) — and the instance advances on its own; no`,
             `set-stage needed.`,
         ],
@@ -166,7 +176,7 @@ export function rawTransitionProjection(evaluation) {
     return evaluation.currentStage.transitions.map((t) => ({
         name: t.transition.name,
         to: t.transition.to,
-        filterSatisfied: t.filterSatisfied,
+        whenSatisfied: t.whenSatisfied,
         unevaluable: t.unevaluable,
         blockedBy: t.insight.blockedBy.map((atom) => ({
             groq: atom.atom.groq,

package/dist/commands/fire-action.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
+import { actionRendering, actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveInstanceContext } from "../lib/context.js";
@@ -20,8 +20,19 @@ function paramLabel(p) {
     return `${p.name}${p.required === true ? '' : '?'}:${p.type}`;
 }
 function actionLines(a) {
-    const mark = a.allowed ? logSymbols.success : logSymbols.error;
     const title = a.title !== undefined ? styleText('dim', `  (${a.title})`) : '';
+    const rendering = actionRendering(a);
+    if (rendering === 'absent')
+        return [];
+    if (rendering === 'automation') {
+        return [
+            `  ${styleText('cyan', '⚡')} ${a.activity} → ${a.action}${title} ${styleText('dim', '[automation]')}`,
+            ...(a.disabledReason?.kind === 'cascade-fired'
+                ? [styleText('dim', `      ${actionDisabledDetail(a.disabledReason)}`)]
+                : []),
+        ];
+    }
+    const mark = a.allowed ? logSymbols.success : logSymbols.error;
     const lines = [
         `  ${mark} ${a.activity} → ${a.action}${title} ${styleText('dim', `[activity ${a.activityStatus}]`)}`,
     ];

package/dist/commands/list.d.ts

@@ -10,9 +10,10 @@ interface InstanceRow {
     lastChangedAt: string;
 }
 interface ListFlags {
-    'in-flight': boolean;
+    'include-completed': boolean;
     failed: boolean;
     definition?: string | undefined;
+    document?: string | undefined;
     tag?: string | undefined;
     limit: number;
 }
@@ -20,6 +21,13 @@ interface ListFlags {
  * Build the GROQ query + params for `list` from its flags. Pure so the
  * filter combinations can be asserted without a live dataset. `--tag` is an
  * optional filter: omit it and the listing spans every partition.
+ *
+ * With `--document` the lake filter is the engine's prefilter arm — a
+ * deliberate superset narrowed to the exact watch-set in JS
+ * ({@link instanceWatchesDocument}) — so the rows come back as full
+ * documents (the narrowing reads fields/stages/ancestors) and UNCAPPED: a
+ * capped superset could silently hide matches. The display limit applies
+ * after narrowing.
  */
 export declare function buildListQuery(flags: ListFlags): {
     groq: string;
@@ -38,9 +46,10 @@ export default class List extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        'in-flight': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'include-completed': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         failed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         definition: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        document: 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

@@ -1,21 +1,34 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_INSTANCE_TYPE, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
+import { WORKFLOW_INSTANCE_TYPE, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveReadTargets } from "../lib/context.js";
+import { failOnThrow } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { runReadAcrossTargets } from "../lib/read-fanout.js";
 import { clipToLimit, formatAge, formatTable } from "../lib/ui.js";
 export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
-    if (flags['in-flight'])
-        filters.push('!defined(completedAt)');
-    if (flags.definition)
+    const params = {};
+    if (!flags['include-completed'])
+        filters.push(inFlightFilter());
+    if (flags.definition) {
         filters.push('definition == $definition');
+        params['definition'] = flags.definition;
+    }
     if (flags.failed)
         filters.push('count(stages[].activities[status == "failed"]) > 0');
-    if (flags.tag)
+    if (flags.tag) {
         filters.push(tagScopeFilter());
+        params['tag'] = flags.tag;
+    }
+    if (flags.document) {
+        const armParams = {};
+        filters.push(`(${documentPrefilter([flags.document], armParams)})`);
+        Object.assign(params, armParams);
+        return { groq: `*[${filters.join(' && ')}] | order(lastChangedAt desc)`, params };
+    }
+    params['limit'] = flags.limit + 1;
     const groq = `*[${filters.join(' && ')}] | order(lastChangedAt desc) [0...$limit]{
       _id,
       definition,
@@ -25,11 +38,6 @@ export function buildListQuery(flags) {
       abortedAt,
       lastChangedAt
     }`;
-    const params = { limit: flags.limit + 1 };
-    if (flags.definition)
-        params['definition'] = flags.definition;
-    if (flags.tag)
-        params['tag'] = flags.tag;
     return { groq, params };
 }
 export function instanceRow(r) {
@@ -46,17 +54,18 @@ export function instanceRow(r) {
     };
 }
 export default class List extends WorkflowCommand {
-    static description = 'List workflow instances in the configured dataset.';
+    static description = 'List workflow instances in the configured dataset (in-flight by default).';
     static examples = [
         '<%= config.bin %> list',
-        '<%= config.bin %> list --in-flight',
+        '<%= config.bin %> list --include-completed',
         '<%= config.bin %> list --definition productLaunch',
+        '<%= config.bin %> list --document dataset:proj:ds:article-1',
         '<%= config.bin %> list --tag prod',
     ];
     static flags = {
         ...tagFlags,
-        'in-flight': Flags.boolean({
-            description: 'Only instances that have not completed.',
+        'include-completed': Flags.boolean({
+            description: 'Include completed/aborted instances (default: in-flight only).',
             default: false,
         }),
         failed: Flags.boolean({
@@ -66,6 +75,10 @@ export default class List extends WorkflowCommand {
         definition: Flags.string({
             description: "Only instances of this workflow definition (its `name`; the instance's `definition` field).",
         }),
+        document: Flags.string({
+            description: 'Only instances that reference this document (resource-qualified GDR URI, ' +
+                'e.g. "dataset:proj:ds:article-1").',
+        }),
         limit: Flags.integer({
             description: 'Maximum rows to return.',
             default: 50,
@@ -74,12 +87,13 @@ export default class List extends WorkflowCommand {
     async run() {
         const { flags } = await this.parse(List);
         const targets = await resolveReadTargets(flags);
-        const { groq, params } = buildListQuery(flags);
+        const { groq, params } = failOnThrow('Invalid --document:', () => buildListQuery(flags));
+        const document = flags.document;
         const failures = await runReadAcrossTargets({
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = await client.fetch(groq, params, { tag: 'list' });
+                const fetched = await fetchRows({ client, groq, params, document });
                 if (fetched.length === 0) {
                     this.log(`${logSymbols.info} no instances match`);
                     return;
@@ -109,3 +123,10 @@ export default class List extends WorkflowCommand {
         }
     }
 }
+async function fetchRows({ client, groq, params, document, }) {
+    if (document === undefined) {
+        return client.fetch(groq, params, { tag: 'list' });
+    }
+    const candidates = await client.fetch(groq, params, { tag: 'list' });
+    return candidates.filter((instance) => instanceWatchesDocument(instance, document));
+}

package/dist/commands/start.d.ts

@@ -1,4 +1,4 @@
-import { type FieldEntry, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance, type WorkflowLifecycle } from '@sanity/workflow-engine';
+import { type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../lib/base-command.ts';
 import { type EngineScope } from '../lib/operation-args.ts';
 export default class Start extends WorkflowCommand {
@@ -15,27 +15,6 @@ export default class Start extends WorkflowCommand {
     };
     run(): Promise<void>;
 }
-/**
- * Why a definition can't be started standalone, or `undefined` when it can.
- * Advisory, mirroring the Startable column in `definition list` — the engine
- * itself does not refuse ({@link isStartableDefinition}), but the CLI has no
- * way to supply the parent context a spawn-only child expects.
- */
-export declare function startRefusal(definition: {
-    lifecycle?: WorkflowLifecycle | undefined;
-}): string | undefined;
-/**
- * Type each `--field name=value` against the workflow's declared field
- * entries — the engine takes typed {@link InitialFieldValue}s, and a value's
- * type IS its declared entry's kind. Only `input`-sourced entries read
- * caller values (the engine silently ignores the rest), so anything else
- * fails here, naming the fields that ARE settable; value validation stays
- * in the engine.
- */
-export declare function buildInitialFields({ declared, values, }: {
-    declared: Pick<FieldEntry, 'type' | 'name' | 'initialValue'>[];
-    values: Record<string, unknown>;
-}): InitialFieldValue[];
 /**
  * The shared engine args ({@link baseEngineArgs}) plus the start-specific
  * fields. Optionals spread conditionally because the engine's optional args

package/dist/commands/start.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { isStartableDefinition, workflow, } from '@sanity/workflow-engine';
+import { buildInitialFields, startRefusal, workflow, } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveContext } from "../lib/context.js";
 import { fetchDeployedDefinition } from "../lib/definitions.js";
@@ -82,31 +82,6 @@ async function resolveStartInputs({ client, name, tag, version, values, }) {
     }
     return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
 }
-export function startRefusal(definition) {
-    if (isStartableDefinition(definition)) {
-        return undefined;
-    }
-    return "definition is spawn-only (lifecycle: 'child') — instances of it are spawned by a parent workflow's activity, not started standalone";
-}
-export function buildInitialFields({ declared, values, }) {
-    const settable = declared.filter((f) => f.initialValue?.type === 'input');
-    const settableNames = settable.map((f) => f.name).join(', ');
-    return Object.entries(values).map(([name, value]) => {
-        const entry = declared.find((f) => f.name === name);
-        if (entry === undefined) {
-            throw new Error(settable.length > 0
-                ? `workflow declares no field "${name}" — input fields: ${settableNames}`
-                : `workflow declares no field "${name}" — it declares no input fields at all`);
-        }
-        if (entry.initialValue?.type !== 'input') {
-            throw new Error(`field "${name}" is not input-sourced — the engine would silently ignore the value. ` +
-                (settable.length > 0
-                    ? `Input fields: ${settableNames}`
-                    : 'This workflow has no input fields.'));
-        }
-        return { type: entry.type, name, value };
-    });
-}
 export function buildStartArgs({ scope, name, version, initialFields, }) {
     return {
         ...baseEngineArgs(scope),