@sanity/workflow-cli 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @sanity/workflow-cli
 
+## 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
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+- ba031fe: **Experimental, and not ready for production use in this release.** Both commands are available so you can try the generated runtime and give feedback; their flags and their output may still change. What you would hit today:
+  - The start watcher runs on every create and update of a subject type, not only on writes that can actually start a workflow, so it wakes for documents that already have an instance or match no definition. The heartbeat is scheduled every minute and evaluates every in-flight instance in the tag when it runs; how often the platform runs it is a plan limit.
+  - `sanity-workflows deploy` does not check the generated tree, so drift between your definitions and the tree on disk is caught only by `blueprint generate --check` in CI.
+  - Definitions and functions deploy in two steps, definitions first, until the Blueprints service registers the `sanity.workflow` resource.
+  - A generated file cannot be taken over: editing one is drift, and the next generation rewrites it.
+  - A retry policy is not checked against its function's timeout at generation, so an effect can be configured to retry for longer than its function may run.
+
+  All of these are tracked, and the next release is the bar for using this in production.
+
+  `sanity-workflows blueprint generate` generates the Sanity Blueprints runtime your definitions require and writes it next to `sanity.workflow.ts`. It prints the needs analysis first — which effects force a drain function, which `$now` condition forces a scheduled heartbeat, which autonomous definition forces a start watcher, and the explicit "no functions needed" answer for a purely interactive workflow — then writes `workflows.blueprint.ts`, one function module and manifest per derived need, the effect-handler registry, and one handler stub per declared effect name. Handler stubs are yours: they are scaffolded once and never overwritten. Your own `sanity.blueprint.ts` receives the `workflowResources` import and spread once. The command deletes nothing; a handler for an effect you removed, a scaffold blocked by a path differing only in case, and a blueprint it could not wire are reported as warnings for you to resolve. The generated tree is one artifact for the whole config, so the command always covers every deployment.
+
+  `sanity-workflows blueprint generate --check` is the CI drift gate. It renders the same runtime in memory, compares it with the files on disk, writes nothing, and exits zero when they match. Otherwise it exits 1 and lists every file with its reason — `missing`, `differs`, an orphaned handler, or a blueprint that is not wired — so a CI log says what to fix without anyone reading source. A declared effect with no handler file on disk reports as `missing`, which is the handler-coverage check.
+
+  **No upgrade action required.** Both commands are new and nothing else changes. To use them, your `sanity.workflow.ts` must export each deployment under its own `name`, and that export must be the deployment object itself — `export const production = {name: 'production', …} satisfies WorkflowDeploymentInput`, then `export default defineWorkflowConfig({deployments: [production]})` — because every generated module imports its deployment from `./sanity.workflow` by that name; a config that only default-exports fails the command with the export to add rather than writing a tree that cannot compile. The command checks the name only, so make sure each export is the deployment the config lists: a typecheck of the generated modules catches a wrong export only where a generated function uses it, and a deployment that needs no functions emits none. Your `sanity.workflow.ts` must also be importable inside a deployed function, because every generated module imports it and each function bundles it: reading an absent variable there yields `undefined`, but a config that throws when a variable is missing, or requires one to build the deployment, fails every deployed function on init. Keep the deployment's resource coordinates literal in that file and read secrets inside your handlers. Deploy your definitions with `sanity-workflows deploy` before `npx sanity blueprints deploy`, because the generated blueprint carries the definitions entry commented out until the Blueprints service accepts the `sanity.workflow` resource type, and a function that starts or advances an instance resolves its definition from the Content Lake. A generated heartbeat is a scheduled function, which the platform only accepts on an organization-scoped stack, and how often it may run is a plan limit. Also install `@sanity/blueprints`, `@sanity/functions`, and `@sanity/workflow-blueprint` in your project: each generated function's manifest copies the specifications your project declares for `@sanity/functions`, `@sanity/workflow-blueprint`, and `@sanity/workflow-engine`, and a package you declare nowhere fails the command instead of being stamped with a guessed range. `typescript` is now a dependency of the CLI, because parsing `sanity.blueprint.ts` to insert the wiring uses the TypeScript compiler.
+
+  **Docs impact:** Rewrite the cookbook chapter on running workflows on a server so it drives the runtime through these two commands rather than describing hand-written functions, and cover the CI drift check there. Update the CLI command reference with both commands, and the Blueprints concept page where it explains who writes the generated tree.
+
+### Patch Changes
+
+- 393ac71: CLI and MCP telemetry now includes `context.surface` (`cli` or `mcp`) and
+  execution mode in each event's `context.environment`. Dashboards can include
+  shell and engine activity while distinguishing it from SDK events marked
+  `sdk`. Existing command trace context is preserved.
+
+  All three surfaces report `production` for `NODE_ENV=production`, and
+  `development` for `development` or `test`. Unset, empty, and unrecognized values
+  default to `production` for CLI and MCP execution mode, and `development` for
+  SDK build mode. SDK environment classification is unchanged. When comparing
+  activity across surfaces, group or filter by surface alongside environment.
+  Environment does not identify a production dataset or deployment; API host,
+  dataset name, and workflow tag do not set it.
+
+  **No upgrade action required.** Existing telemetry consent and opt-out
+  settings still apply. Historical events are unchanged.
+
+  **Docs impact:** Update CLI, MCP, and SDK telemetry guidance to explain surface
+  context, build versus execution mode, the explicit defaults, and how to
+  interpret environment when comparing activity across surfaces.
+
+- 8874c50: **BREAKING:** A `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+  now requires its selected documents to remain readable after initialization.
+  Previously, the flag checked only that an initial value was supplied. Missing
+  required targets now produce a fault and prevent normal actions, triggered
+  actions, and transitions from advancing, even without an activity requirement
+  reading those targets. Abort and direct edits to editable fields remain
+  available. Optional references fault only when an unmet runtime condition needs
+  their content; completed workflows remain completed.
+
+  `StuckCause` adds `document-missing`. Update exhaustive handlers before upgrading,
+  or their typechecks fail and renderers have no matching branch. Evaluation
+  identifies the affected field and reference in `missingDocuments`, with its title
+  and completed availability evidence; `blockingMissingDocuments` selects the
+  references that prevent progress. The engine checks draft, published, and release
+  representations before distinguishing deletion from inaccessible content or
+  content outside the workflow perspective. Studio, CLI, and MCP use that same
+  result. Failed availability checks report unreadable content and log the cause;
+  optional references still permit unrelated actions. Incomplete reads do not
+  claim deletion, and an existing task fault keeps
+  its recovery controls. The fault clears when the required content becomes
+  readable; this release adds no undo-delete operation and does not automatically
+  abort workflows.
+
+  Upgrade every Workflows runtime sharing affected data, including Studio, CLI,
+  MCP servers, and deployed Functions, before relying on continued required-target
+  availability. Then set the deployment's reviewed `expectedMinReaderModel` to
+  `10` before deploying definitions with required content references. Writers stamp
+  model 10; this feature requires reader model 10, while documents without it keep
+  the floor required by their other features, normally 4, 8, or 9. Existing
+  instances remain readable without a backfill and adopt the rule under upgraded
+  engines. Their stored floor rises on the next full write, so an older runtime
+  can still advance an unstamped existing instance until the fleet is upgraded.
+  See `packages/workflow-engine/DATAMODEL.md` for the complete rollout contract.
+
+  The rendered CLI `show` command evaluates running instances. If evaluation fails,
+  it warns and displays stored state; terminal instances and `show --json` retain
+  their stored-state behavior.
+
+  **Docs impact:** Update field requiredness and initialization guidance, required
+  reference repair examples, the model-10 readers-first rollout, the diagnostics
+  reference for `StuckCause` and `MissingDocument`, CLI `show` and `diagnose`, MCP
+  workflow-state guidance, and the Workflows tool and document-view guides for
+  loading, deletion, permissions, and perspectives.
+
+- 3b42bdc: The Workflows CLI command-trace now sets the oclif command id as trace context (`groupOrCommand`) when the built-in telemetry shell starts, so telemetry reporting can break invocations down by command the same way it can for other Sanity CLI commands. The id remains in the log payload as `command` for config-provided telemetry loggers.
+
+  **No upgrade action required.** Existing CLI installs begin emitting the queryable context after upgrading; historical rows are unchanged.
+
+  **Docs impact:** None — internal telemetry envelope shape for an existing event; no public API or user-facing CLI behavior change.
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- 2cef086: Internal maintenance consolidates engine action/edit handling and Studio document
+  and workflow title sorting. Action and field-edit calls retain their inputs and
+  results, and document and workflow titles retain their ordering. Action
+  availability, telemetry, and persisted document formats are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** because public APIs, configuration, and workflow behavior
+  are unchanged.
+
+- Updated dependencies [8874c50]
+- Updated dependencies [b3b2797]
+- Updated dependencies [393ac71]
+- Updated dependencies [8874c50]
+- Updated dependencies [ba031fe]
+- Updated dependencies [0555271]
+- Updated dependencies [b3b2797]
+- Updated dependencies [225e0fb]
+- Updated dependencies [b7510cc]
+- Updated dependencies [7eb9eca]
+- Updated dependencies [2cef086]
+- Updated dependencies [232f811]
+- Updated dependencies [ba031fe]
+  - @sanity/workflow-blueprint@0.33.0
+  - @sanity/workflow-engine@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes