@sanity/workflow-cli 0.31.0 → 0.33.0

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[];

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/lib/ui.d.ts

@@ -69,9 +69,3 @@ export declare function resourceLabel(resource: WorkflowResource): string;
 /** Status glyph per activity state. log-symbols ship pre-colored (green ✔, red ✖),
  *  so those need no extra wrap; the rest carry their own state color. */
 export declare const activityIcon: Record<ActivityStatus, string>;
-/** An engine ISO-8601 timestamp as an absolute `yyyy-MM-dd HH:mm:ss` — the
- *  Sanity CLI's audit-log format (see `backups/list`). For detail views. */
-export declare function formatTimestamp(iso: string): string;
-/** An engine ISO-8601 timestamp as a relative `… ago` — the Sanity CLI's
- *  job-list format (see `datasets/copy`). For scannable overview tables. */
-export declare function formatAge(iso: string): string;