@sanity/workflow-cli 0.10.0 → 0.12.0

package/dist/commands/list.js

@@ -1,21 +1,34 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_INSTANCE_TYPE, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
+import { WORKFLOW_INSTANCE_TYPE, assertReadableModel, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveReadTargets } from "../lib/context.js";
+import { failOnThrow } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { runReadAcrossTargets } from "../lib/read-fanout.js";
 import { clipToLimit, formatAge, formatTable } from "../lib/ui.js";
 export function buildListQuery(flags) {
     const filters = [`_type == "${WORKFLOW_INSTANCE_TYPE}"`];
-    if (flags['in-flight'])
-        filters.push('!defined(completedAt)');
-    if (flags.definition)
+    const params = {};
+    if (!flags['include-completed'])
+        filters.push(inFlightFilter());
+    if (flags.definition) {
         filters.push('definition == $definition');
+        params['definition'] = flags.definition;
+    }
     if (flags.failed)
         filters.push('count(stages[].activities[status == "failed"]) > 0');
-    if (flags.tag)
+    if (flags.tag) {
         filters.push(tagScopeFilter());
+        params['tag'] = flags.tag;
+    }
+    if (flags.document) {
+        const armParams = {};
+        filters.push(`(${documentPrefilter([flags.document], armParams)})`);
+        Object.assign(params, armParams);
+        return { groq: `*[${filters.join(' && ')}] | order(lastChangedAt desc)`, params };
+    }
+    params['limit'] = flags.limit + 1;
     const groq = `*[${filters.join(' && ')}] | order(lastChangedAt desc) [0...$limit]{
       _id,
       definition,
@@ -23,13 +36,10 @@ export function buildListQuery(flags) {
       currentStage,
       completedAt,
       abortedAt,
-      lastChangedAt
+      lastChangedAt,
+      modelVersion,
+      minReaderModel
     }`;
-    const params = { limit: flags.limit + 1 };
-    if (flags.definition)
-        params['definition'] = flags.definition;
-    if (flags.tag)
-        params['tag'] = flags.tag;
     return { groq, params };
 }
 export function instanceRow(r) {
@@ -46,17 +56,18 @@ export function instanceRow(r) {
     };
 }
 export default class List extends WorkflowCommand {
-    static description = 'List workflow instances in the configured dataset.';
+    static description = 'List workflow instances in the configured dataset (in-flight by default).';
     static examples = [
         '<%= config.bin %> list',
-        '<%= config.bin %> list --in-flight',
+        '<%= config.bin %> list --include-completed',
         '<%= config.bin %> list --definition productLaunch',
+        '<%= config.bin %> list --document dataset:proj:ds:article-1',
         '<%= config.bin %> list --tag prod',
     ];
     static flags = {
         ...tagFlags,
-        'in-flight': Flags.boolean({
-            description: 'Only instances that have not completed.',
+        'include-completed': Flags.boolean({
+            description: 'Include completed/aborted instances (default: in-flight only).',
             default: false,
         }),
         failed: Flags.boolean({
@@ -66,6 +77,10 @@ export default class List extends WorkflowCommand {
         definition: Flags.string({
             description: "Only instances of this workflow definition (its `name`; the instance's `definition` field).",
         }),
+        document: Flags.string({
+            description: 'Only instances that reference this document (resource-qualified GDR URI, ' +
+                'e.g. "dataset:proj:ds:article-1").',
+        }),
         limit: Flags.integer({
             description: 'Maximum rows to return.',
             default: 50,
@@ -74,12 +89,13 @@ export default class List extends WorkflowCommand {
     async run() {
         const { flags } = await this.parse(List);
         const targets = await resolveReadTargets(flags);
-        const { groq, params } = buildListQuery(flags);
+        const { groq, params } = failOnThrow('Invalid --document:', () => buildListQuery(flags));
+        const document = flags.document;
         const failures = await runReadAcrossTargets({
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = await client.fetch(groq, params, { tag: 'list' });
+                const fetched = await fetchRows({ client, groq, params, document });
                 if (fetched.length === 0) {
                     this.log(`${logSymbols.info} no instances match`);
                     return;
@@ -109,3 +125,13 @@ export default class List extends WorkflowCommand {
         }
     }
 }
+async function fetchRows({ client, groq, params, document, }) {
+    if (document === undefined) {
+        const rows = await client.fetch(groq, params, { tag: 'list' });
+        return rows.map(assertReadableModel);
+    }
+    const candidates = await client.fetch(groq, params, { tag: 'list' });
+    return candidates
+        .map(assertReadableModel)
+        .filter((instance) => instanceWatchesDocument(instance, document));
+}

package/dist/commands/nuke.d.ts

@@ -0,0 +1,11 @@
+import { WorkflowCommand } from '../lib/base-command.ts';
+export default class Nuke extends WorkflowCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/nuke.js

@@ -0,0 +1,76 @@
+import { Flags } from '@oclif/core';
+import { input } from '@sanity/cli-core/ux';
+import { resourceGdr } from '@sanity/workflow-engine';
+import logSymbols from 'log-symbols';
+import { WorkflowCommand } from "../lib/base-command.js";
+import { clientFor, resolveApiHost, resolveTokenOrFail } from "../lib/client.js";
+import { dedupeResources } from "../lib/context.js";
+import { fail } from "../lib/fail.js";
+import { loadWorkflowConfig } from "../lib/load-config.js";
+import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, renderNukePlan, resolveNukePlan, } from "../lib/nuke.js";
+import { runWriteVerb } from "../lib/ops-report.js";
+import { canPromptOnStderr } from "../lib/prompt.js";
+import { selectDeployment } from "../lib/select-deployment.js";
+export default class Nuke extends WorkflowCommand {
+    static summary = 'Delete every engine-owned document for a deployment tag — the dev-period big red button.';
+    static description = 'The reset for a dataset holding engine documents the versioned upgrade framework cannot yet ' +
+        "migrate: deletes the tag's instances, definitions, and guards (across every alias-bound " +
+        'resource). Content documents are never touched. Prints a dry-run plan, then requires you to ' +
+        'type back every involved dataset (--force skips the prompt; the plan still prints).';
+    static examples = [
+        '<%= config.bin %> nuke --tag plugin-dev',
+        '<%= config.bin %> nuke --tag plugin-dev --force',
+    ];
+    static flags = {
+        tag: Flags.string({
+            description: 'The deployment tag to reset. Required — a destructive reset never guesses the environment.',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Nuke);
+        const config = await loadWorkflowConfig();
+        const deployment = selectDeployment(config, { tag: flags.tag });
+        const targets = buildTargets(deployment, await resolveTokenOrFail());
+        const plan = await resolveNukePlan({ tag: deployment.tag, targets });
+        const apiHost = resolveApiHost() ?? 'https://api.sanity.io (production default)';
+        renderNukePlan(plan, apiHost).forEach((line) => this.log(line));
+        const counts = planCounts(plan);
+        if (counts.total === 0) {
+            this.log(`${logSymbols.info} Nothing to nuke for tag "${deployment.tag}".`);
+            return;
+        }
+        if (!flags.force)
+            await confirmOrFail(involvedTargets(plan));
+        await runWriteVerb({
+            startLabel: 'Nuking…',
+            failLabel: 'Nuke failed',
+            failHeadline: 'workflow nuke error:',
+            run: () => executeNuke(plan),
+            report: () => ({ changed: true, message: formatNukeSummary(deployment.tag, counts) }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+function buildTargets(deployment, token) {
+    const engineResource = deployment.workflowResource;
+    const aliasResources = (deployment.resourceAliases ?? []).map((binding) => binding.resource);
+    return dedupeResources([engineResource, ...aliasResources]).map((resource) => ({
+        resource,
+        client: clientFor(resource, token),
+        holdsEngineDocs: resourceGdr(resource) === resourceGdr(engineResource),
+    }));
+}
+async function confirmOrFail(targets) {
+    if (!canPromptOnStderr()) {
+        fail('Refusing to nuke without confirmation in a non-interactive shell.', 'Re-run with --force to skip the prompt.');
+    }
+    const answer = await input({ message: `Type every target to confirm deletion (space-separated):\n  ${targets.join(' ')}\n` }, { output: process.stderr });
+    if (!confirmationMatches(answer, targets)) {
+        fail('Confirmation did not match — nothing was deleted.', `Expected: ${targets.join(' ')}`);
+    }
+}

package/dist/commands/start.d.ts

@@ -1,4 +1,4 @@
-import { type FieldEntry, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance, type WorkflowLifecycle } from '@sanity/workflow-engine';
+import { StartNotSettledError, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../lib/base-command.ts';
 import { type EngineScope } from '../lib/operation-args.ts';
 export default class Start extends WorkflowCommand {
@@ -11,41 +11,35 @@ export default class Start extends WorkflowCommand {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         field: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'instance-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }
-/**
- * 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 declare function startRefusal(definition: {
-    lifecycle?: WorkflowLifecycle | undefined;
-}): string | undefined;
-/**
- * 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 declare function buildInitialFields({ declared, values, }: {
-    declared: Pick<FieldEntry, 'type' | 'name' | 'initialValue'>[];
-    values: Record<string, unknown>;
-}): InitialFieldValue[];
+/** A created-but-unprimed failure is resumable — the engine message names
+ *  the id and the generic remediation; operators need the CLI's own retry
+ *  spelling appended. Every other error passes through untouched. */
+export declare function withRetryHint(error: unknown): unknown;
+/** The spinner message for a start whose first cascade failed after the
+ *  instance was created and primed: the run exists — say so, name the cause,
+ *  and point at the retry rail instead of reporting a rejection. */
+export declare function startNotSettledReport(error: StartNotSettledError): string;
+/** The `--json` payload for a not-settled start — same `instanceId` key as
+ *  the success payload so scripts can pick up the retry id either way. */
+export declare function startNotSettledJson(error: StartNotSettledError): Record<string, unknown>;
 /**
  * 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 declare function buildStartArgs({ scope, name, version, initialFields, }: {
+export declare function buildStartArgs({ scope, name, version, initialFields, instanceId, }: {
     scope: EngineScope;
     name: string;
     version: number | undefined;
     initialFields: InitialFieldValue[];
+    /** The start's idempotency key (`--instance-id`) — a retry carrying it
+     *  resumes the earlier attempt instead of creating a duplicate. */
+    instanceId?: string | undefined;
 }): StartInstanceArgs & EngineScope;
 /** The success spinner message. Pure so the in-flight / immediately-terminal
  *  permutations can be asserted without driving a real start. */

package/dist/commands/start.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { isStartableDefinition, workflow, } from '@sanity/workflow-engine';
+import { buildInitialFields, errorMessage, StartNotPrimedError, StartNotSettledError, startRefusal, workflow, } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveContext } from "../lib/context.js";
 import { fetchDeployedDefinition } from "../lib/definitions.js";
@@ -16,6 +16,7 @@ export default class Start extends WorkflowCommand {
         '<%= config.bin %> start productLaunch',
         '<%= config.bin %> start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
         '<%= config.bin %> start productLaunch --version 2 --tag prod',
+        '<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6',
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
@@ -32,6 +33,12 @@ export default class Start extends WorkflowCommand {
             multiple: true,
             default: [],
         }),
+        'instance-id': Flags.string({
+            description: "Start under this instance id — for retries. The id is the start's idempotency key: " +
+                'pass the id of a start that failed partway and the engine resumes it instead of ' +
+                'creating a duplicate (an already-settled start replays as a no-op). Omit to mint ' +
+                'a fresh id.',
+        }),
         ...jsonFlags,
     };
     async run() {
@@ -52,25 +59,58 @@ export default class Start extends WorkflowCommand {
                 name: args.name,
                 version: flags.version,
                 initialFields,
+                instanceId: flags['instance-id'],
             }),
         };
         if (flags.json) {
-            const result = await workflow
-                .startInstance(startArgs)
-                .catch((error) => fail('start error:', failureDetail(error)));
-            this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            const result = await workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError) {
+                    this.log(JSON.stringify(startNotSettledJson(error), null, 2));
+                    return undefined;
+                }
+                fail('start error:', failureDetail(withRetryHint(error)));
+            });
+            if (result !== undefined) {
+                this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            }
             return;
         }
         await runWriteVerb({
             startLabel: `Starting ${args.name}…`,
             failLabel: 'Start rejected',
             failHeadline: 'start error:',
-            run: () => workflow.startInstance(startArgs),
-            report: (result) => ({ changed: true, message: startReport(result.instance) }),
+            run: () => workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError)
+                    return error;
+                throw withRetryHint(error);
+            }),
+            report: (result) => result instanceof StartNotSettledError
+                ? { changed: false, message: startNotSettledReport(result) }
+                : { changed: true, message: startReport(result.instance) },
             log: (line) => this.log(line),
         });
     }
 }
+export function withRetryHint(error) {
+    return error instanceof StartNotPrimedError
+        ? new Error(`${errorMessage(error)} (--instance-id ${error.instanceId})`)
+        : error;
+}
+export function startNotSettledReport(error) {
+    const id = styleText('bold', error.instanceId);
+    return (`Started ${id} — but its first auto-advance failed: ${errorMessage(error.cause)}. ` +
+        `It settles on the next tick, or retry with --instance-id ${error.instanceId}.`);
+}
+export function startNotSettledJson(error) {
+    return {
+        instanceId: error.instanceId,
+        notSettled: true,
+        detail: errorMessage(error.cause),
+        ...(error.instance !== undefined
+            ? { currentStage: error.instance.currentStage, definition: error.instance.definition }
+            : {}),
+    };
+}
 async function resolveStartInputs({ client, name, tag, version, values, }) {
     const deployed = await fetchDeployedDefinition({ client, name, tag, version });
     if (deployed === undefined) {
@@ -82,37 +122,13 @@ async function resolveStartInputs({ client, name, tag, version, values, }) {
     }
     return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
 }
-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";
-}
-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.'));
-        }
-        return { type: entry.type, name, value };
-    });
-}
-export function buildStartArgs({ scope, name, version, initialFields, }) {
+export function buildStartArgs({ scope, name, version, initialFields, instanceId, }) {
     return {
         ...baseEngineArgs(scope),
         definition: name,
         ...(version !== undefined ? { version } : {}),
         ...(initialFields.length > 0 ? { initialFields } : {}),
+        ...(instanceId !== undefined ? { instanceId } : {}),
     };
 }
 export function startReport(instance) {

package/dist/commands/tail.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args } from '@oclif/core';
-import { displayTitle, errorMessage } from '@sanity/workflow-engine';
+import { assertReadableModel, displayTitle, errorMessage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { findInstance, resolveReadTargets } from "../lib/context.js";
@@ -31,7 +31,11 @@ export default class Tail extends WorkflowCommand {
         this.log(styleText('dim', `tailing ${styleText('bold', args.instanceId)} (${initial.definition} v${initial.pinnedVersion}, ${initial.history.length} prior entries, currently in ${initial.currentStage})`));
         this.log(styleText('dim', 'Ctrl+C to stop'));
         this.log('');
-        let seen = initial.history.length;
+        let rejectListen;
+        const listenFailed = new Promise((_, reject) => {
+            rejectListen = reject;
+        });
+        let printChain = Promise.resolve(initial.history.length);
         const subscription = client
             .listen(`*[_id == $id]`, { id: args.instanceId }, {
             includeResult: false,
@@ -39,17 +43,13 @@ export default class Tail extends WorkflowCommand {
             tag: TAIL_TAG,
         })
             .subscribe({
-            next: async () => {
-                try {
-                    seen = await this.printNewEntries({ client, instanceId: args.instanceId, seen });
-                }
-                catch (err) {
+            next: () => {
+                printChain = printChain.then((seen) => this.printNewEntries({ client, instanceId: args.instanceId, seen }).catch((err) => {
                     process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${errorMessage(err)}\n`);
-                }
-            },
-            error: (err) => {
-                fail('Listen subscription error:', failureDetail(err));
+                    return seen;
+                }));
             },
+            error: rejectListen,
         });
         const shutdown = () => {
             subscription.unsubscribe();
@@ -58,16 +58,20 @@ export default class Tail extends WorkflowCommand {
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
-        await new Promise(() => { });
+        await listenFailed.catch((err) => {
+            subscription.unsubscribe();
+            fail('Listen subscription error:', failureDetail(err));
+        });
     }
     async printNewEntries({ client, instanceId, seen, }) {
-        const next = await client.getDocument(instanceId, { tag: TAIL_TAG });
-        if (!next)
+        const raw = await client.getDocument(instanceId, { tag: TAIL_TAG });
+        if (!raw)
             return seen;
+        const next = assertReadableModel(raw);
         const newEntries = next.history.slice(seen);
         for (const entry of newEntries) {
             this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', displayTitle(entry._type))}`);
         }
-        return next.history.length;
+        return Math.max(seen, next.history.length);
     }
 }

package/dist/hooks/prerun/telemetry.d.ts

@@ -1,5 +1,8 @@
 import type { Hook } from '@oclif/core';
 /** Builds and installs the invocation's telemetry shell before the command
- *  runs; the `finally` hook completes the trace and flushes. Never throws. */
+ *  runs; the `finally` hook completes the trace and flushes. Never throws.
+ *  An explicit `--share-defs` forces the store to send despite CI /
+ *  `DO_NOT_TRACK` — resolved from raw argv here, since the store is built
+ *  before oclif parses flags. */
 declare const hook: Hook<'prerun'>;
 export default hook;

package/dist/hooks/prerun/telemetry.js

@@ -1,5 +1,9 @@
+import { shouldForceShareTelemetry } from "../../lib/share-definitions.js";
 import { setupCliTelemetry } from "../../lib/telemetry-setup.js";
-const hook = async function ({ config }) {
-    await setupCliTelemetry({ cliVersion: config.version });
+const hook = async function ({ config, Command, argv }) {
+    await setupCliTelemetry({
+        cliVersion: config.version,
+        forceSend: shouldForceShareTelemetry({ commandId: Command?.id, argv }),
+    });
 };
 export default hook;

package/dist/lib/client.d.ts

@@ -1,5 +1,13 @@
 import { type SanityClient } from '@sanity/client';
 import { type WorkflowResource } from '@sanity/workflow-engine';
+/**
+ * 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 (`undefined` here). Pairs with
+ * {@link resolveToken}, which reads the matching session token. Exported so a
+ * destructive command can display the environment its clients will hit.
+ */
+export declare function resolveApiHost(): string | undefined;
 /**
  * Resolve the Sanity auth token. An explicit `SANITY_AUTH_TOKEN` wins (CI /
  * scripted use); otherwise fall back to the `sanity login` session token.

package/dist/lib/client.js

@@ -5,7 +5,7 @@ import { ENV, envAuthToken } from "./env.js";
 import { fail } from "./fail.js";
 const API_VERSION = ENGINE_API_VERSION;
 const STAGING_API_HOST = 'https://api.sanity.work';
-function resolveApiHost() {
+export function resolveApiHost() {
     return process.env[ENV.SANITY_API_HOST] ?? (isStaging() ? STAGING_API_HOST : undefined);
 }
 export async function resolveToken() {

package/dist/lib/context.d.ts

@@ -1,5 +1,5 @@
 import type { SanityClient } from '@sanity/client';
-import type { WorkflowConfig, WorkflowDeployment, WorkflowInstance, WorkflowResource } from '@sanity/workflow-engine';
+import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import type { EngineScope } from './operation-args.ts';
 export interface DeploymentContext {
     deployment: WorkflowDeployment;
@@ -40,9 +40,13 @@ export interface ReadTarget {
 export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
 }): Promise<ReadTarget[]>;
+/** Distinct resources, keyed by their resource-shaped GDR (`<type>:<id>`).
+ *  The first occurrence wins its position, so a caller-ordered list (e.g. the
+ *  engine resource first) keeps its lead entry. */
+export declare function dedupeResources(resources: WorkflowResource[]): WorkflowResource[];
 /** The distinct resources a read targets: the tagged deployment's sole
  *  resource, or — untagged — every distinct one the config's deployments
- *  mention (deduped by `type:id`). */
+ *  mention ({@link dedupeResources}). */
 export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
 /** The single resource a read should target, or fail asking which when the
  *  config spans more than one. For the paths that need one definite dataset

package/dist/lib/context.js

@@ -1,3 +1,4 @@
+import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
@@ -14,15 +15,14 @@ export async function resolveReadTargets(flags) {
     const token = await resolveTokenOrFail();
     return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
 }
+export function dedupeResources(resources) {
+    return [...new Map(resources.map((resource) => [resourceGdr(resource), resource])).values()];
+}
 export function resolveReadResources(config, tag) {
     if (tag !== undefined) {
         return [selectDeployment(config, { tag }).workflowResource];
     }
-    const byKey = new Map(config.deployments.map((d) => [
-        `${d.workflowResource.type}:${d.workflowResource.id}`,
-        d.workflowResource,
-    ]));
-    const resources = [...byKey.values()];
+    const resources = dedupeResources(config.deployments.map((d) => d.workflowResource));
     if (resources.length === 0) {
         fail('No deployments configured.');
     }
@@ -51,7 +51,7 @@ export async function loadInstanceOrFail(client, instanceId) {
     if (!instance) {
         fail(`Workflow instance ${instanceId} not found`);
     }
-    return instance;
+    return assertReadableModel(instance);
 }
 export function soleHitOrFail(hits, subject) {
     const [sole, ...rest] = hits;
@@ -65,7 +65,9 @@ export async function findInstance({ targets, instanceId, requestTag, }) {
         const instance = await target.client.getDocument(instanceId, {
             tag: requestTag,
         });
-        return instance === undefined ? undefined : { ...target, instance };
+        return instance === undefined
+            ? undefined
+            : { ...target, instance: assertReadableModel(instance) };
     }));
     const hits = probes
         .filter((probe) => probe.status === 'fulfilled')

package/dist/lib/definitions.d.ts

@@ -9,6 +9,16 @@ export declare function buildDefinitionShowQuery(flags: DefinitionShowQueryArgs)
     groq: string;
     params: Record<string, unknown>;
 };
+/**
+ * The tag partitions holding any version of a definition name within one
+ * dataset. An untagged lookup that would span several partitions must error
+ * (the highest version ACROSS partitions is meaningless — it could show a
+ * prod operator the dev definition), the same way a cross-dataset hit does.
+ */
+export declare function buildDefinitionTagsQuery(name: string): {
+    groq: string;
+    params: Record<string, unknown>;
+};
 /**
  * Fetch the deployed definition a command targets — latest unless pinned via
  * `version`. An absent pinned version always fails (the caller asked for

package/dist/lib/definitions.js

@@ -1,4 +1,4 @@
-import { WORKFLOW_DEFINITION_TYPE, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, assertReadableModel, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
 export function buildDefinitionShowQuery(flags) {
     const params = { name: flags.name };
@@ -14,6 +14,12 @@ export function buildDefinitionShowQuery(flags) {
     const groq = `*[${filters.join(' && ')}] | order(version desc) [0]`;
     return { groq, params };
 }
+export function buildDefinitionTagsQuery(name) {
+    return {
+        groq: `array::unique(*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $name].tag)`,
+        params: { name },
+    };
+}
 export async function fetchDeployedDefinition({ client, name, tag, version, }) {
     const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
     const deployed = await client.fetch(groq, params, {
@@ -22,7 +28,7 @@ export async function fetchDeployedDefinition({ client, name, tag, version, }) {
     if (deployed === null && version !== undefined) {
         fail(`No deployed definition "${name}" v${version}.`);
     }
-    return deployed ?? undefined;
+    return deployed === null ? undefined : assertReadableModel(deployed);
 }
 export function selectDefinitions(allDefinitions, { only, context = '' }) {
     if (!only) {

package/dist/lib/fail.d.ts

@@ -3,6 +3,13 @@
  * 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.
  */