@sanity/workflow-cli 0.8.0 → 0.9.0

package/dist/lib/definitions.js

@@ -1,103 +1,54 @@
-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");
-        });
+import { WORKFLOW_DEFINITION_TYPE, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
+import { errorMessage, fail } from "./fail.js";
+export function buildDefinitionShowQuery(flags) {
+    const params = { name: flags.name };
+    const filters = [`_type == "${WORKFLOW_DEFINITION_TYPE}"`, 'name == $name'];
+    if (flags.version !== undefined) {
+        params.version = flags.version;
+        filters.push('version == $version');
     }
-    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;
+    if (flags.tag) {
+        params.tag = flags.tag;
+        filters.push(tagScopeFilter());
     }
-    return source;
+    const groq = `*[${filters.join(' && ')}] | order(version desc) [0]`;
+    return { groq, params };
 }
 /**
- * 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.
+ * 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 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.');
+export async function fetchDeployedDefinition({ client, name, tag, version, }) {
+    const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
+    const deployed = await client.fetch(groq, params);
+    if (deployed === null && version !== undefined) {
+        fail(`No deployed definition "${name}" v${version}.`);
     }
-    return exported;
+    return deployed ?? undefined;
 }
 /**
- * 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.
+ * 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.
  */
-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)
+export function selectDefinitions(allDefinitions, { only, context = '' }) {
+    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}`);
+        fail(`${context}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.
+ * 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 function collectValidationErrors(defs) {
     const errors = [];
@@ -114,9 +65,18 @@ export function collectValidationErrors(defs) {
             validateDefinition(d);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            errors.push(`  · ${d.name}: ${message}`);
+            errors.push(`  · ${d.name}: ${errorMessage(err)}`);
         }
     }
     return errors;
 }
