@sanity/workflow-cli 0.9.0 → 0.11.0

package/README.md

@@ -16,7 +16,7 @@ pnpm --filter @sanity/workflow-cli dev <command> [...args]
 # Examples:
 pnpm --filter @sanity/workflow-cli dev --help
 pnpm --filter @sanity/workflow-cli dev deploy --dry-run
-pnpm --filter @sanity/workflow-cli dev list --in-flight
+pnpm --filter @sanity/workflow-cli dev list --include-completed
 pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
 ```
 
@@ -24,6 +24,14 @@ Authenticate once with `sanity login` (the CLI reads that session token); for
 CI, set `SANITY_AUTH_TOKEN` instead. Then create a `sanity.workflow.ts` in the
 directory you run from — see [Configuration](#configuration).
 
+The token must span **every resource the workflow references**, not just the
+workflow resource. Runtime commands build one client from the deployment
+descriptor; when a workflow's subject or `doc.ref` fields point into other
+datasets (or a canvas / media library), the engine reaches them through
+sibling clients derived from that same token. A `sanity login` session or an
+org-capable token covers this out of the box; a token scoped to a single
+project will fail on cross-resource reads.
+
 ## Configuration
 
 The CLI is configured by a `sanity.workflow.ts` (or `.js`/`.mjs`) discovered in
@@ -71,10 +79,10 @@ runtime. Rule of thumb: **different resource → bind an alias and reference it
 entirely.** So the simplest single-dataset setup is just a `workflowResource`
 and `definitions`, with no `resourceAliases` at all.
 
-| Var                 | Purpose                                                                     |
-| ------------------- | --------------------------------------------------------------------------- |
-| `SANITY_AUTH_TOKEN` | CI fallback when there's no `sanity login` session (editor role for writes) |
-| `SANITY_API_HOST`   | Optional API host override (defaults to the prod API)                       |
+| Var                 | Purpose                                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `SANITY_AUTH_TOKEN` | Explicit token for CI / scripted use — wins over the `sanity login` session (editor role for writes) |
+| `SANITY_API_HOST`   | Optional API host override (defaults to the prod API)                                                |
 
 Run through the `dev` / `cli` scripts and the CLI itself and your
 `sanity.workflow.ts` load straight from TypeScript source: the scripts set
@@ -117,19 +125,60 @@ stale compiled output.
 | `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                             |
 | `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                   |
 | `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                            |
-| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields, `--as` for attribution)                                 |
-| `list`                                 | wired — `client.fetch` over `workflow.instance` documents (`--definition <name>` to filter)                                 |
+| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                         |
+| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                          |
 | `show <instance-id>`                   | wired — `client.getDocument`                                                                                                |
-| `diagnose <instance-id>`               | wired — one `workflow.evaluate` call, classifies why the instance is/isn't progressing                                      |
+| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, classifies why the instance is/isn't progressing                                         |
 | `tail <instance-id>`                   | wired — `client.listen()` over the instance, prints new history entries                                                     |
 | `abort <instance-id>`                  | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards)                                   |
 | `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run) |
-| `fire-action <instance-id>`            | wired — `workflow.evaluate` lists actions; `workflow.fireAction` fires one                                                  |
-| `definition list`                      | wired — `client.fetch` over `workflow.definition` documents                                                                 |
+| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                          |
+| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                          |
 | `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                   |
 | `definition diff <name>`               | wired — diffs the in-code definition against the deployed latest (`--version` to pin)                                       |
 | `definition delete <name>`             | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)                                    |
 
