@sanity/workflow-cli 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,485 @@
+# @sanity/workflow-cli
+
+## 0.10.0
+
+### Minor Changes
+
+- d4fd8e6: Deploy grows an explicit definition-sharing opt-in — content sharing, not telemetry, opted into by flag alone with nothing persisted and never a prompt. `deploy --share-definitions-with-sanity` shares the definition documents that deploy newly created, verbatim — the full document: structure, names, titles, GROQ filters, effect configuration, and seeded values, plus its deployment coordinates (project and dataset, or resource id); never content documents, workflow instances, or Sanity auth tokens — for that invocation only. Without the flag, an interactive deploy that created new versions logs a one-line stderr hint pointing at it (CI / non-TTY runs stay silent); telemetry consent and `DO_NOT_TRACK` play no part. Shared documents ride one POST per invocation to Sanity's first-party definition-feedback endpoint — never the telemetry pipeline — and a failed share only warns, never failing a completed deploy. Telemetry keeps a content-free `Editorial Workflows Definition Shared` marker per shared definition, projected from the same structural derivation as `Editorial Workflows Definition Deployed`; unchanged re-deploys neither hint nor share.
+- 5cb0850: `diagnose` renders insight under each unsatisfied exit transition — the transition line gains a dim `↳ Needs: …` summary from the evaluation's derived state, so "stuck" reads as "stuck until X" in the definition's own vocabulary. `--json` gains the RAW derived state instead (`transitions[].blockedBy` with each atom's GROQ and solvable requirement) — structure for scripts, language for humans.
+- 15337f1: Request-tag CLI traffic: clients carry the `sanity.workflows.cli` request-tag prefix — the workflows-owned family with the runtime as its segment, never another team's family. The family identifies the traffic, so per-request tags are bare command ops (`list`, `show`, `definition.list`, `definition.show`, `definition.load`, `instance.load`, `tail` — the tail listener passes a per-request tag because a prefix alone never tags listen requests) and engine verbs strip their `workflow.` root under the family prefix, so everything lands as `sanity.workflows.cli.<op>` in request logs.
+- ced40e4: The CLI is now its own telemetry app shell. A `prerun` hook builds a batched store over the standard Sanity-intake recipe (CI or `DO_NOT_TRACK` deny without a network call; not logged in or no dataset-backed deployment → nothing is sent; otherwise the account-level consent status), shows a one-time stderr disclosure, and threads the store's logger into every engine write verb so engine adoption events flow from CLI-driven operations. A `finally` hook completes the `Editorial Workflows CLI Command Executed` trace — command id, names of declared flags used (never values), success flag — and flushes with a deadline. A `telemetry` logger on the workflow config replaces the built-in shell wholesale: every event flows to it unconditionally and consent/suppression/transport become its business.
+- 0709ab1: De-duplicate the write-verb scaffolding and adopt the engine's canonical helpers:
+  - Every write command (`abort`, `set-stage`, `fire-action`, `start`, `definition delete`) now runs through one `runWriteVerb` helper owning the spinner start / report emit / fail-and-exit catch shape, and the ", then cascaded N auto-transition(s)" suffix comes from one `cascadeTail` helper.
+  - The CLI's local `errorMessage` copy is gone — all error rendering uses the engine's exported `errorMessage` (same control-character stripping as before).
+  - Instance status in `list` and the aborted/completed header in `show` derive from the engine's `terminalState`.
+  - History entries in `tail` and `show --include history` now print the engine's display titles (e.g. "Transition fired") instead of raw discriminators (`transitionFired`).
+  - `fire-action`'s list mode renders the engine's new `instance-aborted` verdict ("instance aborted at …") for actions on aborted instances.
+
+- adf32f7: **BREAKING:** the `--as` / `--as-role` impersonation flags and the pinned `workflow-cli` system actor are removed. Every write is attributed to the user behind the configured token (`/users/me`); impersonation means running with a different token. The CLI declares `executionContext {kind: 'cli', id: 'workflow-cli'}` on its engine scope, so history records the environment without forging identity.
+- 91540de: **BREAKING:** every shell-defined telemetry event name now carries the product name — `Editorial Workflows CLI Command Executed`, `Editorial Workflows Definition Shared` (workflow-cli), `Editorial Workflows MCP Tool Called` (workflow-mcp), `Editorial Workflows Session Started` (workflow-react) — replacing the bare `Workflow <X>` forms, which never shipped. Event names are matched verbatim downstream.
+
+  Shell context parity: every self-owned telemetry shell now attaches its execution environment, following the sanity CLI and Studio precedents. User identity stays sink-side — the intake service resolves the sender from the authenticated session on every event.
+  - CLI: `updateUserProperties` with the sanity CLI's set (cliVersion, platform, architecture, runtime, runtime version, projectId, dataset) plus `surface: 'cli'` and `orgId` resolved once per invocation from the projects API (deadline-capped, degrade-soft — a failed lookup omits the property, never blocks a command).
+  - SDK: Studio-style context enrichment on every posted event — `surface: 'sdk'`, package version, environment, userAgent, project coordinates.
+  - MCP: `updateUserProperties` on store initialization — `surface: 'mcp'`, package version, runtime info, the addressed project coordinates; the server handshake now reports the real package version instead of `0.0.0`.
+  - React hosts (Studio, SDK, custom): the session layer pushes `{surface: host}` into the HOST's own session stream via `updateUserProperties` — Studio-hosted events get an explicit surface marker without touching Studio's transport.
+  - The `Editorial Workflows Definition Shared` marker carries the deploy run's `deployId`, so donated definitions group with the deploy events that minted them.
+
+- d6e92ed: Now published with public npm access (previously restricted) — installable without `@sanity` org membership.
+- 23cf131: Render the engine's new `subject-permission-denied` disabled reason — the actor lacks write permission on a subject document in that subject's own resource.
+- 0a8baa4: Untagged reads now fan out across every distinct resource the config mentions instead of failing with "Config spans multiple resources — pass --tag to choose one": `list` and `definition list` query each dataset and group output under per-resource banners (an unreadable resource is noted in place, the rest still render, and the command exits non-zero), `show` and `tail` look the instance id up across resources (erroring if it exists in several), and `definition show` errors when the name is deployed to more than one dataset. `--tag` still narrows any read to that deployment's resource.
+- f580319: Match the Sanity CLI's output styling: `list` and `definition list` render borderless column tables (lowercase cyan header row, three-space gutters, uncolored cells) instead of boxed tables, and the detail lines under an error headline render in muted red. `definition list` gains a `created` column showing when each definition version was deployed and drops the `startable` column to keep rows scannable, and both list commands print a dim "showing the first N — raise --limit" note when results exceed the limit instead of truncating silently.
+- ced40e4: Request tags move to workflows-owned families with the runtime as the segment: `sanity.workflows.cli`, `sanity.workflows.studio`, `sanity.workflows.sdk` — never another team's family (`sanity.cli.*`, `sanity.studio.*`) — and platform analysis zero-rates `sanity.workflows.*`. The MCP server deliberately sits outside that family as `sanity.workflows-mcp` (no dot boundary), so agent-driven traffic bills. Under any workflows-family prefix the engine's tag wrapper strips the now-redundant `workflow.` root from every relative op tag — stamped fallback and explicit alike — so traffic lands as `sanity.workflows.cli.deploy` with exactly one workflows segment; on raw consumer clients and under foreign host prefixes the root stays, since there it is what identifies the traffic. The Studio adapter's engine and resource-router clients and the SDK telemetry shell's intake client now set their family prefix themselves instead of riding the host's.
+
+### Patch Changes
+
+- e374155: Auth rejections (HTTP 401) now exit through the CLI's clean error path with a recovery hint — re-run `sanity login` when the session token has lapsed, or check `SANITY_AUTH_TOKEN` when the env token is set — instead of surfacing a raw oclif error.
+- 9f5a40f: Document that the CLI's token must span every resource the workflow references — runtime commands build one client from the deployment descriptor, and the engine reaches foreign datasets/resources through sibling clients derived from that same token. Cross-resource runtime routing (`show`, `diagnose`, `fire-action`) is now covered against a subject document living in a different dataset than the workflow resource, with no resolver wiring.
+- 109f900: `workflow deploy` now prints the advisory effect-output lint warnings returned on each deploy result, indented beneath the definition they belong to, so the producer/consumer hints are visible on the CLI deploy path (previously only carried on the result object).
+- 5cb0850: Type-only: the diagnose renderer consumes the engine's narrowed `DiagnosedTransition` slice instead of the full `TransitionEvaluation`, matching what the classifier actually reads. No behavior change.
+- 1045843: `definition diff` and `deploy --dry-run` now show only the authored fields that differ. The deploy envelope (`_id`, `_type`, `tag`, `version`, `contentHash`) is stripped from both sides before diffing — version and document id already appear on the Summary line — and long runs of unchanged context collapse to a dim `… N unchanged lines` marker with three lines of context around each change. Net-new definitions still render in full; the deploy-generated-fields footnote is gone along with the noise it explained.
+- 8077858: The build now cleans `dist/` before compiling, so removed commands can no longer ship as orphaned artifacts in a locally packed tarball (`tsc` never deletes outputs for deleted sources, and `files: ["dist"]` ships the whole directory). A packaging smoke test guards the packed output: the tarball must contain exactly the command modules that exist in `src`, and the built bin must load and register every command — catching broken specifier rewrites and stale workspace-dependency builds that stay green in unit tests and only surface for a consumer.
+- 6c21009: Correct public TSDoc and README claims that contradicted the implementation: CLI auth precedence (an explicit `SANITY_AUTH_TOKEN` wins over the `sanity login` session), the real CLI verbs (`workflow.diagnose`, `workflow.availableActions`) and document types (`sanity.workflow.instance` / `sanity.workflow.definition`), guard predicates reading the delta-mode `before()`/`after()` natives, glob patterns supporting multiple `*`s, where `$can` actually binds (requirements and the editField gate, not action filters alone), the editField target contract (any-scope match with activity-first precedence), guard observation fan-out across the engine dataset plus each watched subject's dataset, the object value expression being op-payload-only, and the MCP descriptor / SDK observer export pointers. The deploy-time `$can` rejection error now states where `$can` actually binds (the caller-bound projection: action filters, requirements, editable predicates) instead of claiming action filters are its only home.
+- 7ffdc77: New `clientConfigFromResource(resource)` export — the `@sanity/client`-config
+  fragment addressing a `WorkflowResource` (dataset via the classic
+  `{projectId, dataset}` config, other resource types passed through as
+  `resource`). The one home for that branch: hosts spread it into their own
+  `createClient` call, and the CLI's `clientFor` now derives its config through
+  it instead of a private copy.
+- 72bd7ef: The packaging suite (subprocess dependency-chain build + `pnpm pack` + spawning the built bin) no longer runs in the default vitest run — it starved sibling suites into nondeterministic timeouts on loaded machines. CI runs it explicitly; opt in locally with `pnpm --filter @sanity/workflow-cli test:packaging`.
+- dc64968: Published tarballs no longer include sourcemaps (whose `sourcesContent` embedded the complete TypeScript source) or inline code comments in the compiled JS — license markers and bundler annotations (`/*@__PURE__*/`-style tree-shaking hints) are preserved. Types and TSDoc in `.d.ts` files ship unchanged, and the tarballs shrink accordingly (workflow-engine: ~3× smaller). Each tarball now ships its `CHANGELOG.md`, so release notes reach consumers who can install the package but cannot see the repository.
+- Updated dependencies [4ca17bb]
+- Updated dependencies [5143707]
+- Updated dependencies [0709ab1]
+- Updated dependencies [6bbf3ca]
+- Updated dependencies [9f5a40f]
+- Updated dependencies [d192d68]
+- Updated dependencies [6c21009]
+- Updated dependencies [109f900]
+- Updated dependencies [109f900]
+- Updated dependencies [444b0e6]
+- Updated dependencies [2511bb5]
+- Updated dependencies [d4fd8e6]
+- Updated dependencies [30ed0e8]
+- Updated dependencies [2834704]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [4607d59]
+- Updated dependencies [52f6024]
+- Updated dependencies [a8f1cb9]
+- Updated dependencies [adf32f7]
+- Updated dependencies [5cb0850]
+- Updated dependencies [70a136c]
+- Updated dependencies [91540de]
+- Updated dependencies [8455fbb]
+- Updated dependencies [325c2d1]
+- Updated dependencies [d6e92ed]
+- Updated dependencies [6c21009]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [325c2d1]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [ced40e4]
+- Updated dependencies [9b1b40d]
+- Updated dependencies [8c319b2]
+- Updated dependencies [dc64968]
+- Updated dependencies [23cf131]
+- Updated dependencies [d192d68]
+- Updated dependencies [15337f1]
+- Updated dependencies [2d1a8e1]
+- Updated dependencies [12cdbd6]
+- Updated dependencies [437b544]
+- Updated dependencies [ced40e4]
+  - @sanity/workflow-engine@0.15.0
+
+## 0.9.0
+
+### Minor Changes
+
+- a0443c4: **BREAKING:** Configure the CLI via a discovered `sanity.workflow.ts` instead of `WORKFLOW_*` environment variables. Every command now loads `defineWorkflowConfig({deployments: [...]})`, selects a deployment by `--tag` (or the sole deployment when only one is configured), and authenticates via the `sanity login` session (falling back to `SANITY_AUTH_TOKEN` for CI). Definitions and resource-handle bindings come from the selected deployment; `deploy` expands the bindings via `resourceAliases` at deploy time.
+
+  Removed env vars: `WORKFLOW_RESOURCE_TYPE`, `WORKFLOW_RESOURCE_ID`, `WORKFLOW_TAG`, `WORKFLOW_DEFS`, `SANITY_PROJECT_ID`, `SANITY_DATASET` (project/dataset are now derived from the deployment's resource).
+
+  Read commands (`list`, `definition list`, `definition show`, `show`, `tail`) inspect everything in the Content Lake resource — the config only locates which resource to read and authenticates; it never filters results to the config's tag or definitions. `--tag` is an optional query filter (omit it to span all partitions). The config selects the resource automatically when all deployments share one, and needs `--tag` only to disambiguate a config that spans multiple resources.
+
+- 83d5924: **BREAKING:** One vocabulary with the engine across the command surface, plus instance start.
+  - `move-stage` is renamed `set-stage`, matching the engine verb it calls (`workflow.setStage`), with help text that states the semantics honestly: an admin override that skips the definition's declared transitions and filters, while the target stage's enter lifecycle and the post-move cascade still run. Its no-op report now distinguishes a terminal instance from an already-at-target one.
+  - The hidden `set-stage` guard-bypass stub is deleted — its name promised the opposite of the engine verb's semantics, and no bypass path exists in the engine. The hidden `retry-activity` stub is renamed `reset-activity` to match the engine's remediation verb.
+  - One noun for definition identity: `definition diff` takes `<name>` (matching `show`/`delete`), `list --workflow-name` becomes `list --definition <name>`, and `definition list --workflow-name` becomes `definition list --name`.
+  - `diagnose` renders remediation verbs under their engine names, so human output and `--json` share one vocabulary; write-command errors are prefixed with the command's own name (`set-stage error:`, `fire-action error:`, `abort error:`, `definition delete error:`) instead of engine verb spellings.
+
+  New: `start <name>` starts an instance from a deployed definition — `--field name=value` supplies the workflow's input-sourced fields (typed against the deployed definition's declared entries; a value for a non-input field is rejected rather than silently ignored), `--version` pins a version, `--as` / `--as-role` attribute the start to a real user, and `--json` emits structured output. Spawn-only (`lifecycle: 'child'`) definitions are refused with an explanation, so the `definition list` Startable column points at a real affordance. Write-path error output is routed through the control-character-stripping `errorMessage` helper across all commands.
+
+- 845266e: `deploy` gains an `--all-tags` flag to deploy every deployment in the config in one run. The default stays a single target: `--tag <tag>` selects a deployment (omittable when only one is configured), and an ambiguous bare `deploy` against a multi-deployment config fails asking for `--tag` or `--all-tags` — deploying everything is always an explicit opt-in, never a default.
+
+  Definitions are validated up front, so a bad definition fails before anything is written — attributed to its deployment when the run spans several. During an `--all-tags` run, deployments are independent and idempotent, so a failure in one doesn't strand the rest: the run continues, then prints a summary of which deployments failed and exits non-zero (a single-target failure propagates directly instead). Deploys stay idempotent — an unchanged, content-addressed definition deploys as a no-op — and `--check` / `--dry-run` compose with both `--tag` and `--all-tags`. Output is labelled per deployment when a run spans more than one.
+
+- 5c69928: **BREAKING:** runtime API coherence pass — one result shape, one session noun, nameable engine args.
+  - `DispatchResult` → `OperationResult`, and its `fired` flag → `changed` with one meaning honored by every verb: this call changed the instance's workflow state (`false` = successful no-op — an idempotent re-fire, a tick that wrote nothing, a `setStage` already at the target, an abort of an already-terminal instance; failures still throw). `tick` derives it from the instance revision, so a persisted activity-gate flip that didn't unlock a transition still reports `changed: true`. `abortInstance` documents its always-`0` cascade (a terminal instance doesn't cascade; ancestor propagation reports on the ancestors).
+  - `startInstance` now returns `OperationResult` instead of a bare `WorkflowInstance` — its cascade is finally observable. Reach the instance via `result.instance`.
+  - Engine argument types are exported and nameable: the exported `*Args` shapes are now exactly what `Engine` methods take, and the raw `workflow.*` namespace takes `<Verb>Args & EngineScopeArgs` (the new exported scope type: `client` / `tag` / `workflowResource` / `resourceClients`). New named args for the read/housekeeping verbs: `InstanceRefArgs`, `ChildrenArgs`, `GuardsForDefinitionArgs`, `InstancesForDocumentArgs`, `QueryArgs`, `QueryInScopeArgs`, `FindPendingEffectsArgs`, `DrainEffectsArgs`, `SessionArgs`. `EvaluateArgs` is likewise scope-free now.
+  - Verb-surface parity between `Engine` and `workflow.*` is exact and documented: `Engine.evaluateInstance` → `Engine.evaluate` (matching `workflow.evaluate`); engine-only members (`session`, `subscriptionDocumentsForInstance`, `drainEffects`, `verifyDeployedDefinitions`) and the namespace-only `workflow.permissions` are called out as deliberate.
+  - One noun for the reactive session handle: `engine.instance(doc, opts?)` → `engine.session({instance, access?, grantsFromPath?})` (args object — no positional outlier), still returning `InstanceSession`; workflow-react's `WorkflowInstanceController` → `WorkflowSession`; the studio/sdk hooks `useWorkflowInstance` → `useWorkflowSession`. "Instance" now always means the document.
+  - Test bench mirrors the engine: `bench.startInstance` returns `OperationResult`, and the `Bench*Args` types are the engine-bound shapes minus `access`.
+  - CLI reports follow the rename: the report objects for `fire-action` / `move-stage` / `abort` (and `fire-action`'s `--json` payload) now say `changed` instead of `fired`.
+
+- 6ee9068: **BREAKING:** follow the engine's vocabulary sweep. `definition list` projects the stored `lifecycle` key (was `role`) to flag spawn-only definitions — definitions deployed before the rename show as startable until redeployed. `fire-action --as` attributes the fire as a `person` actor (was `user`).
+
+### Patch Changes
+
+- a0443c4: `definition diff` (and `deploy --dry-run`) now footnote the detail diff to explain that `_id`, `version`, and `contentHash` are deploy-generated — they change as a function of the content, so their `+`/`-` lines reflect the content change rather than fields the author edited. Without the note an operator could read a bumped `version` as a field they'd set themselves.
+- 2f081a3: Render a `mutation-guard-denied` verdict from its `denied` payload via the engine's shared `deniedGuardLabels` (guard name over id), following the unified guard-denial shape.
+- a0443c4: Instance-targeted commands (`diagnose`, `abort`, `move-stage`, `fire-action`) now derive their tag partition from the instance itself rather than from the config's declared deployments. An instance id is globally unique and carries its own `tag`, so naming one acts on that instance regardless of which tags `sanity.workflow.ts` happens to deploy — the config only locates the resource and authenticates, the same read-context model `show`/`tail` already use. This removes a self-lockout: a `trial`-only config previously could not `diagnose` or `abort` an instance in another partition (e.g. a `bench`- or `prod`-tagged one), failing with "not visible to this engine (tag mismatch)". On these commands `--tag` is now only used to disambiguate a config that spans multiple resources.
+
+  Only `deploy`, `definition diff`, and `definition delete` remain scoped to a declared deployment — they act on the authored definition set or a definition name, which (unlike an instance id) isn't unique across tags.
+
+- df00bbb: The client's API version now comes from the engine's exported `ENGINE_API_VERSION` pin instead of a hand-copied literal, so every client bound to the engine stays on one version by construction.
+- a0443c4: `show` no longer crashes on a workflow instance whose stage omits its `activities` array (an activity-less stage, or an older-shape / raw-client-written document). Such a stage now renders with no activities instead of throwing `activities is not iterable`.
+- Updated dependencies [a0443c4]
+- Updated dependencies [a0443c4]
+- Updated dependencies [ad9b6f6]
+- Updated dependencies [83d5924]
+- Updated dependencies [7a655bd]
+- Updated dependencies [d9c8179]
+- Updated dependencies [0a7979a]
+- Updated dependencies [df00bbb]
+- Updated dependencies [5c69928]
+- Updated dependencies [2f081a3]
+- Updated dependencies [df00bbb]
+- Updated dependencies [113a796]
+- Updated dependencies [df00bbb]
+- Updated dependencies [2829643]
+- Updated dependencies [6ee9068]
+- Updated dependencies [2829643]
+- Updated dependencies [a0443c4]
+  - @sanity/workflow-engine@0.14.0
+
+## 0.8.1
+
+### Patch Changes
+
+- 5bbc3f0: Internal refactor: functions that took 3+ positional parameters now take a single named options object. No public API or behavior change — the package's exported surface (and, for the CLI, its commands and output) is unchanged.
+- Updated dependencies [416d4c9]
+- Updated dependencies [4dfe72a]
+- Updated dependencies [5bbc3f0]
+- Updated dependencies [0bf7503]
+- Updated dependencies [6e51913]
+- Updated dependencies [3229f41]
+  - @sanity/workflow-engine@0.13.0
+
+## 0.8.0
+
+### Minor Changes
+
+- d850aef: **BREAKING:** Workflow definitions are now immutable and content-addressed — the author no longer writes a `version`.
+
+  A definition's `version` (and a new `contentHash` fingerprint) are stamped onto the deployed _document_ at deploy time, derived from the content itself — the same envelope as `_id`/`_type`/`tag`. `defineWorkflow` no longer accepts a `version` (the authoring schema rejects it), and the `WorkflowDefinition` type no longer carries one.
+
+  `deployDefinitions` is now create-only: it hashes the authored content and compares it to the latest deployed version of that name. Identical content is a no-op (`unchanged`); any change mints the next version (`created`). It never patches a deployed version in place, so a definition can no longer change out from under the instances pinned to it. (Engine-side only — true immutability of the deployed document still requires a Content Lake guard; the engine enforces nothing.) Deploying two definitions with the same name in one batch is now rejected.
+
+  Instances pin `pinnedContentHash` alongside `pinnedVersion`, so a consumer can detect a deployed definition that has drifted from what an instance started on.
+
+  API changes:
+  - `defineWorkflow({ version })` / `WorkflowDefinition.version` removed — drop `version` from authored definitions.
+  - `DeployDefinitionResult.status` drops `'updated'` (now `'created' | 'unchanged'`); `DiffEntry.status` drops `'update'` (now `'create' | 'unchanged'`) — a content change is always a new version.
+  - `isDefinitionUnchanged` removed; the content fingerprint is now exposed as `hashDefinitionContent`. `DeployedDefinition` is exported for consumers reading deployed documents.
+  - Spawn refs (`task.subworkflows.definition.version`) are unchanged — you can still pin another definition's deployed version.
+
+- 9519c76: **BREAKING:** Rename the structural `Task` node in the workflow DSL to `Activity`. The node holds multiple Actions, its own scoped Fields, and a status lifecycle — it is not atomic, so in process-modelling terms it is an _Activity_ (BPMN: Activity is the umbrella for work, Task the atomic kind). This frees the word "task" so it never appears in the model — "Tasks" is now purely a product/UI worklist view, not a model entity.
+
+  `Action` (the actor-fired command) is unchanged.
+
+  The rename cascades across the whole surface:
+  - Authoring: `defineTask` → `defineActivity`; the `tasks:` array on a stage → `activities:`; `Task`/`AuthoringTask` types → `Activity`/`AuthoringActivity`.
+  - Classification: `TASK_KINDS` → `ACTIVITY_KINDS`, `TaskKind` → `ActivityKind`, `deriveTaskKind`/`taskKind` → `deriveActivityKind`/`activityKind` (kind values `user`/`service`/`script`/`manual`/`receive` are unchanged). The shipped "task kinds" surface is retitled "Activity kinds".
+  - Status: `TASK_STATUSES`/`TaskStatus` → `ACTIVITY_STATUSES`/`ActivityStatus` (and the terminal-status counterparts); status _values_ are unchanged.
+  - Predicate sentinels: `$tasks` → `$activities`, `$allTasksDone` → `$allActivitiesDone`, `$anyTaskFailed` → `$anyActivityFailed`, `$requiredTasksDone` → `$requiredActivitiesDone`, `$task` → `$activity`. Authored GROQ filters referencing the old names must be updated.
+  - Persisted/wire format: the `'task'` field scope value → `'activity'`, history entry types (`taskActivated`/`taskStatusChanged` → `activityActivated`/`activityStatusChanged`), and engine result/diagnostic codes (`failed-task` → `failed-activity`, `task-not-active` → `activity-not-active`, `reset-task` → `reset-activity`, etc.).
+  - `workflow-react`: the `fireAction` argument `{task}` → `{activity}`.
+
+  Nothing referencing "task" remains in the model. This is a deliberate pre-customer breaking change to land the correct, permanent vocabulary.
+
+- 6aa682e: **BREAKING:** Rename the `--workflow-id` filter to `--workflow-name` on `list` and `definition list`. The flag always filtered by definition name, not an id, so the new name matches both its behaviour and how definitions are referenced everywhere else (`definition show <name>`, etc.). `--workflow-id` is no longer accepted.
+
+### Patch Changes
+
+- Updated dependencies [5b10863]
+- Updated dependencies [ae1434e]
+- Updated dependencies [d850aef]
+- Updated dependencies [9519c76]
+- Updated dependencies [9233cd3]
+- Updated dependencies [3ea4953]
+- Updated dependencies [e5a862a]
+  - @sanity/workflow-engine@0.12.0
+
+## 0.7.1
+
+### Patch Changes
+
+- Updated dependencies [3b8f3de]
+  - @sanity/workflow-engine@0.11.0
+
+## 0.7.0
+
+### Minor Changes
+
+- fae3553: **BREAKING:** Rename the domain concept **state → fields** across the whole API and persisted data model.
+
+  "State" was too easily conflated with "stage". The typed, valued data attached to workflows, stages, and tasks is now called **fields** — clearer, and aligned with Sanity schemas: the fields on a workflow, stage, and task can have typed values. This is a clean break (no migration, no back-compat); already-deployed definitions and instances must be redeployed/recreated.
+
+  **Authoring DSL**
+  - `defineState(...)` → `defineField(...)`
+  - The `state: [...]` array on a workflow / stage / task → `fields: [...]`
+  - The `$state.<name>` GROQ scope token → `$fields.<name>`
+  - A `claim` action's `state:` reference → `field:`
+  - A `stateRead` source → `fieldRead`; its `state:` (entry name) → `field:`
+  - Op targets address the entry by `field:` instead of `state:`
+
+  **Persisted / wire format**
+  - Op type strings `state.set` / `state.unset` / `state.append` / `state.updateWhere` / `state.removeWhere` → `field.*`
+  - The stored `state[]` array on instances, stage entries, and task entries → `fields[]`
+  - `startInstance({ initialState })` → `startInstance({ initialFields })`
+
+  **Types & functions** (engine)
+
+  `StateEntry`→`FieldEntry`, `AuthoringStateEntry`→`AuthoringFieldEntry`, `ResolvedStateEntry`→`ResolvedFieldEntry`, `InitialStateValue`→`InitialFieldValue`, `StateKind`→`FieldKind`, `StateValueMap`→`FieldValueMap`, `StateScope`→`FieldScope`, `StoredStateRef`→`StoredFieldRef`, `STATE_SLOT_DISPLAY`→`FIELD_SLOT_DISPLAY`, `EditStateArgs`→`EditFieldArgs`, `EditStateTarget`→`EditFieldTarget`, `EditStateDeniedError`→`EditFieldDeniedError`, `ConcurrentEditStateError`→`ConcurrentEditFieldError`, `RequiredStateNotProvidedError`→`RequiredFieldNotProvidedError`, and the `editState` verb → `editField`.
+
+  Unchanged: runtime/lifecycle instance "state" (stage moves, `WorkflowStateDivergedError`, the projected instance snapshot), the `field`/`fields` JSON-matching primitives in `updateWhere`/`removeWhere` predicates and object Sources, and the Content Lake release `state`.
+
+### Patch Changes
+
+- Updated dependencies [fae3553]
+  - @sanity/workflow-engine@0.10.0
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [2e4c980]
+- Updated dependencies [fd6b866]
+  - @sanity/workflow-engine@0.9.0
+
+## 0.6.0
+
+### Minor Changes
+
+- d798521: Align CLI output with Sanity CLI conventions.
+  - Instance display (`show`, `diagnose`, `fire-action`): the boxed header is
+    replaced by a plain `styleText` key-value block (bold workflow + id title,
+    dim aligned rows) and task states show colored status glyphs. An aborted
+    instance shows its abort line in place of a misleading green "Completed".
+    `diagnose` and `fire-action` bodies use the same Title-Case section
+    headings as `show` (e.g. `Tasks`, `Exit transitions`, `Why it's stuck`,
+    `Suggested fix`, `Actions on stage '…'`).
+  - `diagnose`: the rendered "Suggested fix" block now lists only remediations
+    the CLI can actually run (`move-stage`, `abort`); planned verbs the engine
+    names but the CLI can't yet perform are no longer shown there (they remain
+    in `--json`).
+  - `definition show`: drops the boxed header for the same plain `styleText`
+    key-value block (bold name + version title, dim `Title` / `Description` /
+    `Tag` rows — the deploy partition is now shown), and the stage/task/action
+    tree uses a bold `Stages` heading with dim secondary text and a cyan
+    `[initial]` marker. Long descriptions now soft-wrap in the terminal instead
+    of being pre-wrapped to a fixed box width.
+  - `list`: drops the `failed` count column and the never-implemented `--subject`
+    flag; adds a relative `Updated` column (`lastChangedAt`) and a `Tag` column
+    (the listing spans partitions); adds an optional `--tag` filter to match
+    `definition list`; colors the `Status` column; orders by most-recently-changed.
+  - `definition list`: narrows the table — folds the version into the `Workflow`
+    column as `name vN` (this CLI's identifier format), drops the redundant
+    `Definition ID` column (the doc `_id` is just `tag.name.vN`, which the
+    Workflow + Tag columns already show, and no command takes a raw `_id`), and
+    shortens the count headers (`Total stages` → `Stages`, `Instances in flight`
+    → `In flight`, `Total instances` → `Instances`).
+  - `definition diff`: the report colors move from `picocolors` to `styleText`
+    and the summary heading uses the shared `sectionHeader` (`Summary:`) for
+    consistency with the rest of the CLI.
+  - Write verbs (`abort`, `move-stage`, `definition delete`), `tail`, and the
+    shared `lib/fail` / `lib/ops-report` helpers move their colors from
+    `picocolors` to `styleText` too. With that the `picocolors` dependency is
+    removed — the CLI now colors output entirely through `node:util`.
+  - Timestamps now go through `date-fns` like the Sanity CLI — absolute
+    `yyyy-MM-dd HH:mm:ss` for detail views (`show`, `diagnose`, `tail`), relative
+    "… ago" for list tables. A missing or unparseable timestamp falls back to its
+    raw value rather than throwing, so one bad document field can't crash a command.
+  - New `lib/ui.ts` mirrors the Sanity CLI's `sectionHeader` / `formatKeyValue`
+    helpers so they fold into the shared ones when this CLI merges in.
+  - Bumps the `engines.node` floor to `>=20.12`, the first release where
+    `node:util`'s `styleText` (which now owns all coloring) is available.
+
+- 8bf467e: Add a definition `role` and a `required` flag on state entries — so spawn-only child workflows can be kept out of standalone-start surfaces, and a load-bearing init slot fails fast instead of silently defaulting.
+  - **`role: 'workflow' | 'child'` on a definition (default `'workflow'`).** A `'child'` definition is spawn-only — instantiated by a parent's `task.subworkflows`, never started cold by a human. The exported `isStartableDefinition(definition)` predicate (plus the `WorkflowRole` type) is the single place that decides "can a human start this", so every consumer filters its start picker the same way. Advisory: the engine does **not** refuse a `startInstance` on a `'child'` def — it's a discoverability flag, not a gate. `@sanity/workflow-cli`'s `definition list` gains a **Startable** column derived from the predicate.
+  - **`required?: boolean` on a state entry — the start/spawn counterpart to action-param validation.** A missing `init`-sourced value previously resolved silently to `null`/`[]`, which is what let a cold-started child come up structurally incomplete (a review with no subject, no assignee). A `required` entry the caller doesn't supply — via `initialState` at start, or the parent's `subworkflows.with` at spawn — now throws the exported `RequiredStateNotProvidedError` and creates nothing, exactly as a missing `required` action param already does. Valid only on a workflow-scope `init` entry; `required` on any other scope or source is a deploy error (`defineWorkflow` rejects it with the offending field path).
+
+  The two compose: `role` keeps a child out of pickers; `required` stops the engine from constructing an incomplete instance if a UI (or a human) starts one anyway.
+
+### Patch Changes
+
+- Updated dependencies [c298ee2]
+- Updated dependencies [8131dd5]
+- Updated dependencies [8bf467e]
+  - @sanity/workflow-engine@0.8.0
+
+## 0.5.2
+
+### Patch Changes
+
+- e618a5f: Fix the release pipeline so `workflow-cli` can publish via CI. `oclif manifest`
+  `import()`s the package's compiled commands, which import the built
+  `@sanity/workflow-engine`; running it inside the publish-time `prepack` depended
+  on a sibling's `dist` being present at that moment and failed `changeset publish`
+  deterministically. The manifest is now generated as an explicit release step
+  after the full workspace build and dropped from `prepack` — it stays gitignored
+  and is still shipped via the package's `files`.
+
+## 0.5.1
+
+### Patch Changes
+
+- 07134ae: Give the `StubCommand` exit-code test generous timeout headroom. A full `Config.load` is fast alone but gets starved past the 5s default on a cold CI runner running every package's suite in parallel, so the test flaked with a timeout.
+
+## 0.5.0
+
+### Minor Changes
+
+- fb3c98a: Make the workflow CLI publishable — both metadata and runtime.
+
+  Metadata: the package drops `private` / `UNLICENSED` and gains the publish fields the other published packages carry — an `MIT` license, `repository`, `homepage`, `bugs`, `author`, `keywords`, an `engines` floor, and a `publishConfig` that resolves the published `exports` to `dist/` only (stripping the `development` / `source` conditions used for in-repo source resolution). Published with `access: restricted`, matching the rest of the workspace.
+
+  Runtime: the previous build was a library bundle (one `dist/index.js` re-exporting `execute`) and never emitted the oclif commands, so a published host had nothing to run. The build now compiles the whole `src/` tree with `tsc` — emitting `dist/commands/**` and rewriting the repo's explicit `.ts` import specifiers to `.js` via `rewriteRelativeImportExtensions` — and the package ships a production `bin/run.js`, an `oclif.manifest.json` generated at pack time, and an ESM-only `exports` map. `oclif.commands` points at `./dist/commands`; dev (`bin/dev.js`) keeps loading the TS sources via oclif's dist→src resolution.
+
+### Patch Changes
+
+- 32f5e64: Name the remediations that would unstick a stuck instance from the engine, not the CLI.
+
+  `workflow.diagnose` now returns `remediations` alongside the diagnosis — a `SuggestedRemediation[]`, empty unless the instance is `stuck`. Each entry names a surface-neutral `RemediationVerb` (`retry-effect` | `drain-effects` | `reset-task` | `set-stage` | `abort`), whether it's runnable as an engine operation today (`available`), and a one-line rationale. The new `remediationsFor` reasoning plus the `SuggestedRemediation` / `RemediationVerb` types are exported. Previously the cause→fix mapping — including which repair verbs exist versus are still planned — lived only in the CLI, so every other consumer (MCP, a future UI) would have had to re-derive it.
+
+  The CLI `diagnose` command now renders its "suggested fix" block from these remediations — a not-yet-runnable verb is dimmed and marked `(planned)` — instead of hardcoding the prose, and includes `remediations` in `--json` output.
+
+- df7582f: Fix two stacked bugs that let a threshold-gated workflow auto-advance past a review it couldn't actually evaluate.
+  - **Filters fail closed on unevaluable operands.** A `task.filter` / `transition.filter` that evaluates to GROQ `null` (a referenced operand was missing or incomparable, e.g. `$state.subject.amount > 10000` when the subject isn't loaded) is no longer coerced to `false`. A `null` gate previously _skipped_ the task / fell through the transition — fail-open. Now an unevaluable `task.filter` keeps the task in scope (the stage holds rather than cascading through), an unevaluable transition filter halts selection, and the undecidability is recorded on `TaskEntry.filterEvaluation.unevaluable` so the audit trail distinguishes "genuinely below threshold" from "couldn't read the field". Unevaluability also propagates through nullary predicates (an unevaluable predicate binds `null`, not `false`).
+  - **Content hydration is draft-preferring.** When an instance has no explicit release perspective, content reads now use a drafts-preferring perspective (drafts overlay published) instead of a published-only point read — uniformly across `doc.ref`/`doc.refs` hydration, `type: "query"` state-entry resolution, and `subworkflows.forEach` discovery (single-sourced as `DEFAULT_CONTENT_PERSPECTIVE`). A subject that exists only as a draft — or whose in-flight edits live in the draft — is now what filters evaluate. Instance / ancestor / `system.release` documents continue to read raw. The reactive App SDK adapter (`@sanity/workflow-sdk`) matches: a content doc with no release is read under the `drafts` perspective instead of relying on the SDK's default, so a reactive session and the engine cascade resolve the same draft-aware view. (The Studio adapter already preferred `version ?? draft ?? published`.)
+  - **Diagnostics tell an undecidable hold from a dead-end.** `TransitionEvaluation` now carries `unevaluable`, and `diagnose` reports a new `transition-unevaluable` stuck cause when every task is resolved but an exit filter can't be evaluated (a recoverable hold — the cascade re-fires once the operand resolves) rather than mislabeling it the permanent `no-transition-fires` routing dead-end. `@sanity/workflow-cli`'s `diagnose` renders the distinct cause.
+  - **Single-document writes commit `visibility: 'sync'`.** `create` and `patch().commit()` now set `visibility: 'sync'` explicitly (via the new `WorkflowCommitOptions`) so the engine never reads a stale value back through a query. Adds `WorkflowCommitOptions` / `WorkflowVisibility` to the public client surface.
+
+- 129258c: Add task `requirements` — a readiness axis for visible-but-not-yet-executable tasks, distinct from ACL and guards.
+
+  A task definition can now declare `requirements: { <name>: <groq-condition> }`: preconditions over the rendered scope that gate _executability_ without affecting visibility. While a requirement is unmet the task stays visible, and every action on it is reported disabled with a new `requirements-unmet` verdict that names the unmet requirements; `TaskEvaluation.unmetRequirements` summarises the same set at the task level so a consumer can explain why the whole task is gated. Requirements are all-of (express any-of inside a single condition), evaluated in the same scope as `filter`, and — like every engine-side check — advisory; the lake remains the enforcement point.
+
+  Diagnostics gain a `blocked` state: an active task held by an unmet requirement is reported as visible-but-not-yet-executable (healthy and transient), distinct from `stuck`, and a requirements-held task no longer masks an actionable sibling in the `waiting` verdict.
+
+  The CLI `fire-action` listing and the MCP server's disabled-reason copy both render the new reason; the CLI `diagnose` command renders the new `blocked` state.
+
+- Updated dependencies [ef927bc]
+- Updated dependencies [32f5e64]
+- Updated dependencies [df7582f]
+- Updated dependencies [ed4174c]
+- Updated dependencies [129258c]
+  - @sanity/workflow-engine@0.7.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [c6d1762]
+  - @sanity/workflow-engine@0.6.0
+
+## 0.4.0
+
+### Minor Changes
+
+- e2a6d5d: Implement `definition delete` (previously a stub): delete a deployed workflow definition by name — every version by default, one via `--version`. Refuses while non-terminal instances exist unless `--cascade` aborts them first (instances are aborted in place, never deleted; `--reason` lands on each abort's history entry), and refuses while any surviving deployed definition spawn-references the target. Reports the deleted versions, cascade-abort count, and orphaned-guard cleanup.
+- b8e364d: Add a `definition diff` command that diffs an in-code definition against the deployed version — the latest deployed version of the workflow by default (so a version bump shows what actually changed), or a specific one via `--version`. Remove the `definition enable` and `definition disable` stubs; no engine semantics back them yet.
+- 4805d29: Add the `diagnose` command: a read-only check that explains why a workflow instance is or isn't progressing, and what would unstick it. It runs a single `workflow.evaluate` and classifies the instance as `progressing`, `waiting` (an active task awaiting a human action — healthy, not stuck), `completed`, `aborted`, or `stuck` with a specific cause (a failed effect, a hung effect, a failed task, or no exit transition firing), printing the evidence and a suggested fix. Supports `--json` for scripting and `--tag` for the environment partition.
+- 1cd93d2: Add the `fire-action` command — fire an action on an instance to unstick a waiting task. Omit `--action` to list the actions available on the current stage (with their allowed/disabled state and params); pass `--task` + `--action` to fire one, with `--param key=value` for action params and `--as <userId>` / `--as-role <role>` to attribute the fire to a real user so assignee- and role-gated filters pass. Honors `--tag` and `--json`. The shared "ops applied" report block is factored out and reused by `move-stage`.
+
+### Patch Changes
+
+- dbc4afa: Move the instance-reasoning behind the CLI's read commands into the engine so every consumer shares one implementation rather than re-deriving it. The engine now exports the stuck-instance classifier (`diagnoseInstance` with `Diagnosis` / `StuckCause` / `DiagnoseInput`, plus `abortReason`, `openStage`, `assigneesOf`, `diagnoseInputFromEvaluation`), the available-actions projection (`availableActions` with `AvailableAction`), and definition-diff classification (`diffEntry` / `computeDiffEntries` with `DiffEntry` / `DeployTarget`) — all reusing the engine's own doc-id minting and no-op verdict. Two instance-id-keyed verbs compose this with `evaluate`: `workflow.diagnose` and `workflow.availableActions` (also on the `Engine` wrapper).
+
+  The CLI's `diagnose`, `fire-action`, `deploy`, and `definition diff` commands keep only their rendering and now call the engine for the reasoning, and the MCP's `get_workflow_state` projects its action verdicts through the same shared `availableActions`. No behavioural change to the CLI or MCP surfaces.
+
+- 4805d29: Fix the boxed instance header (shared by `show` and `diagnose`) so the first row's right border aligns with the rest. The id row now uses a plain `instance:` label instead of a width-ambiguous `ℹ` symbol that `boxen`/`string-width` mis-measured, which had been drifting that line's border.
+- Updated dependencies [dbc4afa]
+- Updated dependencies [e2a6d5d]
+- Updated dependencies [aa87a1c]
+  - @sanity/workflow-engine@0.5.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 4b5f59a: Wire the `abort` command to the engine's new `workflow.abortInstance`: hard-stop an in-flight instance with an optional `--reason` recorded in history. Already-terminal instances report a warning instead of erroring. Aborted instances surface across the read commands too — `list` shows an `aborted` status (instead of `completed`), and `show`'s header carries the abort timestamp plus the recorded reason.
+- fcf938a: Migrate to the new workflow authoring DSL: name identity (`name` /
+  `initialStage` / `currentStage` / `instance.definition`), bare state kinds,
+  type-tagged sources, bare op types with `{scope, state}` targets, GROQ-string
+  conditions and effect bindings, `predicates` as a name→GROQ map, explicit task
+  `activation`, action `status` sugar, claim pairs and audit ops, and
+  `subworkflows` fan-out. The example definitions showcase the new sugar; the
+  CLI and MCP projections read the new stored shapes (terminal = stage with no
+  transitions); the React controller's `fireAction` takes `task` instead of
+  `taskId`; the MCP wire names things what they are — `definition` (the
+  definition's `name`) on the `list_workflow_instances` filter and instance
+  projections, and `task` / `action` (names, not ids) on `fire_action` and
+  the per-task projections, replacing `workflow_id` / `task_id` /
+  `action_id`.
+
+### Patch Changes
+
+- Updated dependencies [4b5f59a]
+- Updated dependencies [fcf938a]
+- Updated dependencies [6c4e0a0]
+- Updated dependencies [12e23b0]
+- Updated dependencies [12e23b0]
+  - @sanity/workflow-engine@0.4.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 440be47: Add a `definition show` command that displays a single deployed workflow definition. Pass a workflow id to show its latest version, or pin one with `--version`, and scope to an environment with `--tag`. Renders a boxed header (workflow id, version, title, description) followed by a stage → task → action breakdown, marking the initial stage and each stage's kind.
+
+### Patch Changes
+
+- 0c6ccde: Extract shared definition-query primitives so the "tag-scoped, latest-or-pinned `workflow.definition`" query lives in one place instead of being hand-written at each call site.
+
+  The engine now exports two reusable GROQ primitives:
+  - `WORKFLOW_DEFINITION_TYPE` / `WORKFLOW_INSTANCE_TYPE` — the lake document-type constants, replacing scattered string literals.
+  - `tagScopeFilter(param?)` — the tag-partition GROQ predicate (`count(tags[@ in $engineTags]) > 0`), defaulting to the `engineTags` parameter the `workflow.query` guard expects.
+
+  Internally these compose into a single `definitionLookupGroq` selector for the "latest-or-pinned definition" query. The engine's own lookups (`deploy`, `spawn`, `drain`) and the CLI (`definition show`/`list`, `list`, `deploy`) now build on these primitives, and every tag-scoped query in those paths standardizes on the `$engineTags` parameter — removing the prior `$tags`/`$engineTags` drift.
+
+- Updated dependencies [41ddd80]
+- Updated dependencies [0c6ccde]
+  - @sanity/workflow-engine@0.3.0
+
+## 0.1.0
+
+### Minor Changes
+
+- e24fe7f: Add a `definition list` command that lists deployed workflow definitions as a table. Filter with `--workflow-id`, or scope to an environment with `--tag` (omit `--tag` to list across all partitions). Each row shows the definition's stage count plus in-flight and total instance counts.
+
+### Patch Changes
+
+- eff2a77: Commands that contact the dataset (`deploy`, `list`, `show`, `tail`, `move-stage`) now fail with a clean, single-line error when a required `SANITY_*` env var is missing, instead of dumping a raw Node stack trace. Missing client config is funnelled through the same `fail()` path that `WORKFLOW_*` config validation already uses.
+- eff2a77: `deploy` no longer hardcodes its definitions to `@sanity/workflow-examples`. The
+  source is now resolved at runtime from a required `WORKFLOW_DEFS` env var — a
+  module path or package name whose `allDefinitions` export holds the
+  `WorkflowDefinition[]` to deploy — so the CLI is agnostic about which
+  definitions it ships. There is no default: an unset source fails hard rather
+  than silently falling back to a built-in set. This also fixes a latent bug
+  where a built/published CLI would throw, since `@sanity/workflow-examples` was only
+  ever a dev dependency.
+- 9d434a1: `deploy` and `move-stage` take a `--tag` flag selecting the engine environment partition (e.g. `--tag prod`). The tag resolves `--tag` → `WORKFLOW_TAG` env → required: commands fail hard when no tag is set rather than silently defaulting. This replaces the previous comma-separated `WORKFLOW_TAGS` env var with a single `WORKFLOW_TAG`.
+- Updated dependencies [d04cbea]
+- Updated dependencies [870188e]
+- Updated dependencies [a4f6d81]
+- Updated dependencies [eff2a77]
+- Updated dependencies [ce6960d]
+- Updated dependencies [dff88ff]
+- Updated dependencies [782272a]
+- Updated dependencies [2b800a8]
+- Updated dependencies [0432670]
+- Updated dependencies [53a0598]
+- Updated dependencies [c2ad7a9]
+  - @sanity/workflow-engine@0.2.0