+/** 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 function validateOrFail(defs, context = '') {
+    const errors = collectValidationErrors(defs);
+    if (errors.length > 0) {
+        fail(`${context}Validation failed:`, errors.join('\n'));
+    }
+}

package/dist/lib/diff.js

@@ -33,6 +33,13 @@ export function diffLines(oldObj, newObj) {
     }
     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.')}`;
+}
 /** The full diff report: the summary block plus a per-change diff. */
 export function diffReport(entries) {
     const lines = ['', sectionHeader('Summary'), ...summaryLines(entries)];
@@ -46,5 +53,6 @@ export function diffReport(entries) {
         // 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('', derivedFieldsNote());
     return lines;
 }

package/dist/lib/env.d.ts

@@ -1,10 +1,4 @@
 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

@@ -1,13 +1,7 @@
-// Typed env var definitions
+// 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 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

@@ -1,3 +1,9 @@
+/**
+ * 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

package/dist/lib/fail.js

@@ -1,5 +1,15 @@
 import { styleText } from 'node:util';
 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
@@ -28,6 +38,6 @@ export function failOnThrow(headline, fn) {
         return fn();
     }
     catch (err) {
-        fail(headline, err instanceof Error ? err.message : String(err));
+        fail(headline, errorMessage(err));
     }
 }

package/dist/lib/flags.d.ts

@@ -1,5 +1,17 @@
-/** Selects the engine environment partition (e.g. prod, test).
- *  Resolved flag → WORKFLOW_TAG (required) in {@link loadWorkflowConfig}. */
+/** 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 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,8 +1,29 @@
 import { Flags } from '@oclif/core';
-/** Selects the engine environment partition (e.g. prod, test).
- *  Resolved flag → WORKFLOW_TAG (required) in {@link loadWorkflowConfig}. */
+/** 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). Overrides WORKFLOW_TAG.',
+        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.',
+        default: false,
     }),
 };

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

@@ -0,0 +1,11 @@
+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 declare function loadWorkflowConfig(cwd?: string): Promise<WorkflowConfig>;

package/dist/lib/load-config.js

@@ -0,0 +1,69 @@
+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 { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defineWorkflowConfig } from '@sanity/workflow-engine/define';
+import { createJiti } from 'jiti';
+import { fail } from "./fail.js";
+const CONFIG_FILE_NAMES = [
+    'sanity.workflow.ts',
+    '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);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    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.
+ */
+async function importDefault(filePath) {
+    const url = pathToFileURL(filePath).href;
+    try {
+        if (filePath.endsWith('.ts')) {
+            return await createJiti(dirname(filePath)).import(url, { default: true });
+        }
+        return (await import(__rewriteRelativeImportExtension(url, true))).default;
+    }
+    catch (err) {
+        fail(`Failed to load ${basename(filePath)}:`, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * 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);
+    }
+    catch (err) {
+        fail(`Invalid config in ${basename(filePath)}:`, err instanceof Error ? err.message : String(err));
+    }
+}

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

@@ -1,12 +1,26 @@
-import type { Actor, OperationArgs } from '@sanity/workflow-engine';
-import type { WorkflowConfig } from './config.ts';
+import type { Actor, EngineScopeArgs, OperationArgs } from '@sanity/workflow-engine';
+/**
+ * The engine-scope a CLI write 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.
+ */
+export declare const SYSTEM_ACTOR: Actor;
 /**
  * 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`).
+ * 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(config: WorkflowConfig): Pick<OperationArgs, 'tag' | 'workflowResource' | 'access'>;
+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);
@@ -20,6 +34,10 @@ export declare function resolveActor(as: string | undefined, roles: string[]): A
  * 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'> & {
+export declare function buildOperationArgs({ scope, instanceId, reason, }: {
+    scope: EngineScope;
+    instanceId: string;
+    reason: string | undefined;
+}): OperationArgs & EngineScope & {
     reason?: string;
 };

package/dist/lib/operation-args.js

@@ -4,18 +4,19 @@
  * `/users/me`, which a token-only CLI can't reach; until the CLI hooks
  * into Sanity auth proper, writes act as this system identity.
  */
-const SYSTEM_ACTOR = { kind: 'system', id: 'workflow-cli' };
+export const SYSTEM_ACTOR = { kind: 'system', id: 'workflow-cli' };
 /**
  * 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`).
+ * 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(config) {
+export function baseEngineArgs(scope, actor) {
     return {
-        tag: config.tag,
-        workflowResource: config.workflowResource,
-        access: { actor: SYSTEM_ACTOR },
+        tag: scope.tag,
+        workflowResource: scope.workflowResource,
+        access: { actor },
     };
 }
 /**
@@ -31,7 +32,7 @@ export function resolveActor(as, roles) {
         }
         return SYSTEM_ACTOR;
     }
-    return { kind: 'user', id: as, ...(roles.length > 0 ? { roles } : {}) };
+    return { kind: 'person', id: as, ...(roles.length > 0 ? { roles } : {}) };
 }
 /**
  * {@link baseEngineArgs} plus the instance-operation fields (everything
@@ -39,9 +40,9 @@ export function resolveActor(as, roles) {
  * conditionally because the engine's optional field rejects an explicit
  * `undefined` under `exactOptionalPropertyTypes`.
  */
-export function buildOperationArgs(config, instanceId, reason) {
+export function buildOperationArgs({ scope, instanceId, reason, }) {
     return {
-        ...baseEngineArgs(config),
+        ...baseEngineArgs(scope, SYSTEM_ACTOR),
         instanceId,
         ...(reason !== undefined ? { reason } : {}),
     };

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

@@ -9,22 +9,34 @@ export interface RanOp {
     };
 }
 /**
- * The "ops applied" block shared by write-verb reports (move-stage,
+ * 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.
  */
 export declare function opsAppliedLines(ranOps: RanOp[] | undefined): string[];
+/** The subset of an engine `OperationResult` the write-verb reports read. */
+export interface WriteOutcome {
+    changed: boolean;
+    cascaded: number;
+    instance: {
+        currentStage: string;
+    };
+    ranOps?: RanOp[];
+}
 /** The spinner message + ops block a write verb prints once its engine
  *  call returns. {@link opsAppliedLines} builds `opsLines`. */
 export interface WriteReport {
-    fired: boolean;
+    changed: boolean;
     message: string;
     opsLines: string[];
 }
 /**
- * Emit a write-verb report through its spinner: warn and bail when the
- * requested intent didn't fire, otherwise succeed and print the ops block.
- * Shared by every write command so the fired / not-fired branches stay
- * consistent.
+ * 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 declare function emitWriteReport(spinner: Ora, report: WriteReport, log: (line: string) => void): void;
+export declare function emitWriteReport({ spinner, report, log, }: {
+    spinner: Ora;
+    report: WriteReport;
+    log: (line: string) => void;
+}): void;

package/dist/lib/ops-report.js

@@ -1,7 +1,7 @@
 import { styleText } from 'node:util';
 import logSymbols from 'log-symbols';
 /**
- * The "ops applied" block shared by write-verb reports (move-stage,
+ * 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.
  */
@@ -13,13 +13,12 @@ export function opsAppliedLines(ranOps) {
     return details.length > 0 ? ['', styleText('dim', 'ops applied:'), ...details] : [];
 }
 /**
- * Emit a write-verb report through its spinner: warn and bail when the
- * requested intent didn't fire, otherwise succeed and print the ops block.
- * Shared by every write command so the fired / not-fired branches stay
- * consistent.
+ * 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.fired) {
+export function emitWriteReport({ spinner, report, log, }) {
+    if (!report.changed) {
         spinner.warn(report.message);
         return;
     }

package/dist/lib/params.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function parseParams(pairs: string[]): Record<string, unknown>;

package/dist/lib/params.js

@@ -0,0 +1,26 @@
+function coerceValue(raw) {
+    try {
+        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;
+    }
+}
+function parsePair(pair) {
+    const eq = pair.indexOf('=');
+    if (eq < 1) {
+        throw new Error(`expected key=value, got "${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/select-deployment.d.ts

@@ -0,0 +1,31 @@
+import { type DeployTarget, type WorkflowConfig, type WorkflowDeployment } from '@sanity/workflow-engine';
+/**
+ * Pick the deployment for the requested `--tag`. Tags are unique across a
+ * config (enforced by defineWorkflowConfig), so a tag names at most one
+ * deployment.
+ *
+ * With no tag: fall back to the sole deployment when there's exactly one
+ * (the common single-environment case), otherwise fail asking for `--tag` —
+ * a multi-deployment config is ambiguous without it. `orAlternative` extends
+ * that ambiguity message for callers with another way out (deploy's `--all-tags`).
+ */
+export declare function selectDeployment(config: WorkflowConfig, { tag, orAlternative }: {
+    tag: string | undefined;
+    orAlternative?: string;
+}): WorkflowDeployment;
+/**
+ * The deployments a `deploy` run acts on: every one with `--all-tags`,
+ * otherwise a single target via {@link selectDeployment} and its failure
+ * modes. Deploying everything is an explicit opt-in — never a default — so an
+ * ambiguous bare `deploy` can't fan a write out across environments.
+ */
+export declare function selectDeployments(config: WorkflowConfig, { tag, allTags }: {
+    tag: string | undefined;
+    allTags: boolean;
+}): WorkflowDeployment[];
+/**
+ * Project a deployment into the engine's {@link DeployTarget} — the shape the
+ * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)
+ * consume — expanding its handle bindings into the alias map in the same step.
+ */
+export declare function deploymentToTarget(deployment: WorkflowDeployment): DeployTarget;