@sanity/workflow-cli 0.5.1

package/dist/commands/show.js

@@ -0,0 +1,85 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { abortReason } from '@sanity/workflow-engine';
+import boxen from 'boxen';
+import logSymbols from 'log-symbols';
+import { loadClient } from "../lib/client.js";
+export default class Show extends Command {
+    static description = 'Show the state, tasks, and effects of a workflow instance.';
+    static examples = [
+        '<%= config.bin %> show wf-instance.abc123',
+        '<%= config.bin %> show wf-instance.abc123 --include history',
+    ];
+    static args = {
+        instanceId: Args.string({
+            required: true,
+            description: 'Workflow instance document id.',
+        }),
+    };
+    static flags = {
+        include: Flags.string({
+            description: 'Optional sections to include in output.',
+            options: ['history'],
+            multiple: true,
+            default: [],
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Show);
+        const client = loadClient();
+        const instance = await client.getDocument(args.instanceId);
+        if (!instance) {
+            this.error(`${logSymbols.error} no instance with id "${args.instanceId}"`, { exit: 1 });
+        }
+        this.log(boxen(instanceHeader(instance), { padding: 1, borderStyle: 'round', title: 'instance' }));
+        this.log('');
+        for (const line of describeInstance(instance, {
+            includeHistory: flags.include.includes('history'),
+        })) {
+            this.log(line);
+        }
+    }
+}
+/** The boxed summary block at the top of `show` output. */
+export function instanceHeader(instance) {
+    const reason = abortReason(instance);
+    const abortedLine = instance.abortedAt
+        ? [`aborted:     ${instance.abortedAt}${reason ? ` — ${reason}` : ''}`]
+        : [];
+    return [
+        `instance:    ${instance._id}`,
+        `workflow:    ${instance.definition} v${instance.pinnedVersion}`,
+        `stage:       ${instance.currentStage}`,
+        `started:     ${instance.startedAt}`,
+        `completed:   ${instance.completedAt ?? '—'}`,
+        ...abortedLine,
+        `tag:         ${instance.tag}`,
+    ].join('\n');
+}
+/**
+ * The per-instance body lines: every stage with its tasks, any pending
+ * effects, and (optionally) the history log. Pure so it can be asserted
+ * without driving the oclif command.
+ */
+export function describeInstance(instance, options) {
+    const lines = ['stages:'];
+    for (const stage of instance.stages) {
+        const exited = stage.exitedAt ? ` (exited ${stage.exitedAt})` : ' (current)';
+        lines.push(`  • ${stage.name}${exited}`);
+        for (const task of stage.tasks) {
+            lines.push(`      - ${task.name}  [${task.status}]`);
+        }
+    }
+    if (instance.pendingEffects.length > 0) {
+        lines.push('', 'pending effects:');
+        for (const eff of instance.pendingEffects) {
+            lines.push(`  • ${eff.name}  (key=${eff._key})`);
+        }
+    }
+    if (options.includeHistory) {
+        lines.push('', 'history:');
+        for (const entry of instance.history) {
+            lines.push(`  • [${entry.at}] ${entry._type}`);
+        }
+    }
+    return lines;
+}

package/dist/commands/tail.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class Tail extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<void>;
+    /**
+     * Fetch the current instance state, print history entries past the
+     * given high-water mark, return the new mark. Pulled out so the
+     * async work in the subscription's `next` handler stays tidy.
+     */
+    private printNewEntries;
+}

package/dist/commands/tail.js

@@ -0,0 +1,73 @@
+import { Args, Command } from '@oclif/core';
+import logSymbols from 'log-symbols';
+import pc from 'picocolors';
+import { buildClient, loadClient } from "../lib/client.js";
+import { fail } from "../lib/fail.js";
+export default class Tail extends Command {
+    static description = 'Stream new history entries on a workflow instance as they land in the dataset.';
+    static examples = ['<%= config.bin %> tail wf-instance.abc123'];
+    static args = {
+        instanceId: Args.string({
+            required: true,
+            description: 'Workflow instance id to tail.',
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(Tail);
+        const client = loadClient();
+        const initial = await client.getDocument(args.instanceId);
+        if (!initial) {
+            fail(`No instance with id "${args.instanceId}"`);
+        }
+        this.log(pc.dim(`tailing ${pc.bold(args.instanceId)} (${initial.definition} v${initial.pinnedVersion}, ${initial.history.length} prior entries, currently in ${initial.currentStage})`));
+        this.log(pc.dim('Ctrl+C to stop'));
+        this.log('');
+        // Track the high-water mark so we only print history entries that
+        // landed after we started tailing. Listening with `includeResult:
+        // false` (matching what the studio does) keeps the wire payload
+        // small — we just refetch on each notification.
+        let seen = initial.history.length;
+        const subscription = client
+            .listen(`*[_id == $id]`, { id: args.instanceId }, { includeResult: false, visibility: 'query' })
+            .subscribe({
+            next: async () => {
+                try {
+                    seen = await this.printNewEntries(client, args.instanceId, seen);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`${pc.red(`${logSymbols.error} fetch failed:`)} ${message}\n`);
+                }
+            },
+            error: (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                fail('Listen subscription error:', message);
+            },
+        });
+        const shutdown = () => {
+            subscription.unsubscribe();
+            process.stderr.write(`\n${pc.dim(`${logSymbols.info} stopped`)}\n`);
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        // Keep the event loop alive — `subscribe` doesn't itself anchor the
+        // process. The shutdown handlers above are the only exit path.
+        await new Promise(() => { });
+    }
+    /**
+     * Fetch the current instance state, print history entries past the
+     * given high-water mark, return the new mark. Pulled out so the
+     * async work in the subscription's `next` handler stays tidy.
+     */
+    async printNewEntries(client, instanceId, seen) {
+        const next = await client.getDocument(instanceId);
+        if (!next)
+            return seen;
+        const newEntries = next.history.slice(seen);
+        for (const entry of newEntries) {
+            this.log(`${pc.dim(`[${entry.at}]`)} ${pc.cyan(entry._type)}`);
+        }
+        return next.history.length;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { execute } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1,4 @@
+// Library entry for the package's `.` export. The CLI itself runs through the
+// `bin/run.js` (published) and `bin/dev.js` (dev) entries; this module exists
+// only to satisfy the repo's source-first exports map.
+export { execute } from '@oclif/core';

package/dist/lib/client.d.ts

@@ -0,0 +1,17 @@
+import { type SanityClient } from '@sanity/client';
+export interface ClientEnv {
+    projectId: string;
+    dataset: string;
+    token: string;
+    apiHost: string;
+    apiVersion: string;
+}
+export declare function buildClient(env?: ClientEnv): SanityClient;
+/**
+ * {@link buildClient} but funnel a missing/empty `SANITY_*` env var
+ * through the standard {@link failOnThrow} path, so commands fail with a
+ * clean message rather than a raw stack trace. This is the boundary
+ * commands call; {@link buildClient} stays throw-based for tests and for
+ * callers that supply their own {@link ClientEnv}.
+ */
+export declare function loadClient(): SanityClient;

package/dist/lib/client.js

@@ -0,0 +1,40 @@
+import { createClient } from '@sanity/client';
+import { ENV } from "./env.js";
+import { failOnThrow } from "./fail.js";
+function readClientEnv() {
+    const projectId = process.env[ENV.SANITY_PROJECT_ID];
+    const token = process.env[ENV.SANITY_AUTH_TOKEN];
+    if (!projectId) {
+        throw new Error('SANITY_PROJECT_ID is required (set in root .env)');
+    }
+    if (!token) {
+        throw new Error('SANITY_AUTH_TOKEN is required with editor role (set in root .env)');
+    }
+    return {
+        projectId,
+        dataset: process.env[ENV.SANITY_DATASET] ?? 'production',
+        token,
+        apiHost: process.env[ENV.SANITY_API_HOST] ?? 'https://api.sanity.io',
+        apiVersion: '2026-04-29',
+    };
+}
+export function buildClient(env = readClientEnv()) {
+    return createClient({
+        projectId: env.projectId,
+        dataset: env.dataset,
+        apiVersion: env.apiVersion,
+        token: env.token,
+        apiHost: env.apiHost,
+        useCdn: false,
+    });
+}
+/**
+ * {@link buildClient} but funnel a missing/empty `SANITY_*` env var
+ * through the standard {@link failOnThrow} path, so commands fail with a
+ * clean message rather than a raw stack trace. This is the boundary
+ * commands call; {@link buildClient} stays throw-based for tests and for
+ * callers that supply their own {@link ClientEnv}.
+ */
+export function loadClient() {
+    return failOnThrow('Invalid Sanity client config:', () => buildClient());
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowResource } from '@sanity/workflow-engine';
+export interface WorkflowConfig {
+    workflowResource: WorkflowResource;
+    tag: string;
+}
+/**
+ * {@link readWorkflowConfig} but funnel a thrown env-validation error
+ * through the standard {@link fail} path so commands don't each have to wrap.
+ */
+export declare function loadWorkflowConfig(tagOverride?: string): WorkflowConfig;
+/**
+ * Resolve the `deploy` command's definitions source — a module specifier
+ * (a path like `./src/workflows.ts`, or a package name) whose
+ * `allDefinitions` export holds the batch to deploy. Required and with no
+ * default: the CLI is agnostic about *which* definitions it ships, so an
+ * unset source is an error rather than a silent fall back to a built-in set.
+ */
+export declare function loadDefinitionsSource(): string;

package/dist/lib/config.js

@@ -0,0 +1,50 @@
+import { ENV } from "./env.js";
+import { fail, failOnThrow } from "./fail.js";
+const VALID_RESOURCE_TYPES = ['dataset', 'canvas', 'media-library', 'dashboard'];
+function isResourceType(value) {
+    return VALID_RESOURCE_TYPES.includes(value);
+}
+/**
+ * Resolve the engine's `workflowResource` + tag from env vars (and an
+ * optional `tagOverride`, e.g. the `--tag` flag).
+ *
+ * - `WORKFLOW_RESOURCE_TYPE` — one of "dataset" / "canvas" / "media-library" /
+ *   "dashboard". Defaults to "dataset".
+ * - `WORKFLOW_RESOURCE_ID` — the resource id (e.g. "test.test" for a
+ *   dataset). Defaults to "test.test".
+ * - `WORKFLOW_TAG` — the single environment tag (e.g. "prod"). Required;
+ *   `tagOverride` takes precedence when supplied.
+ */
+function readWorkflowConfig(tagOverride) {
+    const rawType = process.env[ENV.WORKFLOW_RESOURCE_TYPE] ?? 'dataset';
+    if (!isResourceType(rawType)) {
+        throw new Error(`WORKFLOW_RESOURCE_TYPE must be one of: ${VALID_RESOURCE_TYPES.join(', ')} (got "${rawType}")`);
+    }
+    const id = process.env[ENV.WORKFLOW_RESOURCE_ID] ?? 'test.test';
+    const tag = (tagOverride ?? process.env[ENV.WORKFLOW_TAG] ?? '').trim();
+    if (!tag) {
+        throw new Error('Workflow tag is required - pass --tag or set WORKFLOW_TAG (e.g. prod)');
+    }
+    return { workflowResource: { type: rawType, id }, tag };
+}
+/**
+ * {@link readWorkflowConfig} but funnel a thrown env-validation error
+ * through the standard {@link fail} path so commands don't each have to wrap.
+ */
+export function loadWorkflowConfig(tagOverride) {
+    return failOnThrow('Invalid workflow config:', () => readWorkflowConfig(tagOverride));
+}
+/**
+ * Resolve the `deploy` command's definitions source — a module specifier
+ * (a path like `./src/workflows.ts`, or a package name) whose
+ * `allDefinitions` export holds the batch to deploy. Required and with no
+ * default: the CLI is agnostic about *which* definitions it ships, so an
+ * unset source is an error rather than a silent fall back to a built-in set.
+ */
+export function loadDefinitionsSource() {
+    const source = process.env[ENV.WORKFLOW_DEFS]?.trim();
+    if (source === undefined || source === '') {
+        fail('No definitions source configured.', 'Set WORKFLOW_DEFS to a module that exports `allDefinitions` — a path like ./src/workflows.ts, or a package name.');
+    }
+    return source;
+}

package/dist/lib/definitions.d.ts

@@ -0,0 +1,36 @@
+import { type WorkflowDefinition } from '@sanity/workflow-engine';
+/**
+ * Turn a configured definitions source into a specifier `import()` can
+ * load. Path-like values (relative or absolute) resolve against `cwd` and
+ * become file URLs so they're imported as files, not bare package names;
+ * anything else passes through as a module specifier (e.g. a workspace
+ * package such as `@sanity/workflow-examples`).
+ */
+export declare function resolveDefinitionsSpecifier(source: string, cwd: string): string;
+/**
+ * Pull the `allDefinitions` array out of an imported definitions module,
+ * failing hard with a source-specific message when the module doesn't
+ * expose it. Per-definition structure is validated downstream by
+ * {@link collectValidationErrors}, so this only asserts the array shape.
+ */
+export declare function extractDefinitions(mod: unknown, source: string): WorkflowDefinition[];
+/**
+ * Narrow the local batch to one definition `name`, failing with the
+ * available names when there's no match. With `only` unset the whole batch passes
+ * through (a fresh array, so callers can mutate without aliasing).
+ */
+export declare function selectDefinitions(allDefinitions: WorkflowDefinition[], only: string | undefined): WorkflowDefinition[];
+/**
+ * The full local-definitions pipeline shared by `deploy` and
+ * `definition diff`: resolve the `WORKFLOW_DEFS` source, import it,
+ * narrow to `only` (when given), and fail on any validation error.
+ */
+export declare function loadValidatedDefinitions(only: string | undefined): Promise<WorkflowDefinition[]>;
+/** {@link loadValidatedDefinitions} narrowed to exactly one definition name. */
+export declare function loadValidatedDefinition(name: string): Promise<WorkflowDefinition>;
+/**
+ * Per-definition structural/GROQ checks plus one batch-level check the
+ * engine doesn't do for us: duplicate `name` within the local set.
+ * Returns the human-readable error lines; empty means the batch is valid.
+ */
+export declare function collectValidationErrors(defs: WorkflowDefinition[]): string[];

package/dist/lib/definitions.js

@@ -0,0 +1,122 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validateDefinition } from '@sanity/workflow-engine';
+import { loadDefinitionsSource } from "./config.js";
+import { fail } from "./fail.js";
+/**
+ * Turn a configured definitions source into a specifier `import()` can
+ * load. Path-like values (relative or absolute) resolve against `cwd` and
+ * become file URLs so they're imported as files, not bare package names;
+ * anything else passes through as a module specifier (e.g. a workspace
+ * package such as `@sanity/workflow-examples`).
+ */
+export function resolveDefinitionsSpecifier(source, cwd) {
+    if (source.startsWith('.') || isAbsolute(source)) {
+        return pathToFileURL(resolve(cwd, source)).href;
+    }
+    return source;
+}
+/**
+ * Pull the `allDefinitions` array out of an imported definitions module,
+ * failing hard with a source-specific message when the module doesn't
+ * expose it. Per-definition structure is validated downstream by
+ * {@link collectValidationErrors}, so this only asserts the array shape.
+ */
+export function extractDefinitions(mod, source) {
+    const exported = mod.allDefinitions;
+    if (!Array.isArray(exported)) {
+        fail(`Definitions module "${source}" has no \`allDefinitions\` array export.`, 'Export `allDefinitions: WorkflowDefinition[]` from the module named by WORKFLOW_DEFS.');
+    }
+    return exported;
+}
+/**
+ * Resolve the configured definitions module and dynamic-import it. The
+ * import is dynamic (not a static top-level import) so a `defineWorkflow`
+ * throw inside the module — a missing `version`, a bad schema field —
+ * surfaces here as a friendly CLI error rather than an oclif command-load
+ * crash with a raw stack trace.
+ */
+async function importDefinitions(source) {
+    const specifier = resolveDefinitionsSpecifier(source, process.cwd());
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(specifier, true));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        fail(`Failed to load definitions from "${source}":`, message);
+    }
+    return extractDefinitions(mod, source);
+}
+/**
+ * Narrow the local batch to one definition `name`, failing with the
+ * available names when there's no match. With `only` unset the whole batch passes
+ * through (a fresh array, so callers can mutate without aliasing).
+ */
+export function selectDefinitions(allDefinitions, only) {
+    if (!only)
+        return [...allDefinitions];
+    const filtered = allDefinitions.filter((d) => d.name === only);
+    if (filtered.length === 0) {
+        const available = allDefinitions.map((d) => d.name).join(', ');
+        fail(`No definition named "${only}".`, `Available: ${available}`);
+    }
+    return filtered;
+}
+/**
+ * The full local-definitions pipeline shared by `deploy` and
+ * `definition diff`: resolve the `WORKFLOW_DEFS` source, import it,
+ * narrow to `only` (when given), and fail on any validation error.
+ */
+export async function loadValidatedDefinitions(only) {
+    const allDefinitions = await importDefinitions(loadDefinitionsSource());
+    const selected = selectDefinitions(allDefinitions, only);
+    const errors = collectValidationErrors(selected);
+    if (errors.length > 0) {
+        fail('Validation failed:', errors.join('\n'));
+    }
+    return selected;
+}
+/** {@link loadValidatedDefinitions} narrowed to exactly one definition name. */
+export async function loadValidatedDefinition(name) {
+    const [def] = await loadValidatedDefinitions(name);
+    // selectDefinitions already failed on no match; this narrows the
+    // indexed access for the type checker.
+    if (!def)
+        fail(`No definition named "${name}".`);
+    return def;
+}
+/**
+ * Per-definition structural/GROQ checks plus one batch-level check the
+ * engine doesn't do for us: duplicate `name` within the local set.
+ * Returns the human-readable error lines; empty means the batch is valid.
+ */
+export function collectValidationErrors(defs) {
+    const errors = [];
+    const seen = new Map();
+    for (const d of defs) {
+        const count = (seen.get(d.name) ?? 0) + 1;
+        seen.set(d.name, count);
+        if (count === 2) {
+            errors.push(`  · duplicate name "${d.name}" in local batch`);
+        }
+    }
+    for (const d of defs) {
+        try {
+            validateDefinition(d);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push(`  · ${d.name} v${d.version}: ${message}`);
+        }
+    }
+    return errors;
+}

package/dist/lib/diff.d.ts

@@ -0,0 +1,7 @@
+import type { DiffEntry } from '@sanity/workflow-engine';
+/** One summary line per diff entry, tagged create / update / unchanged. */
+export declare function summaryLines(entries: DiffEntry[]): string[];
+/** Render a JSON diff of `oldObj` → `newObj` as `+`/`-`/context lines. */
+export declare function diffLines(oldObj: object, newObj: object): string[];
+/** The full diff report: the summary block plus a per-change diff. */
+export declare function diffReport(entries: DiffEntry[]): string[];

package/dist/lib/diff.js

@@ -0,0 +1,49 @@
+import { diffJson } from 'diff';
+import logSymbols from 'log-symbols';
+import pc from 'picocolors';
+/** One summary line per diff entry, tagged create / update / unchanged. */
+export function summaryLines(entries) {
+    const tags = {
+        create: pc.green('+ create   '),
+        update: pc.yellow('~ update   '),
+        unchanged: pc.dim('  unchanged'),
+    };
+    return entries.map((e) => {
+        return `  ${tags[e.status]} ${e.name} v${e.version}  ${pc.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 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) === '')
+            chunkLines.pop();
+        for (const line of chunkLines) {
+            if (chunk.added)
+                out.push(pc.green(`+ ${line}`));
+            else if (chunk.removed)
+                out.push(pc.red(`- ${line}`));
+            else
+                out.push(pc.dim(`  ${line}`));
+        }
+    }
+    return out;
+}
+/** The full diff report: the summary block plus a per-change diff. */
+export function diffReport(entries) {
+    const lines = ['', pc.bold('Summary'), ...summaryLines(entries)];
+    const changes = entries.filter((e) => e.status !== 'unchanged');
+    if (changes.length === 0) {
+        lines.push('', `${logSymbols.success} no changes — running deploy would be a no-op`);
+        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('', pc.bold(`── ${e.name} v${e.version} ──`), ...diffLines(e.existing ?? {}, e.expected));
+    }
+    return lines;
+}

package/dist/lib/env.d.ts

@@ -0,0 +1,10 @@
+export declare const ENV: {
+    readonly SANITY_PROJECT_ID: "SANITY_PROJECT_ID";
+    readonly SANITY_AUTH_TOKEN: "SANITY_AUTH_TOKEN";
+    readonly SANITY_DATASET: "SANITY_DATASET";
+    readonly SANITY_API_HOST: "SANITY_API_HOST";
+    readonly WORKFLOW_RESOURCE_TYPE: "WORKFLOW_RESOURCE_TYPE";
+    readonly WORKFLOW_RESOURCE_ID: "WORKFLOW_RESOURCE_ID";
+    readonly WORKFLOW_TAG: "WORKFLOW_TAG";
+    readonly WORKFLOW_DEFS: "WORKFLOW_DEFS";
+};

package/dist/lib/env.js

@@ -0,0 +1,13 @@
+// Typed env var definitions
+export const ENV = {
+    // Sanity client
+    SANITY_PROJECT_ID: 'SANITY_PROJECT_ID',
+    SANITY_AUTH_TOKEN: 'SANITY_AUTH_TOKEN',
+    SANITY_DATASET: 'SANITY_DATASET',
+    SANITY_API_HOST: 'SANITY_API_HOST',
+    // Workflow config
+    WORKFLOW_RESOURCE_TYPE: 'WORKFLOW_RESOURCE_TYPE',
+    WORKFLOW_RESOURCE_ID: 'WORKFLOW_RESOURCE_ID',
+    WORKFLOW_TAG: 'WORKFLOW_TAG',
+    WORKFLOW_DEFS: 'WORKFLOW_DEFS',
+};

package/dist/lib/fail.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export declare function fail(headline: string, detail?: string): never;
+/**
+ * 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 declare function failOnThrow<T>(headline: string, fn: () => T): T;

package/dist/lib/fail.js

@@ -0,0 +1,33 @@
+import logSymbols from 'log-symbols';
+import pc from 'picocolors';
+/**
+ * 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.
+ */
+export function fail(headline, detail) {
+    process.stderr.write(`${pc.red(`${logSymbols.error} ${headline}`)}\n`);
+    if (detail !== undefined && detail !== '') {
+        for (const line of detail.split('\n')) {
+            process.stderr.write(`  ${line}\n`);
+        }
+    }
+    process.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();
+    }
+    catch (err) {
+        fail(headline, err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/lib/flags.d.ts

@@ -0,0 +1,5 @@
+/** Selects the engine environment partition (e.g. prod, test).
+ *  Resolved flag → WORKFLOW_TAG (required) in {@link loadWorkflowConfig}. */
+export declare const tagFlags: {
+    tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};

package/dist/lib/flags.js

@@ -0,0 +1,8 @@
+import { Flags } from '@oclif/core';
+/** Selects the engine environment partition (e.g. prod, test).
+ *  Resolved flag → WORKFLOW_TAG (required) in {@link loadWorkflowConfig}. */
+export const tagFlags = {
+    tag: Flags.string({
+        description: 'Workflow environment tag (e.g. prod, test). Overrides WORKFLOW_TAG.',
+    }),
+};

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

@@ -0,0 +1,25 @@
+import type { Actor, OperationArgs } from '@sanity/workflow-engine';
+import type { WorkflowConfig } from './config.ts';
+/**
+ * The write-verb arguments every engine operation shares: tag scope,
+ * workflow resource, and the CLI's pinned actor ({@link SYSTEM_ACTOR}).
+ * Spread by both the instance verbs ({@link buildOperationArgs}) and the
+ * definition verbs (e.g. `definition delete`).
+ */
+export declare function baseEngineArgs(config: WorkflowConfig): Pick<OperationArgs, 'tag' | 'workflowResource' | '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;
+/**
+ * {@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 declare function buildOperationArgs(config: WorkflowConfig, instanceId: string, reason: string | undefined): Omit<OperationArgs, 'client'> & {
+    reason?: string;
+};