@sanity/workflow-cli 0.8.0 → 0.9.0

package/dist/commands/start.js

@@ -0,0 +1,169 @@
+import { styleText } from 'node:util';
+import { Args, Command, Flags } from '@oclif/core';
+import { isStartableDefinition, workflow, } from '@sanity/workflow-engine';
+import ora from 'ora';
+import { resolveContext } from "../lib/context.js";
+import { fetchDeployedDefinition } from "../lib/definitions.js";
+import { errorMessage, fail, failOnThrow } from "../lib/fail.js";
+import { actorFlags, jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs, resolveActor } from "../lib/operation-args.js";
+import { parseParams } from "../lib/params.js";
+export default class Start extends Command {
+    static description = 'Start a workflow instance from a deployed definition. Supply values for the ' +
+        "workflow's input-sourced fields with --field (e.g. the subject document ref).";
+    static examples = [
+        '<%= config.bin %> start productLaunch',
+        '<%= config.bin %> start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
+        '<%= config.bin %> start article-review --as user.xyz --as-role editor',
+        '<%= config.bin %> start productLaunch --version 2 --tag prod',
+    ];
+    static args = {
+        name: Args.string({ required: true, description: 'Workflow definition name.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        version: Flags.integer({
+            description: 'Definition version to start from (default: highest deployed).',
+        }),
+        field: Flags.string({
+            description: 'Initial value for a declared input-sourced field, as name=value (repeatable). Values ' +
+                'are JSON-parsed, falling back to a string; ref kinds take a JSON object with a GDR ' +
+                '`id` and doc `type`.',
+            multiple: true,
+            default: [],
+        }),
+        ...actorFlags,
+        ...jsonFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Start);
+        const { deployment, client } = await resolveContext(flags);
+        const actor = failOnThrow('start usage error:', () => resolveActor(flags.as, flags['as-role']));
+        const values = failOnThrow('Invalid --field:', () => parseParams(flags.field));
+        const initialFields = await resolveStartInputs({
+            client,
+            name: args.name,
+            tag: deployment.tag,
+            version: flags.version,
+            values,
+        });
+        const startArgs = {
+            client,
+            ...buildStartArgs({
+                scope: deployment,
+                name: args.name,
+                version: flags.version,
+                initialFields,
+                actor,
+            }),
+        };
+        if (flags.json) {
+            const result = await workflow
+                .startInstance(startArgs)
+                .catch((error) => fail('start error:', errorMessage(error)));
+            this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            return;
+        }
+        const spinner = ora(`Starting ${args.name}…`).start();
+        try {
+            const result = await workflow.startInstance(startArgs);
+            spinner.succeed(startReport(result.instance));
+        }
+        catch (error) {
+            spinner.fail('Start rejected');
+            fail('start error:', errorMessage(error));
+        }
+    }
+}
+/**
+ * Everything `start` must resolve before the engine call: fetch the deployed
+ * definition (failing when nothing is deployed under the name), refuse
+ * non-startable ones, and type the operator's `--field` values against the
+ * declared entries.
+ */
+async function resolveStartInputs({ client, name, tag, version, values, }) {
+    const deployed = await fetchDeployedDefinition({ client, name, tag, version });
+    if (deployed === undefined) {
+        fail(`No deployed definition "${name}".`);
+    }
+    const refusal = startRefusal(deployed);
+    if (refusal !== undefined) {
+        fail('start error:', refusal);
+    }
+    return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
+}
+/**
+ * Why a definition can't be started standalone, or `undefined` when it can.
+ * Advisory, mirroring the Startable column in `definition list` — the engine
+ * itself does not refuse ({@link isStartableDefinition}), but the CLI has no
+ * way to supply the parent context a spawn-only child expects.
+ */
+export function startRefusal(definition) {
+    if (isStartableDefinition(definition)) {
+        return undefined;
+    }
+    return "definition is spawn-only (lifecycle: 'child') — instances of it are spawned by a parent workflow's activity, not started standalone";
+}
+/**
+ * Type each `--field name=value` against the workflow's declared field
+ * entries — the engine takes typed {@link InitialFieldValue}s, and a value's
+ * type IS its declared entry's kind. Only `input`-sourced entries read
+ * caller values (the engine silently ignores the rest), so anything else
+ * fails here, naming the fields that ARE settable; value validation stays
+ * in the engine.
+ */
+export function buildInitialFields({ declared, values, }) {
+    const settable = declared.filter((f) => f.initialValue?.type === 'input');
+    const settableNames = settable.map((f) => f.name).join(', ');
+    return Object.entries(values).map(([name, value]) => {
+        const entry = declared.find((f) => f.name === name);
+        if (entry === undefined) {
+            throw new Error(settable.length > 0
+                ? `workflow declares no field "${name}" — input fields: ${settableNames}`
+                : `workflow declares no field "${name}" — it declares no input fields at all`);
+        }
+        if (entry.initialValue?.type !== 'input') {
+            throw new Error(`field "${name}" is not input-sourced — the engine would silently ignore the value. ` +
+                (settable.length > 0
+                    ? `Input fields: ${settableNames}`
+                    : 'This workflow has no input fields.'));
+        }
+        // Operator-supplied JSON; the engine validates the value against the
+        // declared kind at start, so this cast is the CLI/engine boundary.
+        return { type: entry.type, name, value };
+    });
+}
+/**
+ * The shared engine args ({@link baseEngineArgs}) plus the start-specific
+ * fields. Optionals spread conditionally because the engine's optional args
+ * reject an explicit `undefined` under `exactOptionalPropertyTypes`.
+ */
+export function buildStartArgs({ scope, name, version, initialFields, actor, }) {
+    return {
+        ...baseEngineArgs(scope, actor),
+        definition: name,
+        ...(version !== undefined ? { version } : {}),
+        ...(initialFields.length > 0 ? { initialFields } : {}),
+    };
+}
+/** The success spinner message. Pure so the in-flight / immediately-terminal
+ *  permutations can be asserted without driving a real start. */
+export function startReport(instance) {
+    const id = styleText('bold', instance._id);
+    const stage = styleText('bold', instance.currentStage);
+    return instance.completedAt !== undefined
+        ? `Started ${id} — completed immediately at ${stage}`
+        : `Started ${id} — now at ${stage}`;
+}
+/** The `--json` payload. Keys follow the CLI's `--json` vocabulary (matching
+ *  `fire-action`): `instanceId` carries the document `_id`, `version` the
+ *  pinned definition version; the rest mirror the instance fields. */
+export function startResultJson(instance) {
+    return {
+        instanceId: instance._id,
+        definition: instance.definition,
+        version: instance.pinnedVersion,
+        currentStage: instance.currentStage,
+        ...(instance.completedAt !== undefined ? { completedAt: instance.completedAt } : {}),
+    };
+}

