@sanity/workflow-cli 0.9.0 → 0.10.0

package/dist/commands/start.js

@@ -1,20 +1,20 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { isStartableDefinition, workflow, } from '@sanity/workflow-engine';
-import ora from 'ora';
+import { WorkflowCommand } from "../lib/base-command.js";
 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 { fail, failOnThrow, failureDetail } from "../lib/fail.js";
+import { jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs } from "../lib/operation-args.js";
+import { runWriteVerb } from "../lib/ops-report.js";
 import { parseParams } from "../lib/params.js";
-export default class Start extends Command {
+export default class Start extends WorkflowCommand {
     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 = {
@@ -32,13 +32,11 @@ export default class Start extends Command {
             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,
@@ -54,33 +52,25 @@ export default class Start extends Command {
                 name: args.name,
                 version: flags.version,
                 initialFields,
-                actor,
             }),
         };
         if (flags.json) {
             const result = await workflow
                 .startInstance(startArgs)
-                .catch((error) => fail('start error:', errorMessage(error)));
+                .catch((error) => fail('start error:', failureDetail(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));
-        }
+        await runWriteVerb({
+            startLabel: `Starting ${args.name}…`,
+            failLabel: 'Start rejected',
+            failHeadline: 'start error:',
+            run: () => workflow.startInstance(startArgs),
+            report: (result) => ({ changed: true, message: startReport(result.instance) }),
+            log: (line) => this.log(line),
+        });
     }
 }
-/**
- * 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) {
@@ -92,26 +82,12 @@ async function resolveStartInputs({ client, name, tag, version, values, }) {
     }
     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(', ');
@@ -128,26 +104,17 @@ export function buildInitialFields({ declared, values, }) {
                     ? `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, }) {
+export function buildStartArgs({ scope, name, version, initialFields, }) {
     return {
-        ...baseEngineArgs(scope, actor),
+        ...baseEngineArgs(scope),
         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);
@@ -155,9 +122,6 @@ export function startReport(instance) {
         ? `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,

package/dist/commands/tail.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class Tail extends Command {
+import { WorkflowCommand } from '../lib/base-command.ts';
+export default class Tail extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/tail.js

@@ -1,11 +1,14 @@
 import { styleText } from 'node:util';
-import { Args, Command } from '@oclif/core';
+import { Args } from '@oclif/core';
+import { displayTitle, errorMessage } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { resolveReadContext } from "../lib/context.js";
-import { fail } from "../lib/fail.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { findInstance, resolveReadTargets } from "../lib/context.js";
+import { fail, failureDetail } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { formatTimestamp } from "../lib/ui.js";
-export default class Tail extends Command {
+const TAIL_TAG = 'tail';
+export default class Tail extends WorkflowCommand {
     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 = {
@@ -19,34 +22,33 @@ export default class Tail extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Tail);
-        const { client } = await resolveReadContext(flags);
-        const initial = await client.getDocument(args.instanceId);
-        if (!initial) {
+        const targets = await resolveReadTargets(flags);
+        const hit = await findInstance({ targets, instanceId: args.instanceId, requestTag: TAIL_TAG });
+        if (!hit) {
             fail(`No instance with id "${args.instanceId}"`);
         }
+        const { client, instance: initial } = hit;
         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('');
-        // 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' })
+            .listen(`*[_id == $id]`, { id: args.instanceId }, {
+            includeResult: false,
+            visibility: 'query',
+            tag: TAIL_TAG,
+        })
             .subscribe({
             next: async () => {
                 try {
                     seen = await this.printNewEntries({ client, instanceId: args.instanceId, seen });
                 }
                 catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${message}\n`);
+                    process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${errorMessage(err)}\n`);
                 }
             },
             error: (err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                fail('Listen subscription error:', message);
+                fail('Listen subscription error:', failureDetail(err));
             },
         });
         const shutdown = () => {
@@ -56,22 +58,15 @@ export default class Tail extends Command {
         };
         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);
+        const next = await client.getDocument(instanceId, { tag: TAIL_TAG });
         if (!next)
             return seen;
         const newEntries = next.history.slice(seen);
         for (const entry of newEntries) {
-            this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', entry._type)}`);
+            this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', displayTitle(entry._type))}`);
         }
         return next.history.length;
     }

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

@@ -0,0 +1,8 @@
+import type { Hook } from '@oclif/core';
+/**
+ * Completes the command trace — command id, declared-flag names, success —
+ * and flushes the final batch. Runs on success and on error alike (oclif's
+ * `finally`); an invocation the prerun hook left with telemetry off no-ops.
+ */
+declare const hook: Hook<'finally'>;
+export default hook;

package/dist/hooks/finally/telemetry.js

@@ -0,0 +1,13 @@
+import { finishCliTelemetry, usedFlagNames } from "../../lib/telemetry.js";
+const hook = async function (options) {
+    try {
+        await finishCliTelemetry({
+            command: options.id,
+            flags: usedFlagNames(options.argv, options.Command?.flags),
+            success: options.error === undefined,
+        });
+    }
+    catch {
+    }
+};
+export default hook;

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

@@ -0,0 +1,5 @@
+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. */
+declare const hook: Hook<'prerun'>;
+export default hook;

package/dist/hooks/prerun/telemetry.js

@@ -0,0 +1,5 @@
+import { setupCliTelemetry } from "../../lib/telemetry-setup.js";
+const hook = async function ({ config }) {
+    await setupCliTelemetry({ cliVersion: config.version });
+};
+export default hook;

package/dist/index.js

@@ -1,4 +1 @@
-// 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/base-command.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+/**
+ * Base for the API-backed workflow commands: the backstop that renders an
+ * auth rejection (HTTP 401) escaping a command's `run` through the clean
+ * {@link fail} path — with {@link failureDetail}'s recovery hint — instead
+ * of an oclif error dump. Errors caught inside commands render the same
+ * detail at their own `fail` sites; every other error propagates to oclif
+ * unchanged.
+ */
+export declare abstract class WorkflowCommand extends Command {
+    protected catch(err: Error & {
+        exitCode?: number;
+    }): Promise<unknown>;
+}

package/dist/lib/base-command.js

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+import { fail, failureDetail, isAuthRejection } from "./fail.js";
+export class WorkflowCommand extends Command {
+    async catch(err) {
+        if (isAuthRejection(err)) {
+            fail('Authentication failed:', failureDetail(err));
+        }
+        return super.catch(err);
+    }
+}

package/dist/lib/client.js

@@ -1,28 +1,16 @@
 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 { clientConfigFromResource, ENGINE_API_VERSION, errorMessage, } from '@sanity/workflow-engine';
+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';
-/**
- * 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) {
+    const fromEnv = envAuthToken();
+    if (fromEnv !== undefined) {
         return fromEnv;
     }
     const fromSession = await getCliToken();
@@ -31,22 +19,17 @@ export async function resolveToken() {
     }
     throw new Error('No Sanity token found — run `sanity login`, or set SANITY_AUTH_TOKEN.');
 }
-/** {@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)));
+    return resolveToken().catch((err) => fail('Authentication required:', errorMessage(err)));
 }
-/** 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 });
+    const baseParams = {
+        token,
+        apiVersion: API_VERSION,
+        useCdn: false,
+        requestTagPrefix: 'sanity.workflows.cli',
+        ...(apiHost ? { apiHost } : {}),
+    };
+    return createClient({ ...baseParams, ...clientConfigFromResource(resource) });
 }

package/dist/lib/context.d.ts

@@ -20,24 +20,34 @@ export interface InstanceContext {
 export declare function resolveContext(flags: {
     tag?: string | undefined;
 }): Promise<DeploymentContext>;
+/** One resource a read inspects, with its authenticated client. */
+export interface ReadTarget {
+    resource: WorkflowResource;
+    client: SanityClient;
+}
 /**
- * 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.
+ * The resolution every READ shares: an authenticated client per 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 resources 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.
+ * Untagged, this is every distinct resource the config mentions — a read is
+ * harmless to fan out, so "show me what's deployed" spans the whole config.
+ * `--tag` narrows to that deployment's resource. The token resolves once for
+ * the run, however many targets it spans.
  */
-export declare function resolveReadContext(flags: {
+export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
-}): Promise<{
-    client: SanityClient;
-}>;
+}): Promise<ReadTarget[]>;
+/** 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`). */
+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. */
+ *  config spans more than one. For the paths that need one definite dataset
+ *  (the instance-targeted verbs); listings fan out via
+ *  {@link resolveReadResources} instead. */
 export declare function resolveReadResource(config: WorkflowConfig, tag: string | undefined): WorkflowResource;
 /**
  * The resolution an instance-id-targeted command shares, read or write: an
@@ -60,3 +70,29 @@ export declare function resolveInstanceContext(flags: {
  *  {@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>;
+/** A read target that turned out to hold the instance being looked up. */
+export interface InstanceHit extends ReadTarget {
+    instance: WorkflowInstance;
+}
+/**
+ * The sole cross-resource hit, or fail listing every holding resource —
+ * ambiguity across datasets must error, never pick. `subject` names the
+ * thing being looked up in the diagnostic (`Instance <id>`, `Definition "x"`).
+ */
+export declare function soleHitOrFail<T extends {
+    resource: WorkflowResource;
+}>(hits: T[], subject: string): T | undefined;
+/**
+ * Look an instance id up across every read target. Exactly one hit wins —
+ * instance ids are random and collision-free, so a single match IS the
+ * instance. Several hits (id reuse across datasets) fail listing the
+ * resources rather than silently picking one. `undefined` means confidently
+ * not found: when a probe throws and no other target has the id, that error
+ * propagates instead — an unreadable dataset must not masquerade as "no such
+ * instance".
+ */
+export declare function findInstance({ targets, instanceId, requestTag, }: {
+    targets: ReadTarget[];
+    instanceId: string;
+    requestTag: string;
+}): Promise<InstanceHit | undefined>;

