@sanity/workflow-cli 0.14.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @sanity/workflow-cli
 
+## 0.21.0
+
+### Minor Changes
+
+- 9273d55: List the nested `definition` commands (`list`, `show`, `diff`, `delete`) in the
+  standalone binary's flat `--help` output. A custom oclif help class surfaces the
+  bare `definition <verb>` aliases at the root instead of burying them under the
+  `editorial-workflows` topic, so `sanity-workflows --help` shows every command
+  without topic-digging. `help --all` still prints the full canonical tree.
+- e7392af: Add the `resetActivity` admin verb — reset a failed (or otherwise terminal) activity in an instance's current stage back to `active` (re-run) or `skipped` (bypass), then cascade so a `$allActivitiesDone`-gated exit transition can fire. `workflow.diagnose` now marks its `reset-activity` remediation `available`, and the CLI ships the real `reset-activity <instanceId> <activity> [--skip]` command in place of the stub. Emits the `Editorial Workflows Activity Reset` adoption event on every attempt (`changed: false` on a no-op), matching the `set-stage` and `abort` overrides.
+
+  Writes strictly within the existing model-3 grammar: it reuses the `activityStatusChanged` history variant and the existing activity statuses, so it adds no persisted shape — there is no data-model version bump and no reader-floor change.
+
+### Patch Changes
+
+- b248789: CLI error detail lines now render in the terminal's default colour instead of red. The red headline with its `✖` still signals the failure; the detail beneath it (validation output, auth hints, wrapped errors) is the information the user has to read, and long runs of red text were hard to read.
+- f4bc057: **BREAKING:** `list_workflow_instances` now returns one page with `has_more` and an optional `next_cursor`; callers that need every match must continue with the cursor. The optional `limit` accepts 1–100 rows and defaults to 25.
+
+  Bound instance and definition list reads with lake-side filtering and consumer-specific projections.
+
+  Document filtering now excludes exited-stage references and includes live unresolved child-workflow references. Definition discovery selects and model-gates only the latest deployed version of each workflow name; historical versions remain stored and available to history-oriented APIs.
+
+  The MCP eval suite now verifies that agents follow list cursors to find a target beyond the first default page, including in persisted Braintrust runs.
+
+  MCP tool telemetry reports a `cursorUsed` boolean so continued list-page adoption is measurable without sending cursor values, arguments, or results.
+
+- Updated dependencies [d9394e5]
+- Updated dependencies [92e28bd]
+- Updated dependencies [f4bc057]
+- Updated dependencies [bcc30fe]
+- Updated dependencies [e7392af]
+- Updated dependencies [fa9c796]
+  - @sanity/workflow-engine@0.21.0
+
+## 0.20.0
+
+### Minor Changes
+
+- 6e2a066: Ambiguous deployment/resource selection now prompts on an interactive terminal instead of only erroring. When a config has several deployments and no selector is given, `start`, `definition diff`, and `definition delete` show the same deployment picker `deploy` already offered. The instance-targeted commands (`abort`, `set-stage`, `fire-action`, `diagnose`) show that picker too when the config spans several resources — the interactive counterpart to their `--deployment` selector, reading from the chosen deployment's resource. Non-interactive runs (CI, piped output) keep the existing errors asking for `--deployment`/`--tag`, and `nuke` still requires an explicit selector — for a destructive command, naming exactly what is swept is the right friction.
+- 7c4dd86: Reduce guard lifecycle request volume and chunk orphan cleanup transactions.
+- e860898: **BREAKING:** Published Editorial Workflows packages now ship as one fixed release stack and require exact-version peers for every shared runtime package. Install the matching stack so the engine, reactive core, adapters, tools, and UI cannot silently load private or version-skewed copies.
+
+### Patch Changes
+
+- efb4cd9: Error detail below the ✖ headline is no longer dimmed. Validation output, auth hints, and errors caught by command wrappers now render in legible red so the information users need to act on remains readable.
+- Updated dependencies [bce09fc]
+- Updated dependencies [efb4cd9]
+- Updated dependencies [46b0285]
+- Updated dependencies [ab5e454]
+- Updated dependencies [8a76c67]
+- Updated dependencies [e3122cc]
+- Updated dependencies [7e8f459]
+- Updated dependencies [98e488e]
+- Updated dependencies [7c4dd86]
+  - @sanity/workflow-engine@0.20.0
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -60,7 +60,7 @@ import {articleReview, urlDraft} from './src/workflows.ts'
 export default defineWorkflowConfig({
   deployments: [
     {
-      expectedMinReaderModel: 2,
+      expectedMinReaderModel: 4,
       name: 'production', // the deployment's unique identity (lowercase letters, digits, dashes)
       tag: 'prod', // the environment partition the engine's docs are scoped to
       workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
@@ -87,9 +87,12 @@ Pick a deployment with `--deployment <name>`; with a single deployment configure
 can omit it. `--tag <tag>` also works on single-deployment commands while the
 tag names exactly one deployment — on `deploy` it targets every deployment
 carrying the tag (a tag is an environment group). With several configured, a
-bare interactive `deploy` presents a keyboard-driven deployment selector (by
-name, tag alongside). In CI or another non-interactive shell, it fails asking
-for `--deployment`, `--tag`, or `--all-tags` instead of blocking for input.
+bare interactive run presents a keyboard-driven deployment selector (by name,
+tag alongside) — on `deploy`, `start`, and `definition diff`/`delete`, and on
+the instance-targeted commands (`abort`, `set-stage`, `reset-activity`,
+`fire-action`, `diagnose`) when the config spans several resources. In CI or another
+non-interactive shell, the command fails asking for `--deployment` or `--tag`
+(`deploy` also suggests `--all-tags`) instead of blocking for input.
 `--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
@@ -167,6 +170,7 @@ stale compiled output.
 | `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, removes guards)                                                                                                                                                                                                                                                           |
 | `set-stage <instance-id> --to <stage>`          | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run)                                                                                                                                                                                                                           |
+| `reset-activity <instance-id> <activity>`       | wired — calls `workflow.resetActivity` (recovery override: reset a failed activity to `active`, or `--skip` to bypass it; then cascade)                                                                                                                                                                                                               |
 | `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`                                                                                                                                                                                                                                                                                             |

package/dist/commands/editorial-workflows/list.d.ts

@@ -1,4 +1,4 @@
-import { type TerminalState } from '@sanity/workflow-engine';
+import { type GdrUri, type TerminalState } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 interface InstanceRow {
     _id: string;
@@ -19,17 +19,19 @@ interface ListFlags {
     tag?: string | undefined;
     limit: number;
 }
+interface ListQueryClient {
+    fetch<T>(groq: string, params: Record<string, unknown>, options: {
+        tag: string;
+    }): Promise<T>;
+}
 /**
  * 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.
+ * With `--document` the lake filter is the engine's exact watch-set arm. The
+ * projection keeps its ref-bearing fields for a defensive JS recheck while
+ * omitting the instance's unbounded ledgers and definition snapshot.
  */
 export declare function buildListQuery(flags: ListFlags): {
     groq: string;
@@ -58,4 +60,15 @@ export default class List extends WorkflowCommand {
     };
     run(): Promise<void>;
 }
+/** Fetch one target's projected rows, defensively rechecking document refs. */
+export declare function fetchRows({ client, groq, params, document, limit, }: {
+    client: ListQueryClient;
+    groq: string;
+    params: Record<string, unknown>;
+    document: GdrUri | undefined;
+    limit: number;
+}): Promise<{
+    rows: InstanceRow[];
+    hasMore: boolean;
+}>;
 export {};

package/dist/commands/editorial-workflows/list.js

@@ -7,6 +7,23 @@ import { failOnThrow } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
 import { runReadAcrossTargets } from "../../lib/read-fanout.js";
 import { formatAge, logClippedTable } from "../../lib/ui.js";
+const DOCUMENT_LIST_PROJECTION = `{
+  _type,
+  _id,
+  workflowResource,
+  modelVersion,
+  minReaderModel,
+  definition,
+  tag,
+  currentStage,
+  fields,
+  stages,
+  ancestors,
+  subworkflows,
+  completedAt,
+  abortedAt,
+  lastChangedAt
+}`;
 export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
     const params = {};
@@ -26,7 +43,11 @@ export function buildListQuery(flags) {
         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;
+        return {
+            groq: `*[${filters.join(' && ')}] | order(lastChangedAt desc)[0...$limit]${DOCUMENT_LIST_PROJECTION}`,
+            params,
+        };
     }
     params['limit'] = flags.limit + 1;
     const groq = `*[${filters.join(' && ')}] | order(lastChangedAt desc) [0...$limit]{
@@ -96,14 +117,20 @@ export default class List extends WorkflowCommand {
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = await fetchRows({ client, groq, params, document });
-                if (fetched.length === 0) {
-                    this.log(`${logSymbols.info} no instances match`);
+                const fetched = await fetchRows({ client, groq, params, document, limit: flags.limit });
+                if (fetched.rows.length === 0) {
+                    if (fetched.hasMore) {
+                        this.log(`${logSymbols.info} no matches in the first ${flags.limit} candidates — raise --limit to search further`);
+                    }
+                    else {
+                        this.log(`${logSymbols.info} no instances match`);
+                    }
                     return;
                 }
                 logClippedTable({
-                    rows: fetched,
+                    rows: fetched.rows,
                     limit: flags.limit,
+                    moreAvailable: fetched.hasMore,
                     headers: ['instance', 'workflow', 'tag', 'stage', 'status', 'updated'],
                     toCells: (r) => {
                         const row = instanceRow(r);
@@ -125,13 +152,16 @@ export default class List extends WorkflowCommand {
         }
     }
 }
-async function fetchRows({ client, groq, params, document, }) {
+export async function fetchRows({ client, groq, params, document, limit, }) {
     if (document === undefined) {
         const rows = await client.fetch(groq, params, { tag: 'list' });
-        return rows.map(assertReadableModel);
+        return { rows: rows.map(assertReadableModel), hasMore: rows.length > limit };
     }
     const candidates = await client.fetch(groq, params, { tag: 'list' });
-    return candidates
-        .map(assertReadableModel)
-        .filter((instance) => instanceWatchesDocument(instance, document));
+    return {
+        rows: candidates
+            .map(assertReadableModel)
+            .filter((instance) => instanceWatchesDocument(instance, document)),
+        hasMore: candidates.length > limit,
+    };
 }

package/dist/commands/editorial-workflows/nuke.js

@@ -39,7 +39,7 @@ export default class Nuke extends WorkflowCommand {
     async run() {
         const { flags } = await this.parse(Nuke);
         const config = await loadWorkflowConfig();
-        const deployment = selectDeployment(config, { name: flags.deployment, tag: flags.tag });
+        const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
         refuseOverlappingNuke(config.deployments, deployment);
         const targets = buildTargets(deployment, await resolveTokenOrFail());
         const plan = await resolveNukePlan({ tag: deployment.tag, targets });

package/dist/commands/editorial-workflows/reset-activity.d.ts

@@ -1,10 +1,31 @@
-import { StubCommand } from '../../lib/stub.ts';
-export default class ResetActivity extends StubCommand {
-    static hiddenAliases: string[];
-    static hidden: boolean;
+import { type ResetActivityTarget, type WorkflowInstance } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
+import { type WriteOutcome, type WriteReport } from '../../lib/ops-report.ts';
+export default class ResetActivity extends WorkflowCommand {
+    static aliases: string[];
     static description: string;
+    static examples: string[];
     static args: {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
         activity: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
+    static flags: {
+        skip: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/** {@link WriteOutcome} with the terminal stamp the no-op copy reads. */
+interface ResetActivityOutcome extends WriteOutcome {
+    instance: Pick<WorkflowInstance, 'currentStage' | 'completedAt'>;
 }
+/**
+ * Turn a `resetActivity` result into the spinner message. Pure so the
+ * skipped / re-run / already-at-target / terminal / cascaded permutations can
+ * be asserted without driving a real reset.
+ */
+export declare function resetActivityReport(result: ResetActivityOutcome, { activity, to }: {
+    activity: string;
+    to: ResetActivityTarget;
+}): WriteReport;
+export {};

package/dist/commands/editorial-workflows/reset-activity.js

@@ -1,11 +1,61 @@
-import { Args } from '@oclif/core';
-import { StubCommand } from "../../lib/stub.js";
-export default class ResetActivity extends StubCommand {
-    static hiddenAliases = ['reset-activity'];
-    static hidden = true;
-    static description = 'Reset a failed activity on an in-flight instance — back to pending (re-run) or to skipped (bypass).';
+import { styleText } from 'node:util';
+import { Args, Flags } from '@oclif/core';
+import { workflow } from '@sanity/workflow-engine';
+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";
+import { cascadeTail, runWriteVerb, } from "../../lib/ops-report.js";
+export default class ResetActivity extends WorkflowCommand {
+    static aliases = ['reset-activity'];
+    static description = 'Reset a failed activity on an in-flight instance — back to active to re-run it, or --skip to bypass it (mark it skipped) so a gated exit transition can fire.';
+    static examples = [
+        '<%= config.bin %> reset-activity wf-instance.abc123 legal-review',
+        '<%= config.bin %> reset-activity wf-instance.abc123 legal-review --skip',
+    ];
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
         activity: Args.string({ required: true, description: 'Activity name within the current stage.' }),
     };
+    static flags = {
+        ...tagFlags,
+        skip: Flags.boolean({
+            default: false,
+            description: 'Bypass the activity (mark it skipped) instead of re-running it (back to active).',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ResetActivity);
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
+        const to = flags.skip ? 'skipped' : 'active';
+        await runWriteVerb({
+            startLabel: `Resetting ${args.activity} on ${args.instanceId}…`,
+            failLabel: 'Reset rejected',
+            failHeadline: 'reset-activity error:',
+            run: () => workflow.resetActivity({
+                client,
+                ...buildOperationArgs({ scope, instanceId: args.instanceId, reason: undefined }),
+                activity: args.activity,
+                to,
+            }),
+            report: (result) => resetActivityReport(result, { activity: args.activity, to }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+export function resetActivityReport(result, { activity, to }) {
+    const name = styleText('bold', activity);
+    if (!result.changed) {
+        const { completedAt } = result.instance;
+        const message = completedAt !== undefined
+            ? `reset-activity changed nothing — instance is terminal (since ${completedAt})`
+            : `reset-activity changed nothing — ${name} is already ${to}`;
+        return { changed: false, message };
+    }
+    const stage = styleText('bold', result.instance.currentStage);
+    const verb = to === 'skipped' ? 'Skipped' : 'Reset';
+    return {
+        changed: true,
+        message: `${verb} ${name} — now at ${stage}${cascadeTail(result.cascaded)}`,
+    };
 }

package/dist/help.d.ts

@@ -0,0 +1,8 @@
+import { Help } from '@oclif/core';
+export declare const isBareSurface: (idOrName: string) => boolean;
+export declare const keepCommandAtRoot: (id: string) => boolean;
+/** Standalone-binary help that lists the nested `definition` commands flat in
+ *  `--help` rather than under a topic. A mounted host governs its own root help. */
+export default class WorkflowHelp extends Help {
+    protected showRootHelp(): Promise<void>;
+}

package/dist/help.js

@@ -0,0 +1,23 @@
+import { Help } from '@oclif/core';
+export const isBareSurface = (idOrName) => !idOrName.startsWith('editorial-workflows');
+export const keepCommandAtRoot = (id) => id !== '' && isBareSurface(id);
+export default class WorkflowHelp extends Help {
+    async showRootHelp() {
+        if (this.opts.all) {
+            await super.showRootHelp();
+            return;
+        }
+        this.log(this.formatRoot());
+        this.log('');
+        const topics = this.sortedTopics.filter((topic) => isBareSurface(topic.name));
+        if (topics.length > 0) {
+            this.log(this.formatTopics(topics));
+            this.log('');
+        }
+        const commands = this.sortedCommands.filter((command) => keepCommandAtRoot(command.id));
+        if (commands.length > 0) {
+            this.log(this.formatCommands(commands));
+            this.log('');
+        }
+    }
+}

package/dist/lib/context.d.ts

@@ -1,6 +1,7 @@
 import type { SanityClient } from '@sanity/client';
 import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import type { EngineScope } from './operation-args.ts';
+import { type ChooseDeploymentName } from './select-deployment.ts';
 export interface DeploymentContext {
     deployment: WorkflowDeployment;
     client: SanityClient;
@@ -50,10 +51,11 @@ export declare function dedupeResources(resources: WorkflowResource[]): Workflow
  *  tag (tags may repeat across deployments), or — untagged — every distinct
  *  one the config's deployments mention ({@link dedupeResources}). */
 export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
-/** The single resource a read should target, or fail asking which when the
- *  config spans more than one. For the paths that need one definite dataset
- *  (the instance-targeted verbs); listings fan out via
- *  {@link resolveReadResources} instead. */
+/** The single resource an instance-keyed command reads from when it isn't
+ *  disambiguated interactively: the sole resource, the `--tag`-narrowed one, or
+ *  a `fail` asking for `--deployment`/`--tag` when the config spans several. The
+ *  interactive picker lives in {@link resolveInstanceResource}; listings fan out
+ *  via {@link resolveReadResources} instead. */
 export declare function resolveReadResource(config: WorkflowConfig, tag: string | undefined): WorkflowResource;
 /**
  * The resolution an instance-id-targeted command shares, read or write: an
@@ -74,16 +76,22 @@ export declare function resolveInstanceContext(flags: {
 }, instanceId: string): Promise<InstanceContext>;
 /**
  * Which resource an instance-keyed command reads from: the one `--deployment`
- * names (resolved by its unique deployment name), else the sole or
- * `--tag`-narrowed resource ({@link resolveReadResource}). The instance id is
- * globally unique, so this only locates the resource to look in — never the
- * instance's `tag` partition, which the caller takes from the loaded instance.
- * The shared path behind all four instance-keyed commands.
+ * names (resolved by its unique deployment name); otherwise, when the config
+ * spans several resources, an interactive terminal is prompted to pick a
+ * deployment ({@link canPromptOnStderr}) — its resource is the read source, the
+ * interactive counterpart to `--deployment`. A run that can't prompt falls to
+ * the sole or `--tag`-narrowed resource, or the ambiguity error
+ * ({@link resolveReadResource}). The instance id is globally unique, so this
+ * only locates the resource to look in — never the instance's `tag` partition,
+ * which the caller takes from the loaded instance. The shared path behind all
+ * four instance-keyed commands.
  */
-export declare function resolveInstanceResource(config: WorkflowConfig, { deployment, tag }: {
+export declare function resolveInstanceResource(config: WorkflowConfig, { deployment, tag, interactive, chooseDeployment, }: {
     deployment?: string | undefined;
     tag?: string | undefined;
-}): WorkflowResource;
+    interactive?: boolean | undefined;
+    chooseDeployment?: ChooseDeploymentName | undefined;
+}): Promise<WorkflowResource>;
 /** Fetch an instance by id, exiting cleanly when the resource has no such
  *  document — the diagnostic an operator sees on a mistyped id. Split out from
  *  {@link resolveInstanceContext} so the not-found path is unit-testable

package/dist/lib/context.js

@@ -2,11 +2,12 @@ import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
-import { availableDeployments, deploymentsForTag, selectDeployment } from "./select-deployment.js";
+import { canPromptOnStderr } from "./prompt.js";
+import { availableDeployments, deploymentsForTag, selectDeployment, } from "./select-deployment.js";
 import { resourceLabel } from "./ui.js";
 export async function resolveContext(flags) {
     const config = await loadWorkflowConfig();
-    const deployment = selectDeployment(config, { name: flags.deployment, tag: flags.tag });
+    const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
     return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
 }
 export async function resolveReadTargets(flags) {
@@ -42,14 +43,25 @@ export function resolveReadResource(config, tag) {
 }
 export async function resolveInstanceContext(flags, instanceId) {
     const config = await loadWorkflowConfig();
-    const workflowResource = resolveInstanceResource(config, flags);
+    const workflowResource = await resolveInstanceResource(config, flags);
     const client = clientFor(workflowResource, await resolveTokenOrFail());
     const instance = await loadInstanceOrFail(client, instanceId);
     return { client, scope: { tag: instance.tag, workflowResource } };
 }
-export function resolveInstanceResource(config, { deployment, tag }) {
+export async function resolveInstanceResource(config, { deployment, tag, interactive, chooseDeployment, }) {
     if (deployment !== undefined) {
-        return selectDeployment(config, { name: deployment, tag: undefined }).workflowResource;
+        return (await selectDeployment(config, { name: deployment, tag: undefined })).workflowResource;
+    }
+    if (tag === undefined &&
+        (interactive ?? canPromptOnStderr()) &&
+        resolveReadResources(config, undefined).length > 1) {
+        const chosen = await selectDeployment(config, {
+            name: undefined,
+            tag: undefined,
+            interactive: true,
+            chooseName: chooseDeployment,
+        });
+        return chosen.workflowResource;
     }
     return resolveReadResource(config, tag);
 }

package/dist/lib/fail.js

@@ -8,7 +8,7 @@ export function fail(headline, detail) {
     process.stderr.write(`${styleText('red', `${logSymbols.error} ${headline}`)}\n`);
     if (detail !== undefined && detail !== '') {
         for (const line of detail.split('\n')) {
-            process.stderr.write(`  ${styleText(['dim', 'red'], line)}\n`);
+            process.stderr.write(`  ${line}\n`);
         }
     }
     return Errors.exit(1);

package/dist/lib/nuke.d.ts

@@ -59,19 +59,6 @@ export declare function resolveNukePlan(args: {
     tag: string;
     targets: NukeTarget[];
 }): Promise<NukePlan>;
-/**
- * Does a guard doc belong to `tag`? A guard's `sourceInstanceId` is the id of
- * the instance that registered it (`<tag>.wf-instance.<random>`), and its own
- * `_id` embeds that same instance id
- * (`temp.system.guard.<tag>.wf-instance.<random>.<name>`). Matching on either —
- * with the trailing `.` so `prod` never matches `prod-eu` — catches guards
- * whose `sourceInstanceId` was never written as well as guards whose instance
- * is already gone.
- */
-export declare function guardMatchesTag(guard: {
-    _id: string;
-    sourceInstanceId?: string;
-}, tag: string): boolean;
 /** The `project.dataset` labels of resources the plan actually deletes from —
  *  the exact set the operator must type back to confirm. A resource with
  *  nothing to delete is not "involved" and is omitted. */

package/dist/lib/nuke.js

@@ -52,14 +52,12 @@ function engineDocIds(args) {
     return args.client.fetch(`*[_type == $type && ${tagScopeFilter()}]._id`, { type: args.type, tag: args.tag }, { perspective: 'raw', tag: REQUEST_TAG });
 }
 async function tagGuardIds(args) {
-    const guards = await args.client.fetch(`*[_type == $type]{_id, sourceInstanceId}`, { type: GUARD_DOC_TYPE }, { perspective: 'raw', tag: REQUEST_TAG });
-    return guards.filter((guard) => guardMatchesTag(guard, args.tag)).map((guard) => guard._id);
-}
-export function guardMatchesTag(guard, tag) {
-    const instancePrefix = `${tag}.wf-instance.`;
+    const instancePrefix = `${args.tag}.wf-instance.`;
     const guardIdPrefix = `${GUARD_DOC_TYPE}.${instancePrefix}`;
-    return ((guard.sourceInstanceId?.startsWith(instancePrefix) ?? false) ||
-        guard._id.startsWith(guardIdPrefix));
+    return args.client.fetch(`*[_type == $type && (
+      string::startsWith(sourceInstanceId, $instancePrefix) ||
+      string::startsWith(_id, $guardIdPrefix)
+    )]._id`, { type: GUARD_DOC_TYPE, instancePrefix, guardIdPrefix }, { perspective: 'raw', tag: REQUEST_TAG });
 }
 export function involvedTargets(plan) {
     return plan.resources

package/dist/lib/prompt.d.ts

@@ -9,3 +9,17 @@
  * prompts such as nuke's confirmation.
  */
 export declare function canPromptOnStderr(): boolean;
+/**
+ * Ask a `select` question on stderr — the channel this package renders prompts
+ * on so a redirected stdout can't swallow the question (the display side of the
+ * {@link canPromptOnStderr} gate). The single site that routes a `select` to
+ * stderr, so no `select` prompt can silently regress to stdout.
+ */
+export declare function selectOnStderr(config: {
+    message: string;
+    choices: readonly {
+        name: string;
+        value: string;
+        description?: string;
+    }[];
+}): Promise<string>;

package/dist/lib/prompt.js

@@ -1,4 +1,8 @@
 import { isInteractive } from '@sanity/cli-core';
+import { select } from '@sanity/cli-core/ux';
 export function canPromptOnStderr() {
     return isInteractive() && process.stderr.isTTY === true;
 }
+export function selectOnStderr(config) {
+    return select(config, { output: process.stderr });
+}

package/dist/lib/select-deployment.d.ts

@@ -1,5 +1,5 @@
 import { type DeployTarget, type WorkflowConfig, type WorkflowDeployment } from '@sanity/workflow-engine';
-type ChooseDeploymentName = (deployments: WorkflowDeployment[]) => Promise<string>;
+export type ChooseDeploymentName = (deployments: WorkflowDeployment[]) => Promise<string>;
 interface DeploymentSelectionOptions {
     name: string | undefined;
     tag: string | undefined;
@@ -19,17 +19,20 @@ export declare function deploymentLabel({ name, tag }: Pick<WorkflowDeployment,
  * so `--deployment` can disambiguate.
  *
  * With no selector: fall back to the sole deployment when there's exactly one
- * (the common single-environment case), otherwise fail asking for
- * `--deployment` or `--tag` — a multi-deployment config is ambiguous without
- * one. `orAlternative`
- * extends that ambiguity message for callers with another way out (deploy's
+ * (the common single-environment case). When several are configured, an
+ * interactive terminal is prompted to pick one ({@link canPromptOnStderr}); a
+ * run that cannot prompt fails asking for `--deployment` or `--tag` — a
+ * multi-deployment config is ambiguous without one. `orAlternative` extends
+ * that ambiguity message for callers with another way out (deploy's
  * `--all-tags`).
  */
-export declare function selectDeployment(config: WorkflowConfig, { name, tag, orAlternative, }: {
+export declare function selectDeployment(config: WorkflowConfig, { name, tag, orAlternative, interactive, chooseName, }: {
     name: string | undefined;
     tag: string | undefined;
     orAlternative?: string;
-}): WorkflowDeployment;
+    interactive?: boolean | undefined;
+    chooseName?: ChooseDeploymentName | undefined;
+}): Promise<WorkflowDeployment>;
 /**
  * Every deployment carrying `tag`, failing when the tag matches none — the
  * shared resolution for the callers that accept a whole tag group (deploy's

package/dist/lib/select-deployment.js

@@ -1,11 +1,10 @@
-import { select } from '@sanity/cli-core/ux';
 import { resourceAliasesToMap, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
-import { canPromptOnStderr } from "./prompt.js";
+import { canPromptOnStderr, selectOnStderr } from "./prompt.js";
 export function deploymentLabel({ name, tag }) {
     return `${name} (${tag})`;
 }
-export function selectDeployment(config, { name, tag, orAlternative = '', }) {
+export async function selectDeployment(config, { name, tag, orAlternative = '', interactive, chooseName = chooseDeploymentName, }) {
     if (name !== undefined) {
         const deployment = config.deployments.find((candidate) => candidate.name === name);
         if (deployment === undefined) {
@@ -21,7 +20,14 @@ export function selectDeployment(config, { name, tag, orAlternative = '', }) {
         }
         return sole;
     }
+    return selectDefaultDeployment(config, { orAlternative, interactive, chooseName });
+}
+async function selectDefaultDeployment(config, { orAlternative, interactive, chooseName, }) {
     if (config.deployments.length > 1) {
+        if (interactive ?? canPromptOnStderr()) {
+            const selectedName = await chooseName(config.deployments);
+            return selectDeployment(config, { name: selectedName, tag: undefined });
+        }
         fail(`Multiple deployments configured — pass --deployment or --tag${orAlternative}.`, availableDeployments(config));
     }
     const [sole] = config.deployments;
@@ -37,43 +43,28 @@ export function deploymentsForTag(config, tag) {
     }
     return matches;
 }
-export async function selectDeployments(config, { name, tag, allTags, interactive, chooseName = chooseDeploymentName }) {
+export async function selectDeployments(config, { name, tag, allTags, interactive, chooseName }) {
     if (allTags) {
         return config.deployments;
     }
     if (tag !== undefined) {
         return deploymentsForTag(config, tag);
     }
-    if (name === undefined && config.deployments.length > 1) {
-        if (!(interactive ?? canPromptOnStderr())) {
-            return [
-                selectDeployment(config, {
-                    name,
-                    tag,
-                    orAlternative: ', or --all-tags to deploy every deployment',
-                }),
-            ];
-        }
-        const selectedName = await chooseName(config.deployments);
-        return [selectDeployment(config, { name: selectedName, tag: undefined })];
-    }
     return [
-        selectDeployment(config, {
+        await selectDeployment(config, {
             name,
             tag,
             orAlternative: ', or --all-tags to deploy every deployment',
+            interactive,
+            chooseName,
         }),
     ];
 }
 async function chooseDeploymentName(deployments) {
-    return select({
+    return selectOnStderr({
         message: 'Select a deployment',
-        choices: deployments.map(({ name, tag }) => ({
-            name,
-            value: name,
-            description: `tag: ${tag}`,
-        })),
-    }, { output: process.stderr });
+        choices: deployments.map(({ name, tag }) => ({ name, value: name, description: `tag: ${tag}` })),
+    });
 }
 export function availableDeployments(config, deployments = config.deployments) {
     return `Available deployments: ${deployments.map(deploymentLabel).join(', ')}`;

package/dist/lib/ui.d.ts

@@ -37,9 +37,10 @@ export declare function clipToLimit<T>(rows: T[], limit: number): {
  * rows, render them through {@link formatTable}, print every line, and print
  * the clip note (when present) beneath the table.
  */
-export declare function logClippedTable<T>({ rows, limit, headers, toCells, log, }: {
+export declare function logClippedTable<T>({ rows, limit, moreAvailable, headers, toCells, log, }: {
     rows: T[];
     limit: number;
+    moreAvailable?: boolean;
     headers: string[];
     toCells: (row: T) => string[];
     log: (line: string) => void;

package/dist/lib/ui.js

@@ -31,13 +31,14 @@ export function clipToLimit(rows, limit) {
         note: styleText('dim', `showing the first ${limit} — raise --limit to see more`),
     };
 }
-export function logClippedTable({ rows, limit, headers, toCells, log, }) {
+export function logClippedTable({ rows, limit, moreAvailable, headers, toCells, log, }) {
     const { rows: clipped, note } = clipToLimit(rows, limit);
     for (const line of formatTable(headers, clipped.map(toCells))) {
         log(line);
     }
-    if (note) {
-        log(note);
+    if (note || moreAvailable) {
+        log(note ??
+            styleText('dim', `searched the first ${limit} candidates — raise --limit to see more`));
     }
 }
 export function groupBanner({ label, index, total, }) {

package/oclif.manifest.json

@@ -408,7 +408,9 @@
       ]
     },
     "editorial-workflows:reset-activity": {
-      "aliases": [],
+      "aliases": [
+        "reset-activity"
+      ],
       "args": {
         "instanceId": {
           "description": "Workflow instance id.",
@@ -421,13 +423,28 @@
           "required": true
         }
       },
-      "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": [
-        "reset-activity"
+      "description": "Reset a failed activity on an in-flight instance — back to active to re-run it, or --skip to bypass it (mark it skipped) so a gated exit transition can fire.",
+      "examples": [
+        "<%= config.bin %> reset-activity wf-instance.abc123 legal-review",
+        "<%= config.bin %> reset-activity wf-instance.abc123 legal-review --skip"
       ],
+      "flags": {
+        "tag": {
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
+          "name": "tag",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "skip": {
+          "description": "Bypass the activity (mark it skipped) instead of re-running it (back to active).",
+          "name": "skip",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
       "id": "editorial-workflows:reset-activity",
       "pluginAlias": "@sanity/workflow-cli",
       "pluginName": "@sanity/workflow-cli",
@@ -913,5 +930,5 @@
       ]
     }
   },
-  "version": "0.14.0"
+  "version": "0.21.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.14.0",
+  "version": "0.21.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -55,21 +55,25 @@
     "diff": "^9.0.0",
     "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
-    "ora": "^9.4.0",
-    "@sanity/workflow-engine": "0.19.0"
+    "ora": "^9.4.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.13.1",
-    "@sanity/workflow-examples": "0.8.1"
+    "@sanity/workflow-engine": "0.21.0",
+    "@sanity/workflow-engine-test": "0.21.0",
+    "@sanity/workflow-examples": "0.10.0"
+  },
+  "peerDependencies": {
+    "@sanity/workflow-engine": "0.21.0"
   },
   "oclif": {
     "bin": "sanity-workflows",
     "commands": "./dist/commands",
     "dirname": "sanity-workflows",
+    "helpClass": "./dist/help",
     "hooks": {
       "finally": "./dist/hooks/finally/telemetry",
       "prerun": "./dist/hooks/prerun/telemetry"