package/dist/commands/tail.d.ts

@@ -5,6 +5,9 @@ export default class Tail extends Command {
     static args: {
         instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
+    static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
     run(): Promise<void>;
     /**
      * Fetch the current instance state, print history entries past the

package/dist/commands/tail.js

@@ -1,8 +1,9 @@
 import { styleText } from 'node:util';
 import { Args, Command } from '@oclif/core';
 import logSymbols from 'log-symbols';
-import { buildClient, loadClient } from "../lib/client.js";
+import { resolveReadContext } from "../lib/context.js";
 import { fail } from "../lib/fail.js";
+import { tagFlags } from "../lib/flags.js";
 import { formatTimestamp } from "../lib/ui.js";
 export default class Tail extends Command {
     static description = 'Stream new history entries on a workflow instance as they land in the dataset.';
@@ -13,9 +14,12 @@ export default class Tail extends Command {
             description: 'Workflow instance id to tail.',
         }),
     };
+    static flags = {
+        ...tagFlags,
+    };
     async run() {
-        const { args } = await this.parse(Tail);
-        const client = loadClient();
+        const { args, flags } = await this.parse(Tail);
+        const { client } = await resolveReadContext(flags);
         const initial = await client.getDocument(args.instanceId);
         if (!initial) {
             fail(`No instance with id "${args.instanceId}"`);
@@ -33,7 +37,7 @@ export default class Tail extends Command {
             .subscribe({
             next: async () => {
                 try {
-                    seen = await this.printNewEntries(client, args.instanceId, seen);
+                    seen = await this.printNewEntries({ client, instanceId: args.instanceId, seen });
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -61,7 +65,7 @@ export default class Tail extends Command {
      * 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) {
+    async printNewEntries({ client, instanceId, seen, }) {
         const next = await client.getDocument(instanceId);
         if (!next)
             return seen;

package/dist/lib/client.d.ts

@@ -1,17 +1,14 @@
 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;
+import { type WorkflowResource } from '@sanity/workflow-engine';
 /**
- * {@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}.
+ * Resolve the Sanity auth token. An explicit `SANITY_AUTH_TOKEN` wins (CI /
+ * scripted use); otherwise fall back to the `sanity login` session token.
+ * Throws when neither exists rather than building an unauthenticated client
+ * that only 401s once it hits the API.
  */
-export declare function loadClient(): SanityClient;
+export declare function resolveToken(): Promise<string>;
+/** {@link resolveToken}, funnelling the no-token case through the clean
+ *  {@link fail} path rather than letting it surface as an oclif stack. */
+export declare function resolveTokenOrFail(): Promise<string>;
+/** Build a client for a workflow resource, authenticated with `token`. */
+export declare function clientFor(resource: WorkflowResource, token: string): SanityClient;

package/dist/lib/client.js

@@ -1,40 +1,52 @@
+import { getCliToken, isStaging } from '@sanity/cli-core';
 import { createClient } from '@sanity/client';
+import { datasetResourceParts, ENGINE_API_VERSION, } from '@sanity/workflow-engine';
 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)');
+import { fail } from "./fail.js";
+const API_VERSION = ENGINE_API_VERSION;
+const STAGING_API_HOST = 'https://api.sanity.work';
+/**
+ * The API host to hit: an explicit `SANITY_API_HOST` wins; otherwise mirror
+ * the Sanity CLI — staging routes to the staging API, prod falls through to
+ * `@sanity/client`'s default. Pairs with {@link resolveToken}, which reads the
+ * matching session token.
+ */
+function resolveApiHost() {
+    return process.env[ENV.SANITY_API_HOST] ?? (isStaging() ? STAGING_API_HOST : undefined);
+}
+/**
+ * Resolve the Sanity auth token. An explicit `SANITY_AUTH_TOKEN` wins (CI /
+ * scripted use); otherwise fall back to the `sanity login` session token.
+ * Throws when neither exists rather than building an unauthenticated client
+ * that only 401s once it hits the API.
+ */
+export async function resolveToken() {
+    const fromEnv = process.env[ENV.SANITY_AUTH_TOKEN]?.trim();
+    if (fromEnv) {
+        return fromEnv;
     }
-    if (!token) {
-        throw new Error('SANITY_AUTH_TOKEN is required with editor role (set in root .env)');
+    const fromSession = await getCliToken();
+    if (fromSession) {
+        return fromSession;
     }
-    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',
-    };
+    throw new Error('No Sanity token found — run `sanity login`, or set SANITY_AUTH_TOKEN.');
 }
-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 resolveToken}, funnelling the no-token case through the clean
+ *  {@link fail} path rather than letting it surface as an oclif stack. */
+export async function resolveTokenOrFail() {
+    return resolveToken().catch((err) => fail('Authentication required:', err instanceof Error ? err.message : String(err)));
 }
