@sanity/workflow-cli 0.8.1 → 0.10.0

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

package/dist/lib/telemetry.js

@@ -0,0 +1,89 @@
+import { createBatchedStore, createSessionId, defineEvent, defineTrace, } from '@sanity/telemetry';
+import { createTelemetryIntake, isTelemetryEnvDenied, noopTelemetry, } from '@sanity/workflow-engine';
+export const WorkflowCliCommandExecuted = defineTrace({
+    name: 'Editorial Workflows CLI Command Executed',
+    version: 1,
+    description: 'A workflow CLI command was executed — payload is the command id, the names of declared flags used (never their values), and a success flag',
+});
+export const WorkflowDefinitionShared = defineEvent({
+    name: 'Editorial Workflows Definition Shared',
+    version: 1,
+    description: 'A newly created workflow definition version was donated through the explicit definition-sharing opt-in. Content-free marker: the content hash plus the same structural counts Editorial Workflows Definition Deployed carries — the document itself goes to the first-party definition-feedback endpoint, never through telemetry.',
+});
+const OFF = { kind: 'off', logger: noopTelemetry };
+let current = OFF;
+let activeTrace;
+export function cliTelemetry() {
+    return current;
+}
+export function setCliTelemetry(telemetry) {
+    current = telemetry;
+    if (telemetry.kind === 'builtin') {
+        activeTrace = telemetry.store.logger.trace(WorkflowCliCommandExecuted);
+        activeTrace.start();
+    }
+}
+export function clearCliTelemetry() {
+    current = OFF;
+    activeTrace = undefined;
+}
+export function createBuiltinTelemetry(args) {
+    const { client, projectId, env } = args;
+    const envDenied = isTelemetryEnvDenied(env);
+    const store = createBatchedStore(createSessionId(), createTelemetryIntake({ client, projectId, denied: envDenied }));
+    return { kind: 'builtin', logger: store.logger, store, envDenied };
+}
+function traceAsLogEvent(trace) {
+    const { name, version, description } = trace;
+    return { type: 'log', name, version, description };
+}
+const FLUSH_DEADLINE_MS = 3_000;
+export async function raceWithDeadline(work, deadlineMs) {
+    let deadline;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((resolve) => {
+                deadline = setTimeout(() => resolve(undefined), deadlineMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+}
+export async function finishCliTelemetry(data) {
+    if (current.kind === 'provided') {
+        current.logger.log(traceAsLogEvent(WorkflowCliCommandExecuted), data);
+        return;
+    }
+    if (current.kind !== 'builtin')
+        return;
+    if (activeTrace !== undefined) {
+        activeTrace.log(data);
+        activeTrace.complete();
+        activeTrace = undefined;
+    }
+    const { store } = current;
+    try {
+        await raceWithDeadline(store.flush(), FLUSH_DEADLINE_MS);
+    }
+    finally {
+        store.end();
+    }
+}
+export function usedFlagNames(argv, flagDefs) {
+    const terminator = argv.indexOf('--');
+    const tokens = argv.slice(0, terminator === -1 ? argv.length : terminator);
+    return Object.entries(flagDefs ?? {})
+        .filter(([name, def]) => tokens.some((token) => matchesFlag({ token, name, char: def.char })))
+        .map(([name]) => name)
+        .sort();
+}
+function matchesFlag(args) {
+    const { token, name, char } = args;
+    if (token === `--${name}` || token.startsWith(`--${name}=`) || token === `--no-${name}`) {
+        return true;
+    }
+    return char !== undefined && (token === `-${char}` || token.startsWith(`-${char}=`));
+}

package/dist/lib/ui.d.ts

@@ -1,4 +1,4 @@
-import type { ActivityStatus } from '@sanity/workflow-engine';
+import type { ActivityStatus, WorkflowResource } from '@sanity/workflow-engine';
 /**
  * A bold `Title:` section heading. Mirrors the Sanity CLI's `sectionHeader`
  * (name + shape) so it folds into the shared helper when this CLI merges in.
@@ -15,6 +15,38 @@ export declare function formatKeyValue({ key, value, indent, padTo, }: {
     indent?: number;
     padTo?: number;
 }): string;
+/**
+ * A borderless column table as printable lines: cyan header row, every
+ * column padded to its widest cell, columns joined by three spaces.
+ * Mirrors the Sanity CLI's list-table shape (see `projects list`) so it
+ * folds into the shared helper when this CLI merges in. Widths count
+ * visible characters, so a pre-styled (ANSI) cell still pads correctly.
+ */
+export declare function formatTable(headers: string[], rows: string[][]): string[];
+/**
+ * Clip a probe-fetched result back to `limit`. The list query builders
+ * fetch one row past the display limit; when that probe row comes back,
+ * `note` carries the dim "showing the first N" hint to print under the table.
+ */
+export declare function clipToLimit<T>(rows: T[], limit: number): {
+    rows: T[];
+    note?: string;
+};
+/**
+ * The `▸ label` banner printed above a group's output when a run spans
+ * several groups (deployments for deploy, resources for fanned-out reads),
+ * so each block is attributable. `undefined` for a lone group — it keeps its
+ * original unprefixed output. A leading blank line separates every group
+ * after the first.
+ */
+export declare function groupBanner({ label, index, total, }: {
+    label: string;
+    index: number;
+    total: number;
+}): string | undefined;
+/** A workflow resource as a display label: a dataset's `project.dataset` id
+ *  reads naturally bare; other resource types keep their type for clarity. */
+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>;

package/dist/lib/ui.js

@@ -1,26 +1,46 @@
-import { styleText } from 'node:util';
+import { stripVTControlCharacters, styleText } from 'node:util';
 import { formatDistanceToNow } from 'date-fns/formatDistanceToNow';
 import { lightFormat } from 'date-fns/lightFormat';
 import { parseISO } from 'date-fns/parseISO';
 import logSymbols from 'log-symbols';
-/**
- * A bold `Title:` section heading. Mirrors the Sanity CLI's `sectionHeader`
- * (name + shape) so it folds into the shared helper when this CLI merges in.
- */
 export function sectionHeader(title) {
     return styleText('bold', `${title}:`);
 }
-/**
- * A `  key:   value` detail row — a dim, padded key then the value. Mirrors
- * the Sanity CLI's `formatKeyValue` so it folds into the shared helper on
- * merge; pass `padTo` (the longest key's length) to align a block of rows.
- */
 export function formatKeyValue({ key, value, indent = 2, padTo = 0, }) {
     const paddedKey = `${key}:`.padEnd(padTo > 0 ? padTo + 1 : key.length + 1);
     return `${' '.repeat(indent)}${styleText('dim', paddedKey)} ${value}`;
 }
-/** 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 function formatTable(headers, rows) {
+    const width = (cell) => stripVTControlCharacters(cell).length;
+    const widths = headers.map((header, i) => Math.max(width(header), ...rows.map((row) => width(row[i] ?? ''))));
+    const formatRow = (row) => widths
+        .map((columnWidth, i) => {
+        const cell = row[i] ?? '';
+        return cell + ' '.repeat(columnWidth - width(cell));
+    })
+        .join('   ')
+        .trimEnd();
+    return [styleText('cyan', formatRow(headers)), ...rows.map(formatRow)];
+}
+export function clipToLimit(rows, limit) {
+    if (rows.length <= limit) {
+        return { rows };
+    }
+    return {
+        rows: rows.slice(0, limit),
+        note: styleText('dim', `showing the first ${limit} — raise --limit to see more`),
+    };
+}
+export function groupBanner({ label, index, total, }) {
+    if (total <= 1) {
+        return undefined;
+    }
+    const gap = index > 0 ? '\n' : '';
+    return `${gap}${styleText('bold', `▸ ${label}`)}`;
+}
+export function resourceLabel(resource) {
+    return resource.type === 'dataset' ? resource.id : `${resource.type}:${resource.id}`;
+}
 export const activityIcon = {
     done: logSymbols.success,
     active: styleText('cyan', '●'),
@@ -28,25 +48,16 @@ export const activityIcon = {
     failed: logSymbols.error,
     skipped: styleText('dim', '⊘'),
 };
-/** Parse an engine ISO-8601 timestamp, or `undefined` when it's missing or
- *  unparseable. The engine writes valid ISO, but the lake is the only
- *  enforcement boundary — a legacy or raw-client-written doc can carry a bad
- *  or absent timestamp, and `parseISO`/`lightFormat` throw on those. Callers
- *  fall back to the raw value so one bad field never crashes a whole command. */
 function parseTimestamp(iso) {
     if (!iso)
         return undefined;
     const date = parseISO(iso);
     return Number.isNaN(date.getTime()) ? undefined : date;
 }
-/** 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 function formatTimestamp(iso) {
     const date = parseTimestamp(iso);
     return date ? lightFormat(date, 'yyyy-MM-dd HH:mm:ss') : iso;
 }
-/** An engine ISO-8601 timestamp as a relative `… ago` — the Sanity CLI's
- *  job-list format (see `datasets/copy`). For scannable overview tables. */
 export function formatAge(iso) {
     const date = parseTimestamp(iso);
     return date ? `${formatDistanceToNow(date)} ago` : iso;