@sanity/workflow-cli 0.32.0 → 0.33.0

package/dist/lib/cause-detail.js

@@ -0,0 +1,111 @@
+import { styleText } from 'node:util';
+import { formatDateTime } from '@sanity/cli-core/dates';
+import { _additionalMissingDocuments, _fieldTargetLabel, _missingDocumentsSummary, } from '@sanity/workflow-engine';
+import logSymbols from 'log-symbols';
+import { sectionHeader } from "./ui.js";
+function missingDocumentsDetail(documents) {
+    return {
+        headline: 'referenced document missing',
+        why: [
+            ...documents.map(({ target, reference }) => `${_fieldTargetLabel(target)}: ${reference.id}`),
+            _missingDocumentsSummary(documents),
+        ],
+    };
+}
+function additionalDocumentLines(diagnosis, allMissingDocuments) {
+    const documents = _additionalMissingDocuments(diagnosis, allMissingDocuments);
+    if (documents.length === 0)
+        return [];
+    return ['', sectionHeader('Missing references'), ...missingDocumentsDetail(documents).why];
+}
+function failedEffectDetail(effect) {
+    const ran = effect.durationMs !== undefined ? ` (after ${effect.durationMs}ms)` : '';
+    return {
+        headline: `a failed effect from action '${effect.origin.name}' is blocking its activity`,
+        why: [
+            styleText('red', `${logSymbols.error} failed effect: ${effect.name}`),
+            `  queued by action '${effect.origin.name}', failed ${formatDateTime(effect.ranAt)}${ran}`,
+            ...(effect.error !== undefined ? [`  error: ${effect.error.message}`] : []),
+            '',
+            `The activity that fired '${effect.origin.name}' is waiting on this effect. It failed`,
+            `against an external system, so the activity never resolves and the stage can't advance.`,
+        ],
+    };
+}
+function hungEffectDetail(effect) {
+    return {
+        headline: `effect '${effect.name}' was claimed but never completed`,
+        why: [
+            styleText('yellow', `${logSymbols.warning} hung effect: ${effect.name}`),
+            `  claimed ${formatDateTime(effect.claim?.claimedAt ?? '?')} but never reported back — the`,
+            `  drainer likely died mid-dispatch, so it won't drain on its own.`,
+        ],
+    };
+}
+function failedActivityDetail(activity) {
+    return {
+        headline: `activity '${activity}' failed`,
+        why: [
+            styleText('red', `${logSymbols.error} activity '${activity}' is in a terminal failed state.`),
+            `Any exit transition gated on '${activity}' being done can never fire.`,
+        ],
+    };
+}
+function noTransitionDetail() {
+    return {
+        headline: `no exit transition's trigger is satisfied`,
+        why: [
+            `${logSymbols.info} every activity is resolved, but no exit transition's \`when\` is true.`,
+            `Likely a routing state value a trigger reads never got written.`,
+        ],
+    };
+}
+function transitionUnevaluableDetail(transitions) {
+    return {
+        headline: `an exit transition's trigger could not be evaluated`,
+        why: [
+            `${logSymbols.info} every activity is resolved, but ${transitions.join(', ')} reads an operand`,
+            `that is missing or unreadable (GROQ null), so routing is held rather than`,
+            `falling through. Make the data the trigger reads readable — publish the`,
+            `subject (or fill the field) — and the instance advances on its own; no`,
+            `set-stage needed.`,
+        ],
+    };
+}
+function remediationLines(remediations) {
+    return remediations.map((r) => `  • ${r.verb} — ${r.rationale}`);
+}
+function causeDetail(cause) {
+    switch (cause.kind) {
+        case 'document-missing':
+            return missingDocumentsDetail(cause.documents);
+        case 'failed-effect':
+            return failedEffectDetail(cause.effect);
+        case 'hung-effect':
+            return hungEffectDetail(cause.effect);
+        case 'failed-activity':
+            return failedActivityDetail(cause.activity);
+        case 'no-transition-fires':
+            return noTransitionDetail();
+        case 'transition-unevaluable':
+            return transitionUnevaluableDetail(cause.transitions);
+    }
+}
+export function stuckHeadline(cause) {
+    return `${logSymbols.warning} ${styleText('yellow', 'STUCK')} — ${causeDetail(cause).headline}`;
+}
+export function stuckDiagnosisLines({ diagnosis, allMissingDocuments, remediations, }) {
+    if (diagnosis.state !== 'stuck')
+        return [];
+    const detail = causeDetail(diagnosis.cause);
+    const runnable = remediations.filter((remediation) => remediation.available);
+    return [
+        '',
+        sectionHeader("Why it's stuck"),
+        ...detail.why,
+        ...additionalDocumentLines(diagnosis, allMissingDocuments),
+        ...(runnable.length > 0
+            ? ['', sectionHeader('Suggested fix'), ...remediationLines(runnable)]
+            : []),
+    ];
+}