-/**
- * {@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());
+/** Build a client for a workflow resource, authenticated with `token`. */
+export function clientFor(resource, token) {
+    const apiHost = resolveApiHost();
+    const baseParams = { token, apiVersion: API_VERSION, useCdn: false, ...(apiHost ? { apiHost } : {}) };
+    // A dataset goes through the classic {projectId, dataset} config — the proven
+    // path, and it keeps `tail`'s client.listen() on well-trodden ground. Other
+    // resource types have no projectId/dataset split, so they pass through as a
+    // resource directly.
+    if (resource.type === 'dataset') {
+        const { projectId, dataset } = datasetResourceParts(resource.id);
+        return createClient({ ...baseParams, projectId, dataset });
+    }
+    return createClient({ ...baseParams, resource });
 }

package/dist/lib/context.d.ts

@@ -0,0 +1,62 @@
+import type { SanityClient } from '@sanity/client';
+import type { WorkflowConfig, WorkflowDeployment, WorkflowInstance, WorkflowResource } from '@sanity/workflow-engine';
+import type { EngineScope } from './operation-args.ts';
+export interface DeploymentContext {
+    deployment: WorkflowDeployment;
+    client: SanityClient;
+}
+export interface InstanceContext {
+    client: SanityClient;
+    /** The engine scope derived from the instance itself — `{tag, workflowResource}`
+     *  ready to pass straight to an engine verb, so callers never re-assemble it. */
+    scope: EngineScope;
+}
+/**
+ * The resolution a WRITE shares: discover the config, pick the deployment for
+ * `--tag` (or the sole one), and build an authenticated client for that
+ * deployment's resource. A write acts on one specific deployment, so a
+ * single, definite target is exactly what it needs.
+ */
+export declare function resolveContext(flags: {
+    tag?: string | undefined;
+}): Promise<DeploymentContext>;
+/**
+ * The resolution a READ shares: an authenticated client for the resource to
+ * inspect — and nothing more. A read lists/inspects whatever is in the Content
+ * Lake, so it must NOT inherit a deployment's tag or definition set as a
+ * filter. The config only locates the resource here; the command applies the
+ * user's explicit `--tag` (if any) as a query filter itself.
+ *
+ * Resource selection: when every deployment targets the same resource (the
+ * common case) it's used with no `--tag` needed; only a config that spans
+ * *different* resources needs `--tag` to say which dataset to read.
+ */
+export declare function resolveReadContext(flags: {
+    tag?: string | undefined;
+}): Promise<{
+    client: SanityClient;
+}>;
+/** The single resource a read should target, or fail asking which when the
+ *  config spans more than one. */
+export declare function resolveReadResource(config: WorkflowConfig, tag: string | undefined): WorkflowResource;
+/**
+ * The resolution an instance-id-targeted command shares, read or write: an
+ * authenticated client for the resource, plus the instance itself — so the
+ * command derives its partition (`tag`) from the instance, never from the
+ * config's declared deployments. An instance id is globally unique and carries
+ * its own `tag`, so a command that names one acts on that instance regardless
+ * of which tags the config happens to deploy; the config only locates the
+ * resource (via {@link resolveReadResource}, no tag filter).
+ *
+ * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
+ * declared deployment because it acts on the authored definition set (or a
+ * definition name, which — unlike an instance id — isn't unique across tags).
+ */
+export declare function resolveInstanceContext(flags: {
+    tag?: string | undefined;
+}, instanceId: string): Promise<InstanceContext>;
+/** Fetch an instance by id, exiting cleanly when the resource has no such
+ *  document — the diagnostic an operator sees on a mistyped id. Split out from
+ *  {@link resolveInstanceContext} so the not-found path is unit-testable
+ *  without a live config/token/client. */
+export declare function loadInstanceOrFail(client: Pick<SanityClient, 'getDocument'>, instanceId: string): Promise<WorkflowInstance>;

