@sanity/workflow-cli 0.9.0 → 0.10.0

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-definitions-with-sanity': 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-definitions-with-sanity': Flags.boolean({
+            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-in for this invocation only; the CLI never prompts. Independent of telemetry consent.',
+            default: false,
+        }),
     };
     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-definitions-with-sanity'],
+            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;
+    filterSatisfied: 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: {

package/dist/commands/diagnose.js

@@ -1,10 +1,12 @@
 import { styleText } from 'node:util';
-import { Args, Command } from '@oclif/core';
-import { diagnoseInputFromEvaluation, workflow, } from '@sanity/workflow-engine';
+import { Args } from '@oclif/core';
+import { diagnoseInputFromEvaluation, workflow, unsatisfiedTransitionSummaries, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
+import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveInstanceContext } from "../lib/context.js";
-import { errorMessage, fail } from "../lib/fail.js";
+import { fail, failureDetail } from "../lib/fail.js";
 import { jsonFlags, tagFlags } from "../lib/flags.js";
+import { baseEngineArgs } from "../lib/operation-args.js";
 import { formatTimestamp, sectionHeader, activityIcon } from "../lib/ui.js";
 import { instanceHeader } from "./show.js";
 function formatAssignee(a) {
@@ -16,11 +18,12 @@ function activityLine(t, assignees) {
         : '';
     return `  ${activityIcon[t.status]} ${t.activity.name} ${styleText('dim', `[${t.status}]`)}${who}`;
 }
-function transitionLine(tr) {
+function transitionLine(tr, explanation) {
     const mark = tr.filterSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
-    return `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    return explanation !== undefined ? `${line}\n      ${styleText('dim', `↳ ${explanation}`)}` : line;
 }
-function currentStageLines(input) {
+function currentStageLines(input, explanations) {
     const lines = [
         `${sectionHeader('Stage')} ${input.instance.currentStage}`,
         sectionHeader('Activities'),
@@ -31,7 +34,7 @@ function currentStageLines(input) {
     if (input.transitions.length > 0) {
         lines.push('', sectionHeader('Exit transitions'));
         for (const tr of input.transitions) {
-            lines.push(transitionLine(tr));
+            lines.push(transitionLine(tr, explanations?.get(tr.transition.name)));
         }
     }
     return lines;
@@ -107,11 +110,6 @@ function noTransitionDetail() {
         ],
     };
 }
-/** An unevaluable exit filter is a *recoverable* hold, not a dead end: it
- *  clears itself once the operand becomes readable, and no engine verb
- *  unsticks it (so the engine emits no remediation). The "what to do" —
- *  make the operand readable — lives here in the why, since there is no
- *  runnable fix to render. */
 function transitionUnevaluableDetail(transitions) {
     return {
         headline: `an exit transition's filter could not be evaluated`,
@@ -124,12 +122,6 @@ function transitionUnevaluableDetail(transitions) {
         ],
     };
 }
-/** Render the engine's structured remediations as the "suggested fix" block.
- *  Verbs render under their engine names — the same vocabulary `--json`
- *  emits, so scripts and humans read one language. Only runnable ones reach
- *  here: {@link renderDiagnosis} filters on the engine's `available` flag,
- *  so verbs that aren't callable engine operations yet never render as a
- *  fix (the full set, planned verbs included, still rides `--json`). */
 function remediationLines(remediations) {
     return remediations.map((r) => `  • ${r.verb} — ${r.rationale}`);
 }
@@ -147,6 +139,11 @@ function causeDetail(cause) {
             return transitionUnevaluableDetail(cause.transitions);
     }
 }
+function liveChildrenTail(diagnosis) {
+    if (diagnosis.liveChildren === undefined)
+        return '';
+    return ` ${styleText('yellow', `${diagnosis.liveChildren} spawned child workflow(s) still running.`)}`;
+}
 function statusLine(diagnosis) {
     switch (diagnosis.state) {
         case 'progressing':
@@ -156,31 +153,37 @@ function statusLine(diagnosis) {
         case 'blocked':
             return `${logSymbols.info} ${styleText('cyan', 'blocked')} — ${blockedHeadline(diagnosis)}`;
         case 'completed':
-            return `${logSymbols.success} ${styleText('green', 'completed')} at ${formatTimestamp(diagnosis.at)}.`;
+            return `${logSymbols.success} ${styleText('green', 'completed')} at ${formatTimestamp(diagnosis.at)}.${liveChildrenTail(diagnosis)}`;
         case 'aborted': {
             const tail = diagnosis.reason !== undefined ? ` — ${diagnosis.reason}` : '';
-            return `${logSymbols.info} ${styleText('dim', 'aborted')} at ${formatTimestamp(diagnosis.at)}${tail}.`;
+            return `${logSymbols.info} ${styleText('dim', 'aborted')} at ${formatTimestamp(diagnosis.at)}${tail}.${liveChildrenTail(diagnosis)}`;
         }
         case 'stuck':
             return `${logSymbols.warning} ${styleText('yellow', 'STUCK')} — ${causeDetail(diagnosis.cause).headline}`;
     }
 }
-/**
- * The diagnosis body: the verdict line, the current stage's activities +
- * transitions as evidence (for any in-flight state), and the cause block with
- * the engine's suggested fix when stuck. Pure so every verdict permutation is
- * assertable without driving a live evaluation. Takes the engine's
- * {@link SuggestedRemediation}s rather than re-deriving them, so the rendered
- * fix block and the `--json` output stay one computation.
- */
-export function renderDiagnosis({ diagnosis, input, remediations, }) {
+export function rawTransitionProjection(evaluation) {
+    return evaluation.currentStage.transitions.map((t) => ({
+        name: t.transition.name,
+        to: t.transition.to,
+        filterSatisfied: t.filterSatisfied,
+        unevaluable: t.unevaluable,
+        blockedBy: t.insight.blockedBy.map((atom) => ({
+            groq: atom.atom.groq,
+            negated: atom.atom.negated,
+            pivotal: atom.pivotal,
+            ...(atom.requirement !== undefined ? { requirement: atom.requirement } : {}),
+        })),
+    }));
+}
+export function renderDiagnosis({ diagnosis, input, remediations, explanations, }) {
     const lines = [statusLine(diagnosis)];
     const inFlight = diagnosis.state === 'progressing' ||
         diagnosis.state === 'waiting' ||
         diagnosis.state === 'blocked' ||
         diagnosis.state === 'stuck';
     if (inFlight) {
-        lines.push('', ...currentStageLines(input));
+        lines.push('', ...currentStageLines(input, explanations));
     }
     if (diagnosis.state === 'waiting') {
         lines.push('', ...waitingLines(diagnosis));
@@ -192,16 +195,13 @@ export function renderDiagnosis({ diagnosis, input, remediations, }) {
         const detail = causeDetail(diagnosis.cause);
         const runnable = remediations.filter((r) => r.available);
         lines.push('', sectionHeader("Why it's stuck"), ...detail.why);
-        // A recoverable hold (e.g. an unevaluable transition filter) has no
-        // runnable remediation — its "what to do" is in the why above, so skip
-        // the empty fix header rather than dangle it.
         if (runnable.length > 0) {
             lines.push('', sectionHeader('Suggested fix'), ...remediationLines(runnable));
         }
     }
     return lines;
 }
-export default class Diagnose extends Command {
+export default class Diagnose extends WorkflowCommand {
     static description = "Explain why a workflow instance is or isn't progressing, and what would unstick it.";
     static examples = [
         '<%= config.bin %> diagnose wf-instance.abc123',
@@ -221,18 +221,10 @@ export default class Diagnose extends Command {
         const { evaluation, diagnosis, remediations } = await workflow
             .diagnose({
             client,
-            tag: scope.tag,
-            workflowResource: scope.workflowResource,
+            ...baseEngineArgs(scope),
             instanceId: args.instanceId,
-            // Token-auth CLI can't hit /users/me; pin the same system actor the
-            // write verbs use. Transition filters and activity status are actor-
-            // independent. A requirement that reads $actor/$assigned/$can is the
-            // exception — it's evaluated against this system actor, so a `blocked`
-            // verdict on such a requirement reflects the engine's view, not a
-            // specific assignee's.
-            access: { actor: { kind: 'system', id: 'workflow-cli' } },
         })
-            .catch((error) => fail('diagnose failed:', errorMessage(error)));
+            .catch((error) => fail('diagnose failed:', failureDetail(error)));
         const input = diagnoseInputFromEvaluation(evaluation);
         if (flags.json) {
             this.log(JSON.stringify({
@@ -240,12 +232,14 @@ export default class Diagnose extends Command {
                 stage: evaluation.instance.currentStage,
                 diagnosis,
                 remediations,
+                transitions: rawTransitionProjection(evaluation),
             }, null, 2));
             return;
         }
         this.log(instanceHeader(evaluation.instance));
         this.log('');
-        for (const line of renderDiagnosis({ diagnosis, input, remediations })) {
+        const explanations = new Map(unsatisfiedTransitionSummaries(evaluation).map((entry) => [entry.transition, entry.summary]));
+        for (const line of renderDiagnosis({ diagnosis, input, remediations, explanations })) {
             this.log(line);
         }
     }

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

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
 import { type AvailableAction } from '@sanity/workflow-engine';
+import { WorkflowCommand } from '../lib/base-command.ts';
 import { type WriteOutcome, type WriteReport } from '../lib/ops-report.ts';
 /**
  * The list-mode body: every action on the current stage's activities, marked
@@ -29,7 +29,7 @@ export declare function fireActionReport({ result, activity, action, }: {
     activity: string;
     action: string;
 }): WriteReport;
-export default class FireAction extends Command {
+export default class FireAction extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static args: {
@@ -37,8 +37,6 @@ export default class FireAction extends Command {
     };
     static flags: {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        as: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'as-role': import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
         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>;