@sanity/workflow-cli 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @sanity/workflow-cli
 
+## 0.35.0
+
+### Minor Changes
+
+- a3489d2: Workflows CLI commands now load `sanity.workflow.ts` in projects using
+  TypeScript 7. `blueprint generate` and `blueprint generate --check` work with
+  TypeScript 6, TypeScript 7, or no project TypeScript installation: the CLI
+  supplies its own TypeScript 6 compatibility compiler for editing an existing
+  `sanity.blueprint.ts`. Direct generator callers can pass that API through
+  `emissionWritePlan({compiler})` or as the second argument to `wireBlueprint`.
+  When no usable compiler is available, direct wiring reports how to supply one.
+  The Blueprint package root now exports `CONFIG_FILE_NAMES` so custom loaders
+  can share the same config discovery order without importing the generator.
+  The workflow engine and generated function runtimes do not acquire a compiler
+  dependency.
+
+  **No upgrade action required.** Install the updated Workflows release normally;
+  keep your project's TypeScript version and existing config files.
+
+  **Docs impact:** Update the Blueprint generation reference to explain the
+  optional compiler argument and root `CONFIG_FILE_NAMES` export for direct
+  callers, and the CLI installation guidance to say Blueprint commands work in
+  projects using TypeScript 6, TypeScript 7, or no installed TypeScript.
+
+### Patch Changes
+
+- 2f040b6: The README's Telemetry section now states the payload policy as an explicit
+  collected / never-collected pair, governed by
+  [Sanity's telemetry policy](https://www.sanity.io/telemetry), replacing the
+  claim that payloads never include customer-authored strings. That claim was
+  wrong in three ways it is worth knowing about: the dataset name is sent as a
+  session property, effect events carry the author-chosen effect name, and the
+  deployment tag reaches telemetry inside `instanceId`, whose engine-minted form
+  is `<tag>.wf-instance.<random>`. A caller-supplied instance id is sent
+  verbatim. Nothing about what the CLI sends changes; only the description of it
+  does.
+
+  The never-collected list now separates what the company policy excludes from
+  what this package additionally chooses not to send. Flag values, definition
+  names, and stage names sit in the second group: the policy does not prohibit
+  them, so do not read their absence here as a company-wide guarantee. Error
+  messages sit there too, with the policy permitting error information that
+  excludes sensitive data while this package sends none.
+
+  **No upgrade action required.** Review the new lists if you assessed this
+  package's telemetry against the previous wording, in particular if your
+  deployment tags or instance ids encode something you would not want in an
+  analytics pipeline. Consent and opt-out are unchanged: account-level
+  `sanity telemetry disable`, `DO_NOT_TRACK`, and CI suppression all behave as
+  before.
+
+  **Docs impact:** The Telemetry section of the package README is the change.
+  Any internal analytics or privacy guidance quoting the old
+  "never include customer-authored strings" sentence needs the same correction,
+  and guidance that assumes deployment tags are absent from telemetry should be
+  revisited.
+
+- Updated dependencies [a3489d2]
+- Updated dependencies [7e24e4a]
+- Updated dependencies [ab8754a]
+  - @sanity/workflow-blueprint@0.35.0
+  - @sanity/workflow-engine@0.35.0
+
+## 0.34.0
+
+### Patch Changes
+
+- Updated dependencies [00bb88f]
+  - @sanity/workflow-blueprint@0.34.0
+  - @sanity/workflow-engine@0.34.0
+
 ## 0.33.0
 
 ### Minor Changes

package/README.md

@@ -225,6 +225,9 @@ start instances from document writes. `blueprint generate` derives that runtime
 from the definitions and writes it next to `sanity.workflow.ts`, so
 `npx sanity blueprints deploy` has something to deploy. A purely interactive
 workflow needs none of it, and the command says so.
+The CLI supplies its own compiler API for editing `sanity.blueprint.ts`, so your
+project can use TypeScript 6 or 7 without changing versions and does not need
+to install TypeScript for this command.
 
 Five prerequisites:
 
@@ -373,16 +376,60 @@ needs.
 
 ## Telemetry
 
-The CLI collects usage telemetry through Sanity's standard pipeline: a
-per-command trace (`Workflows CLI Command Executed` — the command id, the
-names of declared flags used, never their values, and a success flag) plus
-the engine's adoption events from the operations it drives. Consent is the
-account-wide status managed by `npx sanity telemetry enable|disable|status`;
-CI and trueish `DO_NOT_TRACK` suppress everything (except a deploy that may share
+The CLI collects usage telemetry through Sanity's standard pipeline. Consent
+is the account-wide status managed by `npx sanity telemetry enable|disable|status`.
+CI and trueish `DO_NOT_TRACK` suppress everything except a deploy that may share
 new definitions, which forces that deploy's telemetry unless `--no-share-defs`
-is passed — see [Definition sharing](#definition-sharing)),
-and a session that isn't logged in sends nothing. A one-time notice on stderr
-discloses collection on first use.
+is passed — see [Definition sharing](#definition-sharing). A session that isn't
+logged in sends nothing. A one-time notice on stderr discloses collection on
+first use.
+
+What may be collected is governed by [Sanity's telemetry
+policy](https://www.sanity.io/telemetry). This package sends a subset of it.
+
+Collected:
+
+- Project id, dataset, and organization id, as session properties. The
+  organization id is best effort: it needs a lookup that can resolve to
+  nothing, and the event sends either way.
+- Operating system, CPU architecture, JavaScript runtime and version, and the
+  CLI version.
+- The command invoked, and the names of declared flags used on it.
+- Structural counts and closed vocabulary values derived from a definition or
+  instance: stage and action counts, activity and field kinds, lifecycle,
+  status enums, and durations.
+- Content fingerprints of definitions, and random run ids.
+- `instanceId`, the instance document `_id`. Engine-minted ids embed the
+  deployment tag (`<tag>.wf-instance.<random>`), so the tag reaches telemetry
+  through this field. A caller-supplied instance id is sent verbatim.
+- The author-chosen effect name, on effect events.
+
+Never collected, because the policy excludes them:
+
+- Environment variables, file paths, and file contents.
+- Logs and serialized JavaScript stack traces.
+
+Never collected, because this package goes further than the policy requires.
+The policy does not prohibit any of these, so their absence here is this
+package's choice and not a company-wide guarantee:
+
+- Flag values and argv tokens. Only a declared flag's name is sent, so
+  `--tag=prod` reports `tag`.
+- Error messages, and stack traces of any language. The policy permits error
+  information that excludes sensitive data, but this package's errors quote
+  definition names, tags, and argv, so none is sent. A failure is reported as
+  a success boolean and nothing else.
+- Document content, GROQ, and field values.
+- Definition names and stage names. A stage is reported by its position in
+  `stages[]`, never by name.
+
+Note that a dataset name, a deployment tag, and an effect name are all
+customer-authored. They are collected deliberately, as identifiers and as a
+closed label, not as free text.
+
+Definition sharing sends the definition document to a first-party feedback
+endpoint, not through this pipeline; telemetry only records the content-free
+markers below.
 
 Each event includes `context.surface: 'cli'` and its process execution mode
 in `context.environment`. `NODE_ENV=production` reports `production`;
@@ -400,6 +447,117 @@ One extension point: supply your own logger as `telemetry` in
 every event flows to your implementation unconditionally (CI included), and
 consent, suppression, and destination become its business.
 
+### Session properties
+
+The built-in store attaches these user properties once per invocation (joined
+to events by session id). User identity is not in the payload; the intake
+service resolves the sender from the authenticated session.
+
+| Property          | What it is                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `surface`         | Always `'cli'`.                                                                                  |
+| `machinePlatform` | Node `process.platform` (for example `darwin`, `linux`).                                         |
+| `cpuArchitecture` | Node `process.arch`.                                                                             |
+| `runtime`         | Always `'node'` for this CLI.                                                                    |
+| `runtimeVersion`  | Node `process.version`.                                                                          |
+| `cliVersion`      | The CLI package version, when oclif supplied it.                                                 |
+| `projectId`       | Project id of the first dataset-backed deployment in `sanity.workflow.ts`.                       |
+| `dataset`         | Dataset of that same deployment.                                                                 |
+| `orgId`           | Organization id for that project, when the lookup succeeds before the command flushes. Optional. |
+
+### CLI events
+
+These events are defined by this package.
+
+#### `Workflows CLI Command Executed` (version 1)
+
+One trace per workflows command. The built-in store starts the trace in the
+prerun hook with `groupOrCommand` set to the oclif command id (for example
+`workflows:deploy`, `workflows:definition:list`, `workflows:fire-action`) and
+completes it in the finally hook. A config-supplied logger receives the same
+payload as a log, with no trace. Host commands outside the `workflows` topic
+do not emit.
+
+| Field     | Type       | What is collected                                                                                                                                                       |
+| --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command` | `string`   | The oclif command id (`workflows:…`). Never argv free-text.                                                                                                             |
+| `flags`   | `string[]` | Names of **declared** flags present on the invocation, sorted. Long form, `--no-name`, and short chars. Never values, never undeclared tokens, never tokens after `--`. |
+| `success` | `boolean`  | `true` when the command finished without an oclif error.                                                                                                                |
+
+#### `Workflows Definition Shared` (version 1)
+
+One content-free marker per newly created definition version that actually
+reached Sanity's definition-feedback endpoint. Unchanged redeploys, dry runs,
+and `--check` never emit it. The document itself is not in this event.
+
+| Field              | Type       | What is collected                                                                                    |
+| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `contentHash`      | `string`   | Content fingerprint of the donated definition.                                                       |
+| `deployId`         | `string`   | Random run id shared with that invocation's `Workflows Definition Deployed` events.                  |
+| `stageCount`       | `number`   | Declared stages.                                                                                     |
+| `activityCount`    | `number`   | Activities across those stages.                                                                      |
+| `actionCount`      | `number`   | Actions across those activities.                                                                     |
+| `transitionCount`  | `number`   | Declared transitions.                                                                                |
+| `fieldCount`       | `number`   | Declared field entries at workflow, stage, and activity scope.                                       |
+| `activityKinds`    | `string[]` | Distinct effective activity kinds, sorted: `user`, `service`, `script`, `manual`, `receive`.         |
+| `fieldKinds`       | `string[]` | Distinct declared field kinds, sorted (engine field kinds such as `string`, `subject`, `assignees`). |
+| `guardCount`       | `number`   | Guards declared on stages.                                                                           |
+| `effectCount`      | `number`   | Effects declared on actions.                                                                         |
+| `subworkflowCount` | `number`   | Actions that carry a `spawn` block.                                                                  |
+| `lifecycle`        | `string`   | `'standalone'` or `'child'`.                                                                         |
+
+#### `Workflows Definition Sharing Decided` (version 2)
+
+One event per `deploy` that created at least one new definition version,
+whether or not anything was donated. Measures opt-out rate without carrying
+the document.
+
+| Field             | Type      | What is collected                                                                                                             |
+| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `decision`        | `string`  | `'opt-in'` (`--share-defs`), `'opt-out'` (`--no-share-defs`), or `'default'` (neither flag).                                  |
+| `shared`          | `boolean` | Whether a donation POST reached the endpoint. `false` for any non-sharing decision, and for a chosen share whose POST failed. |
+| `definitionCount` | `number`  | Newly created definition versions this invocation could have donated.                                                         |
+
+### Engine events the CLI records
+
+Write commands pass the CLI logger into the engine, so a successful operation
+also records the engine's adoption events on the same session. Read commands
+(`list`, `show`, `diagnose`, `tail`, `definition list` / `show` / `diff`) do
+not emit engine events. `nuke` deletes engine-owned documents outside those
+verbs and does not emit them either.
+
+Every engine event includes:
+
+| Field              | Type     | What is collected                                                                       |
+| ------------------ | -------- | --------------------------------------------------------------------------------------- |
+| `executionRuntime` | `string` | The JavaScript runtime the engine detected around itself. Always `'node'` for this CLI. |
+| `executionKind`    | `string` | The host the engine was told it is running in. Always `'cli'` for this CLI.             |
+
+Every instance-scoped engine event additionally includes:
+
+| Field                   | Type     | What is collected                                                                                  |
+| ----------------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `definitionContentHash` | `string` | Content fingerprint of the pinned definition. Omitted when the definition predates fingerprinting. |
+| `instanceId`            | `string` | Instance document `_id`.                                                                           |
+
+| Event                           | Version | When the CLI emits it                                               | Additional payload                                                                                                                                                                                                                      |
+| ------------------------------- | ------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Workflows Definition Deployed` | 2       | `deploy` for each definition (created or unchanged)                 | Same structural counts as `Workflows Definition Shared`, plus `status`: `'created'` or `'unchanged'`.                                                                                                                                   |
+| `Workflows Instance Started`    | 2       | `start`, and a `fire-action` that spawns a child                    | `initialFieldCount` (number of caller-supplied initial fields), `viaSpawn` (`true` only for a spawned child), `lifecycle`.                                                                                                              |
+| `Workflows Stage Transitioned`  | 2       | A committed hop from `fire-action`, `start` cascade, or `set-stage` | `fromStageIndex`, `toStageIndex` (indexes into `stages[]`, never names), `toIsTerminal`, `isRevisit`, `dwellMs` (milliseconds in the exited stage, omitted if that entry is missing), `via`: `'transition'` or `'setStage'`. Unsampled. |
+| `Workflows Action Fired`        | 2       | `fire-action`                                                       | `activityKind` (optional; derived kind of the fired activity), `hasParams` (whether params were supplied — not the params), `cascaded` (auto-transitions in the post-action cascade).                                                   |
+| `Workflows Instance Aborted`    | 2       | `abort`                                                             | `changed`: `false` if the instance was already terminal.                                                                                                                                                                                |
+| `Workflows Stage Set`           | 2       | `set-stage`                                                         | `changed`: `false` if already at the target stage.                                                                                                                                                                                      |
+| `Workflows Activity Reset`      | 2       | `reset-activity`                                                    | `changed`: `false` if already at the target status, or the instance was terminal.                                                                                                                                                       |
+| `Workflows Definition Deleted`  | 2       | `definition delete`                                                 | `deletedVersionCount`, `cascadeAbortedCount`, `deletedGuardCount` (guards only when the last version goes).                                                                                                                             |
+| `Workflows Effect Completed`    | 2       | `abort` cancelling a pending effect                                 | `effect` (author-chosen name), `status` (`'done'`, `'failed'`, or `'cancelled'`), `origin` (`'action'`), `cascaded`.                                                                                                                    |
+
+The engine also defines `Workflows Field Edited`, `Workflows Instance Ticked`,
+`Workflows Effects Drained`, and `Workflows Effect State Reported`. This CLI
+does not call those verbs, so it does not record those events. Field-edit and
+tick events are sampled at most once per 60 seconds when some other shell
+does emit them.
+
 ## Definition sharing
 
 Separate from telemetry, a `deploy` that creates new definition versions

package/dist/lib/blueprint-emit.js

@@ -1,5 +1,6 @@
 import { styleText } from 'node:util';
 import { applyEmissionWritePlan, deploymentExportIdentifier, emissionDivergences, emissionWritePlan, GENERATED_BY, readGenerationRoot, runtimeEmissionPlan, } from '@sanity/workflow-blueprint/generate';
+import ts from '@typescript/typescript6';
 import logSymbols from 'log-symbols';
 import { needsReportLines } from "./blueprint-needs.js";
 import { validateOrFail } from "./definitions.js";
@@ -33,7 +34,7 @@ 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 }));
+    const writePlan = failOnThrow('Cannot plan the generated tree:', () => emissionWritePlan({ plan: needs, configFile: args.configFile, compiler: ts, ...onDisk }));
     assertDeploymentsAreExported(args);
     return { needs, writePlan, existingPaths: onDisk.existingPaths };
 }

package/dist/lib/load-config.d.ts

@@ -6,7 +6,7 @@ import { type WorkflowConfig } from '@sanity/workflow-engine';
 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}. */
+     *  actually has among the supported config filenames. */
     configFile: string;
     /** Every name the module exports, `default` included. `blueprint generate`
      *  reads it because each generated module imports its deployment as a named

package/dist/lib/load-config.js

@@ -9,7 +9,7 @@ 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 { CONFIG_FILE_NAMES } from '@sanity/workflow-blueprint';
 import { errorMessage } from '@sanity/workflow-engine';
 import { defineWorkflowConfig } from '@sanity/workflow-engine/define';
 import { createJiti } from 'jiti';

package/dist/lib/telemetry.d.ts

@@ -1,7 +1,7 @@
-/** Payload policy: no customer strings, ever — flag NAMES only (never values,
- *  arguments, or error text); shared-definition events are content-free markers. */
+/** Payload policy under https://www.sanity.io/telemetry: declared flag names
+ *  only, never values, argv, or error text. README Telemetry has the lists. */
 import { type DefinedTelemetryTrace, type TelemetryStore } from '@sanity/telemetry';
-import { type TelemetryIntakeClient, type WorkflowDefinitionDeployedData, type WorkflowTelemetryLogger } from '@sanity/workflow-engine';
+import { type DerivedEventData, type TelemetryIntakeClient, type WorkflowDefinitionDeployedData, type WorkflowTelemetryLogger } from '@sanity/workflow-engine';
 export interface WorkflowCliCommandData {
     /** The oclif command id — ours, never user free-text. */
     command: string;
@@ -11,11 +11,7 @@ export interface WorkflowCliCommandData {
     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 type WorkflowDefinitionSharedData = Omit<DerivedEventData<WorkflowDefinitionDeployedData>, 'status'>;
 export declare const WorkflowDefinitionShared: import("@sanity/telemetry").DefinedTelemetryLog<WorkflowDefinitionSharedData>;
 /**
  * How the donation decision was reached, and what it was. Paired with `shared`

package/oclif.manifest.json

@@ -1007,5 +1007,5 @@
       ]
     }
   },
-  "version": "0.33.0"
+  "version": "0.35.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -49,12 +49,12 @@
     "@oclif/plugin-help": "^6.2.50",
     "@sanity/client": "^7.22.1",
     "@sanity/telemetry": "^1.1.0",
+    "@typescript/typescript6": "^6.0.2",
     "boxen": "^8.0.1",
     "diff": "^9.0.0",
     "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
-    "ora": "^9.4.0",
-    "typescript": "^6.0.3"
+    "ora": "^9.4.0"
   },
   "devDependencies": {
     "@sanity/blueprints": "^0.21.0",
@@ -64,16 +64,16 @@
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-blueprint": "0.33.0",
-    "@sanity/workflow-engine": "0.33.0",
-    "@sanity/workflow-engine-test": "0.33.0",
-    "@sanity/workflow-examples": "0.12.1",
+    "@sanity/workflow-blueprint": "0.35.0",
+    "@sanity/workflow-engine": "0.35.0",
+    "@sanity/workflow-engine-test": "0.35.0",
+    "@sanity/workflow-examples": "0.12.3",
     "@sanity/workflow-test-fixtures": "0.0.0"
   },
   "peerDependencies": {
     "@sanity/cli-core": "^3.6.0",
-    "@sanity/workflow-blueprint": "0.33.0",
-    "@sanity/workflow-engine": "0.33.0"
+    "@sanity/workflow-blueprint": "0.35.0",
+    "@sanity/workflow-engine": "0.35.0"
   },
   "oclif": {
     "bin": "sanity-workflows",