package/dist/lib/context.js

@@ -0,0 +1,82 @@
+import { clientFor, resolveTokenOrFail } from "./client.js";
+import { fail } from "./fail.js";
+import { loadWorkflowConfig } from "./load-config.js";
+import { selectDeployment } from "./select-deployment.js";
+/**
+ * The resolution a WRITE shares: discover the config, pick the deployment for
+ * `--tag` (or the sole one), and build an authenticated client for that
+ * deployment's resource. A write acts on one specific deployment, so a
+ * single, definite target is exactly what it needs.
+ */
+export async function resolveContext(flags) {
+    const config = await loadWorkflowConfig();
+    const deployment = selectDeployment(config, { tag: flags.tag });
+    return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
+}
+/**
+ * The resolution a READ shares: an authenticated client for the resource to
+ * inspect — and nothing more. A read lists/inspects whatever is in the Content
+ * Lake, so it must NOT inherit a deployment's tag or definition set as a
+ * filter. The config only locates the resource here; the command applies the
+ * user's explicit `--tag` (if any) as a query filter itself.
+ *
+ * Resource selection: when every deployment targets the same resource (the
+ * common case) it's used with no `--tag` needed; only a config that spans
+ * *different* resources needs `--tag` to say which dataset to read.
+ */
+export async function resolveReadContext(flags) {
+    const config = await loadWorkflowConfig();
+    return { client: clientFor(resolveReadResource(config, flags.tag), await resolveTokenOrFail()) };
+}
+/** The single resource a read should target, or fail asking which when the
+ *  config spans more than one. */
+export function resolveReadResource(config, tag) {
+    const byKey = new Map(config.deployments.map((d) => [
+        `${d.workflowResource.type}:${d.workflowResource.id}`,
+        d.workflowResource,
+    ]));
+    const resources = [...byKey.values()];
+    const [sole] = resources;
+    if (sole === undefined) {
+        fail('No deployments configured.');
+    }
+    if (resources.length === 1) {
+        return sole;
+    }
+    if (tag === undefined) {
+        const tags = config.deployments.map((d) => d.tag).join(', ');
+        fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
+    }
+    return selectDeployment(config, { tag }).workflowResource;
+}
+/**
+ * The resolution an instance-id-targeted command shares, read or write: an
+ * authenticated client for the resource, plus the instance itself — so the
+ * command derives its partition (`tag`) from the instance, never from the
+ * config's declared deployments. An instance id is globally unique and carries
+ * its own `tag`, so a command that names one acts on that instance regardless
+ * of which tags the config happens to deploy; the config only locates the
+ * resource (via {@link resolveReadResource}, no tag filter).
+ *
+ * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
+ * declared deployment because it acts on the authored definition set (or a
+ * definition name, which — unlike an instance id — isn't unique across tags).
+ */
+export async function resolveInstanceContext(flags, instanceId) {
+    const config = await loadWorkflowConfig();
+    const workflowResource = resolveReadResource(config, flags.tag);
+    const client = clientFor(workflowResource, await resolveTokenOrFail());
+    const instance = await loadInstanceOrFail(client, instanceId);
+    return { client, scope: { tag: instance.tag, workflowResource } };
+}
+/** Fetch an instance by id, exiting cleanly when the resource has no such
+ *  document — the diagnostic an operator sees on a mistyped id. Split out from
+ *  {@link resolveInstanceContext} so the not-found path is unit-testable
+ *  without a live config/token/client. */
+export async function loadInstanceOrFail(client, instanceId) {
+    const instance = await client.getDocument(instanceId);
+    if (!instance) {
+        fail(`Workflow instance ${instanceId} not found`);
+    }
+    return instance;
+}

