@sanity/workflow-cli 0.9.0 → 0.11.0

package/dist/lib/diff.js

@@ -2,8 +2,6 @@ import { styleText } from 'node:util';
 import { diffJson } from 'diff';
 import logSymbols from 'log-symbols';
 import { sectionHeader } from "./ui.js";
-/** One summary line per diff entry, tagged create / unchanged. Definitions are
- *  immutable, so a content change is a new version (`create`), never an update. */
 export function summaryLines(entries) {
     const tags = {
         create: styleText('green', '+ create   '),
@@ -13,34 +11,73 @@ export function summaryLines(entries) {
         return `  ${tags[e.status]} ${e.name} v${e.version}  ${styleText('dim', `(${e.docId})`)}`;
     });
 }
-/** Render a JSON diff of `oldObj` → `newObj` as `+`/`-`/context lines. */
-export function diffLines(oldObj, newObj) {
-    const out = [];
-    for (const chunk of diffJson(oldObj, newObj)) {
+const CONTEXT_LINES = 3;
+const DEPLOY_STAMPED_KEYS = new Set(['tag', 'version', 'contentHash']);
+function authoredContent(doc) {
+    return Object.fromEntries(Object.entries(doc).filter(([key]) => !key.startsWith('_') && !DEPLOY_STAMPED_KEYS.has(key)));
+}
+function chunkKind(chunk) {
+    if (chunk.added) {
+        return 'added';
+    }
+    if (chunk.removed) {
+        return 'removed';
+    }
+    return 'context';
+}
+function taggedLines(oldObj, newObj) {
+    return diffJson(oldObj, newObj).flatMap((chunk) => {
         const chunkLines = chunk.value.split('\n');
-        // diffJson appends a trailing empty string when the chunk ends in "\n";
-        // drop it so we don't emit a blank line per chunk boundary.
-        if (chunkLines.at(-1) === '')
+        if (chunkLines.at(-1) === '') {
             chunkLines.pop();
-        for (const line of chunkLines) {
-            if (chunk.added)
-                out.push(styleText('green', `+ ${line}`));
-            else if (chunk.removed)
-                out.push(styleText('red', `- ${line}`));
-            else
-                out.push(styleText('dim', `  ${line}`));
         }
+        return chunkLines.map((text) => ({ kind: chunkKind(chunk), text }));
+    });
+}
+function collapseUnchanged(lines, context) {
+    const changed = lines.flatMap((line, i) => (line.kind === 'context' ? [] : [i]));
+    if (changed.length === 0) {
+        return lines;
     }
+    const keep = lines.map((_, i) => changed.some((c) => Math.abs(c - i) <= context));
+    const out = [];
+    let run = [];
+    const flushRun = () => {
+        if (run.length === 1) {
+            out.push(...run);
+        }
+        else if (run.length > 1) {
+            out.push({ kind: 'elision', count: run.length });
+        }
+        run = [];
+    };
+    lines.forEach((line, i) => {
+        if (keep[i]) {
+            flushRun();
+            out.push(line);
+        }
+        else {
+            run.push(line);
+        }
+    });
+    flushRun();
     return out;
 }
-/** Footnote for the detail diff: `_id`, `version`, and `contentHash` are
- *  stamped by deploy as a function of the content — never authored. Without
- *  this an operator can read their `+`/`-` lines as fields they edited (e.g. a
- *  `version` they never set), when they only reflect the content change. */
-function derivedFieldsNote() {
-    return `${logSymbols.info} ${styleText('dim', '_id, version and contentHash are deploy-generated — they change automatically with the content, not fields you edit.')}`;
+function renderLine(line) {
+    if (line.kind === 'elision') {
+        return styleText('dim', `  … ${line.count} unchanged lines`);
+    }
+    if (line.kind === 'added') {
+        return styleText('green', `+ ${line.text}`);
+    }
+    if (line.kind === 'removed') {
+        return styleText('red', `- ${line.text}`);
+    }
+    return styleText('dim', `  ${line.text}`);
+}
+export function diffLines(oldObj, newObj) {
+    return collapseUnchanged(taggedLines(oldObj, newObj), CONTEXT_LINES).map(renderLine);
 }
-/** The full diff report: the summary block plus a per-change diff. */
 export function diffReport(entries) {
     const lines = ['', sectionHeader('Summary'), ...summaryLines(entries)];
     const changes = entries.filter((e) => e.status !== 'unchanged');
@@ -49,10 +86,7 @@ export function diffReport(entries) {
         return lines;
     }
     for (const e of changes) {
-        // For net-new docs, existing is undefined — render the whole expected
-        // doc as added lines so the operator sees what would land.
-        lines.push('', styleText('bold', `── ${e.name} v${e.version} ──`), ...diffLines(e.existing ?? {}, e.expected));
+        lines.push('', styleText('bold', `── ${e.name} v${e.version} ──`), ...diffLines(authoredContent(e.existing ?? {}), authoredContent(e.expected)));
     }
-    lines.push('', derivedFieldsNote());
     return lines;
 }

package/dist/lib/env.d.ts

@@ -2,3 +2,7 @@ export declare const ENV: {
     readonly SANITY_AUTH_TOKEN: "SANITY_AUTH_TOKEN";
     readonly SANITY_API_HOST: "SANITY_API_HOST";
 };
+/** The explicit env token, or undefined when unset/blank. The single owner
+ *  of "did the token come from the env?" — token resolution and the auth
+ *  recovery hint must never disagree on it. */
+export declare function envAuthToken(): string | undefined;

package/dist/lib/env.js

@@ -1,7 +1,8 @@
-// Typed env var definitions. Client config (projectId/dataset) is derived from
-// the deployment's resource, and the tag comes from `--tag`/the config — so the
-// only env vars left are auth + host overrides.
 export const ENV = {
     SANITY_AUTH_TOKEN: 'SANITY_AUTH_TOKEN',
     SANITY_API_HOST: 'SANITY_API_HOST',
 };
+export function envAuthToken() {
+    const token = process.env[ENV.SANITY_AUTH_TOKEN]?.trim();
+    return token ? token : undefined;
+}

package/dist/lib/fail.d.ts

@@ -1,14 +1,15 @@
-/**
- * The human-readable message of a caught `unknown`. Strips control characters
- * (keeping newlines and tabs) so server-derived error text can't smuggle
- * terminal escape sequences into CLI output.
- */
-export declare function errorMessage(error: unknown): string;
 /**
  * Render a user-facing error and exit non-zero. Writes straight to
  * stderr — no oclif framing, no Node stack — so expected failures
  * (validation, missing input, conflicting flags) read clean.
  *
+ * Exits by THROWING oclif's `ExitError`, never `process.exit`: the error
+ * rides the normal command lifecycle, so the `finally` hook still runs —
+ * completing the command trace and flushing batched telemetry — before
+ * oclif's handler exits 1 without printing anything further. A raw
+ * `process.exit` here would silently drop the trace and every batched
+ * event (including already-logged events from earlier in the command).
+ *
  * For unexpected failures (network, engine throw) prefer letting the
  * error propagate so the stack is visible for debugging.
  */
@@ -20,3 +21,15 @@ export declare function fail(headline: string, detail?: string): never;
  * helpers pure and unit-testable while giving callers one clean boundary.
  */
 export declare function failOnThrow<T>(headline: string, fn: () => T): T;
+/** An API rejection of the auth token itself — as opposed to a 403, where
+ *  the identity is valid but lacks the role for the operation. Walks the
+ *  `cause` chain because the 401 often arrives wrapped: the engine's
+ *  `/users/me` actor resolution rethrows it inside its own `Error`. */
+export declare function isAuthRejection(err: unknown): boolean;
+/**
+ * The detail block for a command failure: the error's message, plus the
+ * auth recovery hint when the API rejected the token. Every site that
+ * renders a caught command error should build its detail here, so the
+ * hint reaches the user no matter which call the token died at.
+ */
+export declare function failureDetail(err: unknown): string;

package/dist/lib/fail.js

@@ -1,38 +1,18 @@
 import { styleText } from 'node:util';
+import { Errors } from '@oclif/core';
+import { ClientError } from '@sanity/client';
+import { errorMessage } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-/**
- * The human-readable message of a caught `unknown`. Strips control characters
- * (keeping newlines and tabs) so server-derived error text can't smuggle
- * terminal escape sequences into CLI output.
- */
-export function errorMessage(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    // [^\P{Cc}\n\t] = every control character except \n and \t.
-    return message.replace(/[^\P{Cc}\n\t]/gu, '');
-}
-/**
- * Render a user-facing error and exit non-zero. Writes straight to
- * stderr — no oclif framing, no Node stack — so expected failures
- * (validation, missing input, conflicting flags) read clean.
- *
- * For unexpected failures (network, engine throw) prefer letting the
- * error propagate so the stack is visible for debugging.
- */
+import { envAuthToken } from "./env.js";
 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(`  ${line}\n`);
+            process.stderr.write(`  ${styleText(['dim', 'red'], line)}\n`);
         }
     }
-    process.exit(1);
+    return Errors.exit(1);
 }
-/**
- * Run `fn`, funnelling a thrown env/validation error through {@link fail}
- * so an expected, user-fixable failure (missing input, bad value) reads
- * clean instead of as an oclif stack trace. Keeps the throwing `read*`
- * helpers pure and unit-testable while giving callers one clean boundary.
- */
 export function failOnThrow(headline, fn) {
     try {
         return fn();
@@ -41,3 +21,23 @@ export function failOnThrow(headline, fn) {
         fail(headline, errorMessage(err));
     }
 }
+export function isAuthRejection(err) {
+    let current = err;
+    for (let depth = 0; depth < 5 && current !== undefined; depth++) {
+        if (current instanceof ClientError && current.statusCode === 401) {
+            return true;
+        }
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return false;
+}
+function authRecoveryHint() {
+    if (envAuthToken() !== undefined) {
+        return 'The SANITY_AUTH_TOKEN token was rejected — check it is valid and has access to this project.';
+    }
+    return 'Your `sanity login` session may have expired — run `sanity login` and retry.';
+}
+export function failureDetail(err) {
+    const message = errorMessage(err);
+    return isAuthRejection(err) ? `${message}\n${authRecoveryHint()}` : message;
+}

package/dist/lib/flags.d.ts

@@ -5,13 +5,6 @@
 export declare const tagFlags: {
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
-/** Actor attribution for write verbs — name a real user (plus roles) instead
- *  of the pinned workflow-cli system actor, so assignee- and role-gated
- *  filters pass. Commands resolve the pair with `resolveActor`. */
-export declare const actorFlags: {
-    as: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-    'as-role': import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
-};
 export declare const jsonFlags: {
     json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };

package/dist/lib/flags.js

@@ -1,26 +1,9 @@
 import { Flags } from '@oclif/core';
-/** The environment tag (e.g. prod, test). For write commands it selects which
- *  deployment in the discovered `sanity.workflow` config to act on (omittable
- *  when only one is configured); for read commands it's an optional query
- *  filter — and the resource disambiguator when a config spans more than one. */
 export const tagFlags = {
     tag: Flags.string({
         description: 'Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.',
     }),
 };
-/** Actor attribution for write verbs — name a real user (plus roles) instead
- *  of the pinned workflow-cli system actor, so assignee- and role-gated
- *  filters pass. Commands resolve the pair with `resolveActor`. */
-export const actorFlags = {
-    as: Flags.string({
-        description: 'Attribute the write to this Sanity user id (default: a workflow-cli system actor).',
-    }),
-    'as-role': Flags.string({
-        description: 'Role to attribute to the --as user (repeatable), so role-gated filters pass.',
-        multiple: true,
-        default: [],
-    }),
-};
 export const jsonFlags = {
     json: Flags.boolean({
         description: 'Emit structured JSON instead of rendered output.',

package/dist/lib/load-config.d.ts

@@ -1,11 +1,15 @@
-import type { WorkflowConfig } from '@sanity/workflow-engine';
+import { type WorkflowConfig } from '@sanity/workflow-engine';
 /**
  * Discover the `sanity.workflow.{ts,js,mjs}` in `cwd`, import its default
- * export, and validate it through {@link defineWorkflowConfig}.
- *
- * Re-validating here (rather than trusting the export) means a config authored
- * as a raw object — `export default {deployments: [...]}` without the helper —
- * is still checked, and a malformed one fails with the engine's path-prefixed
- * message at the CLI boundary instead of mid-deploy.
+ * export, and validate it through {@link defineWorkflowConfig}. Any problem —
+ * no file, unloadable module, invalid config — exits through the clean `fail`
+ * path.
  */
 export declare function loadWorkflowConfig(cwd?: string): Promise<WorkflowConfig>;
+/**
+ * {@link loadWorkflowConfig} for telemetry setup, which must never break (or
+ * exit) a command: `undefined` when the file is absent or unusable. A broken
+ * config is not swallowed for real — the command's own load reports it through
+ * the clean `fail` path; this caller just runs with telemetry off.
+ */
+export declare function loadWorkflowConfigIfPresent(cwd?: string): Promise<WorkflowConfig | undefined>;

package/dist/lib/load-config.js

@@ -9,6 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { errorMessage } from '@sanity/workflow-engine';
 import { defineWorkflowConfig } from '@sanity/workflow-engine/define';
 import { createJiti } from 'jiti';
 import { fail } from "./fail.js";
@@ -17,7 +18,6 @@ const CONFIG_FILE_NAMES = [
     'sanity.workflow.js',
     'sanity.workflow.mjs',
 ];
-/** First `sanity.workflow.{ts,js,mjs}` in `cwd`, or undefined. */
 function findConfigFile(cwd) {
     for (const name of CONFIG_FILE_NAMES) {
         const candidate = join(cwd, name);
@@ -27,12 +27,15 @@ function findConfigFile(cwd) {
     }
     return undefined;
 }
-/**
- * Import the config module's default export. `.ts` goes through jiti (no build
- * step); `.js`/`.mjs` use native dynamic import. A throw inside the module — a
- * syntax error, a `defineWorkflowConfig` that rejected — surfaces as a clean
- * CLI error rather than an oclif stack trace.
- */
+class ConfigLoadError extends Error {
+    headline;
+    detail;
+    constructor(headline, detail) {
+        super(`${headline} ${detail}`);
+        this.headline = headline;
+        this.detail = detail;
+    }
+}
 async function importDefault(filePath) {
     const url = pathToFileURL(filePath).href;
     try {
@@ -42,28 +45,45 @@ async function importDefault(filePath) {
         return (await import(__rewriteRelativeImportExtension(url, true))).default;
     }
     catch (err) {
-        fail(`Failed to load ${basename(filePath)}:`, err instanceof Error ? err.message : String(err));
+        throw new ConfigLoadError(`Failed to load ${basename(filePath)}:`, errorMessage(err));
+    }
+}
+const parsedConfigs = new Map();
+function parseConfigFile(filePath) {
+    const cached = parsedConfigs.get(filePath);
+    if (cached !== undefined) {
+        return cached;
     }
+    const parsed = importDefault(filePath).then((exported) => {
+        try {
+            return defineWorkflowConfig(exported);
+        }
+        catch (err) {
+            throw new ConfigLoadError(`Invalid config in ${basename(filePath)}:`, errorMessage(err));
+        }
+    });
+    parsedConfigs.set(filePath, parsed);
+    return parsed;
 }
-/**
- * Discover the `sanity.workflow.{ts,js,mjs}` in `cwd`, import its default
- * export, and validate it through {@link defineWorkflowConfig}.
- *
- * Re-validating here (rather than trusting the export) means a config authored
- * as a raw object — `export default {deployments: [...]}` without the helper —
- * is still checked, and a malformed one fails with the engine's path-prefixed
- * message at the CLI boundary instead of mid-deploy.
- */
 export async function loadWorkflowConfig(cwd = process.cwd()) {
     const filePath = findConfigFile(cwd);
     if (filePath === undefined) {
         fail(`No ${CONFIG_FILE_NAMES[0]} found in ${cwd}.`, 'Create one that `export default defineWorkflowConfig({deployments: [...]})`.');
     }
-    const exported = await importDefault(filePath);
     try {
-        return defineWorkflowConfig(exported);
+        return await parseConfigFile(filePath);
     }
     catch (err) {
-        fail(`Invalid config in ${basename(filePath)}:`, err instanceof Error ? err.message : String(err));
+        if (err instanceof ConfigLoadError) {
+            fail(err.headline, err.detail);
+        }
+        throw err;
+    }
+}
+export async function loadWorkflowConfigIfPresent(cwd = process.cwd()) {
+    const filePath = findConfigFile(cwd);
+    if (filePath === undefined) {
+        return undefined;
     }
+    return parseConfigFile(filePath).catch(() => undefined);
 }

package/dist/lib/operation-args.d.ts

@@ -1,33 +1,24 @@
-import type { Actor, EngineScopeArgs, OperationArgs } from '@sanity/workflow-engine';
+import { type EngineScopeArgs, type OperationArgs, type WorkflowTelemetryLogger } from '@sanity/workflow-engine';
 /**
- * The engine-scope a CLI write needs: which tag partition and which resource
+ * The engine-scope a CLI verb needs: which tag partition and which resource
  * the engine's own data lives in — {@link EngineScopeArgs} minus the client.
  * A {@link import('@sanity/workflow-engine').WorkflowDeployment} satisfies it,
  * so commands pass their resolved deployment straight through.
  */
 export type EngineScope = Pick<EngineScopeArgs, 'tag' | 'workflowResource'>;
 /**
- * The synthetic actor a CLI write is attributed to when the operator
- * doesn't name a real user. The engine resolves a real actor from
- * `/users/me`, which a token-only CLI can't reach; until the CLI hooks
- * into Sanity auth proper, writes act as this system identity.
+ * The engine args every CLI verb shares: tag scope, workflow resource,
+ * the CLI's declared execution context — the advisory "via what" stamped
+ * on history; identity itself is always the token behind the client
+ * (`/users/me`), never injected — and the invocation's telemetry logger,
+ * so the engine's adoption vocabulary flows from CLI-driven operations
+ * (the raw-verb equivalent of `createEngine({telemetry})`). Spread by the
+ * instance verbs ({@link buildOperationArgs}), the definition verbs
+ * (e.g. `definition delete`), and reads like `diagnose`.
  */
-export declare const SYSTEM_ACTOR: Actor;
-/**
- * The write-verb arguments every engine operation shares: tag scope,
- * workflow resource, and the actor the write is attributed to — commands
- * with `--as` resolve one via {@link resolveActor}; the rest pass
- * {@link SYSTEM_ACTOR} explicitly. Spread by both the instance verbs
- * ({@link buildOperationArgs}) and the definition verbs (e.g. `definition delete`).
- */
-export declare function baseEngineArgs(scope: EngineScope, actor: Actor): EngineScope & Pick<OperationArgs, 'access'>;
-/**
- * Resolve the actor a write is attributed to. With a named user the fire
- * is pinned to it (plus any roles, so role-gated action filters pass);
- * without one the {@link SYSTEM_ACTOR} fallback applies. Roles without a
- * named user throw — they'd silently attach to nothing otherwise.
- */
-export declare function resolveActor(as: string | undefined, roles: string[]): Actor;
+export declare function baseEngineArgs(scope: EngineScope): EngineScope & Pick<EngineScopeArgs, 'executionContext'> & {
+    telemetry: WorkflowTelemetryLogger;
+};
 /**
  * {@link baseEngineArgs} plus the instance-operation fields (everything
  * but the client and the verb-specific fields). The `reason` is spread
@@ -38,6 +29,6 @@ export declare function buildOperationArgs({ scope, instanceId, reason, }: {
     scope: EngineScope;
     instanceId: string;
     reason: string | undefined;
-}): OperationArgs & EngineScope & {
+}): OperationArgs & ReturnType<typeof baseEngineArgs> & {
     reason?: string;
 };

package/dist/lib/operation-args.js

@@ -1,48 +1,16 @@
-/**
- * The synthetic actor a CLI write is attributed to when the operator
- * doesn't name a real user. The engine resolves a real actor from
- * `/users/me`, which a token-only CLI can't reach; until the CLI hooks
- * into Sanity auth proper, writes act as this system identity.
- */
-export const SYSTEM_ACTOR = { kind: 'system', id: 'workflow-cli' };
-/**
- * The write-verb arguments every engine operation shares: tag scope,
- * workflow resource, and the actor the write is attributed to — commands
- * with `--as` resolve one via {@link resolveActor}; the rest pass
- * {@link SYSTEM_ACTOR} explicitly. Spread by both the instance verbs
- * ({@link buildOperationArgs}) and the definition verbs (e.g. `definition delete`).
- */
-export function baseEngineArgs(scope, actor) {
+import { EXECUTION_KINDS, } from '@sanity/workflow-engine';
+import { cliTelemetry } from "./telemetry.js";
+export function baseEngineArgs(scope) {
     return {
         tag: scope.tag,
         workflowResource: scope.workflowResource,
-        access: { actor },
+        executionContext: { kind: EXECUTION_KINDS.cli, id: 'workflow-cli' },
+        telemetry: cliTelemetry().logger,
     };
 }
-/**
- * Resolve the actor a write is attributed to. With a named user the fire
- * is pinned to it (plus any roles, so role-gated action filters pass);
- * without one the {@link SYSTEM_ACTOR} fallback applies. Roles without a
- * named user throw — they'd silently attach to nothing otherwise.
- */
-export function resolveActor(as, roles) {
-    if (as === undefined) {
-        if (roles.length > 0) {
-            throw new Error('--as-role requires --as <userId>');
-        }
-        return SYSTEM_ACTOR;
-    }
-    return { kind: 'person', id: as, ...(roles.length > 0 ? { roles } : {}) };
-}
-/**
- * {@link baseEngineArgs} plus the instance-operation fields (everything
- * but the client and the verb-specific fields). The `reason` is spread
- * conditionally because the engine's optional field rejects an explicit
- * `undefined` under `exactOptionalPropertyTypes`.
- */
 export function buildOperationArgs({ scope, instanceId, reason, }) {
     return {
-        ...baseEngineArgs(scope, SYSTEM_ACTOR),
+        ...baseEngineArgs(scope),
         instanceId,
         ...(reason !== undefined ? { reason } : {}),
     };

package/dist/lib/ops-report.d.ts

@@ -1,4 +1,3 @@
-import type { Ora } from 'ora';
 /** A single engine primitive that ran during a write commit — the
  *  reportable subset of the engine's `OpAppliedSummary`. */
 export interface RanOp {
@@ -24,19 +23,28 @@ export interface WriteOutcome {
     ranOps?: RanOp[];
 }
 /** The spinner message + ops block a write verb prints once its engine
- *  call returns. {@link opsAppliedLines} builds `opsLines`. */
+ *  call returns. {@link opsAppliedLines} builds `opsLines`; verbs whose
+ *  commits never run ops omit it. */
 export interface WriteReport {
     changed: boolean;
     message: string;
-    opsLines: string[];
+    opsLines?: string[];
 }
+/** The ", then cascaded N auto-transition(s)" suffix a write report appends
+ *  when the commit cascaded the instance onward; empty when it didn't. */
+export declare function cascadeTail(cascaded: number): string;
 /**
- * Emit a write-verb report through its spinner: warn and bail on a no-op
- * (`changed: false`), otherwise succeed and print the ops block. Shared by
- * every write command so the changed / no-op branches stay consistent.
+ * Run a write verb behind its spinner: start it, run the engine call, and
+ * emit the report — warn and bail on a no-op (`changed: false`), otherwise
+ * succeed and print the ops block. A throw fails the spinner and exits
+ * through {@link fail}. The one spinner + report + catch shape every write
+ * command (abort, set-stage, fire-action, start, definition delete) shares.
  */
-export declare function emitWriteReport({ spinner, report, log, }: {
-    spinner: Ora;
-    report: WriteReport;
+export declare function runWriteVerb<T>({ startLabel, failLabel, failHeadline, run, report, log, }: {
+    startLabel: string;
+    failLabel: string;
+    failHeadline: string;
+    run: () => Promise<T>;
+    report: (result: T) => WriteReport;
     log: (line: string) => void;
-}): void;
+}): Promise<void>;

package/dist/lib/ops-report.js

@@ -1,10 +1,7 @@
 import { styleText } from 'node:util';
 import logSymbols from 'log-symbols';
-/**
- * The "ops applied" block shared by write-verb reports (set-stage,
- * fire-action): a blank separator, a header, and one line per primitive
- * that ran. Empty when nothing ran, so callers append it unconditionally.
- */
+import ora from 'ora';
+import { fail, failureDetail } from "./fail.js";
 export function opsAppliedLines(ranOps) {
     const details = (ranOps ?? []).map((op) => {
         const target = op.target ? styleText('dim', ` → ${op.target.scope}.${op.target.field}`) : '';
@@ -12,16 +9,23 @@ export function opsAppliedLines(ranOps) {
     });
     return details.length > 0 ? ['', styleText('dim', 'ops applied:'), ...details] : [];
 }
-/**
- * Emit a write-verb report through its spinner: warn and bail on a no-op
- * (`changed: false`), otherwise succeed and print the ops block. Shared by
- * every write command so the changed / no-op branches stay consistent.
- */
-export function emitWriteReport({ spinner, report, log, }) {
-    if (!report.changed) {
-        spinner.warn(report.message);
-        return;
+export function cascadeTail(cascaded) {
+    return cascaded > 0 ? `, then cascaded ${cascaded} auto-transition(s)` : '';
+}
+export async function runWriteVerb({ startLabel, failLabel, failHeadline, run, report, log, }) {
+    const spinner = ora(startLabel).start();
+    try {
+        const result = await run();
+        const emitted = report(result);
+        if (!emitted.changed) {
+            spinner.warn(emitted.message);
+            return;
+        }
+        spinner.succeed(emitted.message);
+        emitted.opsLines?.forEach(log);
+    }
+    catch (error) {
+        spinner.fail(failLabel);
+        fail(failHeadline, failureDetail(error));
     }
-    spinner.succeed(report.message);
-    report.opsLines.forEach(log);
 }

package/dist/lib/params.js

@@ -3,8 +3,6 @@ function coerceValue(raw) {
         return JSON.parse(raw);
     }
     catch {
-        // Not valid JSON — treat it as a plain string so `--param note=hi`
-        // needs no quoting. The engine validates the typed value either way.
         return raw;
     }
 }
@@ -15,12 +13,6 @@ function parsePair(pair) {
     }
     return [pair.slice(0, eq), coerceValue(pair.slice(eq + 1))];
 }
-/**
- * Parse repeated `key=value` flag pairs (`--param`, `--field`) into an
- * object. Each value is JSON-parsed so numbers/booleans/objects type
- * correctly, falling back to the raw string. The engine validates the
- * result against the declared types the consuming flag targets.
- */
 export function parseParams(pairs) {
     return Object.fromEntries(pairs.map(parsePair));
 }

package/dist/lib/read-fanout.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowResource } from '@sanity/workflow-engine';
+import type { ReadTarget } from './context.ts';
+/** A read target whose query threw — noted in place and reflected in the
+ *  command's exit code. */
+export interface ReadFailure {
+    resource: WorkflowResource;
+    message: string;
+}
+/**
+ * Run a read over every target, grouping output per resource: a banner when
+ * the read spans several, then whatever `run` logs for that target. A throw
+ * from one target is noted under its banner and the rest still render — a
+ * token that can't read one dataset must not sink the whole listing. A
+ * single-target run rethrows instead, keeping the plain unprefixed output
+ * and clean error rendering at the command boundary. Callers exit non-zero
+ * when failures come back.
+ */
+export declare function runReadAcrossTargets({ targets, log, run, }: {
+    targets: ReadTarget[];
+    log: (line: string) => void;
+    run: (target: ReadTarget) => Promise<void>;
+}): Promise<ReadFailure[]>;