@sanity/workflow-cli 0.13.0 → 0.20.0

package/dist/lib/context.js

@@ -2,11 +2,12 @@ import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
-import { selectDeployment } from "./select-deployment.js";
+import { canPromptOnStderr } from "./prompt.js";
+import { availableDeployments, deploymentsForTag, selectDeployment, } from "./select-deployment.js";
 import { resourceLabel } from "./ui.js";
 export async function resolveContext(flags) {
     const config = await loadWorkflowConfig();
-    const deployment = selectDeployment(config, { tag: flags.tag });
+    const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
     return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
 }
 export async function resolveReadTargets(flags) {
@@ -20,7 +21,7 @@ export function dedupeResources(resources) {
 }
 export function resolveReadResources(config, tag) {
     if (tag !== undefined) {
-        return [selectDeployment(config, { tag }).workflowResource];
+        return dedupeResources(deploymentsForTag(config, tag).map((deployment) => deployment.workflowResource));
     }
     const resources = dedupeResources(config.deployments.map((d) => d.workflowResource));
     if (resources.length === 0) {
@@ -34,16 +35,36 @@ export function resolveReadResource(config, tag) {
     if (resources.length === 1 && sole !== undefined) {
         return sole;
     }
-    const tags = config.deployments.map((d) => d.tag).join(', ');
-    fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
+    if (tag === undefined) {
+        fail('Config spans multiple resources — pass --deployment or --tag to choose one.', availableDeployments(config));
+    }
+    const carriers = config.deployments.filter((d) => d.tag === tag);
+    fail(`Tag "${tag}" spans multiple resources — pass --deployment to choose one.`, availableDeployments(config, carriers));
 }
 export async function resolveInstanceContext(flags, instanceId) {
     const config = await loadWorkflowConfig();
-    const workflowResource = resolveReadResource(config, flags.tag);
+    const workflowResource = await resolveInstanceResource(config, flags);
     const client = clientFor(workflowResource, await resolveTokenOrFail());
     const instance = await loadInstanceOrFail(client, instanceId);
     return { client, scope: { tag: instance.tag, workflowResource } };
 }
+export async function resolveInstanceResource(config, { deployment, tag, interactive, chooseDeployment, }) {
+    if (deployment !== undefined) {
+        return (await selectDeployment(config, { name: deployment, tag: undefined })).workflowResource;
+    }
+    if (tag === undefined &&
+        (interactive ?? canPromptOnStderr()) &&
+        resolveReadResources(config, undefined).length > 1) {
+        const chosen = await selectDeployment(config, {
+            name: undefined,
+            tag: undefined,
+            interactive: true,
+            chooseName: chooseDeployment,
+        });
+        return chosen.workflowResource;
+    }
+    return resolveReadResource(config, tag);
+}
 export async function loadInstanceOrFail(client, instanceId) {
     const instance = await client.getDocument(instanceId, {
         tag: 'instance.load',

package/dist/lib/fail.js

@@ -8,7 +8,7 @@ export function fail(headline, detail) {
     process.stderr.write(`${styleText('red', `${logSymbols.error} ${headline}`)}\n`);
     if (detail !== undefined && detail !== '') {
         for (const line of detail.split('\n')) {
-            process.stderr.write(`  ${styleText(['dim', 'red'], line)}\n`);
+            process.stderr.write(`  ${styleText('red', line)}\n`);
         }
     }
     return Errors.exit(1);

package/dist/lib/flags.d.ts

@@ -1,11 +1,33 @@
-/** The environment tag (e.g. prod, test). For write commands it selects which
- *  deployment in the discovered `sanity.workflow` config to act on. A sole
- *  deployment needs no tag, and an interactive `deploy` asks when several are
- *  configured. For read commands it's an optional query filter — and the
- *  resource disambiguator when a config spans more than one. */
+/** The environment tag (e.g. prod, test). Tags group deployments by
+ *  environment and may repeat across a config. For the read commands that
+ *  consume this directly it's an optional query filter — and the resource
+ *  disambiguator when a config spans more than one. Write commands layer
+ *  selection semantics on top via {@link deploymentFlags}; instance-keyed
+ *  commands add `--deployment` alongside it via {@link instanceFlags}. */
 export declare const tagFlags: {
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
+/** The selectors an instance-keyed command (`diagnose`, `abort`, `set-stage`,
+ *  `fire-action`) takes. An instance id is globally unique and carries its own
+ *  `tag`, so these only pick WHICH resource to read it from — never the
+ *  instance's partition, which always comes from the loaded instance.
+ *  `--deployment` names one deployment and reads from the resource it targets;
+ *  `--tag` stays the optional narrower {@link tagFlags} describes. Mutually
+ *  exclusive; a sole-resource config needs neither. */
+export declare const instanceFlags: {
+    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>;
+};
+/** The selectors a single-deployment (write) command takes: `--deployment` —
+ *  the deployment's unique name identity — or `--tag`, which resolves while the
+ *  tag names exactly one deployment and errors asking for `--deployment` when
+ *  it spans several. Mutually exclusive; a sole-deployment config needs neither.
+ *  `deploy` overrides the `tag` description with its group semantics (every
+ *  deployment carrying the tag). */
+export declare const deploymentFlags: {
+    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>;
+};
 export declare const jsonFlags: {
     json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };

package/dist/lib/flags.js

@@ -1,7 +1,23 @@
 import { Flags } from '@oclif/core';
+const tagAsFilterDescription = 'Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.';
 export const tagFlags = {
+    tag: Flags.string({ description: tagAsFilterDescription }),
+};
+export const instanceFlags = {
+    deployment: Flags.string({
+        description: 'Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.',
+        exclusive: ['tag'],
+    }),
+    tag: Flags.string({ description: tagAsFilterDescription, exclusive: ['deployment'] }),
+};
+export const deploymentFlags = {
+    deployment: Flags.string({
+        description: 'Deployment name — the unique identity of one deployment in the config.',
+        exclusive: ['tag'],
+    }),
     tag: Flags.string({
-        description: 'Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.',
+        description: 'Workflow environment tag (e.g. prod, test) — selects the deployment to act on while the tag names exactly one; pass --deployment when it spans several.',
+        exclusive: ['deployment'],
     }),
 };
 export const jsonFlags = {

package/dist/lib/nuke.d.ts

@@ -1,4 +1,4 @@
-import { type WorkflowClient, type WorkflowResource } from '@sanity/workflow-engine';
+import { type WorkflowClient, type WorkflowDeployment, type WorkflowResource } from '@sanity/workflow-engine';
 /** A resource a nuke may delete from, with the client that reads/writes it and
  *  whether it is the engine's own resource — the only one that holds instances
  *  and definitions (guards can co-locate with subjects in any resource). */
@@ -32,6 +32,20 @@ export interface PlanCounts {
     datasets: number;
     total: number;
 }
+/** Every resource a deployment's nuke sweeps: its own workflow resource (which
+ *  holds instances + definitions + guards) plus each alias-bound resource
+ *  (guards co-locate with the subjects they lock). */
+export declare function sweptResources(deployment: WorkflowDeployment): WorkflowResource[];
+/**
+ * Fail before any nuke work when another same-tag deployment sweeps a resource
+ * the selected one does. Guard document ids embed only the tag
+ * (`temp.system.guard.<tag>.wf-instance.*`), so within a shared resource the
+ * sweep cannot tell such deployments' guards apart — nuking one would delete
+ * the others' live locks, invisibly to the plan. Config validation already
+ * forbids sharing tag + workflow resource, so an overlap can only arrive
+ * through alias bindings.
+ */
+export declare function refuseOverlappingNuke(deployments: WorkflowDeployment[], selected: WorkflowDeployment): void;
 /**
  * Resolve what a tag-scoped nuke would delete, per resource — the dry-run plan
  * printed before any deletion. Instances and definitions are read only from the
@@ -45,19 +59,6 @@ export declare function resolveNukePlan(args: {
     tag: string;
     targets: NukeTarget[];
 }): Promise<NukePlan>;
-/**
- * Does a guard doc belong to `tag`? A guard's `sourceInstanceId` is the id of
- * the instance that registered it (`<tag>.wf-instance.<random>`), and its own
- * `_id` embeds that same instance id
- * (`temp.system.guard.<tag>.wf-instance.<random>.<name>`). Matching on either —
- * with the trailing `.` so `prod` never matches `prod-eu` — catches guards
- * whose `sourceInstanceId` was never written as well as guards whose instance
- * is already gone.
- */
-export declare function guardMatchesTag(guard: {
-    _id: string;
-    sourceInstanceId?: string;
-}, tag: string): boolean;
 /** The `project.dataset` labels of resources the plan actually deletes from —
  *  the exact set the operator must type back to confirm. A resource with
  *  nothing to delete is not "involved" and is omitted. */

package/dist/lib/nuke.js

@@ -1,8 +1,29 @@
 import { styleText } from 'node:util';
-import { GUARD_DOC_TYPE, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { GUARD_DOC_TYPE, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, resourceGdr, tagScopeFilter, } from '@sanity/workflow-engine';
+import { fail } from "./fail.js";
+import { deploymentLabel } from "./select-deployment.js";
 import { formatTable, resourceLabel, sectionHeader } from "./ui.js";
 const CHUNK = 200;
 const REQUEST_TAG = 'nuke';
+export function sweptResources(deployment) {
+    return [
+        deployment.workflowResource,
+        ...(deployment.resourceAliases ?? []).map((binding) => binding.resource),
+    ];
+}
+export function refuseOverlappingNuke(deployments, selected) {
+    const swept = new Set(sweptResources(selected).map(resourceGdr));
+    const clashing = deployments.filter((candidate) => candidate.name !== selected.name &&
+        candidate.tag === selected.tag &&
+        sweptResources(candidate).some((resource) => swept.has(resourceGdr(resource))));
+    if (clashing.length === 0) {
+        return;
+    }
+    fail(`Refusing to nuke "${deploymentLabel(selected)}" — its guards are indistinguishable ` +
+        `from ${clashing.map(deploymentLabel).join(', ')}'s in the shared resource(s).`, `Guard ids embed only the tag, and these deployments share tag "${selected.tag}" plus ` +
+        "a swept resource — the sweep would delete the other deployments' live guards. " +
+        'Give them distinct tags first.');
+}
 export async function resolveNukePlan(args) {
     const { tag, targets } = args;
     const resources = await Promise.all(targets.map((target) => resolveResourcePlan({ tag, target })));
@@ -31,14 +52,12 @@ function engineDocIds(args) {
     return args.client.fetch(`*[_type == $type && ${tagScopeFilter()}]._id`, { type: args.type, tag: args.tag }, { perspective: 'raw', tag: REQUEST_TAG });
 }
 async function tagGuardIds(args) {
-    const guards = await args.client.fetch(`*[_type == $type]{_id, sourceInstanceId}`, { type: GUARD_DOC_TYPE }, { perspective: 'raw', tag: REQUEST_TAG });
-    return guards.filter((guard) => guardMatchesTag(guard, args.tag)).map((guard) => guard._id);
-}
-export function guardMatchesTag(guard, tag) {
-    const instancePrefix = `${tag}.wf-instance.`;
+    const instancePrefix = `${args.tag}.wf-instance.`;
     const guardIdPrefix = `${GUARD_DOC_TYPE}.${instancePrefix}`;
-    return ((guard.sourceInstanceId?.startsWith(instancePrefix) ?? false) ||
-        guard._id.startsWith(guardIdPrefix));
+    return args.client.fetch(`*[_type == $type && (
+      string::startsWith(sourceInstanceId, $instancePrefix) ||
+      string::startsWith(_id, $guardIdPrefix)
+    )]._id`, { type: GUARD_DOC_TYPE, instancePrefix, guardIdPrefix }, { perspective: 'raw', tag: REQUEST_TAG });
 }
 export function involvedTargets(plan) {
     return plan.resources

package/dist/lib/prompt.d.ts

@@ -9,3 +9,17 @@
  * prompts such as nuke's confirmation.
  */
 export declare function canPromptOnStderr(): boolean;
+/**
+ * Ask a `select` question on stderr — the channel this package renders prompts
+ * on so a redirected stdout can't swallow the question (the display side of the
+ * {@link canPromptOnStderr} gate). The single site that routes a `select` to
+ * stderr, so no `select` prompt can silently regress to stdout.
+ */
+export declare function selectOnStderr(config: {
+    message: string;
+    choices: readonly {
+        name: string;
+        value: string;
+        description?: string;
+    }[];
+}): Promise<string>;

package/dist/lib/prompt.js

@@ -1,4 +1,8 @@
 import { isInteractive } from '@sanity/cli-core';
+import { select } from '@sanity/cli-core/ux';
 export function canPromptOnStderr() {
     return isInteractive() && process.stderr.isTTY === true;
 }
+export function selectOnStderr(config) {
+    return select(config, { output: process.stderr });
+}

package/dist/lib/select-deployment.d.ts

@@ -1,32 +1,57 @@
 import { type DeployTarget, type WorkflowConfig, type WorkflowDeployment } from '@sanity/workflow-engine';
-type ChooseDeploymentTag = (deployments: WorkflowDeployment[]) => Promise<string>;
+export type ChooseDeploymentName = (deployments: WorkflowDeployment[]) => Promise<string>;
 interface DeploymentSelectionOptions {
+    name: string | undefined;
     tag: string | undefined;
     allTags: boolean;
     interactive?: boolean;
-    chooseTag?: ChooseDeploymentTag;
+    chooseName?: ChooseDeploymentName;
 }
+/** The one identity format for a deployment in output — banners, failure
+ *  summaries, and "available deployments" listings all render it the same
+ *  way. */
+export declare function deploymentLabel({ name, tag }: Pick<WorkflowDeployment, 'name' | 'tag'>): string;
 /**
- * Pick the deployment for the requested `--tag`. Tags are unique across a
- * config (enforced by defineWorkflowConfig), so a tag names at most one
- * deployment.
+ * Pick the deployment for the requested `--deployment` or `--tag`. Names are
+ * unique across a config (enforced by defineWorkflowConfig), so a name resolves
+ * exactly one deployment. Tags are repeatable — a tag resolves only while it
+ * names exactly one deployment; when it spans several, the failure lists them
+ * so `--deployment` can disambiguate.
  *
- * With no tag: fall back to the sole deployment when there's exactly one
- * (the common single-environment case), otherwise fail asking for `--tag` —
- * a multi-deployment config is ambiguous without it. `orAlternative` extends
- * that ambiguity message for callers with another way out (deploy's `--all-tags`).
+ * With no selector: fall back to the sole deployment when there's exactly one
+ * (the common single-environment case). When several are configured, an
+ * interactive terminal is prompted to pick one ({@link canPromptOnStderr}); a
+ * run that cannot prompt fails asking for `--deployment` or `--tag` — a
+ * multi-deployment config is ambiguous without one. `orAlternative` extends
+ * that ambiguity message for callers with another way out (deploy's
+ * `--all-tags`).
  */
-export declare function selectDeployment(config: WorkflowConfig, { tag, orAlternative }: {
+export declare function selectDeployment(config: WorkflowConfig, { name, tag, orAlternative, interactive, chooseName, }: {
+    name: string | undefined;
     tag: string | undefined;
     orAlternative?: string;
-}): WorkflowDeployment;
+    interactive?: boolean | undefined;
+    chooseName?: ChooseDeploymentName | undefined;
+}): Promise<WorkflowDeployment>;
 /**
- * The deployments a `deploy` run acts on: every one with `--all-tags`,
- * otherwise a single target via {@link selectDeployment}. An ambiguous bare
- * interactive run asks for a tag; a run that cannot prompt keeps the explicit
- * flag guidance. Deploying everything is an explicit opt-in — never a default.
+ * Every deployment carrying `tag`, failing when the tag matches none — the
+ * shared resolution for the callers that accept a whole tag group (deploy's
+ * tag-as-environment run, the read paths' resource narrowing).
  */
-export declare function selectDeployments(config: WorkflowConfig, { tag, allTags, interactive, chooseTag }: DeploymentSelectionOptions): Promise<WorkflowDeployment[]>;
+export declare function deploymentsForTag(config: WorkflowConfig, tag: string): WorkflowDeployment[];
+/**
+ * The deployments a `deploy` run acts on: every one with `--all-tags`, one
+ * definite deployment via `--deployment`, every deployment carrying the tag with
+ * `--tag` (a tag is an environment group), otherwise the sole deployment. An
+ * ambiguous bare interactive run asks which deployment; a run that cannot
+ * prompt keeps the explicit flag guidance. Deploying everything is an
+ * explicit opt-in — never a default.
+ */
+export declare function selectDeployments(config: WorkflowConfig, { name, tag, allTags, interactive, chooseName }: DeploymentSelectionOptions): Promise<WorkflowDeployment[]>;
+/** The "Available deployments: name (tag), …" hint every ambiguity failure
+ *  prints — one vocabulary across the write and instance-keyed paths, so a
+ *  reader always sees both the `--deployment` names and their `--tag`s. */
+export declare function availableDeployments(config: WorkflowConfig, deployments?: WorkflowDeployment[]): string;
 /**
  * Project a deployment into the engine's {@link DeployTarget} — the shape the
  * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)

package/dist/lib/select-deployment.js

@@ -1,56 +1,73 @@
-import { select } from '@sanity/cli-core/ux';
 import { resourceAliasesToMap, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
-import { canPromptOnStderr } from "./prompt.js";
-export function selectDeployment(config, { tag, orAlternative = '' }) {
-    if (tag === undefined) {
-        if (config.deployments.length > 1) {
-            fail(`Multiple deployments configured — pass --tag${orAlternative}.`, availableTags(config));
+import { canPromptOnStderr, selectOnStderr } from "./prompt.js";
+export function deploymentLabel({ name, tag }) {
+    return `${name} (${tag})`;
+}
+export async function selectDeployment(config, { name, tag, orAlternative = '', interactive, chooseName = chooseDeploymentName, }) {
+    if (name !== undefined) {
+        const deployment = config.deployments.find((candidate) => candidate.name === name);
+        if (deployment === undefined) {
+            fail(`No deployment named "${name}".`, availableDeployments(config));
         }
-        const [sole] = config.deployments;
-        if (sole === undefined) {
-            fail('No deployments configured.');
+        return deployment;
+    }
+    if (tag !== undefined) {
+        const matches = deploymentsForTag(config, tag);
+        const [sole, ...rest] = matches;
+        if (sole === undefined || rest.length > 0) {
+            fail(`Multiple deployments tagged "${tag}" — pass --deployment to choose one.`, availableDeployments(config, matches));
         }
         return sole;
     }
-    const deployment = config.deployments.find((candidate) => candidate.tag === tag);
-    if (deployment === undefined) {
-        fail(`No deployment for tag "${tag}".`, availableTags(config));
+    return selectDefaultDeployment(config, { orAlternative, interactive, chooseName });
+}
+async function selectDefaultDeployment(config, { orAlternative, interactive, chooseName, }) {
+    if (config.deployments.length > 1) {
+        if (interactive ?? canPromptOnStderr()) {
+            const selectedName = await chooseName(config.deployments);
+            return selectDeployment(config, { name: selectedName, tag: undefined });
+        }
+        fail(`Multiple deployments configured — pass --deployment or --tag${orAlternative}.`, availableDeployments(config));
+    }
+    const [sole] = config.deployments;
+    if (sole === undefined) {
+        fail('No deployments configured.');
     }
-    return deployment;
+    return sole;
 }
-export async function selectDeployments(config, { tag, allTags, interactive, chooseTag = chooseDeploymentTag }) {
+export function deploymentsForTag(config, tag) {
+    const matches = config.deployments.filter((candidate) => candidate.tag === tag);
+    if (matches.length === 0) {
+        fail(`No deployment for tag "${tag}".`, availableDeployments(config));
+    }
+    return matches;
+}
+export async function selectDeployments(config, { name, tag, allTags, interactive, chooseName }) {
     if (allTags) {
         return config.deployments;
     }
-    if (tag === undefined && config.deployments.length > 1) {
-        if (!(interactive ?? canPromptOnStderr())) {
-            return [
-                selectDeployment(config, {
-                    tag,
-                    orAlternative: ', or --all-tags to deploy every deployment',
-                }),
-            ];
-        }
-        const selectedTag = await chooseTag(config.deployments);
-        return [selectDeployment(config, { tag: selectedTag })];
+    if (tag !== undefined) {
+        return deploymentsForTag(config, tag);
     }
     return [
-        selectDeployment(config, { tag, orAlternative: ', or --all-tags to deploy every deployment' }),
+        await selectDeployment(config, {
+            name,
+            tag,
+            orAlternative: ', or --all-tags to deploy every deployment',
+            interactive,
+            chooseName,
+        }),
     ];
 }
-async function chooseDeploymentTag(deployments) {
-    return select({
-        message: 'Select a deployment tag',
-        choices: deployments.map(({ name, tag }) => ({
-            name: tag,
-            value: tag,
-            description: name,
-        })),
-    }, { output: process.stderr });
-}
-function availableTags(config) {
-    return `Available tags: ${config.deployments.map((candidate) => candidate.tag).join(', ')}`;
+async function chooseDeploymentName(deployments) {
+    return selectOnStderr({
+        message: 'Select a deployment',
+        choices: deployments.map(({ name, tag }) => ({ name, value: name, description: `tag: ${tag}` })),
+    });
+}
+export function availableDeployments(config, deployments = config.deployments) {
+    return `Available deployments: ${deployments.map(deploymentLabel).join(', ')}`;
 }
 export function deploymentToTarget(deployment) {
     return {