+## Telemetry
+
+The CLI collects usage telemetry through Sanity's standard pipeline: a
+per-command trace (`Editorial Workflows CLI Command Executed` — the command id, the
+names of declared flags used, never their values, and a success flag) plus
+the engine's adoption events from the operations it drives. Consent is the
+account-wide status managed by `npx sanity telemetry enable|disable|status`;
+CI and trueish `DO_NOT_TRACK` suppress everything (except a `deploy --share-defs`,
+which forces that deploy's telemetry — see [Definition sharing](#definition-sharing)),
+and a session that isn't logged in sends nothing. A one-time notice on stderr
+discloses collection on first use.
+
+One extension point: supply your own logger as `telemetry` in
+`sanity.workflow.ts` and the built-in pipeline is not constructed at all —
+every event flows to your implementation unconditionally (CI included), and
+consent, suppression, and destination become its business.
+
+## Definition sharing
+
+Separate from telemetry, a `deploy` that creates new definition versions
+donates those documents to Sanity — verbatim (structure, names, titles, GROQ
+filters, effect configuration, seeded values), plus their deployment
+coordinates (project and dataset, or resource id) — never content documents,
+instances, or your auth token. The documents go to Sanity's first-party
+definition-feedback endpoint, not the telemetry pipeline; telemetry carries
+only a content-free marker (content hash plus structural counts) per shared
+definition and a per-invocation decision event.
+
+Sharing is **opt-out**. Pass `--share-defs` to donate without being asked, or
+`--no-share-defs` to decline. With neither flag, an interactive terminal is
+asked **once** — the answer is remembered in your Sanity user config, so the
+prompt never repeats — before anything is sent; notice always precedes the
+send. Every later flagless deploy then prints a one-line reminder of the
+current state (sharing, or not) and the flag to change it, so an ongoing
+donation is never silent. Unattended runs (CI, `DO_NOT_TRACK`, a non-TTY pipe)
+can't prompt: by default they donate nothing (opt in per run with
+`--share-defs`). An explicit `--share-defs` also sends that deploy's telemetry
+regardless of CI / `DO_NOT_TRACK` — a command-line arg beats env vars;
+account-level `sanity telemetry disable` still applies. A failed share only
+warns, never failing a completed deploy.
+
 ## Known gaps
 
 - **No `sanity workflow` plugin wiring yet.** The proposal targets the
@@ -139,15 +188,18 @@ stale compiled output.
 - **No true bypass.** `set-stage` is the engine's `setStage` admin
   override: it skips the definition's declared transitions and filters, but
   the target stage's enter lifecycle and the post-move cascade still run. A
-  command that also bypasses guards + enter effects (`force-stage`) needs
-  engine work that hasn't landed.
-- **Actor identity.** Write paths default the actor to
-  `{ kind: "system", id: "workflow-cli" }` rather than resolving the real
-  user via `/users/me` (which a token-only CLI can't reach). `start` and
-  `fire-action` take `--as <userId>` / `--as-role <role>` to attribute the
-  write to a real user, so assignee- and role-gated filters pass. Once we
-  host inside the Sanity CLI's auth flow, the real user can flow through
-  everywhere.
+  true force-set that also bypasses guards + enter effects does not exist
+  yet — it needs engine work that hasn't landed.
+
+## Identity
+
+Identity is the token behind the configured client: the engine resolves the
+acting user (and their roles) from `/users/me`, so every write is attributed
+to whoever the token authenticates — there is no identity injection and no
+`--as` impersonation. Alongside that "who", the CLI declares an advisory
+"via what": every verb carries
+`executionContext: { kind: "cli", id: "workflow-cli" }`, stamped on history
+entries as provenance.
 
 ## Tech stack
 

package/bin/run.js

@@ -1,8 +1,4 @@
 #!/usr/bin/env node
-// Production entry for the published package: loads the compiled commands
-// from ./dist/commands (per the `oclif.commands` field). The dev counterpart,
-// bin/dev.js, passes `development: true` to load TS sources instead.
-
 import {execute} from '@oclif/core'
 
 await execute({dir: import.meta.url})

package/dist/commands/abort.d.ts

@@ -1,6 +1,7 @@
-import { Command } from '@oclif/core';
 import { type WorkflowInstance } from '@sanity/workflow-engine';
-export default class Abort extends Command {
+import { WorkflowCommand } from '../lib/base-command.ts';
+import { type WriteReport } from '../lib/ops-report.ts';
+export default class Abort extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
@@ -21,8 +22,5 @@ interface AbortOutcome {
  * aborted / already-terminal permutations can be asserted without driving
  * a real abort.
  */
-export declare function abortReport(result: AbortOutcome): {
-    changed: boolean;
-    message: string;
-};
+export declare function abortReport(result: AbortOutcome): WriteReport;
 export {};

package/dist/commands/abort.js

@@ -1,12 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
-import ora from 'ora';
+import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveInstanceContext } from "../lib/context.js";
-import { errorMessage, fail } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { buildOperationArgs } from "../lib/operation-args.js";
-export default class Abort extends Command {
+import { runWriteVerb } from "../lib/ops-report.js";
+export default class Abort extends WorkflowCommand {
     static description = 'Abort an in-flight workflow instance — a hard stop: pending effects are cancelled, stage guards lifted, and the instance is marked terminal where it stands.';
     static examples = [
         '<%= config.bin %> abort wf-instance.abc123',
@@ -22,34 +22,23 @@ export default class Abort extends Command {
     async run() {
         const { args, flags } = await this.parse(Abort);
         const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
-        const spinner = ora(`Aborting ${args.instanceId}…`).start();
-        try {
-            const result = await workflow.abortInstance({
+        await runWriteVerb({
+            startLabel: `Aborting ${args.instanceId}…`,
+            failLabel: 'Abort rejected',
+            failHeadline: 'abort error:',
+            run: () => workflow.abortInstance({
                 client,
                 ...buildOperationArgs({
                     scope,
                     instanceId: args.instanceId,
                     reason: flags.reason,
                 }),
-            });
-            const report = abortReport(result);
-            if (!report.changed) {
-                spinner.warn(report.message);
-                return;
-            }
-            spinner.succeed(report.message);
-        }
-        catch (error) {
-            spinner.fail('Abort rejected');
-            fail('abort error:', errorMessage(error));
-        }
+            }),
+            report: abortReport,
+            log: (line) => this.log(line),
+        });
     }
 }
-/**
- * Turn an `abortInstance` result into the spinner message. Pure so the
- * aborted / already-terminal permutations can be asserted without driving
- * a real abort.
- */
 export function abortReport(result) {
     const stage = styleText('bold', result.instance.currentStage);
     if (!result.changed) {

package/dist/commands/definition/delete.d.ts

@@ -1,7 +1,7 @@
-import { Command } from '@oclif/core';
 import { type DeleteDefinitionArgs, type DeleteDefinitionResult } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 import { type EngineScope } from '../../lib/operation-args.ts';
-export default class DefinitionDelete extends Command {
+export default class DefinitionDelete extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/definition/delete.js

@@ -1,12 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { workflow, } from '@sanity/workflow-engine';
-import ora from 'ora';
+import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveContext } from "../../lib/context.js";
-import { errorMessage, fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { SYSTEM_ACTOR, baseEngineArgs } from "../../lib/operation-args.js";
-export default class DefinitionDelete extends Command {
+import { baseEngineArgs } from "../../lib/operation-args.js";
+import { runWriteVerb } from "../../lib/ops-report.js";
+export default class DefinitionDelete extends WorkflowCommand {
     static description = 'Delete a deployed workflow definition (every version, or one via --version). ' +
         'Refuses while non-terminal instances exist unless --cascade aborts them first — ' +
         'instances are aborted in place, never deleted.';
@@ -35,41 +35,28 @@ export default class DefinitionDelete extends Command {
         const { args, flags } = await this.parse(DefinitionDelete);
         const { deployment, client } = await resolveContext(flags);
         const deleteArgs = buildDeleteArgs({ scope: deployment, name: args.name, flags });
-        const spinner = ora(`Deleting definition ${deleteTargetLabel(deleteArgs)}…`).start();
-        try {
-            const result = await workflow.deleteDefinition({ client, ...deleteArgs });
-            spinner.succeed(deleteReport(result));
-        }
-        catch (error) {
-            spinner.fail('Delete rejected');
-            fail('definition delete error:', errorMessage(error));
-        }
+        await runWriteVerb({
+            startLabel: `Deleting definition ${deleteTargetLabel(deleteArgs)}…`,
+            failLabel: 'Delete rejected',
+            failHeadline: 'definition delete error:',
+            run: () => workflow.deleteDefinition({ client, ...deleteArgs }),
+            report: (result) => ({ changed: true, message: deleteReport(result) }),
+            log: (line) => this.log(line),
+        });
     }
 }
-/**
- * The shared engine args ({@link baseEngineArgs}) plus the delete-specific
- * targeting. `version` and `reason` spread conditionally because the
- * engine's optionals reject an explicit `undefined` under
- * `exactOptionalPropertyTypes`.
- */
 export function buildDeleteArgs({ scope, name, flags, }) {
     return {
-        ...baseEngineArgs(scope, SYSTEM_ACTOR),
+        ...baseEngineArgs(scope),
         definition: name,
         cascade: flags.cascade,
         ...(flags.version !== undefined ? { version: flags.version } : {}),
         ...(flags.reason !== undefined ? { reason: flags.reason } : {}),
     };
 }
-/** What the spinner names: the workflow, or one pinned version of it. */
 export function deleteTargetLabel(args) {
     return args.version === undefined ? args.definition : `${args.definition} v${args.version}`;
 }
-/**
- * Turn a `deleteDefinition` result into the spinner message. Pure so the
- * version / cascade / guard permutations can be asserted without driving
- * a real delete.
- */
 export function deleteReport(result) {
     const versions = result.deletedVersions.map((v) => `v${v}`).join(', ');
     const parts = [`Deleted ${styleText('bold', result.name)} ${versions}`];

package/dist/commands/definition/diff.d.ts

@@ -1,6 +1,6 @@
-import { Command } from '@oclif/core';
 import { type WorkflowDefinition } from '@sanity/workflow-engine';
-export default class DefinitionDiff extends Command {
+import { WorkflowCommand } from '../../lib/base-command.ts';
+export default class DefinitionDiff extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/definition/diff.js

@@ -1,12 +1,13 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { diffEntry } from '@sanity/workflow-engine';
 import ora from 'ora';
+import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveContext } from "../../lib/context.js";
 import { fetchDeployedDefinition, selectDefinitions, validateOrFail } from "../../lib/definitions.js";
 import { diffReport } from "../../lib/diff.js";
 import { tagFlags } from "../../lib/flags.js";
 import { deploymentToTarget } from "../../lib/select-deployment.js";
-export default class DefinitionDiff extends Command {
+export default class DefinitionDiff extends WorkflowCommand {
     static description = 'Diff an in-code definition against the deployed version (latest by default).';
     static examples = [
         '<%= config.bin %> definition diff productLaunch',
@@ -27,8 +28,6 @@ export default class DefinitionDiff extends Command {
         const spinner = ora(`Diffing ${args.name} against deployed…`).start();
         let deployed;
         try {
-            // An absent latest is a legitimate "create" diff, so `undefined`
-            // flows straight into the diff entry.
             deployed = await fetchDeployedDefinition({
                 client,
                 name: args.name,
@@ -45,16 +44,8 @@ export default class DefinitionDiff extends Command {
             this.log(line);
     }
 }
-/**
- * Pick the single definition to diff by name and validate it, failing cleanly
- * when it's missing from the deployment or doesn't pass validation. Extracted
- * from `run` so the command's orchestration stays thin and this stays testable.
- */
 export function selectDefinitionToDiff(definitions, name) {
     const [def] = selectDefinitions(definitions, { only: name });
-    // selectDefinitions already fails on no-match (naming the available defs), so
-    // a named lookup always yields at least one — this narrows the type, it is
-    // not a reachable failure.
     if (def === undefined) {
         throw new Error(`selectDefinitions returned no match for "${name}"`);
     }

package/dist/commands/definition/list.d.ts

@@ -1,5 +1,4 @@
-import { Command } from '@oclif/core';
-import { type WorkflowLifecycle } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
 interface DefinitionListFlags {
     tag?: string | undefined;
     name?: string | undefined;
@@ -10,16 +9,16 @@ export interface DefinitionListRow {
     version: number;
     title: string;
     tag: string;
-    lifecycle?: WorkflowLifecycle;
     stageCount: number;
     inFlightCount: number;
     totalInstances: number;
+    _createdAt: string;
 }
 export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
     groq: string;
     params: Record<string, unknown>;
 };
-export default class DefinitionList extends Command {
+export default class DefinitionList extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/definition/list.js

@@ -1,20 +1,18 @@
-import { Command, Flags } from '@oclif/core';
-import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, isStartableDefinition, tagScopeFilter, } from '@sanity/workflow-engine';
-import { Table } from 'console-table-printer';
+import { Flags } from '@oclif/core';
+import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, inFlightFilter, tagScopeFilter, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { resolveReadContext } from "../../lib/context.js";
+import { WorkflowCommand } from "../../lib/base-command.js";
+import { resolveReadTargets } from "../../lib/context.js";
 import { tagFlags } from "../../lib/flags.js";
+import { runReadAcrossTargets } from "../../lib/read-fanout.js";
+import { clipToLimit, formatTable } from "../../lib/ui.js";
 export function buildDefinitionListQuery(flags) {
-    const params = { limit: flags.limit };
+    const params = { limit: flags.limit + 1 };
     const filters = [`_type == "${WORKFLOW_DEFINITION_TYPE}"`];
     const instanceFilters = [
         `_type == "${WORKFLOW_INSTANCE_TYPE}"`,
         'definition == ^.name',
         'pinnedVersion == ^.version',
-        // Correlate the count to each definition's own partition. Listing
-        // can span partitions (when `--tag` is omitted), and two partitions
-        // can hold a same-named, same-version definition — without this, one
-        // row's count would bleed in the other partition's instances.
         'tag == ^.tag',
     ];
     if (flags.tag) {
@@ -31,14 +29,14 @@ export function buildDefinitionListQuery(flags) {
       version,
       title,
       tag,
-      lifecycle,
+      _createdAt,
       "stageCount": count(stages),
-      "inFlightCount": count(*[${instanceMatch} && !defined(completedAt)]),
+      "inFlightCount": count(*[${instanceMatch} && ${inFlightFilter()}]),
       "totalInstances": count(*[${instanceMatch}])
     }`;
     return { groq, params };
 }
-export default class DefinitionList extends Command {
+export default class DefinitionList extends WorkflowCommand {
     static description = 'List deployed workflow definitions.';
     static examples = [
         '<%= config.bin %> definition list',
@@ -56,43 +54,39 @@ export default class DefinitionList extends Command {
     };
     async run() {
         const { flags } = await this.parse(DefinitionList);
-        const { client } = await resolveReadContext(flags);
+        const targets = await resolveReadTargets(flags);
         const { groq, params } = buildDefinitionListQuery(flags);
-        const rows = await client.fetch(groq, params);
-        if (!rows.length) {
-            this.log(`${logSymbols.info} no definitions found`);
-            return;
-        }
-        const table = new Table({
-            columns: [
-                { name: 'workflow', title: 'Workflow', alignment: 'left' },
-                { name: 'title', title: 'Title', alignment: 'left' },
-                { name: 'tag', title: 'Tag', alignment: 'left' },
-                { name: 'startable', title: 'Startable', alignment: 'center' },
-                { name: 'stageCount', title: 'Stages', alignment: 'right' },
-                { name: 'inFlightCount', title: 'In flight', alignment: 'right' },
-                { name: 'totalInstances', title: 'Instances', alignment: 'right' },
-            ],
+        const failures = await runReadAcrossTargets({
+            targets,
+            log: (line) => this.log(line),
+            run: async ({ client }) => {
+                const fetched = await client.fetch(groq, params, {
+                    tag: 'definition.list',
+                });
+                if (!fetched.length) {
+                    this.log(`${logSymbols.info} no definitions found`);
+                    return;
+                }
+                const { rows, note } = clipToLimit(fetched, flags.limit);
+                const lines = formatTable(['workflow', 'title', 'tag', 'stages', 'in flight', 'instances', 'created'], rows.map((r) => [
+                    `${r.name} v${r.version}`,
+                    r.title,
+                    r.tag,
+                    String(r.stageCount),
+                    String(r.inFlightCount),
+                    String(r.totalInstances),
+                    r._createdAt,
+                ]));
+                for (const line of lines) {
+                    this.log(line);
+                }
+                if (note) {
+                    this.log(note);
+                }
+            },
         });
-        for (const r of rows) {
-            // The doc `_id` is `tag.name.vN`, so a Definition ID column would just
-            // repeat Workflow + Tag — and no command takes an `_id` anyway (they take
-            // name + --tag/--version). `name vN` is this CLI's identifier format (the
-            // `definition show` title). Only declared keys are passed — console-table-
-            // printer renders any extra key as a stray column.
-            //
-            // `lifecycle: 'child'` defs are spawn-only; the Startable column tells an admin
-            // which definitions a human can actually start standalone.
-            table.addRow({
-                workflow: `${r.name} v${r.version}`,
-                title: r.title,
-                tag: r.tag,
-                startable: isStartableDefinition(r) ? 'yes' : 'spawn-only',
-                stageCount: r.stageCount,
-                inFlightCount: r.inFlightCount,
-                totalInstances: r.totalInstances,
-            });
+        if (failures.length > 0) {
+            this.exit(1);
         }
-        table.printTable();
     }
 }

package/dist/commands/definition/show.d.ts

@@ -1,6 +1,7 @@
-import { Command } from '@oclif/core';
-import { type WorkflowDefinition } from '@sanity/workflow-engine';
-export default class DefinitionShow extends Command {
+import { type DeployedDefinition, type WorkflowDefinition, type WorkflowResource } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../../lib/base-command.ts';
+import { type ReadTarget } from '../../lib/context.ts';
+export default class DefinitionShow extends WorkflowCommand {
     static description: string;
     static args: {
         name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
@@ -11,6 +12,37 @@ export default class DefinitionShow extends Command {
     };
     run(): Promise<void>;
 }
+/**
+ * Resolve the one definition `show` names, refusing every ambiguity: an
+ * untagged name spanning several tag partitions within a dataset
+ * ({@link assertSingleTagPartition}) and a name held by several datasets
+ * ({@link soleHitOrFail}) both error, never pick. `undefined` means nothing
+ * is deployed under the name.
+ */
+export declare function resolveShownDefinition({ targets, name, tag, version, }: {
+    targets: ReadTarget[];
+    name: string;
+    tag: string | undefined;
+    version: number | undefined;
+}): Promise<DeployedDefinition | undefined>;
+/** How a lookup names the version it asked for: `vN` for a pinned
+ *  `--version`, `latest` when unpinned. */
+export declare function versionLabel(version: number | undefined): string;
+/**
+ * One deployed document per target that has the name: the authored
+ * {@link WorkflowDefinition} plus the deploy-stamped envelope (`version`,
+ * `contentHash`, `tag`). A probe failure propagates — with an unreadable
+ * resource, "which dataset holds this name" is unanswerable, unlike an
+ * instance-id lookup where any hit IS the instance.
+ */
+export declare function fetchDefinitionHits({ targets, groq, params, }: {
+    targets: ReadTarget[];
+    groq: string;
+    params: Record<string, unknown>;
+}): Promise<{
+    resource: WorkflowResource;
+    def: DeployedDefinition;
+}[]>;
 /** The summary block at the top of `definition show`: a bold name + version
  *  title, then the human title, description, and deploy `tag` as aligned
  *  detail rows. `tag` is deployment metadata (the partition), not part of the