package/dist/lib/definitions.d.ts

@@ -1,36 +1,45 @@
-import { type WorkflowDefinition } from '@sanity/workflow-engine';
+import type { SanityClient } from '@sanity/client';
+import { type DeployedDefinition, type WorkflowDefinition } from '@sanity/workflow-engine';
+interface DefinitionShowQueryArgs {
+    name: string;
+    tag?: string | undefined;
+    version?: number | undefined;
+}
+export declare function buildDefinitionShowQuery(flags: DefinitionShowQueryArgs): {
+    groq: string;
+    params: Record<string, unknown>;
+};
 /**
- * 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`).
+ * Fetch the deployed definition a command targets — latest unless pinned via
+ * `version`. An absent pinned version always fails (the caller asked for
+ * something specific); an absent latest returns `undefined` so the caller
+ * decides whether that's fatal.
  */
-export declare function resolveDefinitionsSpecifier(source: string, cwd: string): string;
+export declare function fetchDeployedDefinition({ client, name, tag, version, }: {
+    client: SanityClient;
+    name: string;
+    tag: string;
+    version: number | undefined;
+}): Promise<DeployedDefinition | undefined>;
 /**
- * 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.
+ * Narrow a batch to one definition name (`only`), 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). `context` prefixes
+ * the failure so callers whose run spans several deployments can attribute it.
  */
-export declare function extractDefinitions(mod: unknown, source: string): WorkflowDefinition[];
+export declare function selectDefinitions(allDefinitions: WorkflowDefinition[], { only, context }: {
+    only: string | undefined;
+    context?: 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.
+ * Per-definition structural/GROQ checks plus one batch-level check the engine
+ * doesn't do for us: duplicate `name` within the set. Returns the
+ * human-readable error lines; empty means the batch is valid.
  */
 export declare function collectValidationErrors(defs: WorkflowDefinition[]): string[];
+/** Validate a set of definitions, exiting with the collected errors on any
+ *  failure. The single validate-then-fail gate `deploy` and `definition diff`
+ *  share, so the two can't drift into divergent failure messages. `context`
+ *  prefixes the failure with the deployment it belongs to in multi-target runs. */
+export declare function validateOrFail(defs: WorkflowDefinition[], context?: string): void;
+export {};