@sanity/workflow-cli 0.32.0 → 0.34.0

package/dist/commands/workflows/diagnose.js

@@ -4,6 +4,7 @@ import { formatDateTime } from '@sanity/cli-core/dates';
 import { diagnoseInputFromEvaluation, workflow, unsatisfiedTransitionSummaries, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
+import { stuckDiagnosisLines, stuckHeadline } from "../../lib/cause-detail.js";
 import { resolveInstanceContext } from "../../lib/context.js";
 import { fail, failureDetail } from "../../lib/fail.js";
 import { instanceFlags, jsonFlags } from "../../lib/flags.js";
@@ -40,39 +41,6 @@ function currentStageLines(input, explanations) {
     }
     return lines;
 }
-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 waitingHeadline(w) {
     const who = w.assignees.length > 0 ? ` on ${w.assignees.map(formatAssignee).join(', ')}` : '';
     if (w.waitingFor === 'automation') {
@@ -120,44 +88,6 @@ function blockedLines(b) {
         `activity completing, required content landing). It will not advance on its own.`,
     ];
 }
-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 '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);
-    }
-}
 function liveChildrenTail(diagnosis) {
     if (diagnosis.liveChildren === undefined)
         return '';
@@ -178,7 +108,7 @@ function statusLine(diagnosis) {
             return `${logSymbols.info} ${styleText('dim', 'aborted')} at ${formatDateTime(diagnosis.at)}${tail}.${liveChildrenTail(diagnosis)}`;
         }
         case 'stuck':
-            return `${logSymbols.warning} ${styleText('yellow', 'STUCK')} — ${causeDetail(diagnosis.cause).headline}`;
+            return stuckHeadline(diagnosis.cause);
     }
 }
 export function rawTransitionProjection(evaluation) {
@@ -195,7 +125,7 @@ export function rawTransitionProjection(evaluation) {
         })),
     }));
 }
-export function renderDiagnosis({ diagnosis, input, remediations, explanations, }) {
+export function renderDiagnosis({ diagnosis, input, remediations, explanations, allMissingDocuments, }) {
     const lines = [statusLine(diagnosis)];
     const inFlight = diagnosis.state === 'progressing' ||
         diagnosis.state === 'waiting' ||
@@ -210,14 +140,7 @@ export function renderDiagnosis({ diagnosis, input, remediations, explanations,
     if (diagnosis.state === 'blocked') {
         lines.push('', ...blockedLines(diagnosis));
     }
-    if (diagnosis.state === 'stuck') {
-        const detail = causeDetail(diagnosis.cause);
-        const runnable = remediations.filter((r) => r.available);
-        lines.push('', sectionHeader("Why it's stuck"), ...detail.why);
-        if (runnable.length > 0) {
-            lines.push('', sectionHeader('Suggested fix'), ...remediationLines(runnable));
-        }
-    }
+    lines.push(...stuckDiagnosisLines({ diagnosis, allMissingDocuments, remediations }));
     return lines;
 }
 export default class Diagnose extends WorkflowCommand {
@@ -258,7 +181,13 @@ export default class Diagnose extends WorkflowCommand {
         this.log(instanceHeader(evaluation.instance));
         this.log('');
         const explanations = new Map(unsatisfiedTransitionSummaries(evaluation).map((entry) => [entry.transition, entry.summary]));
-        for (const line of renderDiagnosis({ diagnosis, input, remediations, explanations })) {
+        for (const line of renderDiagnosis({
+            diagnosis,
+            input,
+            remediations,
+            explanations,
+            allMissingDocuments: evaluation.missingDocuments,
+        })) {
             this.log(line);
         }
     }

package/dist/commands/workflows/show.d.ts

@@ -1,5 +1,6 @@
 import { type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
+import { type InstanceDiagnostic } from '../../lib/cause-detail.ts';
 export default class Show extends WorkflowCommand {
     static description: string;
     static examples: string[];
@@ -12,15 +13,12 @@ export default class Show extends WorkflowCommand {
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private diagnostic;
 }
 /** The summary block at the top of `show` (and reused by `diagnose` /
  *  `fire-action`): a bold workflow + id title, then aligned detail rows. */
 export declare function instanceHeader(instance: WorkflowInstance): string;
-/**
- * The per-instance body lines: every stage with its activities, any pending
- * effects, and (optionally) the history log. Pure so it can be asserted
- * without driving the oclif command.
- */
 export declare function describeInstance(instance: WorkflowInstance, options: {
     includeHistory: boolean;
+    diagnostic?: InstanceDiagnostic | undefined;
 }): string[];

package/dist/commands/workflows/show.js

@@ -1,11 +1,13 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
 import { formatDateTime } from '@sanity/cli-core/dates';
-import { abortReason, displayTitle, terminalState, } from '@sanity/workflow-engine';
+import { abortReason, workflow, errorMessage, displayTitle, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
+import { stuckDiagnosisLines, stuckHeadline, } from "../../lib/cause-detail.js";
 import { findInstance, resolveReadTargets } from "../../lib/context.js";
 import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { baseEngineArgs } from "../../lib/operation-args.js";
 import { formatKeyValue, sectionHeader, activityIcon } from "../../lib/ui.js";
 export default class Show extends WorkflowCommand {
     static description = 'Show the state, activities, and effects of a workflow instance.';
@@ -42,14 +44,33 @@ export default class Show extends WorkflowCommand {
             this.log(JSON.stringify(instance, null, 2));
             return;
         }
+        const diagnostic = await this.diagnostic(hit);
         this.log(instanceHeader(instance));
         this.log('');
         for (const line of describeInstance(instance, {
             includeHistory: flags.include.includes('history'),
+            diagnostic,
         })) {
             this.log(line);
         }
     }
+    async diagnostic(hit) {
+        const { instance } = hit;
+        if (terminalState(instance) !== 'in-flight')
+            return undefined;
+        try {
+            const { diagnosis, evaluation, remediations } = await workflow.diagnose({
+                client: hit.client,
+                ...baseEngineArgs({ tag: instance.tag, workflowResource: instance.workflowResource }),
+                instanceId: instance._id,
+            });
+            return { diagnosis, remediations, allMissingDocuments: evaluation.missingDocuments };
+        }
+        catch (error) {
+            this.warn(`Could not evaluate the instance: ${errorMessage(error)}. Showing stored state; reference availability is unknown.`);
+            return undefined;
+        }
+    }
 }
 const HEADER_PAD = 9;
 export function instanceHeader(instance) {
@@ -77,11 +98,17 @@ export function instanceHeader(instance) {
 }
 export function describeInstance(instance, options) {
     return [
+        ...diagnosticLines(options.diagnostic),
         ...stageLines(instance),
         ...pendingEffectLines(instance),
         ...(options.includeHistory ? historyLines(instance) : []),
     ];
 }
+function diagnosticLines(diagnostic) {
+    if (diagnostic?.diagnosis.state !== 'stuck')
+        return [];
+    return [stuckHeadline(diagnostic.diagnosis.cause), ...stuckDiagnosisLines(diagnostic), ''];
+}
 function stageLines(instance) {
     return [
         sectionHeader('Stages'),

package/dist/hooks/prerun/telemetry.d.ts

@@ -6,5 +6,11 @@ import type { Hook } from '@oclif/core';
  *  resolved from raw argv because the store is built before oclif parses
  *  flags. Skips non-workflows commands when this package is mounted as a
  *  host plugin so `sanity dataset list` does not inherit the shell. */
+export declare function installPrerunTelemetry(args: {
+    bin: string;
+    version: string;
+    commandId: string | undefined;
+    argv: string[];
+}): Promise<void>;
 declare const hook: Hook<'prerun'>;
 export default hook;

package/dist/hooks/prerun/telemetry.js

@@ -1,16 +1,23 @@
 import { shouldRunWorkflowCliTelemetry } from "../../command-ids.js";
 import { shouldForceShareTelemetry } from "../../lib/share-definitions.js";
 import { setupCliTelemetry } from "../../lib/telemetry-setup.js";
-const hook = async function ({ config, Command, argv }) {
-    if (!shouldRunWorkflowCliTelemetry({
-        bin: config.bin,
-        commandId: Command?.id,
-    })) {
+export async function installPrerunTelemetry(args) {
+    const { bin, version, commandId, argv } = args;
+    if (!shouldRunWorkflowCliTelemetry({ bin, commandId })) {
         return;
     }
     await setupCliTelemetry({
-        cliVersion: config.version,
-        forceSend: shouldForceShareTelemetry({ commandId: Command?.id, argv }),
+        cliVersion: version,
+        forceSend: shouldForceShareTelemetry({ commandId, argv }),
+        ...(commandId !== undefined ? { commandId } : {}),
+    });
+}
+const hook = async function ({ config, Command, argv }) {
+    await installPrerunTelemetry({
+        bin: config.bin,
+        version: config.version,
+        commandId: Command?.id,
+        argv,
     });
 };
 export default hook;

package/dist/lib/blueprint-emit.d.ts

@@ -0,0 +1,30 @@
+import type { WorkflowConfig } from '@sanity/workflow-engine';
+export interface BlueprintGenerationArgs {
+    /** The directory the config was loaded from. Every planned path is relative
+     *  to it, and the tree is written under it. */
+    root: string;
+    config: WorkflowConfig;
+    /** The config file's name as discovered in `root`. Decides the specifier the
+     *  generated modules import their deployment from, and names the file in a
+     *  diagnostic. */
+    configFile: string;
+    exportedNames: readonly string[];
+    log: (line: string) => void;
+}
+/**
+ * Writes the runtime tree `config` requires under `root`. A handler stub is
+ * written only where none exists, and nothing is ever deleted.
+ *
+ * Exits through the clean `fail` path, writing nothing, when a definition fails
+ * deploy-time validation, when the definitions cannot produce a plan, when the
+ * config module does not export a deployment by name, or when the project
+ * declares no version for a dependency the generated functions import.
+ */
+export declare function generateBlueprint(args: BlueprintGenerationArgs): void;
+/**
+ * Compares the runtime tree `config` requires with the files under `root`,
+ * writing nothing. Logs one success line when they match, and otherwise exits
+ * non-zero through the clean `fail` path with one entry per problem. Takes the
+ * same exits as {@link generateBlueprint} before it can compare anything.
+ */
+export declare function checkBlueprint(args: BlueprintGenerationArgs): void;

package/dist/lib/blueprint-emit.js

@@ -0,0 +1,147 @@
+import { styleText } from 'node:util';
+import { applyEmissionWritePlan, deploymentExportIdentifier, emissionDivergences, emissionWritePlan, GENERATED_BY, readGenerationRoot, runtimeEmissionPlan, } from '@sanity/workflow-blueprint/generate';
+import logSymbols from 'log-symbols';
+import { needsReportLines } from "./blueprint-needs.js";
+import { validateOrFail } from "./definitions.js";
+import { fail, failOnThrow } from "./fail.js";
+import { deploymentLabel } from "./select-deployment.js";
+import { sectionHeader } from "./ui.js";
+export function generateBlueprint(args) {
+    const planned = planGeneration(args);
+    for (const line of needsReportLines(planned.needs))
+        args.log(line);
+    const applied = failOnThrow('Failed to write the generated tree:', () => applyEmissionWritePlan({ root: args.root, plan: planned.writePlan }));
+    args.log('');
+    for (const line of emitReportLines({ applied, planned }))
+        args.log(line);
+}
+export function checkBlueprint(args) {
+    const planned = planGeneration(args);
+    const problems = [
+        ...emissionDivergences({ root: args.root, plan: planned.writePlan }).map((divergence) => [
+            divergenceRow(divergence),
+        ]),
+        ...misalignmentReports(planned.writePlan),
+    ];
+    if (problems.length === 0) {
+        args.log(`${logSymbols.success} the generated tree matches the definitions`);
+        return;
+    }
+    fail(`The generated tree does not match the definitions (${problems.length}):`, [...problems.flat(), `Run \`${GENERATED_BY}\` to bring it back in line.`].join('\n'));
+}
+function planGeneration(args) {
+    validateEveryDeployment(args.config);
+    const needs = failOnThrow('The definitions cannot produce a runtime:', () => runtimeEmissionPlan(args.config));
+    const onDisk = readGenerationRoot(args.root);
+    const writePlan = failOnThrow('Cannot plan the generated tree:', () => emissionWritePlan({ plan: needs, configFile: args.configFile, ...onDisk }));
+    assertDeploymentsAreExported(args);
+    return { needs, writePlan, existingPaths: onDisk.existingPaths };
+}
+function validateEveryDeployment(config) {
+    const attributed = config.deployments.length > 1;
+    for (const deployment of config.deployments) {
+        validateOrFail(deployment.definitions, attributed ? `${deploymentLabel(deployment)} — ` : '');
+    }
+}
+function assertDeploymentsAreExported(args) {
+    const exported = new Set(args.exportedNames);
+    const missing = args.config.deployments
+        .map((deployment) => deploymentExportIdentifier(deployment.name))
+        .filter((identifier) => !exported.has(identifier));
+    if (missing.length === 0)
+        return;
+    const [first = ''] = missing;
+    fail(`${args.configFile} does not export ${missing.map((name) => `"${name}"`).join(', ')}:`, [
+        `Every generated module imports its deployment by name from ${args.configFile}, so each`,
+        `deployment needs its own named export, and that export must be the deployment object`,
+        `itself. Declare it once and reuse it:`,
+        '',
+        `  export const ${first} = {name: '${first}', /* … */}`,
+        `  export default defineWorkflowConfig({deployments: [${missing.join(', ')}]})`,
+        '',
+        `Only the name is checked here, so make sure each export is the deployment this config`,
+        `lists. A typecheck of the generated modules catches a wrong export only where a`,
+        `generated function uses it.`,
+    ].join('\n'));
+}
+const STATUS_WIDTH = 10;
+const WRITE_NOTES = {
+    generated: '',
+    scaffold: 'yours now — implement the effect',
+    wired: 'the workflow resources spread',
+};
+const DIVERGENCE_NOTES = {
+    generated: '',
+    scaffold: 'no handler for a declared effect',
+    wired: 'the workflow resources spread is absent',
+};
+function statusRow(args) {
+    const tail = args.note === '' ? '' : `  ${styleText('dim', args.note)}`;
+    return `  ${args.status.padEnd(STATUS_WIDTH)} ${args.path}${tail}`;
+}
+function warningRow(path, note) {
+    return `  ${logSymbols.warning} ${path} — ${note}`;
+}
+function emitReportLines(args) {
+    const { applied, planned } = args;
+    const kept = ownedStubPaths(planned);
+    const misalignments = misalignmentReports(planned.writePlan);
+    const attention = misalignments.length === 0 ? '' : `, ${misalignments.length} need your attention`;
+    return [
+        sectionHeader('Generated tree'),
+        ...applied.map((write) => statusRow({ status: write.status, path: write.path, note: WRITE_NOTES[write.ownership] })),
+        ...kept.map((path) => statusRow({ status: 'kept', path, note: 'yours, left untouched' })),
+        ...misalignments.flat(),
+        '',
+        `${logSymbols.success} ${applied.length} file(s) written, ${kept.length} left untouched${attention}`,
+    ];
+}
+function ownedStubPaths(planned) {
+    const written = new Set(planned.writePlan.writes.map((write) => write.path));
+    const reported = new Set(reportedPaths(planned.writePlan));
+    return planned.existingPaths
+        .filter((path) => path.endsWith('.ts') && !written.has(path) && !reported.has(path))
+        .toSorted();
+}
+function reportedPaths(plan) {
+    return [
+        ...plan.orphanedStubs.map((stub) => stub.path),
+        ...plan.caseCollisions.map((collision) => collision.existingPath),
+        ...(plan.orphanedRegistry === undefined ? [] : [plan.orphanedRegistry]),
+    ];
+}
+function divergenceRow(divergence) {
+    return statusRow({
+        status: divergence.reason,
+        path: divergence.path,
+        note: DIVERGENCE_NOTES[divergence.ownership],
+    });
+}
+function misalignmentReports(plan) {
+    const wiring = plan.manualBlueprintWiring;
+    return [
+        ...plan.orphanedStubs.map((stub) => [
+            warningRow(stub.path, `no definition declares the effect "${stub.effectName}" — delete it`),
+        ]),
+        ...(plan.orphanedRegistry === undefined
+            ? []
+            : [
+                [
+                    warningRow(plan.orphanedRegistry, 'no definition declares an effect, so nothing imports the registry — delete it'),
+                ],
+            ]),
+        ...plan.caseCollisions.map((collision) => [
+            warningRow(collision.plannedPath, `not written: ${collision.existingPath} differs from it only in case — rename that file ` +
+                `to match the effect "${collision.effectName}"`),
+        ]),
+        ...(wiring === undefined
+            ? []
+            : [
+                [
+                    warningRow(wiring.path, 'could not be wired automatically — add these two lines by hand'),
+                    `      ${wiring.importLine}`,
+                    `      ${wiring.spreadLine}`,
+                ],
+            ]),
+    ];
+}

package/dist/lib/blueprint-needs.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeEmissionPlan } from '@sanity/workflow-blueprint/generate';
+export declare function needsReportLines(plan: RuntimeEmissionPlan): string[];

package/dist/lib/blueprint-needs.js

@@ -0,0 +1,109 @@
+import { styleText } from 'node:util';
+import logSymbols from 'log-symbols';
+import { deploymentLabel } from "./select-deployment.js";
+import { sectionHeader } from "./ui.js";
+export function needsReportLines(plan) {
+    return [
+        sectionHeader('Runtime needs'),
+        ...plan.deployments.flatMap((deployment) => ['', ...deploymentNeedsLines(deployment)]),
+    ];
+}
+const DETAIL = '    → ';
+const REASON = '      ';
+function deploymentNeedsLines(plan) {
+    const { emission } = plan;
+    return [
+        styleText('bold', `▸ ${deploymentLabel({ name: plan.deploymentName, tag: plan.tag })}`),
+        ...hostingLines(plan),
+        ...(emission === undefined
+            ? ['  no functions needed — the reactive session is already this deployment runtime']
+            : [...drainLines(plan, emission), ...clockLines(plan, emission), ...watcherLines(emission)]),
+        ...selfHostedLines(plan),
+        ...warningLines(plan),
+    ];
+}
+const HOSTING_NOTE = {
+    function: '',
+    durableFunction: 'no functions are emitted for these yet',
+    selfHosted: 'nothing is emitted — your own process runs these',
+};
+const HOSTING_ORDER = ['function', 'durableFunction', 'selfHosted'];
+function hostingLines(plan) {
+    return [
+        `  hosting: this deployment declares ${plan.runtimeKind}, and each level below inherits it`,
+        ...kindLines('workflow', plan.hosting.workflows),
+        ...kindLines('effect', plan.hosting.effects),
+    ];
+}
+function kindLines(what, byKind) {
+    return HOSTING_ORDER.flatMap((kind) => {
+        const names = byKind[kind];
+        if (names.length === 0)
+            return [];
+        const note = HOSTING_NOTE[kind];
+        const suffix = note === '' ? '' : ` — ${note}`;
+        return [`${DETAIL}${kind} ${what}(s): ${names.join(', ')}${suffix}`];
+    });
+}
+const SELF_HOSTED_DUTIES = [
+    { key: 'startInstances', duty: 'start instances of' },
+    { key: 'tickDeadlines', duty: 'tick the $now deadlines of' },
+    { key: 'drainEffects', duty: 'drain the effects' },
+    { key: 'reevaluateParents', duty: 're-evaluate, when a child settles,' },
+];
+function selfHostedLines(plan) {
+    const duties = SELF_HOSTED_DUTIES.flatMap(({ key, duty }) => {
+        const names = plan.selfHosted[key];
+        return names.length === 0 ? [] : [`${REASON}${duty} ${names.join(', ')}`];
+    });
+    if (duties.length === 0)
+        return [];
+    return ['  self-hosted: nothing below is emitted, so your own process must', ...duties];
+}
+function drainLines(plan, emission) {
+    const declared = plan.needs.drain.effectNames;
+    if (declared.length === 0)
+        return [];
+    return [
+        `  effects: ${declared.length} declared — ${declared.join(', ')}`,
+        ...emission.drains.map((drain) => `${DETAIL}drain function ${drain.name} runs ${drain.effectNames.join(', ')}`),
+        `${REASON}triggered by instance writes matching ${emission.drainFilter}`,
+    ];
+}
+function clockLines(plan, emission) {
+    const { heartbeat } = emission;
+    if (heartbeat === undefined)
+        return [];
+    const ticked = new Set(plan.hosting.workflows.function);
+    return [
+        `  clock: ${heartbeat.reasons.join('; ')}`,
+        ...timeSiteLines(plan.needs.heartbeat.timeSites.filter((site) => ticked.has(site.definition))),
+        `${DETAIL}scheduled function ${heartbeat.name} on ${heartbeat.schedule}`,
+        `${REASON}a scheduled function runs at most as often as your organization's plan allows` +
+            ` — every minute on Enterprise, hourly on Growth, daily on Free` +
+            ` (https://www.sanity.io/docs/functions/functions-introduction) — and a schedule below` +
+            ` that threshold is deployed and never invoked`,
+    ];
+}
+function timeSiteLines(sites) {
+    return sites.map((site) => `${REASON}${site.definition} · ${site.stage ?? 'definition'} · ${site.address.kind} · ` +
+        site.condition);
+}
+function watcherLines(emission) {
+    const [first] = emission.startWatchers;
+    if (first === undefined)
+        return [];
+    return [
+        `  autonomous starts: ${first.definitions.length} definition(s) — ${first.definitions.join(', ')}`,
+        ...emission.startWatchers.map((watcher) => `${DETAIL}start watcher ${watcher.name} on ${watcher.projectId}.${watcher.dataset}` +
+            ` matching ${watcher.filter}`),
+    ];
+}
+function warningLines(plan) {
+    return [
+        ...plan.anyTypeSubjects.map((name) => `  ${logSymbols.warning} ${name} declares a subject with no types, so its watcher fires` +
+            ` on every create in the dataset — declare types unless that is intended`),
+        ...plan.subjectlessDefinitions.map((name) => `  ${logSymbols.warning} ${name} starts autonomously but declares no subject, so no` +
+            ` document write can start it and it gets no watcher`),
+    ];
+}

package/dist/lib/cause-detail.d.ts

@@ -0,0 +1,9 @@
+import { type Diagnosis, type MissingDocument, type StuckCause, type SuggestedRemediation } from '@sanity/workflow-engine';
+export declare function stuckHeadline(cause: StuckCause): string;
+export interface InstanceDiagnostic {
+    diagnosis: Diagnosis;
+    /** Full evaluation evidence, including references outside the blocking subset. */
+    allMissingDocuments?: MissingDocument[] | undefined;
+    remediations: SuggestedRemediation[];
+}
+export declare function stuckDiagnosisLines({ diagnosis, allMissingDocuments, remediations, }: InstanceDiagnostic): string[];