@sanity/workflow-cli 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @sanity/workflow-cli
 
+## 0.22.0
+
+### Minor Changes
+
+- 1c6d4c0: Name the target deployment and resource on `deploy` progress and result lines. The spinner and completion line now read `Deploying N definition(s) to <name> (<tag>) → <resource>…` / `Processed N definition(s) · <name> (<tag>) → <resource>` (and the dry-run equivalents), so a single-deployment run — the common case, which prints no per-batch banner — always shows where the deploy landed.
+- fb42001: The instance-keyed commands — `diagnose`, `fire-action`, `set-stage`, `abort`, `reset-activity` — now locate an instance by fanning out across every configured resource, the same way `show` and the other read commands already do. Passing an instance id is enough: on a config that spans several resources they no longer prompt for (or require) a `--deployment` / `--tag` selector — those stay as optional narrowers. As an optimization, an id carrying the engine's default `<tag>.` mint prefix probes that tag's resource first and skips the fan-out on a hit. `reset-activity` also gains the `--deployment` narrower its siblings already had.
+- 84ff807: The read commands — `list`, `show`, `definition list`, `definition show` — now take `--json`, emitting structured output on stdout for parity with the verb commands. `show` and `definition show` print the fetched document as stored; `list` and `definition list` print their table's row view (each row annotated with the `resource` it came from) under a `truncated` flag. A JSON read spanning several resources is all-or-nothing: an unreadable resource fails the whole command rather than emitting a partial listing a script would mistake for the complete result.
+
+### Patch Changes
+
+- a8c460c: Colour the whole terminal-status row in the instance header — aborted rows render bold yellow, completed rows bold green — so a finished instance stands out from the neutral detail rows instead of only its timestamp carrying colour.
+- Updated dependencies [88ba4ba]
+  - @sanity/workflow-engine@0.22.0
+
+## 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/definition/list.d.ts

@@ -26,10 +26,26 @@ export default class DefinitionList extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }
+/** Map a queried definition to its display row. Drops the stamp pair (gate
+ *  plumbing, not view data) and `_id` — `tag.name.vN`, which just repeats
+ *  name + tag + version, and no command takes an `_id` anyway (they take
+ *  name + --tag/--version); `name vN` is this CLI's identifier format (the
+ *  `definition show` title). */
+export declare function definitionRow(r: DefinitionListRow): {
+    name: string;
+    version: number;
+    title: string;
+    tag: string;
+    stageCount: number;
+    inFlightCount: number;
+    totalInstances: number;
+    _createdAt: string;
+};
 export {};

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

@@ -3,8 +3,8 @@ import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, assertReadableModel,
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../../lib/base-command.js";
 import { resolveReadTargets } from "../../../lib/context.js";
-import { tagFlags } from "../../../lib/flags.js";
-import { runReadAcrossTargets } from "../../../lib/read-fanout.js";
+import { jsonFlags, tagFlags } from "../../../lib/flags.js";
+import { logJsonListing, runReadAcrossTargets } from "../../../lib/read-fanout.js";
 import { logClippedTable } from "../../../lib/ui.js";
 export function buildDefinitionListQuery(flags) {
     const params = { limit: flags.limit + 1 };
@@ -45,6 +45,7 @@ export default class DefinitionList extends WorkflowCommand {
     static examples = [
         '<%= config.bin %> definition list',
         '<%= config.bin %> definition list --tag prod',
+        '<%= config.bin %> definition list --json',
     ];
     static flags = {
         ...tagFlags,
@@ -55,35 +56,48 @@ export default class DefinitionList extends WorkflowCommand {
         name: Flags.string({
             description: 'Filter to a single workflow definition name (e.g. product-launch).',
         }),
+        ...jsonFlags,
     };
     async run() {
         const { flags } = await this.parse(DefinitionList);
         const targets = await resolveReadTargets(flags);
         const { groq, params } = buildDefinitionListQuery(flags);
+        if (flags.json) {
+            await logJsonListing({
+                targets,
+                key: 'definitions',
+                limit: flags.limit,
+                log: (line) => this.log(line),
+                fetch: ({ client }) => fetchDefinitionRows({ client, groq, params, limit: flags.limit }),
+                toRow: definitionRow,
+            });
+            return;
+        }
         const failures = await runReadAcrossTargets({
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = (await client.fetch(groq, params, {
-                    tag: 'definition.list',
-                })).map(assertReadableModel);
-                if (!fetched.length) {
+                const fetched = await fetchDefinitionRows({ client, groq, params, limit: flags.limit });
+                if (!fetched.rows.length) {
                     this.log(`${logSymbols.info} no definitions found`);
                     return;
                 }
                 logClippedTable({
-                    rows: fetched,
+                    rows: fetched.rows,
                     limit: flags.limit,
                     headers: ['workflow', 'title', 'tag', 'stages', 'in flight', 'instances', 'created'],
-                    toCells: (r) => [
-                        `${r.name} v${r.version}`,
-                        r.title,
-                        r.tag,
-                        String(r.stageCount),
-                        String(r.inFlightCount),
-                        String(r.totalInstances),
-                        r._createdAt,
-                    ],
+                    toCells: (r) => {
+                        const row = definitionRow(r);
+                        return [
+                            `${row.name} v${row.version}`,
+                            row.title,
+                            row.tag,
+                            String(row.stageCount),
+                            String(row.inFlightCount),
+                            String(row.totalInstances),
+                            row._createdAt,
+                        ];
+                    },
                     log: (line) => this.log(line),
                 });
             },
@@ -93,3 +107,19 @@ export default class DefinitionList extends WorkflowCommand {
         }
     }
 }
+export function definitionRow(r) {
+    return {
+        name: r.name,
+        version: r.version,
+        title: r.title,
+        tag: r.tag,
+        stageCount: r.stageCount,
+        inFlightCount: r.inFlightCount,
+        totalInstances: r.totalInstances,
+        _createdAt: r._createdAt,
+    };
+}
+async function fetchDefinitionRows({ client, groq, params, limit, }) {
+    const rows = await client.fetch(groq, params, { tag: 'definition.list' });
+    return { rows: rows.map(assertReadableModel), hasMore: rows.length > limit };
+}

package/dist/commands/editorial-workflows/definition/show.d.ts

@@ -8,6 +8,7 @@ export default class DefinitionShow extends WorkflowCommand {
         name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };

package/dist/commands/editorial-workflows/definition/show.js

@@ -6,7 +6,7 @@ import { WorkflowCommand } from "../../../lib/base-command.js";
 import { resolveReadTargets, soleHitOrFail } from "../../../lib/context.js";
 import { buildDefinitionShowQuery, buildDefinitionTagsQuery } from "../../../lib/definitions.js";
 import { fail } from "../../../lib/fail.js";
-import { tagFlags } from "../../../lib/flags.js";
+import { jsonFlags, tagFlags } from "../../../lib/flags.js";
 import { formatKeyValue, resourceLabel, sectionHeader } from "../../../lib/ui.js";
 export default class DefinitionShow extends WorkflowCommand {
     static aliases = ['definition:show'];
@@ -17,6 +17,7 @@ export default class DefinitionShow extends WorkflowCommand {
     static flags = {
         ...tagFlags,
         version: Flags.integer({ description: 'Specific version (default: latest).' }),
+        ...jsonFlags,
     };
     async run() {
         const { args, flags } = await this.parse(DefinitionShow);
@@ -32,6 +33,10 @@ export default class DefinitionShow extends WorkflowCommand {
                 exit: 1,
             });
         }
+        if (flags.json) {
+            this.log(JSON.stringify(def, null, 2));
+            return;
+        }
         this.log(definitionHeader(def, def.tag));
         this.log('');
         for (const line of describeDefinition(def)) {

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

@@ -77,6 +77,24 @@ export declare function deploymentBanner({ deployment, index, total, }: {
     index: number;
     total: number;
 }): string | undefined;
+/** The deploy target as one label — the deployment's friendly name/tag
+ *  ({@link deploymentLabel}) and the resource it writes to
+ *  ({@link resourceLabel}) — so every progress and result line names where a
+ *  deploy landed, including the common single-deployment run that prints no
+ *  banner. */
+export declare function targetLabel(deployment: WorkflowDeployment): string;
+/** The deploy spinner's progress line — names the full target it writes to. */
+export declare function deployStartLine(count: number, where: string): string;
+/** The dry-run spinner's progress line — a diff reads the resource's deployed
+ *  state, so it names the resource it compares against, not the deployment. */
+export declare function dryRunStartLine(count: number, resource: string): string;
+/** A completed deploy/dry-run result line: the past-tense verb, the count, and
+ *  the full target, so a finished run always shows where it landed. */
+export declare function resultLine({ verb, count, where, }: {
+    verb: 'Processed' | 'Diffed';
+    count: number;
+    where: string;
+}): string;
 /** One line per deployed definition, symbol-tagged by its result status,
  *  followed by any advisory effect-output lint warnings indented beneath it. */
 export declare function deployResultLines(results: DeployDefinitionResult[]): string[];

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

@@ -13,7 +13,7 @@ import { loadWorkflowConfig } from "../../lib/load-config.js";
 import { deploymentLabel, deploymentToTarget, selectDeployments, } from "../../lib/select-deployment.js";
 import { shareDefinitionsAfterDeploy } from "../../lib/share-definitions.js";
 import { cliTelemetry } from "../../lib/telemetry.js";
-import { groupBanner } from "../../lib/ui.js";
+import { groupBanner, resourceLabel } from "../../lib/ui.js";
 export default class Deploy extends WorkflowCommand {
     static aliases = ['deploy'];
     static description = 'Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.';
@@ -110,14 +110,16 @@ export default class Deploy extends WorkflowCommand {
     }
     async processDeployment({ deployment, defs, dryRun, client, }) {
         const target = deploymentToTarget(deployment);
+        const where = targetLabel(deployment);
+        const resource = resourceLabel(deployment.workflowResource);
         if (dryRun) {
-            await this.runDryRun({ client, defs, target });
+            await this.runDryRun({ client, defs, target, where, resource });
             return undefined;
         }
-        return this.executeDeploy({ client, defs, target });
+        return this.executeDeploy({ client, defs, target, where });
     }
-    async executeDeploy({ client, defs, target, }) {
-        const spinner = ora(`Deploying ${defs.length} definition(s)…`).start();
+    async executeDeploy({ client, defs, target, where, }) {
+        const spinner = ora(deployStartLine(defs.length, where)).start();
         try {
             const deployed = await workflow.deployDefinitions({
                 ...target,
@@ -125,7 +127,7 @@ export default class Deploy extends WorkflowCommand {
                 definitions: defs,
                 telemetry: cliTelemetry().logger,
             });
-            spinner.succeed(`Processed ${deployed.results.length} definition(s)`);
+            spinner.succeed(resultLine({ verb: 'Processed', count: deployed.results.length, where }));
             for (const line of deployResultLines(deployed.results))
                 this.log(line);
             return deployed;
@@ -135,11 +137,11 @@ export default class Deploy extends WorkflowCommand {
             throw error;
         }
     }
-    async runDryRun({ client, defs, target, }) {
-        const spinner = ora(`Diffing ${defs.length} definition(s) against dataset…`).start();
+    async runDryRun({ client, defs, target, where, resource, }) {
+        const spinner = ora(dryRunStartLine(defs.length, resource)).start();
         try {
             const entries = await computeDiffEntries({ client, defs, target });
-            spinner.succeed(`Diffed ${defs.length} definition(s)`);
+            spinner.succeed(resultLine({ verb: 'Diffed', count: defs.length, where }));
             for (const line of diffReport(entries))
                 this.log(line);
         }
@@ -194,6 +196,18 @@ export function deploySummary({ total, failures, }) {
 export function deploymentBanner({ deployment, index, total, }) {
     return groupBanner({ label: deploymentLabel(deployment), index, total });
 }
+export function targetLabel(deployment) {
+    return `${deploymentLabel(deployment)} → ${resourceLabel(deployment.workflowResource)}`;
+}
+export function deployStartLine(count, where) {
+    return `Deploying ${count} definition(s) to ${where}…`;
+}
+export function dryRunStartLine(count, resource) {
+    return `Diffing ${count} definition(s) against ${resource}…`;
+}
+export function resultLine({ verb, count, where, }) {
+    return `${verb} ${count} definition(s) · ${where}`;
+}
 export function deployResultLines(results) {
     const symbols = {
         created: logSymbols.success,

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;
@@ -49,6 +51,7 @@ export default class List extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        json: 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>;
@@ -58,4 +61,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

@@ -4,9 +4,26 @@ 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 { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { logJsonListing, 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]{
@@ -64,6 +85,7 @@ export default class List extends WorkflowCommand {
         '<%= config.bin %> list --definition productLaunch',
         '<%= config.bin %> list --document dataset:proj:ds:article-1',
         '<%= config.bin %> list --tag prod',
+        '<%= config.bin %> list --json',
     ];
     static flags = {
         ...tagFlags,
@@ -86,24 +108,42 @@ export default class List extends WorkflowCommand {
             description: 'Maximum rows to return.',
             default: 50,
         }),
+        ...jsonFlags,
     };
     async run() {
         const { flags } = await this.parse(List);
         const targets = await resolveReadTargets(flags);
         const { groq, params } = failOnThrow('Invalid --document:', () => buildListQuery(flags));
         const document = flags.document;
+        if (flags.json) {
+            await logJsonListing({
+                targets,
+                key: 'instances',
+                limit: flags.limit,
+                log: (line) => this.log(line),
+                fetch: ({ client }) => fetchRows({ client, groq, params, document, limit: flags.limit }),
+                toRow: instanceRow,
+            });
+            return;
+        }
         const failures = await runReadAcrossTargets({
             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 +165,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,32 @@
-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>;
+        deployment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/** {@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 { instanceFlags } 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 = {
+        ...instanceFlags,
+        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/commands/editorial-workflows/show.d.ts

@@ -8,6 +8,7 @@ export default class Show extends WorkflowCommand {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         include: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };