@sanity/workflow-cli 0.13.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @sanity/workflow-cli
 
+## 0.20.0
+
+### Minor Changes
+
+- 6e2a066: Ambiguous deployment/resource selection now prompts on an interactive terminal instead of only erroring. When a config has several deployments and no selector is given, `start`, `definition diff`, and `definition delete` show the same deployment picker `deploy` already offered. The instance-targeted commands (`abort`, `set-stage`, `fire-action`, `diagnose`) show that picker too when the config spans several resources — the interactive counterpart to their `--deployment` selector, reading from the chosen deployment's resource. Non-interactive runs (CI, piped output) keep the existing errors asking for `--deployment`/`--tag`, and `nuke` still requires an explicit selector — for a destructive command, naming exactly what is swept is the right friction.
+- 7c4dd86: Reduce guard lifecycle request volume and chunk orphan cleanup transactions.
+- e860898: **BREAKING:** Published Editorial Workflows packages now ship as one fixed release stack and require exact-version peers for every shared runtime package. Install the matching stack so the engine, reactive core, adapters, tools, and UI cannot silently load private or version-skewed copies.
+
+### Patch Changes
+
+- efb4cd9: Error detail below the ✖ headline is no longer dimmed. Validation output, auth hints, and errors caught by command wrappers now render in legible red so the information users need to act on remains readable.
+- Updated dependencies [bce09fc]
+- Updated dependencies [efb4cd9]
+- Updated dependencies [46b0285]
+- Updated dependencies [ab5e454]
+- Updated dependencies [8a76c67]
+- Updated dependencies [e3122cc]
+- Updated dependencies [7e8f459]
+- Updated dependencies [98e488e]
+- Updated dependencies [7c4dd86]
+  - @sanity/workflow-engine@0.20.0
+
+## 0.14.0
+
+### Minor Changes
+
+- 59b40fd: **BREAKING:** deployment selection now keys on the deployment `name`, selected with `--deployment`. Deployment-targeted commands (`start`, `definition diff`, `definition delete`, `nuke`) take `--deployment` as the precise selector; `--tag` still selects while it names exactly one deployment and errors listing the candidates when it spans several. `deploy --tag <tag>` now deploys every deployment carrying the tag (a tag is an environment group); `--deployment` deploys one, `--all-tags` deploys everything, and the three are mutually exclusive. `nuke` requires exactly one of `--deployment` / `--tag`, and refuses when another same-tag deployment sweeps an overlapping resource — guard document ids embed only the tag, so within a shared dataset the sweep cannot tell the deployments' guards apart and would delete the other's live locks. The interactive deploy prompt selects by name with the tag as its description. Read commands keep `--tag` as an optional filter — a repeated tag fans reads out across every resource it is deployed to.
+- de7ccfa: The instance-keyed commands (`diagnose`, `abort`, `set-stage`, `fire-action`) accept `--deployment <name>` to choose which resource to read the instance from — the precise selector consistent with the deployment-targeted commands. `--deployment` names one deployment and reads from the resource it targets; `--tag` stays the optional narrower it was, and the instance's own tag partition still comes from the loaded instance itself, never from the flag. This closes the dead end where a tag repeated across several resources left these commands unable to resolve a resource, and the "spans multiple resources" failures now point at `--deployment` as the remedy.
+
+### Patch Changes
+
+- Updated dependencies [24b11dd]
+- Updated dependencies [2005ab7]
+- Updated dependencies [24b11dd]
+- Updated dependencies [59b40fd]
+  - @sanity/workflow-engine@0.19.0
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -49,7 +49,8 @@ project will fail on cross-resource reads.
 
 The CLI is configured by a `sanity.workflow.ts` (or `.js`/`.mjs`) discovered in
 the directory you run from. It exports a config built with
-`defineWorkflowConfig`, declaring one **deployment** per environment:
+`defineWorkflowConfig`, declaring your **deployments** (typically one per
+environment):
 
 ```ts
 import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
@@ -60,7 +61,7 @@ export default defineWorkflowConfig({
   deployments: [
     {
       expectedMinReaderModel: 2,
-      name: 'production',
+      name: 'production', // the deployment's unique identity (lowercase letters, digits, dashes)
       tag: 'prod', // the environment partition the engine's docs are scoped to
       workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
       resourceAliases: [
@@ -76,11 +77,23 @@ export default defineWorkflowConfig({
 })
 ```
 
