@sanity/workflow-cli 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @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

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
@@ -89,8 +89,8 @@ 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 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`, `fire-action`,
-`diagnose`) when the config spans several resources. In CI or another
+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
@@ -170,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/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/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('red', line)}\n`);
+            process.stderr.write(`  ${line}\n`);
         }
     }
     return Errors.exit(1);

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.20.0"
+  "version": "0.21.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -62,17 +62,18 @@
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.20.0",
-    "@sanity/workflow-engine-test": "0.20.0",
-    "@sanity/workflow-examples": "0.9.0"
+    "@sanity/workflow-engine": "0.21.0",
+    "@sanity/workflow-engine-test": "0.21.0",
+    "@sanity/workflow-examples": "0.10.0"
   },
   "peerDependencies": {
-    "@sanity/workflow-engine": "0.20.0"
+    "@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"