package/dist/lib/context.js

@@ -2,66 +2,41 @@ 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.
- */
+import { resourceLabel } from "./ui.js";
 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) {
+export async function resolveReadTargets(flags) {
     const config = await loadWorkflowConfig();
-    return { client: clientFor(resolveReadResource(config, flags.tag), await resolveTokenOrFail()) };
+    const resources = resolveReadResources(config, flags.tag);
+    const token = await resolveTokenOrFail();
+    return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
 }
-/** The single resource a read should target, or fail asking which when the
- *  config spans more than one. */
-export function resolveReadResource(config, tag) {
+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 [sole] = resources;
-    if (sole === undefined) {
+    if (resources.length === 0) {
         fail('No deployments configured.');
     }
-    if (resources.length === 1) {
+    return resources;
+}
+export function resolveReadResource(config, tag) {
+    const resources = resolveReadResources(config, tag);
+    const [sole] = resources;
+    if (resources.length === 1 && sole !== undefined) {
         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;
+    const tags = config.deployments.map((d) => d.tag).join(', ');
+    fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
 }
-/**
- * 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);
@@ -69,14 +44,40 @@ export async function resolveInstanceContext(flags, instanceId) {
     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);
+    const instance = await client.getDocument(instanceId, {
+        tag: 'instance.load',
+    });
     if (!instance) {
         fail(`Workflow instance ${instanceId} not found`);
     }
     return instance;
 }
+export function soleHitOrFail(hits, subject) {
+    const [sole, ...rest] = hits;
+    if (rest.length > 0) {
+        fail(`${subject} exists in several resources — pass --tag to choose one.`, hits.map((hit) => resourceLabel(hit.resource)).join('\n'));
+    }
+    return sole;
+}
+export async function findInstance({ targets, instanceId, requestTag, }) {
+    const probes = await Promise.allSettled(targets.map(async (target) => {
+        const instance = await target.client.getDocument(instanceId, {
+            tag: requestTag,
+        });
+        return instance === undefined ? undefined : { ...target, instance };
+    }));
+    const hits = probes
+        .filter((probe) => probe.status === 'fulfilled')
+        .map((probe) => probe.value)
+        .filter((hit) => hit !== undefined);
+    const sole = soleHitOrFail(hits, `Instance ${instanceId}`);
+    if (sole !== undefined) {
+        return sole;
+    }
+    const failedProbe = probes.find((probe) => probe.status === 'rejected');
+    if (failedProbe !== undefined) {
+        throw failedProbe.reason;
+    }
+    return undefined;
+}