@sanity/workflow-cli 0.9.0 → 0.10.0

package/dist/lib/ops-report.js

@@ -1,10 +1,7 @@
 import { styleText } from 'node:util';
 import logSymbols from 'log-symbols';
-/**
- * The "ops applied" block shared by write-verb reports (set-stage,
- * fire-action): a blank separator, a header, and one line per primitive
- * that ran. Empty when nothing ran, so callers append it unconditionally.
- */
+import ora from 'ora';
+import { fail, failureDetail } from "./fail.js";
 export function opsAppliedLines(ranOps) {
     const details = (ranOps ?? []).map((op) => {
         const target = op.target ? styleText('dim', ` → ${op.target.scope}.${op.target.field}`) : '';
@@ -12,16 +9,23 @@ export function opsAppliedLines(ranOps) {
     });
     return details.length > 0 ? ['', styleText('dim', 'ops applied:'), ...details] : [];
 }
-/**
- * Emit a write-verb report through its spinner: warn and bail on a no-op
- * (`changed: false`), otherwise succeed and print the ops block. Shared by
- * every write command so the changed / no-op branches stay consistent.
- */
-export function emitWriteReport({ spinner, report, log, }) {
-    if (!report.changed) {
-        spinner.warn(report.message);
-        return;
+export function cascadeTail(cascaded) {
+    return cascaded > 0 ? `, then cascaded ${cascaded} auto-transition(s)` : '';
+}
+export async function runWriteVerb({ startLabel, failLabel, failHeadline, run, report, log, }) {
+    const spinner = ora(startLabel).start();
+    try {
+        const result = await run();
+        const emitted = report(result);
+        if (!emitted.changed) {
+            spinner.warn(emitted.message);
+            return;
+        }
+        spinner.succeed(emitted.message);
+        emitted.opsLines?.forEach(log);
+    }
+    catch (error) {
+        spinner.fail(failLabel);
+        fail(failHeadline, failureDetail(error));
     }
-    spinner.succeed(report.message);
-    report.opsLines.forEach(log);
 }

package/dist/lib/params.js

@@ -3,8 +3,6 @@ function coerceValue(raw) {
         return JSON.parse(raw);
     }
     catch {
-        // Not valid JSON — treat it as a plain string so `--param note=hi`
-        // needs no quoting. The engine validates the typed value either way.
         return raw;
     }
 }
@@ -15,12 +13,6 @@ function parsePair(pair) {
     }
     return [pair.slice(0, eq), coerceValue(pair.slice(eq + 1))];
 }
-/**
- * Parse repeated `key=value` flag pairs (`--param`, `--field`) into an
- * object. Each value is JSON-parsed so numbers/booleans/objects type
- * correctly, falling back to the raw string. The engine validates the
- * result against the declared types the consuming flag targets.
- */
 export function parseParams(pairs) {
     return Object.fromEntries(pairs.map(parsePair));
 }

package/dist/lib/read-fanout.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowResource } from '@sanity/workflow-engine';
+import type { ReadTarget } from './context.ts';
+/** A read target whose query threw — noted in place and reflected in the
+ *  command's exit code. */
+export interface ReadFailure {
+    resource: WorkflowResource;
+    message: string;
+}
+/**
+ * Run a read over every target, grouping output per resource: a banner when
+ * the read spans several, then whatever `run` logs for that target. A throw
+ * from one target is noted under its banner and the rest still render — a
+ * token that can't read one dataset must not sink the whole listing. A
+ * single-target run rethrows instead, keeping the plain unprefixed output
+ * and clean error rendering at the command boundary. Callers exit non-zero
+ * when failures come back.
+ */
+export declare function runReadAcrossTargets({ targets, log, run, }: {
+    targets: ReadTarget[];
+    log: (line: string) => void;
+    run: (target: ReadTarget) => Promise<void>;
+}): Promise<ReadFailure[]>;

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,86 @@
+/**
+ * Definition sharing — an explicit per-invocation opt-in, independent of
+ * telemetry consent. Sharing deployed workflow definitions with 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.
+ *
+ * Consent model: flag-only, never a prompt, nothing persists. Sharing
+ * happens exactly when `--share-definitions-with-sanity` is on the
+ * invocation; without it, an interactive deploy that created new
+ * definition versions logs a one-line stderr hint instead. The telemetry
+ * environment gates (`DO_NOT_TRACK`, account consent) do not apply to
+ * the feedback POST: it is explicit first-party consent, not tracking.
+ */
+import { type DeployDefinitionResult, type DeployedDefinition, type WorkflowResource } from '@sanity/workflow-engine';
+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 hint's full copy — a product contract, pinned by test: it must
+ * state honestly what sharing sends (the document ships VERBATIM, plus
+ * its deployment coordinates) and what never is sent. Logged to stderr
+ * after an interactive deploy that created new definition versions
+ * without the flag — never a prompt, and never on CI / non-TTY runs.
+ */
+export declare const SHARE_HINT: 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;
+/**
+ * The whole post-deploy sharing flow. With the flag: created versions →
+ * read-back → ONE feedback POST for the invocation → a content-free
+ * telemetry marker per shared definition. Without it: the stderr hint
+ * (interactive runs only), nothing sent. No newly created versions
+ * (unchanged re-deploys, dry runs, nothing succeeded) means no hint and
+ * no POST. Any sharing-path failure warns and returns: the deploy
+ * already succeeded, and sharing must never turn it into a failure.
+ *
+ * The optional args exist for the hint's dependencies, mirroring
+ * `setupCliTelemetry` — omitted, the real process surfaces apply.
+ */
+export declare function shareDefinitionsAfterDeploy(args: {
+    flag: boolean;
+    candidates: ShareCandidate[];
+    warn: (message: string) => void;
+    interactive?: boolean;
+    writeStderr?: (message: string) => void;
+}): Promise<void>;

package/dist/lib/share-definitions.js

@@ -0,0 +1,106 @@
+import { styleText } from 'node:util';
+import { isInteractive } from '@sanity/cli-core';
+import { definitionDeployedData, errorMessage, } from '@sanity/workflow-engine';
+import { buildDefinitionShowQuery } from "./definitions.js";
+import { cliTelemetry, WorkflowDefinitionShared, } from "./telemetry.js";
+export const SHARE_ENDPOINT_URI = '/workflow/definition-feedback';
+const SHARE_TAG = 'definition.share';
+export const SHARE_HINT = `\n${styleText('bold', 'Enjoying workflows?')} Show us how you use them: deploy with\n` +
+    `${styleText('cyan', '--share-definitions-with-sanity')} to share newly created definition documents\n` +
+    '(verbatim, with their deployment coordinates) with Sanity — never content\n' +
+    'documents, workflow instances, or your Sanity auth token.\n';
+export function definitionShareMarker(args) {
+    const { status: _status, ...structural } = definitionDeployedData(args.definition, {
+        contentHash: args.contentHash,
+        status: 'created',
+        deployId: args.deployId,
+    });
+    return structural;
+}
+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;
+    }
+}
+export async function shareDefinitionsAfterDeploy(args) {
+    const created = args.candidates.flatMap((candidate) => candidate.results
+        .filter((result) => result.status === 'created')
+        .map((result) => ({ candidate, result })));
+    if (created.length === 0) {
+        return;
+    }
+    if (!args.flag) {
+        const interactive = args.interactive ?? (isInteractive() && process.stderr.isTTY === true);
+        if (interactive) {
+            const writeStderr = args.writeStderr ?? ((message) => void process.stderr.write(message));
+            writeStderr(SHARE_HINT);
+        }
+        return;
+    }
+    const shared = [];
+    try {
+        for (const item of created) {
+            const entry = await loadShareEntry({ ...item, warn: args.warn });
+            if (entry !== undefined) {
+                shared.push({ entry, candidate: item.candidate });
+            }
+        }
+        if (shared.length === 0) {
+            return;
+        }
+        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;
+    }
+    try {
+        const { logger } = cliTelemetry();
+        for (const { entry, candidate } of shared) {
+            logger.log(WorkflowDefinitionShared, definitionShareMarker({ ...entry, deployId: candidate.deployId }));
+        }
+    }
+    catch {
+    }
+}

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,66 @@
+/**
+ * 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;
+    /** 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,92 @@
+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,
+        });
+        setCliTelemetry(telemetry);
+        if (!telemetry.envDenied) {
+            telemetry.store.logger.updateUserProperties(cliUserProperties({ project, cliVersion: args?.cliVersion }));
+            void resolveOrgId(client, project.projectId).then((orgId) => {
+                if (orgId !== undefined)
+                    telemetry.store.logger.updateUserProperties({ orgId });
+            });
+            maybeShowTelemetryDisclosure({
+                userConfig: args?.userConfig ?? getUserConfig(),
+                writeStderr: args?.writeStderr ?? ((message) => void process.stderr.write(message)),
+            });
+        }
+    }
+    catch {
+    }
+}
+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;
+    }
+}

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The CLI's telemetry shell. A standalone oclif binary is its own app
+ * shell — no host to ride — so this module owns the store, the standard
+ * Sanity-intake consent/transport recipe (shared via
+ * `@sanity/workflow-engine`'s `createTelemetryIntake`), and the one-time
+ * disclosure. The `prerun` hook assembles it once per invocation and the
+ * `finally` hook completes the command trace and flushes.
+ *
+ * Consent recipe: CI / `DO_NOT_TRACK` → denied; not logged in → no store
+ * (undetermined, nothing sent); otherwise the account-level status the
+ * intake recipe fetches. Consent is managed account-wide by
+ * `sanity telemetry enable|disable|status` — the CLI inherits it and
+ * ships no consent UX of its own.
+ *
+ * Provided-implementation caveat: a `telemetry` logger on the workflow
+ * config replaces this shell wholesale — the built-in store is never
+ * constructed and none of its policy (consent, environment suppression,
+ * transport) applies; every event flows to the provided logger
+ * unconditionally. Gates live in the store, not at emission sites.
+ *
+ * Payload policy: no customer strings, ever. The command trace carries
+ * the command id, the NAMES of declared flags used, and a success flag —
+ * never flag values, arguments, or error text. `Editorial Workflows
+ * Definition Shared` is a content-free marker (hash + structural counts); the shared
+ * document itself rides the first-party feedback endpoint, never
+ * telemetry (see `share-definitions.ts`).
+ */
+import { type DefinedTelemetryTrace, type TelemetryStore } from '@sanity/telemetry';
+import { type TelemetryIntakeClient, type WorkflowDefinitionDeployedData, type WorkflowTelemetryLogger } from '@sanity/workflow-engine';
+export interface WorkflowCliCommandData {
+    /** The oclif command id — ours, never user free-text. */
+    command: string;
+    /** Names of DECLARED flags present on the invocation — never values,
+     *  never undeclared tokens. */
+    flags: string[];
+    success: boolean;
+}
+export declare const WorkflowCliCommandExecuted: DefinedTelemetryTrace<WorkflowCliCommandData, void>;
+/** {@link WorkflowDefinitionDeployedData} minus the deploy status — the marker
+ *  is projected from the engine's own structural derivation so the two events
+ *  can never disagree about one definition, and only newly created versions
+ *  are ever shared, so status carries nothing. */
+export type WorkflowDefinitionSharedData = Omit<WorkflowDefinitionDeployedData, 'status'>;
+export declare const WorkflowDefinitionShared: import("@sanity/telemetry").DefinedTelemetryLog<WorkflowDefinitionSharedData>;
+/**
+ * The shell for one CLI invocation. `builtin` is the Sanity-intake store;
+ * `provided` is a config-supplied logger that replaces the shell and its
+ * policy wholesale; `off` (the default) emits nothing — no config-derived
+ * project, no auth token, or telemetry setup failed.
+ */
+export type CliTelemetry = {
+    kind: 'builtin';
+    logger: WorkflowTelemetryLogger;
+    store: TelemetryStore<unknown>;
+    envDenied: boolean;
+} | {
+    kind: 'provided';
+    logger: WorkflowTelemetryLogger;
+} | {
+    kind: 'off';
+    logger: WorkflowTelemetryLogger;
+};
+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;
+export declare function clearCliTelemetry(): void;
+/** Build the built-in Sanity-intake shell over an authenticated,
+ *  project-bound client. */
+export declare function createBuiltinTelemetry(args: {
+    client: TelemetryIntakeClient;
+    projectId: string;
+    env: Record<string, string | undefined>;
+}): Extract<CliTelemetry, {
+    kind: 'builtin';
+}>;
+/**
+ * Race `work` against a deadline, resolving `undefined` when the deadline
+ * wins. The timer is always cleared once the race settles — oclif never
+ * force-exits on success, so a pending timer would hold a finished process
+ * open. The losing promise's eventual settlement is absorbed by the race.
+ */
+export declare function raceWithDeadline<T>(work: Promise<T>, deadlineMs: number): Promise<T | undefined>;
+/**
+ * Complete the command trace and flush the final batch — the `finally`
+ * hook's whole job. On the built-in store the trace completes with the
+ * payload and the store flushes (deadline-capped); a provided logger gets
+ * the same payload through its `log` seam and owns its own delivery.
+ */
+export declare function finishCliTelemetry(data: WorkflowCliCommandData): Promise<void>;
+/**
+ * The names of declared flags present in `argv` — long form (`--name`,
+ * `--name=value`), negated booleans (`--no-name`), and short chars
+ * (`-c`). Matching against the command's declared flags is what keeps
+ * values and free-text out of the payload; tokens after the `--`
+ * terminator are never inspected.
+ */
+export declare function usedFlagNames(argv: string[], flagDefs: Record<string, {
+    char?: string;
+}> | undefined): string[];