-Pick a deployment with `--tag <tag>`; with a single deployment configured you
-can omit it. With several configured, a bare interactive `deploy` presents a
-keyboard-driven tag selector. In CI or another non-interactive shell, it fails
-asking for `--tag` or `--all-tags` instead of blocking for input. `--all-tags`
-deploys every deployment in the config in one run: a failure in one doesn't
+`name` is the deployment's identity: unique across the config and constrained
+to the same grammar as `tag`. Tags group deployments by environment and may
+repeat, as long as no two deployments share both a `workflowResource` and a
+`tag` — that pair is the storage partition, and the config rejects the
+collision naming both entries.
+
+Pick a deployment with `--deployment <name>`; with a single deployment configured you
+can omit it. `--tag <tag>` also works on single-deployment commands while the
+tag names exactly one deployment — on `deploy` it targets every deployment
+carrying the tag (a tag is an environment group). With several configured, a
+bare interactive run presents a keyboard-driven deployment selector (by name,
+tag alongside) — on `deploy`, `start`, and `definition diff`/`delete`, and on
+the instance-targeted commands (`abort`, `set-stage`, `fire-action`,
+`diagnose`) when the config spans several resources. In CI or another
+non-interactive shell, the command fails asking for `--deployment` or `--tag`
+(`deploy` also suggests `--all-tags`) instead of blocking for input.
+`--all-tags` deploys every deployment in the config in one run: a failure in one doesn't
 stop the rest — the run continues, prints a summary of what failed, and exits
 non-zero. The client's project + dataset are derived from the deployment's
 `workflowResource`, and `deploy` expands each definition's `@<handle>:`
@@ -143,26 +156,26 @@ stale compiled output.
 
 ## Command status
 
-| Command                                | Status                                                                                                                                                                                           |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                                                                                            |
-| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                                                                                          |
-| `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)                                                                                                                              |
-| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                               |
-| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                                                                                     |
-| `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, removes 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.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`)                                                                                                         |
-| `nuke --tag <tag>`                     | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the tag (instances, definitions, guards across resources); plan + typed confirm |
+| Command                                         | Status                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deploy`                                        | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                                                                                                                                                                                                                                                 |
+| `deploy --all-tags`                             | wired — deploys every deployment in the config, continuing past per-deployment failures                                                                                                                                                                                                                                                               |
+| `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)                                                                                                                                                                                                                                                                                   |
+| `list`                                          | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                                                                                                                                                                                    |
+| `show <instance-id>`                            | wired — `client.getDocument`                                                                                                                                                                                                                                                                                                                          |
+| `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, removes 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.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`)                                                                                                                                                                                                                                                              |
+| `nuke --deployment <name>` / `nuke --tag <tag>` | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the deployment's tag (instances, definitions, guards across resources); exactly one selector required; refuses while another same-tag deployment sweeps an overlapping resource (guard ids embed only the tag); plan + typed confirm |
 
 ## Telemetry
 

package/dist/commands/editorial-workflows/abort.d.ts

@@ -10,6 +10,7 @@ export default class Abort extends WorkflowCommand {
     };
     static flags: {
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/abort.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
-import { tagFlags } from "../../lib/flags.js";
+import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 export default class Abort extends WorkflowCommand {
@@ -17,7 +17,7 @@ export default class Abort extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         reason: Flags.string({ description: 'Reason for aborting (recorded in history).' }),
     };
     async run() {

package/dist/commands/editorial-workflows/definition/delete.d.ts

@@ -12,6 +12,7 @@ export default class DefinitionDelete extends WorkflowCommand {
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         cascade: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/definition/delete.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow, } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../../lib/base-command.js";
 import { resolveContext } from "../../../lib/context.js";
-import { tagFlags } from "../../../lib/flags.js";
+import { deploymentFlags } from "../../../lib/flags.js";
 import { baseEngineArgs } from "../../../lib/operation-args.js";
 import { runWriteVerb } from "../../../lib/ops-report.js";
 export default class DefinitionDelete extends WorkflowCommand {
@@ -20,7 +20,7 @@ export default class DefinitionDelete extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({
             description: 'Delete only this deployed version (default: every version).',
         }),

package/dist/commands/editorial-workflows/definition/diff.d.ts

@@ -9,6 +9,7 @@ export default class DefinitionDiff extends WorkflowCommand {
     };
     static flags: {
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/definition/diff.js

@@ -5,7 +5,7 @@ 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 { deploymentFlags } from "../../../lib/flags.js";
 import { deploymentToTarget } from "../../../lib/select-deployment.js";
 export default class DefinitionDiff extends WorkflowCommand {
     static aliases = ['definition:diff'];
@@ -18,7 +18,7 @@ export default class DefinitionDiff extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({ description: 'Deployed version to diff against (default: latest).' }),
     };
     async run() {

package/dist/commands/editorial-workflows/deploy.d.ts

@@ -15,12 +15,13 @@ export default class Deploy extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'all-tags': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         only: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'share-defs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     /** Deploy (or diff, for `--dry-run`) one deployment's definitions.

package/dist/commands/editorial-workflows/deploy.js

@@ -8,9 +8,9 @@ import { clientFor, resolveTokenOrFail } from "../../lib/client.js";
 import { selectDefinitions, validateOrFail } from "../../lib/definitions.js";
 import { diffReport } from "../../lib/diff.js";
 import { fail, isAuthRejection } from "../../lib/fail.js";
-import { tagFlags } from "../../lib/flags.js";
+import { deploymentFlags } from "../../lib/flags.js";
 import { loadWorkflowConfig } from "../../lib/load-config.js";
-import { deploymentToTarget, selectDeployments } from "../../lib/select-deployment.js";
+import { deploymentLabel, deploymentToTarget, selectDeployments, } from "../../lib/select-deployment.js";
 import { shareDefinitionsAfterDeploy } from "../../lib/share-definitions.js";
 import { cliTelemetry } from "../../lib/telemetry.js";
 import { groupBanner } from "../../lib/ui.js";
@@ -18,6 +18,7 @@ export default class Deploy extends WorkflowCommand {
     static aliases = ['deploy'];
     static description = 'Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.';
     static examples = [
+        '<%= config.bin %> deploy --deployment review-prod',
         '<%= config.bin %> deploy --tag prod',
         '<%= config.bin %> deploy --all-tags',
         '<%= config.bin %> deploy --check',
@@ -25,11 +26,15 @@ export default class Deploy extends WorkflowCommand {
         '<%= config.bin %> deploy --only productLaunch',
     ];
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
+        tag: Flags.string({
+            description: 'Workflow environment tag (e.g. prod, test) — deploys every deployment carrying the tag (a tag is an environment group).',
+            exclusive: ['deployment'],
+        }),
         'all-tags': Flags.boolean({
-            description: 'Deploy every deployment in the config, not just one tag.',
+            description: 'Deploy every deployment in the config, not just a selection.',
             default: false,
-            exclusive: ['tag'],
+            exclusive: ['tag', 'deployment'],
         }),
         'dry-run': Flags.boolean({
             description: 'Validate + diff against the deployed version; do not write.',
@@ -51,7 +56,11 @@ export default class Deploy extends WorkflowCommand {
         const { flags } = await this.parse(Deploy);
         validateModeFlags(flags.check, flags['dry-run']);
         const config = await loadWorkflowConfig();
-        const batches = buildBatches(await selectDeployments(config, { tag: flags.tag, allTags: flags['all-tags'] }), flags.only);
+        const batches = buildBatches(await selectDeployments(config, {
+            name: flags.deployment,
+            tag: flags.tag,
+            allTags: flags['all-tags'],
+        }), flags.only);
         const log = (line) => this.log(line);
         if (flags.check) {
             await reconcileBatches({
@@ -145,9 +154,6 @@ export function validateModeFlags(check, dryRun) {
         fail('Pass either --check or --dry-run, not both.');
     }
 }
-function deploymentLabel({ name, tag }) {
-    return `${name} (${tag})`;
-}
 export function buildBatches(deployments, only) {
     return deployments.map((deployment) => {
         const context = deployments.length > 1 ? `${deploymentLabel(deployment)} — ` : '';

package/dist/commands/editorial-workflows/diagnose.d.ts

@@ -40,6 +40,7 @@ export default class Diagnose extends WorkflowCommand {
     };
     static flags: {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/diagnose.js

@@ -5,7 +5,7 @@ import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
 import { fail, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { instanceFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { formatTimestamp, sectionHeader, activityIcon } from "../../lib/ui.js";
 import { instanceHeader } from "./show.js";
@@ -223,7 +223,7 @@ export default class Diagnose extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         ...jsonFlags,
     };
     async run() {

package/dist/commands/editorial-workflows/fire-action.d.ts

@@ -41,6 +41,7 @@ export default class FireAction extends WorkflowCommand {
         activity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         action: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         param: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/fire-action.js

@@ -5,7 +5,7 @@ import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
 import { fail, failOnThrow, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { instanceFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../../lib/ops-report.js";
 import { parseParams } from "../../lib/params.js";
@@ -93,7 +93,7 @@ export default class FireAction extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         activity: Flags.string({
             description: 'Activity the action belongs to. Required to fire; omit --action to list.',
         }),

package/dist/commands/editorial-workflows/nuke.d.ts

@@ -5,7 +5,8 @@ export default class Nuke extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        tag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/editorial-workflows/nuke.js

@@ -7,7 +7,7 @@ import { clientFor, resolveApiHost, resolveTokenOrFail } from "../../lib/client.
 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 { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, refuseOverlappingNuke, renderNukePlan, resolveNukePlan, sweptResources, } from "../../lib/nuke.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 import { canPromptOnStderr } from "../../lib/prompt.js";
 import { selectDeployment } from "../../lib/select-deployment.js";
@@ -19,13 +19,17 @@ export default class Nuke extends WorkflowCommand {
         '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 --deployment plugin-dev',
         '<%= config.bin %> nuke --tag plugin-dev --force',
     ];
     static flags = {
+        deployment: Flags.string({
+            description: 'The deployment name to reset.',
+            exactlyOne: ['deployment', 'tag'],
+        }),
         tag: Flags.string({
-            description: 'The deployment tag to reset. Required — a destructive reset never guesses the environment.',
-            required: true,
+            description: 'The deployment tag to reset (while it names exactly one deployment).',
+            exactlyOne: ['deployment', 'tag'],
         }),
         force: Flags.boolean({
             description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
@@ -35,7 +39,8 @@ export default class Nuke extends WorkflowCommand {
     async run() {
         const { flags } = await this.parse(Nuke);
         const config = await loadWorkflowConfig();
-        const deployment = selectDeployment(config, { tag: flags.tag });
+        const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
+        refuseOverlappingNuke(config.deployments, deployment);
         const targets = buildTargets(deployment, await resolveTokenOrFail());
         const plan = await resolveNukePlan({ tag: deployment.tag, targets });
         const apiHost = resolveApiHost() ?? 'https://api.sanity.io (production default)';
@@ -58,12 +63,11 @@ export default class Nuke extends WorkflowCommand {
     }
 }
 function buildTargets(deployment, token) {
-    const engineResource = deployment.workflowResource;
-    const aliasResources = (deployment.resourceAliases ?? []).map((binding) => binding.resource);
-    return dedupeResources([engineResource, ...aliasResources]).map((resource) => ({
+    const engineGdr = resourceGdr(deployment.workflowResource);
+    return dedupeResources(sweptResources(deployment)).map((resource) => ({
         resource,
         client: clientFor(resource, token),
-        holdsEngineDocs: resourceGdr(resource) === resourceGdr(engineResource),
+        holdsEngineDocs: resourceGdr(resource) === engineGdr,
     }));
 }
 async function confirmOrFail(targets) {

package/dist/commands/editorial-workflows/set-stage.d.ts

@@ -12,6 +12,7 @@ export default class SetStage extends WorkflowCommand {
     static flags: {
         to: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/set-stage.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
-import { tagFlags } from "../../lib/flags.js";
+import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../../lib/ops-report.js";
 export default class SetStage extends WorkflowCommand {
@@ -20,7 +20,7 @@ export default class SetStage extends WorkflowCommand {
         }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         to: Flags.string({
             required: true,
             description: 'Target stage name.',

package/dist/commands/editorial-workflows/start.d.ts

@@ -13,6 +13,7 @@ export default class Start extends WorkflowCommand {
         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>;
+        deployment: 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>;

package/dist/commands/editorial-workflows/start.js

@@ -5,7 +5,7 @@ import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveContext } from "../../lib/context.js";
 import { fetchDeployedDefinition } from "../../lib/definitions.js";
 import { fail, failOnThrow, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { deploymentFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 import { parseParams } from "../../lib/params.js";
@@ -23,7 +23,7 @@ export default class Start extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({
             description: 'Definition version to start from (default: highest deployed).',
         }),

package/dist/lib/context.d.ts

@@ -1,6 +1,7 @@
 import type { SanityClient } from '@sanity/client';
 import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import type { EngineScope } from './operation-args.ts';
+import { type ChooseDeploymentName } from './select-deployment.ts';
 export interface DeploymentContext {
     deployment: WorkflowDeployment;
     client: SanityClient;
@@ -13,11 +14,12 @@ export interface InstanceContext {
 }
 /**
  * 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.
+ * `--deployment` or `--tag` (or the sole one), and build an authenticated
+ * client for that deployment's resource. A write acts on one specific
+ * deployment, so a single, definite target is exactly what it needs.
  */
 export declare function resolveContext(flags: {
+    deployment?: string | undefined;
     tag?: string | undefined;
 }): Promise<DeploymentContext>;
 /** One resource a read inspects, with its authenticated client. */
@@ -34,8 +36,9 @@ export interface ReadTarget {
  *
  * 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.
+ * `--tag` narrows to the resources deployed under that tag (tags may repeat
+ * across deployments). The token resolves once for the run, however many
+ * targets it spans.
  */
 export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
@@ -44,14 +47,15 @@ export declare function resolveReadTargets(flags: {
  *  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 ({@link dedupeResources}). */
+/** The distinct resources a read targets: every resource deployed under the
+ *  tag (tags may repeat across deployments), or — untagged — every distinct
+ *  one the config's deployments 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
- *  (the instance-targeted verbs); listings fan out via
- *  {@link resolveReadResources} instead. */
+/** The single resource an instance-keyed command reads from when it isn't
+ *  disambiguated interactively: the sole resource, the `--tag`-narrowed one, or
+ *  a `fail` asking for `--deployment`/`--tag` when the config spans several. The
+ *  interactive picker lives in {@link resolveInstanceResource}; 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,15 +64,34 @@ export declare function resolveReadResource(config: WorkflowConfig, tag: string
  * 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).
+ * resource (via {@link resolveInstanceResource}, no tag filter).
  *
  * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
  * declared deployment because it acts on the authored definition set (or a
  * definition name, which — unlike an instance id — isn't unique across tags).
  */
 export declare function resolveInstanceContext(flags: {
+    deployment?: string | undefined;
     tag?: string | undefined;
 }, instanceId: string): Promise<InstanceContext>;
+/**
+ * Which resource an instance-keyed command reads from: the one `--deployment`
+ * names (resolved by its unique deployment name); otherwise, when the config
+ * spans several resources, an interactive terminal is prompted to pick a
+ * deployment ({@link canPromptOnStderr}) — its resource is the read source, the
+ * interactive counterpart to `--deployment`. A run that can't prompt falls to
+ * the sole or `--tag`-narrowed resource, or the ambiguity error
+ * ({@link resolveReadResource}). The instance id is globally unique, so this
+ * only locates the resource to look in — never the instance's `tag` partition,
+ * which the caller takes from the loaded instance. The shared path behind all
+ * four instance-keyed commands.
+ */
+export declare function resolveInstanceResource(config: WorkflowConfig, { deployment, tag, interactive, chooseDeployment, }: {
+    deployment?: string | undefined;
+    tag?: string | undefined;
+    interactive?: boolean | undefined;
+    chooseDeployment?: ChooseDeploymentName | undefined;
+}): Promise<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