package/dist/lib/load-config.d.ts

@@ -1,4 +1,18 @@
 import { type WorkflowConfig } from '@sanity/workflow-engine';
+/**
+ * The validated config a `sanity.workflow` module exports, and the names that
+ * module exports it alongside.
+ */
+export interface LoadedWorkflowConfig {
+    config: WorkflowConfig;
+    /** The discovered file's name, so a diagnostic names the file the user
+     *  actually has out of {@link CONFIG_FILE_NAMES}. */
+    configFile: string;
+    /** Every name the module exports, `default` included. `blueprint generate`
+     *  reads it because each generated module imports its deployment as a named
+     *  export from this file. */
+    exportedNames: readonly string[];
+}
 /**
  * Discover the `sanity.workflow.{ts,js,mjs}` in `cwd`, import its default
  * export, and validate it through {@link defineWorkflowConfig}. Any problem —
@@ -6,6 +20,12 @@ import { type WorkflowConfig } from '@sanity/workflow-engine';
  * path.
  */
 export declare function loadWorkflowConfig(cwd?: string): Promise<WorkflowConfig>;
+/**
+ * {@link loadWorkflowConfig} plus the names the config module exports, for a
+ * caller that has to check one. Takes the same clean `fail` path on every
+ * problem.
+ */
+export declare function loadWorkflowConfigModule(cwd?: string): Promise<LoadedWorkflowConfig>;
 /**
  * {@link loadWorkflowConfig} for telemetry setup, which must never break (or
  * exit) a command: `undefined` when the file is absent or unusable. A broken

package/dist/lib/load-config.js

@@ -9,15 +9,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { CONFIG_FILE_NAMES } from '@sanity/workflow-blueprint/generate';
 import { errorMessage } from '@sanity/workflow-engine';
 import { defineWorkflowConfig } from '@sanity/workflow-engine/define';
 import { createJiti } from 'jiti';
 import { fail } from "./fail.js";
-const CONFIG_FILE_NAMES = [
-    'sanity.workflow.ts',
-    'sanity.workflow.js',
-    'sanity.workflow.mjs',
-];
 function findConfigFile(cwd) {
     for (const name of CONFIG_FILE_NAMES) {
         const candidate = join(cwd, name);
@@ -36,13 +32,13 @@ class ConfigLoadError extends Error {
         this.detail = detail;
     }
 }
-async function importDefault(filePath) {
+async function importModule(filePath) {
     const url = pathToFileURL(filePath).href;
     try {
-        if (filePath.endsWith('.ts')) {
-            return await createJiti(dirname(filePath)).import(url, { default: true });
-        }
-        return (await import(__rewriteRelativeImportExtension(url, true))).default;
+        const loaded = filePath.endsWith('.ts')
+            ? await createJiti(dirname(filePath)).import(url)
+            : await import(__rewriteRelativeImportExtension(url, true));
+        return { default: loaded.default, names: Object.keys(loaded) };
     }
     catch (err) {
         throw new ConfigLoadError(`Failed to load ${basename(filePath)}:`, errorMessage(err));
@@ -54,9 +50,13 @@ function parseConfigFile(filePath) {
     if (cached !== undefined) {
         return cached;
     }
-    const parsed = importDefault(filePath).then((exported) => {
+    const parsed = importModule(filePath).then((loaded) => {
         try {
-            return defineWorkflowConfig(exported);
+            return {
+                config: defineWorkflowConfig(loaded.default),
+                configFile: basename(filePath),
+                exportedNames: loaded.names,
+            };
         }
         catch (err) {
             throw new ConfigLoadError(`Invalid config in ${basename(filePath)}:`, errorMessage(err));
@@ -66,6 +66,9 @@ function parseConfigFile(filePath) {
     return parsed;
 }
 export async function loadWorkflowConfig(cwd = process.cwd()) {
+    return (await loadWorkflowConfigModule(cwd)).config;
+}
+export async function loadWorkflowConfigModule(cwd = process.cwd()) {
     const filePath = findConfigFile(cwd);
     if (filePath === undefined) {
         fail(`No ${CONFIG_FILE_NAMES[0]} found in ${cwd}.`, 'Create one that `export default defineWorkflowConfig({deployments: [...]})`.');
@@ -85,5 +88,5 @@ export async function loadWorkflowConfigIfPresent(cwd = process.cwd()) {
     if (filePath === undefined) {
         return undefined;
     }
-    return parseConfigFile(filePath).catch(() => undefined);
+    return parseConfigFile(filePath).then((loaded) => loaded.config, () => undefined);
 }

package/dist/lib/share-definitions.d.ts

@@ -11,7 +11,7 @@ export interface ShareClient {
         tag: string;
     }): Promise<T>;
     request<T>(opts: {
-        uri: string;
+        url: string;
         method: string;
         body: unknown;
         tag: string;
@@ -31,7 +31,7 @@ export interface ShareCandidate {
 }
 /** Sanity's first-party definition-feedback endpoint (editorial-ai-backend,
  *  routed project-agnostically through the API gateway). */
-export declare const SHARE_ENDPOINT_URI = "/workflow/definition-feedback";
+export declare const SHARE_ENDPOINT_URL = "/workflow/definition-feedback";
 /**
  * The first-run disclosure — a product contract, pinned by test. It must
  * name the recipient (Sanity), state that the document ships VERBATIM with its

package/dist/lib/share-definitions.js

@@ -5,7 +5,7 @@ import { WORKFLOWS_DEPLOY_COMMAND_ID } from "../command-ids.js";
 import { buildDefinitionShowQuery } from "./definitions.js";
 import { canPromptOnStderr } from "./prompt.js";
 import { cliTelemetry, WorkflowDefinitionShared, WorkflowDefinitionSharingDecided, } from "./telemetry.js";
-export const SHARE_ENDPOINT_URI = '/workflow/definition-feedback';
+export const SHARE_ENDPOINT_URL = '/workflow/definition-feedback';
 const SHARE_TAG = 'definition.share';
 const SHARE_DECISION_KEY = 'workflowCliDefinitionSharing';
 export const SHARE_FIRST_RUN_NOTICE = `${styleText('bold', 'Sharing new workflow definitions with Sanity')} to improve Workflows.\n` +
@@ -127,7 +127,7 @@ async function donate(args) {
             return false;
         }
         await shared[0].candidate.client.request({
-            uri: SHARE_ENDPOINT_URI,
+            url: SHARE_ENDPOINT_URL,
             method: 'POST',
             body: { definitions: shared.map(({ entry }) => entry) },
             tag: SHARE_TAG,

package/dist/lib/telemetry-setup.d.ts

@@ -41,6 +41,8 @@ export declare function setupCliTelemetry(args?: {
     /** Intake client override — tests inject a fake here, like the other
      *  hook dependencies above; omitted, the real project client applies. */
     client?: TelemetryIntakeClient;
+    /** oclif command id — becomes the command trace's `groupOrCommand` context. */
+    commandId?: string;
 }): Promise<void>;
 /**
  * The invocation's environment user properties — the sanity CLI's precedent

package/dist/lib/telemetry-setup.js

@@ -51,7 +51,7 @@ export async function setupCliTelemetry(args) {
             env: args?.env ?? process.env,
             forceSend: args?.forceSend ?? false,
         });
-        setCliTelemetry(telemetry);
+        setCliTelemetry(telemetry, args?.commandId !== undefined ? { commandId: args.commandId } : undefined);
         attachBuiltinContext({ telemetry, project, client, deps: args });
     }
     catch {
@@ -87,7 +87,7 @@ export function cliUserProperties(args) {
 export async function resolveOrgId(client, projectId) {
     try {
         const project = await raceWithDeadline(client.request({
-            uri: `/projects/${projectId}`,
+            url: `/projects/${encodeURIComponent(projectId)}`,
             tag: CONTEXT_TAG,
             timeout: ORG_LOOKUP_DEADLINE_MS,
         }), ORG_LOOKUP_DEADLINE_MS);

package/dist/lib/telemetry.d.ts

@@ -58,8 +58,11 @@ export type CliTelemetry = {
 };
 export declare function cliTelemetry(): CliTelemetry;
 /** Install the invocation's shell and, for the built-in store, start the
- *  command trace (completed by {@link finishCliTelemetry}). */
-export declare function setCliTelemetry(telemetry: CliTelemetry): void;
+ *  command trace (completed by {@link finishCliTelemetry}). `commandId`
+ *  becomes that trace's `groupOrCommand` context. */
+export declare function setCliTelemetry(telemetry: CliTelemetry, options?: {
+    commandId?: string;
+}): void;
 export declare function clearCliTelemetry(): void;
 /** Build the built-in Sanity-intake shell over an authenticated,
  *  project-bound client. `forceSend` overrides the environment denial

package/dist/lib/telemetry.js

@@ -1,5 +1,5 @@
 import { createBatchedStore, createSessionId, defineEvent, defineTrace, } from '@sanity/telemetry';
-import { createTelemetryIntake, isTelemetryEnvDenied, noopTelemetry, } from '@sanity/workflow-engine';
+import { createTelemetryIntake, _resolveTelemetryEnvironment, isTelemetryEnvDenied, noopTelemetry, } from '@sanity/workflow-engine';
 export const WorkflowCliCommandExecuted = defineTrace({
     name: 'Workflows CLI Command Executed',
     version: 1,
@@ -21,10 +21,11 @@ let activeTrace;
 export function cliTelemetry() {
     return current;
 }
-export function setCliTelemetry(telemetry) {
+export function setCliTelemetry(telemetry, options) {
     current = telemetry;
     if (telemetry.kind === 'builtin') {
-        activeTrace = telemetry.store.logger.trace(WorkflowCliCommandExecuted);
+        const context = options?.commandId !== undefined ? { groupOrCommand: options.commandId } : undefined;
+        activeTrace = telemetry.store.logger.trace(WorkflowCliCommandExecuted, context);
         activeTrace.start();
     }
 }
@@ -35,7 +36,15 @@ export function clearCliTelemetry() {
 export function createBuiltinTelemetry(args) {
     const { client, projectId, env, forceSend = false } = args;
     const envDenied = isTelemetryEnvDenied(env);
-    const store = createBatchedStore(createSessionId(), createTelemetryIntake({ client, projectId, denied: forceSend ? false : envDenied }));
+    const store = createBatchedStore(createSessionId(), createTelemetryIntake({
+        client,
+        projectId,
+        denied: forceSend ? false : envDenied,
+        context: {
+            surface: 'cli',
+            environment: _resolveTelemetryEnvironment(env.NODE_ENV, 'production'),
+        },
+    }));
     return { kind: 'builtin', logger: store.logger, store, envDenied, forceSend };
 }
 function traceAsLogEvent(trace) {

package/dist/standalone-argv.d.ts

@@ -1,9 +1,9 @@
 /**
  * First argv tokens that belong under {@link WORKFLOWS_TOPIC}.
  * Keep in sync with `src/commands/workflows/` (top-level command
- * files plus the `definition` subtopic directory).
+ * files plus the `blueprint` and `definition` subtopic directories).
  */
-export declare const STANDALONE_ROOT_COMMANDS: readonly ["abort", "definition", "deploy", "diagnose", "fire-action", "list", "nuke", "reset-activity", "set-stage", "show", "start", "tail"];
+export declare const STANDALONE_ROOT_COMMANDS: readonly ["abort", "blueprint", "definition", "deploy", "diagnose", "fire-action", "list", "nuke", "reset-activity", "set-stage", "show", "start", "tail"];
 /** Index of the first argv token that is not a flag (and not `--`). */
 export declare function firstPositionalIndex(args: string[]): number;
 /**

package/dist/standalone-argv.js

@@ -1,6 +1,7 @@
 import { WORKFLOWS_TOPIC } from "./command-ids.js";
 export const STANDALONE_ROOT_COMMANDS = [
     'abort',
+    'blueprint',
     'definition',
     'deploy',
     'diagnose',

package/oclif.manifest.json

@@ -739,6 +739,38 @@
         "tail.js"
       ]
     },
+    "workflows:blueprint:generate": {
+      "aliases": [],
+      "args": {},
+      "description": "Experimental: generate the Sanity Blueprints runtime the definitions require, next to sanity.workflow.ts. Writes the workflow resources, one function per derived need, the effect-handler registry, and a handler stub per declared effect. Covers every deployment in the config, because the emitted resources module declares them all. These flags and this output may change before the Blueprints backend accepts the sanity.workflow resource.",
+      "examples": [
+        "<%= config.bin %> workflows blueprint generate",
+        "<%= config.bin %> workflows blueprint generate --check"
+      ],
+      "flags": {
+        "check": {
+          "description": "Experimental: verify the tree on disk still matches the definitions; write nothing and exit non-zero on any difference. The CI drift gate.",
+          "name": "check",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "workflows:blueprint:generate",
+      "pluginAlias": "@sanity/workflow-cli",
+      "pluginName": "@sanity/workflow-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "workflows",
+        "blueprint",
+        "generate.js"
+      ]
+    },
     "workflows:definition:delete": {
       "aliases": [],
       "args": {
@@ -975,5 +1007,5 @@
       ]
     }
   },
-  "version": "0.32.0"
+  "version": "0.33.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -53,21 +53,27 @@
     "diff": "^9.0.0",
     "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
-    "ora": "^9.4.0"
+    "ora": "^9.4.0",
+    "typescript": "^6.0.3"
   },
   "devDependencies": {
+    "@sanity/blueprints": "^0.21.0",
     "@sanity/cli-core": "^3.6.0",
+    "@sanity/functions": "^1.7.2",
     "@types/diff": "^8.0.0",
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.32.0",
-    "@sanity/workflow-engine-test": "0.32.0",
-    "@sanity/workflow-examples": "0.12.0"
+    "@sanity/workflow-blueprint": "0.33.0",
+    "@sanity/workflow-engine": "0.33.0",
+    "@sanity/workflow-engine-test": "0.33.0",
+    "@sanity/workflow-examples": "0.12.1",
+    "@sanity/workflow-test-fixtures": "0.0.0"
   },
   "peerDependencies": {
     "@sanity/cli-core": "^3.6.0",
-    "@sanity/workflow-engine": "0.32.0"
+    "@sanity/workflow-blueprint": "0.33.0",
+    "@sanity/workflow-engine": "0.33.0"
   },
   "oclif": {
     "bin": "sanity-workflows",
@@ -86,6 +92,9 @@
       "workflows": {
         "description": "Deploy, inspect, and administer Workflows definitions and instances",
         "subtopics": {
+          "blueprint": {
+            "description": "Generate and verify the Sanity Blueprints runtime the definitions require"
+          },
           "definition": {
             "description": "Read and manage workflow definitions"
           }