@sanity/workflow-cli 0.9.0 → 0.11.0

package/dist/lib/read-fanout.js

@@ -0,0 +1,28 @@
+import logSymbols from 'log-symbols';
+import { failureDetail } from "./fail.js";
+import { groupBanner, resourceLabel } from "./ui.js";
+export async function runReadAcrossTargets({ targets, log, run, }) {
+    const failures = [];
+    for (const [index, target] of targets.entries()) {
+        const banner = groupBanner({
+            label: resourceLabel(target.resource),
+            index,
+            total: targets.length,
+        });
+        if (banner !== undefined) {
+            log(banner);
+        }
+        try {
+            await run(target);
+        }
+        catch (error) {
+            if (targets.length === 1) {
+                throw error;
+            }
+            const message = failureDetail(error);
+            failures.push({ resource: target.resource, message });
+            log(`${logSymbols.error} ${message}`);
+        }
+    }
+    return failures;
+}

package/dist/lib/select-deployment.js

@@ -1,15 +1,5 @@
 import { resourceAliasesToMap, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
-/**
- * Pick the deployment for the requested `--tag`. Tags are unique across a
- * config (enforced by defineWorkflowConfig), so a tag names at most one
- * deployment.
- *
- * With no tag: fall back to the sole deployment when there's exactly one
- * (the common single-environment case), otherwise fail asking for `--tag` —
- * a multi-deployment config is ambiguous without it. `orAlternative` extends
- * that ambiguity message for callers with another way out (deploy's `--all-tags`).
- */
 export function selectDeployment(config, { tag, orAlternative = '' }) {
     if (tag === undefined) {
         if (config.deployments.length > 1) {
@@ -27,12 +17,6 @@ export function selectDeployment(config, { tag, orAlternative = '' }) {
     }
     return deployment;
 }
-/**
- * The deployments a `deploy` run acts on: every one with `--all-tags`,
- * otherwise a single target via {@link selectDeployment} and its failure
- * modes. Deploying everything is an explicit opt-in — never a default — so an
- * ambiguous bare `deploy` can't fan a write out across environments.
- */
 export function selectDeployments(config, { tag, allTags }) {
     if (allTags) {
         return config.deployments;
@@ -44,11 +28,6 @@ export function selectDeployments(config, { tag, allTags }) {
 function availableTags(config) {
     return `Available tags: ${config.deployments.map((candidate) => candidate.tag).join(', ')}`;
 }
-/**
- * Project a deployment into the engine's {@link DeployTarget} — the shape the
- * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)
- * consume — expanding its handle bindings into the alias map in the same step.
- */
 export function deploymentToTarget(deployment) {
     return {
         tag: deployment.tag,

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

@@ -0,0 +1,120 @@
+/**
+ * Definition sharing — donating deployed workflow definitions to Sanity is
+ * CONTENT sharing, not telemetry: definitions carry customer-authored
+ * strings (names, titles, GROQ filters) that the telemetry payload policy
+ * bans, so the documents go to Sanity's first-party definition-feedback
+ * endpoint — one POST per deploy invocation — and telemetry carries only a
+ * content-free marker per shared definition plus a per-invocation decision
+ * event.
+ *
+ * Consent model: opt-OUT. A deploy that creates new definition versions
+ * donates by default. The choice is skipped by an explicit flag:
+ * `--share-defs` (donate, no prompt) or `--no-share-defs` (don't). Without a
+ * flag, an interactive terminal takes a ONE-TIME acknowledgement (persisted
+ * in the shared Sanity user config, so it is asked once ever) before the
+ * first donation — notice must precede the send, since we cannot disclose
+ * taking content after taking it. Unattended runs (CI / `DO_NOT_TRACK` / a
+ * non-TTY pipe) can't prompt, so they donate nothing — the standard Sanity-CLI
+ * "silent in CI / `DO_NOT_TRACK`" rule; opt in per run with `--share-defs`.
+ */
+import { type DeployDefinitionResult, type DeployedDefinition, type WorkflowResource } from '@sanity/workflow-engine';
+import type { UserConfigStore } from './telemetry-setup.ts';
+import { type WorkflowDefinitionSharedData } from './telemetry.ts';
+/** The client slice sharing uses — the read-back of just-deployed
+ *  documents and the feedback POST, structurally, so a full
+ *  `SanityClient` satisfies it and tests fake exactly these calls. */
+export interface ShareClient {
+    fetch<T>(query: string, params: Record<string, unknown>, options: {
+        tag: string;
+    }): Promise<T>;
+    request<T>(opts: {
+        uri: string;
+        method: string;
+        body: unknown;
+        tag: string;
+    }): Promise<T>;
+}
+/** One successfully deployed deployment's outcome, paired with the client
+ *  that can read the just-deployed documents back and the resource the
+ *  entries' deployment coordinates derive from. */
+export interface ShareCandidate {
+    client: ShareClient;
+    tag: string;
+    resource: WorkflowResource;
+    results: DeployDefinitionResult[];
+    /** The deploy call's run id — the markers carry the same id the engine's
+     *  deploy events minted, so donated definitions group with their deploy. */
+    deployId: string;
+}
+/** 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";
+/**
+ * The first-run consent prompt — a product contract, pinned by test. It must
+ * name the recipient (Sanity), state that the document ships VERBATIM with its
+ * deployment coordinates and is kept, name what is never shared, and disclose
+ * that the answer is remembered machine-wide (not just for this deploy) with
+ * the per-run override. Shown once (persisted) before the first donation on an
+ * interactive terminal; the answer decides and is remembered.
+ */
+export declare const SHARE_CONSENT_PROMPT: string;
+/**
+ * The one-line reminders printed on every flagless interactive deploy after the
+ * first — product contracts, pinned by test. They keep an ongoing donation (or
+ * a remembered decline) visible every run, never silent, and name the per-run
+ * override. `_ON` shows when the remembered answer shares, `_OFF` when it does not.
+ */
+export declare const SHARE_REMINDER_ON: string;
+export declare const SHARE_REMINDER_OFF: string;
+/**
+ * The content-free telemetry marker for one shared definition — projected
+ * from the engine's own deploy-event derivation ({@link definitionDeployedData})
+ * so `Editorial Workflows Definition Shared` and `Editorial Workflows Definition Deployed` can
+ * never disagree about one definition's structure. Status is dropped:
+ * only newly created versions are ever shared.
+ */
+export declare function definitionShareMarker(args: {
+    definition: DeployedDefinition;
+    contentHash: string;
+    deployId: string;
+}): WorkflowDefinitionSharedData;
+/**
+ * Whether the invocation's telemetry should send despite the environment
+ * denial (CI / `DO_NOT_TRACK`). Only an explicit `--share-defs` that actually
+ * donates forces it — a command-line arg beats env vars, and a `--share-defs`
+ * donation must never be recorded-less. Account-level consent is never
+ * overridden (the intake still reads `/intake/telemetry-status`).
+ *
+ * Computed from raw argv because the prerun hook builds the store before oclif
+ * parses flags, so it must land on the same value oclif will: repeated
+ * `allowNo` booleans are **last-token-wins**, and tokens after `--` aren't
+ * flags. `--dry-run` / `--check` never create versions, so they never donate —
+ * no telemetry to force. The `share-defs` flag has no char/alias/env source,
+ * so `--share-defs` / `--no-share-defs` are its only tokens (add one and this
+ * match must learn it too).
+ */
+export declare function shouldForceShareTelemetry(args: {
+    commandId: string | undefined;
+    argv: string[];
+}): boolean;
+/**
+ * The whole post-deploy sharing flow. Resolves the opt-out decision (explicit
+ * flag, one-time acknowledgement, or standing policy), donates when it lands
+ * on share, and always records the content-free per-invocation decision so
+ * adoption dashboards can measure opt-out rate. No newly created versions
+ * (unchanged re-deploys, dry runs, nothing succeeded) means no decision, no
+ * prompt, and no POST.
+ *
+ * The optional args exist for the flow's dependencies, mirroring
+ * `setupCliTelemetry` — omitted, the real process surfaces apply.
+ */
+export declare function shareDefinitionsAfterDeploy(args: {
+    flag: boolean | undefined;
+    candidates: ShareCandidate[];
+    warn: (message: string) => void;
+    interactive?: boolean;
+    envDenied?: boolean;
+    writeStderr?: (message: string) => void;
+    userConfig?: UserConfigStore;
+    confirmShare?: () => Promise<boolean>;
+}): Promise<void>;

package/dist/lib/share-definitions.js

@@ -0,0 +1,187 @@
+import { styleText } from 'node:util';
+import { getUserConfig, isInteractive } from '@sanity/cli-core';
+import { confirm } from '@sanity/cli-core/ux';
+import { definitionDeployedData, errorMessage, isTelemetryEnvDenied, } from '@sanity/workflow-engine';
+import { buildDefinitionShowQuery } from "./definitions.js";
+import { cliTelemetry, WorkflowDefinitionShared, WorkflowDefinitionSharingDecided, } from "./telemetry.js";
+export const SHARE_ENDPOINT_URI = '/workflow/definition-feedback';
+const SHARE_TAG = 'definition.share';
+const SHARE_DECISION_KEY = 'workflowCliDefinitionSharing';
+export const SHARE_CONSENT_PROMPT = `${styleText('bold', 'Share the workflow definitions this deploy creates with Sanity?')}\n` +
+    'They are sent verbatim (structure, names, filters, effect configuration,\n' +
+    'seeded values) with their deployment coordinates, and kept to improve\n' +
+    'Editorial Workflows — never your content documents, workflow instances, or\n' +
+    'your Sanity auth token. Your answer is remembered for future deploys on\n' +
+    `this machine; override any run with ${styleText('cyan', '--share-defs')} / ${styleText('cyan', '--no-share-defs')}.`;
+export const SHARE_REMINDER_ON = `${styleText('bold', 'Sharing new workflow definitions with Sanity')} to improve Editorial Workflows` +
+    ` — opt out with ${styleText('cyan', '--no-share-defs')}.\n`;
+export const SHARE_REMINDER_OFF = `Not sharing workflow definitions with Sanity — share with ${styleText('cyan', '--share-defs')}.\n`;
+export function definitionShareMarker(args) {
+    const { status: _status, ...structural } = definitionDeployedData(args.definition, {
+        contentHash: args.contentHash,
+        status: 'created',
+        deployId: args.deployId,
+    });
+    return structural;
+}
+export function shouldForceShareTelemetry(args) {
+    const { commandId, argv } = args;
+    if (commandId !== 'deploy') {
+        return false;
+    }
+    const terminator = argv.indexOf('--');
+    const tokens = terminator === -1 ? argv : argv.slice(0, terminator);
+    if (tokens.includes('--dry-run') || tokens.includes('--check')) {
+        return false;
+    }
+    return tokens.lastIndexOf('--share-defs') > tokens.lastIndexOf('--no-share-defs');
+}
+async function loadShareEntry(args) {
+    const { candidate, result, warn } = args;
+    const deployed = await loadDeployedForShare(args);
+    if (deployed === undefined) {
+        return undefined;
+    }
+    if (deployed.contentHash === undefined) {
+        warn(`${result.name} v${result.version} carries no content hash — not shared.`);
+        return undefined;
+    }
+    return {
+        definition: deployed,
+        contentHash: deployed.contentHash,
+        name: result.name,
+        version: result.version,
+        resourceType: candidate.resource.type,
+        resourceId: candidate.resource.id,
+    };
+}
+async function loadDeployedForShare(args) {
+    const { candidate, result, warn } = args;
+    const { groq, params } = buildDefinitionShowQuery({
+        name: result.name,
+        tag: candidate.tag,
+        version: result.version,
+    });
+    try {
+        const deployed = await candidate.client.fetch(groq, params, {
+            tag: SHARE_TAG,
+        });
+        if (deployed === null) {
+            warn(`Could not read back ${result.name} v${result.version} — not shared.`);
+            return undefined;
+        }
+        return deployed;
+    }
+    catch (error) {
+        warn(`Could not read back ${result.name} v${result.version} — not shared. ${errorMessage(error)}`);
+        return undefined;
+    }
+}
+function collectCreated(candidates) {
+    return candidates.flatMap((candidate) => candidate.results
+        .filter((result) => result.status === 'created')
+        .map((result) => ({ candidate, result })));
+}
+function readShareDecision(userConfig) {
+    const value = userConfig.get(SHARE_DECISION_KEY);
+    return typeof value === 'boolean' ? value : undefined;
+}
+async function promptFirstRun(args) {
+    let share;
+    try {
+        share = await args.confirmShare();
+    }
+    catch {
+        return false;
+    }
+    try {
+        args.userConfig.set(SHARE_DECISION_KEY, share);
+    }
+    catch {
+    }
+    return share;
+}
+async function resolveShareIntent(args) {
+    if (args.flag === true) {
+        return { share: true, decision: 'opt-in' };
+    }
+    if (args.flag === false) {
+        return { share: false, decision: 'opt-out' };
+    }
+    const unattended = args.envDenied || !args.interactive;
+    if (unattended) {
+        return { share: false, decision: 'unattended' };
+    }
+    const remembered = readShareDecision(args.userConfig);
+    if (remembered !== undefined) {
+        args.writeStderr(remembered ? SHARE_REMINDER_ON : SHARE_REMINDER_OFF);
+        return { share: remembered, decision: remembered ? 'remembered-share' : 'remembered-decline' };
+    }
+    const accepted = await promptFirstRun(args);
+    return { share: accepted, decision: accepted ? 'prompt-accepted' : 'prompt-declined' };
+}
+async function donate(args) {
+    const shared = [];
+    try {
+        for (const item of args.created) {
+            const entry = await loadShareEntry({ ...item, warn: args.warn });
+            if (entry !== undefined) {
+                shared.push({ entry, candidate: item.candidate });
+            }
+        }
+        if (shared.length === 0) {
+            return false;
+        }
+        await shared[0].candidate.client.request({
+            uri: SHARE_ENDPOINT_URI,
+            method: 'POST',
+            body: { definitions: shared.map(({ entry }) => entry) },
+            tag: SHARE_TAG,
+        });
+    }
+    catch (error) {
+        args.warn(`Definition sharing failed — nothing shared. ${errorMessage(error)}`);
+        return false;
+    }
+    emitShareMarkers(shared);
+    return true;
+}
+function emitShareMarkers(shared) {
+    try {
+        const { logger } = cliTelemetry();
+        for (const { entry, candidate } of shared) {
+            logger.log(WorkflowDefinitionShared, definitionShareMarker({ ...entry, deployId: candidate.deployId }));
+        }
+    }
+    catch {
+    }
+}
+function emitSharingDecided(data) {
+    try {
+        cliTelemetry().logger.log(WorkflowDefinitionSharingDecided, data);
+    }
+    catch {
+    }
+}
+export async function shareDefinitionsAfterDeploy(args) {
+    const created = collectCreated(args.candidates);
+    if (created.length === 0) {
+        return;
+    }
+    try {
+        const { share, decision } = await resolveShareIntent({
+            flag: args.flag,
+            interactive: args.interactive ?? (isInteractive() && process.stderr.isTTY === true),
+            envDenied: args.envDenied ?? isTelemetryEnvDenied(process.env),
+            userConfig: args.userConfig ?? getUserConfig(),
+            writeStderr: args.writeStderr ?? ((message) => void process.stderr.write(message)),
+            confirmShare: args.confirmShare ??
+                (() => confirm({ message: SHARE_CONSENT_PROMPT, default: true }, { output: process.stderr })),
+        });
+        const shared = share ? await donate({ created, warn: args.warn }) : false;
+        emitSharingDecided({ decision, shared, definitionCount: created.length });
+    }
+    catch (error) {
+        args.warn(`Definition sharing skipped — ${errorMessage(error)}`);
+    }
+}

package/dist/lib/stub.js

@@ -1,15 +1,8 @@
 import { Command } from '@oclif/core';
 import boxen from 'boxen';
 import logSymbols from 'log-symbols';
-/**
- * Base class for commands that aren't wired to the engine yet. Parses
- * the subclass's args + flags, then prints a "not yet implemented"
- * banner plus the parsed inputs so the surface is testable end-to-end,
- * and exits non-zero — a stub must never report success to a caller.
- */
 export class StubCommand extends Command {
     async run() {
-        // `this.parse()` with no args picks up the subclass's static metadata.
         const parsed = await this.parse(this.ctor);
         const body = [
             `${logSymbols.warning} not yet implemented`,

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

@@ -0,0 +1,70 @@
+/**
+ * Once-per-invocation assembly of the CLI telemetry shell — the `prerun`
+ * hook's whole job. Discovery is deliberately soft: telemetry must never
+ * break (or exit) a command, so a missing/broken config, missing token,
+ * or dataset-less config just leaves the invocation with telemetry off;
+ * the command itself surfaces those problems where they matter.
+ */
+import { processShellUserProperties, type TelemetryIntakeClient, type WorkflowResource } from '@sanity/workflow-engine';
+/** The get/set slice of the shared Sanity user config (cli-core's
+ *  `getUserConfig`) the shell persists flags into — narrow so tests fake
+ *  exactly what's read and written. */
+export interface UserConfigStore {
+    get: (key: string) => unknown;
+    set: (key: string, value: unknown) => void;
+}
+/**
+ * The one-time transparency notice, mirroring the sanity CLI's
+ * `telemetryDisclosure` — both CLIs feed the same pipeline. Written to
+ * stderr so it never garbles command output.
+ */
+export declare function maybeShowTelemetryDisclosure(args: {
+    userConfig: UserConfigStore;
+    writeStderr: (message: string) => void;
+}): void;
+/**
+ * Assemble and install the invocation's shell: a config-provided
+ * `telemetry` logger replaces the built-in shell wholesale (none of its
+ * policy applies); otherwise the built-in Sanity-intake store is
+ * constructed when an auth token and a dataset-backed deployment exist —
+ * mirroring the standard recipe's "not logged in → nothing sent".
+ *
+ * The optional args exist for the hook's dependencies (cwd, environment,
+ * user config, stderr) — omitted, the real process surfaces apply.
+ */
+export declare function setupCliTelemetry(args?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    userConfig?: UserConfigStore;
+    writeStderr?: (message: string) => void;
+    /** The oclif config's version — the prerun hook supplies it. */
+    cliVersion?: string;
+    /** Override the environment denial (CI / `DO_NOT_TRACK`) — the prerun hook
+     *  sets this for a deploy that explicitly opts into definition sharing with
+     *  `--share-defs`. */
+    forceSend?: boolean;
+    /** Intake client override — tests inject a fake here, like the other
+     *  hook dependencies above; omitted, the real project client applies. */
+    client?: TelemetryIntakeClient;
+}): Promise<void>;
+/**
+ * The invocation's environment user properties — the sanity CLI's precedent
+ * set (versions, platform, runtime, project coordinates). `orgId` — which
+ * Studio's shell sends and the sanity CLI doesn't yet — attaches separately
+ * once {@link resolveOrgId} resolves. Joined to the session's events by
+ * sessionId downstream; user identity stays sink-side.
+ */
+export declare function cliUserProperties(args: {
+    project: {
+        projectId: string;
+        resource: WorkflowResource;
+    };
+    cliVersion: string | undefined;
+}): ReturnType<typeof processShellUserProperties> & {
+    cliVersion?: string;
+    projectId: string;
+    dataset: string;
+};
+/** The intake project's organization id — degrade-soft: a failed, slow, or
+ *  org-less lookup resolves undefined, never rejects, never breaks a command. */
+export declare function resolveOrgId(client: TelemetryIntakeClient, projectId: string): Promise<string | undefined>;

package/dist/lib/telemetry-setup.js

@@ -0,0 +1,99 @@
+import { styleText } from 'node:util';
+import { getUserConfig } from '@sanity/cli-core';
+import { datasetResourceParts, processShellUserProperties, } from '@sanity/workflow-engine';
+import boxen from 'boxen';
+import { clientFor, resolveToken } from "./client.js";
+import { loadWorkflowConfigIfPresent } from "./load-config.js";
+import { createBuiltinTelemetry, raceWithDeadline, setCliTelemetry } from "./telemetry.js";
+const DISCLOSURE_KEY = 'workflowCliTelemetryDisclosed';
+const SANITY_CLI_DISCLOSURE_KEY = 'telemetryDisclosed';
+export function maybeShowTelemetryDisclosure(args) {
+    const { userConfig, writeStderr } = args;
+    if (userConfig.get(DISCLOSURE_KEY) !== undefined ||
+        userConfig.get(SANITY_CLI_DISCLOSURE_KEY) !== undefined) {
+        return;
+    }
+    writeStderr(`${boxen(`The Sanity workflow CLI collects telemetry data on general usage and errors.
+This helps us improve workflows and prioritize features.
+
+To opt in/out, run ${styleText('cyan', 'npx sanity telemetry enable/disable')}.
+Learn more: https://www.sanity.io/telemetry`, { borderColor: 'yellow', borderStyle: 'round', margin: 1, padding: 1 })}\n`);
+    userConfig.set(DISCLOSURE_KEY, Date.now());
+}
+function intakeProject(config) {
+    const resource = config.deployments
+        .map((deployment) => deployment.workflowResource)
+        .find((candidate) => candidate.type === 'dataset');
+    if (resource === undefined) {
+        return undefined;
+    }
+    return { projectId: datasetResourceParts(resource.id).projectId, resource };
+}
+export async function setupCliTelemetry(args) {
+    try {
+        const config = await loadWorkflowConfigIfPresent(args?.cwd);
+        if (config === undefined) {
+            return;
+        }
+        if (config.telemetry !== undefined) {
+            setCliTelemetry({ kind: 'provided', logger: config.telemetry });
+            return;
+        }
+        const token = await resolveToken().catch(() => undefined);
+        const project = token === undefined ? undefined : intakeProject(config);
+        if (token === undefined || project === undefined) {
+            return;
+        }
+        const client = args?.client ?? clientFor(project.resource, token);
+        const telemetry = createBuiltinTelemetry({
+            client,
+            projectId: project.projectId,
+            env: args?.env ?? process.env,
+            forceSend: args?.forceSend ?? false,
+        });
+        setCliTelemetry(telemetry);
+        attachBuiltinContext({ telemetry, project, client, deps: args });
+    }
+    catch {
+    }
+}
+function attachBuiltinContext(args) {
+    const { telemetry, project, client, deps } = args;
+    if (!telemetry.envDenied || telemetry.forceSend) {
+        telemetry.store.logger.updateUserProperties(cliUserProperties({ project, cliVersion: deps?.cliVersion }));
+        void resolveOrgId(client, project.projectId).then((orgId) => {
+            if (orgId !== undefined)
+                telemetry.store.logger.updateUserProperties({ orgId });
+        });
+    }
+    if (!telemetry.envDenied) {
+        maybeShowTelemetryDisclosure({
+            userConfig: deps?.userConfig ?? getUserConfig(),
+            writeStderr: deps?.writeStderr ?? ((message) => void process.stderr.write(message)),
+        });
+    }
+}
+const ORG_LOOKUP_DEADLINE_MS = 2_000;
+const CONTEXT_TAG = 'telemetry.context';
+export function cliUserProperties(args) {
+    const { project, cliVersion } = args;
+    return {
+        ...processShellUserProperties('cli'),
+        ...(cliVersion !== undefined ? { cliVersion } : {}),
+        projectId: project.projectId,
+        dataset: datasetResourceParts(project.resource.id).dataset,
+    };
+}
+export async function resolveOrgId(client, projectId) {
+    try {
+        const project = await raceWithDeadline(client.request({
+            uri: `/projects/${projectId}`,
+            tag: CONTEXT_TAG,
+            timeout: ORG_LOOKUP_DEADLINE_MS,
+        }), ORG_LOOKUP_DEADLINE_MS);
+        return project?.organizationId ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}