@sanity/workflow-cli 0.9.0 → 0.11.0

package/dist/commands/definition/show.js

@@ -1,12 +1,14 @@
 import { styleText } from 'node:util';
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { isTerminalStage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { resolveReadContext } from "../../lib/context.js";
-import { buildDefinitionShowQuery } from "../../lib/definitions.js";
+import { WorkflowCommand } from "../../lib/base-command.js";
+import { resolveReadTargets, soleHitOrFail } from "../../lib/context.js";
+import { buildDefinitionShowQuery, buildDefinitionTagsQuery } from "../../lib/definitions.js";
+import { fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { formatKeyValue, sectionHeader } from "../../lib/ui.js";
-export default class DefinitionShow extends Command {
+import { formatKeyValue, resourceLabel, sectionHeader } from "../../lib/ui.js";
+export default class DefinitionShow extends WorkflowCommand {
     static description = 'Show a deployed workflow definition.';
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
@@ -17,18 +19,17 @@ export default class DefinitionShow extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(DefinitionShow);
-        const { client } = await resolveReadContext(flags);
-        const { groq, params } = buildDefinitionShowQuery({
+        const targets = await resolveReadTargets(flags);
+        const def = await resolveShownDefinition({
+            targets,
             name: args.name,
             tag: flags.tag,
             version: flags.version,
         });
-        // A deployed document: the authored {@link WorkflowDefinition} plus the
-        // deploy-stamped envelope (`version`, `contentHash`, `tag`).
-        const def = await client.fetch(groq, params);
         if (!def) {
-            const at = flags.version ? `v${flags.version}` : 'latest';
-            this.error(`${logSymbols.error} no definition "${args.name}" (${at})`, { exit: 1 });
+            this.error(`${logSymbols.error} no definition "${args.name}" (${versionLabel(flags.version)})`, {
+                exit: 1,
+            });
         }
         this.log(definitionHeader(def, def.tag));
         this.log('');
@@ -37,11 +38,37 @@ export default class DefinitionShow extends Command {
         }
     }
 }
-const HEADER_PAD = 11; // "Description" — the longest label in the block
-/** 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
- *  authored definition, so it's passed separately and omitted when unknown. */
+export async function resolveShownDefinition({ targets, name, tag, version, }) {
+    if (tag === undefined) {
+        await assertSingleTagPartition({ targets, name });
+    }
+    const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
+    const hits = await fetchDefinitionHits({ targets, groq, params });
+    return soleHitOrFail(hits, `Definition "${name}"`)?.def;
+}
+export function versionLabel(version) {
+    return version === undefined ? 'latest' : `v${version}`;
+}
+async function assertSingleTagPartition({ targets, name, }) {
+    const { groq, params } = buildDefinitionTagsQuery(name);
+    await Promise.all(targets.map(async (target) => {
+        const tags = await target.client.fetch(groq, params, { tag: 'definition.show' });
+        if (tags.length > 1) {
+            fail(`Definition "${name}" exists in several tag partitions in ` +
+                `${resourceLabel(target.resource)} — pass --tag to choose one.`, tags.toSorted().join('\n'));
+        }
+    }));
+}
+export async function fetchDefinitionHits({ targets, groq, params, }) {
+    const probes = await Promise.all(targets.map(async (target) => {
+        const def = await target.client.fetch(groq, params, {
+            tag: 'definition.show',
+        });
+        return def === null ? undefined : { resource: target.resource, def };
+    }));
+    return probes.filter((hit) => hit !== undefined);
+}
+const HEADER_PAD = 11;
 export function definitionHeader(def, tag) {
     const rows = [
         formatKeyValue({ key: 'Title', value: def.title, padTo: HEADER_PAD }),
@@ -56,18 +83,15 @@ export function definitionHeader(def, tag) {
     }
     return [styleText('bold', `${def.name} v${def.version}`), ...rows].join('\n');
 }
-/** One `· action` line, annotated with the terminal status its `status.set` op sets, if any. */
 function actionLine(action) {
     const statusOp = (action.ops ?? []).find((op) => op.type === 'status.set');
     const status = statusOp ? styleText('dim', ` → ${statusOp.status}`) : '';
     return `          · ${action.name}${status}`;
 }
-/** A `- activity` line followed by one line per action it exposes. */
 function activityBlock(activity) {
     const title = activity.title ? styleText('dim', ` — ${activity.title}`) : '';
     return [`      - ${activity.name}${title}`, ...(activity.actions ?? []).map(actionLine)];
 }
-/** A `• stage` line (with initial/terminal markers) followed by its activity blocks. */
 function stageBlock(stage, initialStage) {
     const title = stage.title ? styleText('dim', ` — ${stage.title}`) : '';
     const terminal = isTerminalStage(stage) ? styleText('dim', ' (terminal)') : '';
@@ -77,10 +101,6 @@ function stageBlock(stage, initialStage) {
         ...(stage.activities ?? []).flatMap(activityBlock),
     ];
 }
-/**
- * The body lines for `definition show`: every stage with its activities and each
- * activity's actions. Pure so it can be asserted without driving the oclif command.
- */
 export function describeDefinition(def) {
     return [
         sectionHeader('Stages'),

package/dist/commands/deploy.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
 import { type DeployDefinitionResult, type WorkflowDefinition, type WorkflowDeployment } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
 /** A deployment paired with the definitions selected + validated for it. */
 interface DeployBatch {
     deployment: WorkflowDeployment;
@@ -10,7 +10,7 @@ interface DeployFailure {
     deployment: Pick<WorkflowDeployment, 'name' | 'tag'>;
     message: string;
 }
-export default class Deploy extends Command {
+export default class Deploy extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
@@ -18,9 +18,13 @@ export default class Deploy extends Command {
         '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>;
     };
     run(): Promise<void>;
+    /** Deploy (or diff, for `--dry-run`) one deployment's definitions.
+     *  Returns the per-definition results for a real deploy; `undefined`
+     *  for a dry run, which writes nothing. */
     private processDeployment;
     private executeDeploy;
     private runDryRun;
@@ -42,6 +46,8 @@ export declare function buildBatches(deployments: WorkflowDeployment[], only: st
  * to their message for {@link deploySummary}. A single-batch run rethrows
  * instead: it has no summary, so a throw from before the deploy spinner starts
  * would otherwise surface nowhere — and propagating keeps the stack visible.
+ * An auth rejection also rethrows regardless of batch count: a dead token is
+ * never batch-local, so continuing would just repeat the same failure.
  */
 export declare function reconcileBatches({ batches, log, processBatch, }: {
     batches: DeployBatch[];
@@ -62,14 +68,14 @@ export declare function deploySummary({ total, failures, }: {
 /**
  * The banner printed above a deployment's output so a multi-deployment run is
  * attributable. `undefined` for a single-target run — it keeps its original
- * unprefixed output. A leading blank line separates every deployment after the
- * first.
+ * unprefixed output.
  */
 export declare function deploymentBanner({ deployment, index, total, }: {
     deployment: Pick<WorkflowDeployment, 'name' | 'tag'>;
     index: number;
     total: number;
 }): string | undefined;
-/** One line per deployed definition, symbol-tagged by its result status. */
+/** One line per deployed definition, symbol-tagged by its result status,
+ *  followed by any advisory effect-output lint warnings indented beneath it. */
 export declare function deployResultLines(results: DeployDefinitionResult[]): string[];
 export {};

package/dist/commands/deploy.js

@@ -1,16 +1,20 @@
 import { styleText } from 'node:util';
-import { Command, Flags } from '@oclif/core';
-import { computeDiffEntries, workflow, } from '@sanity/workflow-engine';
+import { Flags } from '@oclif/core';
+import { computeDiffEntries, errorMessage, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import ora from 'ora';
+import { WorkflowCommand } from "../lib/base-command.js";
 import { clientFor, resolveTokenOrFail } from "../lib/client.js";
 import { selectDefinitions, validateOrFail } from "../lib/definitions.js";
 import { diffReport } from "../lib/diff.js";
-import { errorMessage, fail } from "../lib/fail.js";
+import { fail, isAuthRejection } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { loadWorkflowConfig } from "../lib/load-config.js";
 import { deploymentToTarget, selectDeployments } from "../lib/select-deployment.js";
-export default class Deploy extends Command {
+import { shareDefinitionsAfterDeploy } from "../lib/share-definitions.js";
+import { cliTelemetry } from "../lib/telemetry.js";
+import { groupBanner } from "../lib/ui.js";
+export default class Deploy extends WorkflowCommand {
     static description = 'Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.';
     static examples = [
         '<%= config.bin %> deploy --tag prod',
@@ -37,17 +41,17 @@ export default class Deploy extends Command {
         only: Flags.string({
             description: 'Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.',
         }),
+        'share-defs': Flags.boolean({
+            allowNo: true,
+            description: 'Share the definition documents newly created by this deploy with Sanity — the full document, verbatim (structure, names, filters, effect configuration, seeded values), plus its deployment coordinates (project and dataset, or resource id); never content documents, instances, or your Sanity auth token. Opt-out: an interactive terminal is asked once (the answer is remembered), while unattended runs (CI / non-TTY / DO_NOT_TRACK) share nothing unless --share-defs is passed. Use --no-share-defs to opt out. An explicit --share-defs also sends telemetry for this deploy regardless of CI / DO_NOT_TRACK.',
+        }),
     };
     async run() {
         const { flags } = await this.parse(Deploy);
         validateModeFlags(flags.check, flags['dry-run']);
         const config = await loadWorkflowConfig();
-        // Validate every deployment up front (below), so a bad definition fails
-        // before any write — never a partial reconcile from a validation error.
         const batches = buildBatches(selectDeployments(config, { tag: flags.tag, allTags: flags['all-tags'] }), flags.only);
         const log = (line) => this.log(line);
-        // buildBatches already validated everything offline — --check only has to
-        // report that pass, so it never resolves a token or builds a client.
         if (flags.check) {
             await reconcileBatches({
                 batches,
@@ -58,36 +62,63 @@ export default class Deploy extends Command {
             });
             return;
         }
-        // One token up front, so an --all-tags run authenticates once, not per deployment.
         const token = await resolveTokenOrFail();
+        const candidates = [];
         const failures = await reconcileBatches({
             batches,
             log,
-            processBatch: ({ deployment, defs }) => this.processDeployment({ deployment, defs, dryRun: flags['dry-run'], token }),
+            processBatch: async ({ deployment, defs }) => {
+                const client = clientFor(deployment.workflowResource, token);
+                const deployed = await this.processDeployment({
+                    deployment,
+                    defs,
+                    dryRun: flags['dry-run'],
+                    client,
+                });
+                if (deployed !== undefined) {
+                    candidates.push({
+                        client,
+                        tag: deployment.tag,
+                        resource: deployment.workflowResource,
+                        results: deployed.results,
+                        deployId: deployed.deployId,
+                    });
+                }
+            },
         });
         for (const line of deploySummary({ total: batches.length, failures })) {
             log(line);
         }
+        await shareDefinitionsAfterDeploy({
+            flag: flags['share-defs'],
+            candidates,
+            warn: (message) => this.warn(message),
+        });
         if (failures.length > 0) {
             this.exit(1);
         }
     }
-    async processDeployment({ deployment, defs, dryRun, token, }) {
+    async processDeployment({ deployment, defs, dryRun, client, }) {
         const target = deploymentToTarget(deployment);
-        const client = clientFor(deployment.workflowResource, token);
         if (dryRun) {
             await this.runDryRun({ client, defs, target });
-            return;
+            return undefined;
         }
-        await this.executeDeploy({ client, defs, target });
+        return this.executeDeploy({ client, defs, target });
     }
     async executeDeploy({ client, defs, target, }) {
         const spinner = ora(`Deploying ${defs.length} definition(s)…`).start();
         try {
-            const { results } = await workflow.deployDefinitions({ ...target, client, definitions: defs });
-            spinner.succeed(`Processed ${results.length} definition(s)`);
-            for (const line of deployResultLines(results))
+            const deployed = await workflow.deployDefinitions({
+                ...target,
+                client,
+                definitions: defs,
+                telemetry: cliTelemetry().logger,
+            });
+            spinner.succeed(`Processed ${deployed.results.length} definition(s)`);
+            for (const line of deployResultLines(deployed.results))
                 this.log(line);
+            return deployed;
         }
         catch (error) {
             spinner.fail(`Deploy failed — ${errorMessage(error)}`);
@@ -108,24 +139,14 @@ export default class Deploy extends Command {
         }
     }
 }
-/** Reject the contradictory `--check --dry-run` combination. */
 export function validateModeFlags(check, dryRun) {
     if (check && dryRun) {
         fail('Pass either --check or --dry-run, not both.');
     }
 }
-/** The one identity format for a deployment in output — banner, failure
- *  summary, and validation attribution all render it the same way. */
 function deploymentLabel({ name, tag }) {
     return `${name} (${tag})`;
 }
-/**
- * Select and validate every deployment's definitions up front. Validation runs
- * before any network write ({@link validateOrFail} exits on a bad definition),
- * so a whole-config deploy can never leave a partial reconcile behind a broken
- * batch. In a multi-deployment run the failure names its deployment — it exits
- * before any banner could attribute it.
- */
 export function buildBatches(deployments, only) {
     return deployments.map((deployment) => {
         const context = deployments.length > 1 ? `${deploymentLabel(deployment)} — ` : '';
@@ -134,14 +155,6 @@ export function buildBatches(deployments, only) {
         return { deployment, defs };
     });
 }
-/**
- * Run `processBatch` over each batch, continuing past a failure so one bad
- * deployment can't strand the rest — deployments are independent, and deploys
- * are idempotent, so a partial run is safe to re-run. Failures are flattened
- * to their message for {@link deploySummary}. A single-batch run rethrows
- * instead: it has no summary, so a throw from before the deploy spinner starts
- * would otherwise surface nowhere — and propagating keeps the stack visible.
- */
 export async function reconcileBatches({ batches, log, processBatch, }) {
     const failures = [];
     for (const [index, batch] of batches.entries()) {
@@ -153,7 +166,7 @@ export async function reconcileBatches({ batches, log, processBatch, }) {
             await processBatch(batch);
         }
         catch (error) {
-            if (batches.length === 1) {
+            if (batches.length === 1 || isAuthRejection(error)) {
                 throw error;
             }
             failures.push({ deployment: batch.deployment, message: errorMessage(error) });
@@ -161,13 +174,6 @@ export async function reconcileBatches({ batches, log, processBatch, }) {
     }
     return failures;
 }
-/**
- * The closing summary for a multi-deployment run that had failures: the
- * succeeded/failed tally and each failed deployment. Empty for a clean run.
- * The wording is mode-neutral because a `--dry-run` failure lands here too,
- * where nothing was deployed. Single-batch runs never reach it — their lone
- * failure rethrows out of {@link reconcileBatches}.
- */
 export function deploySummary({ total, failures, }) {
     if (failures.length === 0) {
         return [];
@@ -178,26 +184,17 @@ export function deploySummary({ total, failures, }) {
         ...failures.map((f) => styleText('red', `  ${logSymbols.error} ${deploymentLabel(f.deployment)} — ${f.message}`)),
     ];
 }
-/**
- * The banner printed above a deployment's output so a multi-deployment run is
- * attributable. `undefined` for a single-target run — it keeps its original
- * unprefixed output. A leading blank line separates every deployment after the
- * first.
- */
 export function deploymentBanner({ deployment, index, total, }) {
-    if (total <= 1) {
-        return undefined;
-    }
-    const gap = index > 0 ? '\n' : '';
-    return `${gap}${styleText('bold', `▸ ${deploymentLabel(deployment)}`)}`;
+    return groupBanner({ label: deploymentLabel(deployment), index, total });
 }
-/** One line per deployed definition, symbol-tagged by its result status. */
 export function deployResultLines(results) {
     const symbols = {
         created: logSymbols.success,
     };
-    return results.map((r) => {
+    return results.flatMap((r) => {
         const symbol = symbols[r.status] ?? logSymbols.warning;
-        return `  ${symbol} ${r.status.padEnd(9)} ${r.name} v${r.version}`;
+        const head = `  ${symbol} ${r.status.padEnd(9)} ${r.name} v${r.version}`;
+        const warnings = (r.warnings ?? []).map((w) => `      ${logSymbols.warning} ${w}`);
+        return [head, ...warnings];
     });
 }

package/dist/commands/diagnose.d.ts

@@ -1,5 +1,20 @@
-import { Command } from '@oclif/core';
-import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation } from '@sanity/workflow-engine';
+import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation, type WorkflowEvaluation } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
+/** The `--json` transitions payload: raw derived state (atom GROQ, negation,
+ *  pivotality, solvable requirement) — structure for scripts, never baked
+ *  English. Pure so the shape is a testable contract. */
+export declare function rawTransitionProjection(evaluation: WorkflowEvaluation): {
+    name: string;
+    to: string;
+    whenSatisfied: boolean;
+    unevaluable: boolean;
+    blockedBy: {
+        requirement?: import("@sanity/groq-condition-describe").AtomRequirement;
+        groq: string;
+        negated: boolean;
+        pivotal: boolean;
+    }[];
+}[];
 /**
  * The diagnosis body: the verdict line, the current stage's activities +
  * transitions as evidence (for any in-flight state), and the cause block with
@@ -8,12 +23,15 @@ import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation } from '@
  * {@link SuggestedRemediation}s rather than re-deriving them, so the rendered
  * fix block and the `--json` output stay one computation.
  */
-export declare function renderDiagnosis({ diagnosis, input, remediations, }: {
+export declare function renderDiagnosis({ diagnosis, input, remediations, explanations, }: {
     diagnosis: Diagnosis;
     input: DiagnoseInput;
     remediations: SuggestedRemediation[];
+    /** Insight summaries per unsatisfied transition name — rendered under the
+     *  transition line so "stuck" reads as "stuck until X". */
+    explanations?: ReadonlyMap<string, string> | undefined;
 }): string[];
-export default class Diagnose extends Command {
+export default class Diagnose extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {