# @walkeros/cli

## 4.6.1

### Patch Changes

- @walkeros/collector@4.6.1
- @walkeros/core@4.6.1
- @walkeros/server-core@4.6.1
- @walkeros/server-destination-api@4.6.1
- @walkeros/transformer-validate@4.6.1

## 4.6.0

### Minor Changes

- 23e9034: `walkeros auth login` now uses the standard device authorization
  grant and refreshes its session automatically. Existing tokens keep working
  until they expire; run `walkeros auth login` once to switch.

  Breaking: `getAuthHeaders` is async, and it rejects when the session needs a
  refresh that cannot be carried out rather than quietly returning no header.
  `createApiClient` no longer throws when unauthenticated, the request it makes
  does. Removed exports: `getToken`, `requestDeviceCode`, `pollForToken`, and
  the `DeviceCodeResult`, `DeviceCodeOptions`, `PollOptions` and `PollResult`
  types; `startDeviceAuthorization` and `completeDeviceLogin` replace the last
  two.

### Patch Changes

- 8802281: The BigQuery destination no longer applies `config.timeout` as a
  deadline on the Storage Write API append stream, which killed healthy
  connections roughly every ten seconds and caused reconnect churn, latency
  spikes, and intermittent 5xx responses. Error logs now show the error's
  message, name and status code in CLI output, and no longer include event
  payloads.
- fd5949e: `fetchHealth` and `compareContract` accept an optional base URL, so a
  caller that is not the local CLI can probe its own backend instead of the one
  resolved from `WALKEROS_APP_URL` and the CLI config file. Omitting it keeps
  today's resolution.

  `diagnostics` passes the app URL it reports, so the contract verdict and
  `appUrl.resolved` always describe the same backend. A hosted MCP no longer
  probes production while naming its own deployment.

- 403ff6c: The MCP server carries `hub_manage`, which reads a flow's release
  history, its rationale and the threads on it, and a read-only `frame_manage`,
  which reads the frames of a measurement plan. The CLI gains the matching
  programmatic calls. `ToolClient` gains eleven required methods, so a custom
  implementation of that interface must add them.
- Updated dependencies [8802281]
  - @walkeros/collector@4.6.0
  - @walkeros/server-core@4.6.0
  - @walkeros/core@4.6.0
  - @walkeros/server-destination-api@4.6.0
  - @walkeros/transformer-validate@4.6.0

## 4.5.0

### Minor Changes

- 5977896: `walkeros setup` now resolves a component's package the same way
  `walkeros bundle` does: the flow's pinned version is downloaded from the
  registry (sharing the bundle cache) and imported from there. Setup works via
  npx without a local install; `path:` packages are supported for local
  development.

### Patch Changes

- 3571ca1: Add package READMEs and npm keywords. The MCP packages now ship
  install instructions for Claude Code, Cursor, and VS Code plus MCP registry
  metadata (mcpName).
- f7536a6: A `path` entry in `config.bundle.packages` now counts as the package
  pin, so bundling and setup use the local package instead of failing when steps
  still declare conflicting inline versions of it.
- Updated dependencies [3571ca1]
- Updated dependencies [63845bb]
- Updated dependencies [4de76ed]
- Updated dependencies [79cdcb0]
- Updated dependencies [756b571]
  - @walkeros/transformer-validate@4.5.0
  - @walkeros/core@4.5.0
  - @walkeros/server-destination-api@4.5.0
  - @walkeros/collector@4.5.0
  - @walkeros/server-core@4.5.0

## 4.4.0

### Patch Changes

- Updated dependencies [393b942]
- Updated dependencies [6c89afb]
- Updated dependencies [393b942]
- Updated dependencies [35756dd]
- Updated dependencies [034b1de]
- Updated dependencies [d00e2bd]
  - @walkeros/collector@4.4.0
  - @walkeros/core@4.4.0
  - @walkeros/server-core@4.4.0
  - @walkeros/server-destination-api@4.4.0
  - @walkeros/transformer-validate@4.4.0

## 4.3.2

### Patch Changes

- a32ac49: The Observe session lifecycle is now available programmatically:
  `startObserveSession`, `getObserveSession`, and the new `endObserveSession`
  are exported from `@walkeros/cli`, so tools built on the CLI can open an
  Observe session on a flow, read its status and record count, and end it.
  Starting one also accepts `origins` to bind its web activation grant.
  - @walkeros/collector@4.3.2
  - @walkeros/core@4.3.2
  - @walkeros/server-core@4.3.2
  - @walkeros/server-destination-api@4.3.2
  - @walkeros/transformer-validate@4.3.2

## 4.3.1

### Patch Changes

- f2030ab: `walkeros validate --type contract` now rejects the flat contract
  shape (a bare entity-action map, or a `$`-prefixed root key) with a
  `FLAT_CONTRACT_SHAPE` error, and warns on unrecognized keys instead of
  ignoring them. Rule-level `tagging` and `schema` fields are also checked for
  their expected types.
- 2d6ab82: Connect a running flow to an observation session and watch its live
  events from web, server, or bundled runtimes. Commit only a public observer
  URL and project binding; the per-session credential arrives out-of-band, so no
  secrets land in code or artifacts. Ingest posts carry a versioned envelope
  with release provenance, and `walkeros observe start` opens sessions from the
  terminal.
- 747e42f: The deprecated telemetry bundle options that baked a plaintext ingest
  token into wrapped browser bundles are removed; observation wiring now always
  uses the bake-nothing `observe` connect config. `walkeros observe start` sends
  `level` and `replace`, renders the activation URL, web credential, server env
  block, expiry, and record count, and keeps the session warm while waiting.
- Updated dependencies [f2030ab]
- Updated dependencies [2d6ab82]
  - @walkeros/core@4.3.1
  - @walkeros/collector@4.3.1
  - @walkeros/server-core@4.3.1
  - @walkeros/server-destination-api@4.3.1
  - @walkeros/transformer-validate@4.3.1

## 4.3.0

### Minor Changes

- e01036e: Web bundles no longer assign `window.elb`; the browser source owns
  that global. The `windowElb` setting is deprecated: its value is forwarded to
  the browser source's `config.settings.elb` with a warning, so custom global
  names keep working.
- e01036e: Flow observation records now carry per-event journey correlation: a
  W3C `traceparent` links a web send to the server flow that receives it, plus
  the originating source id and a monotonic sequence that makes dropped
  telemetry visible. At trace level, destinations can opt in to recording their
  outgoing vendor calls.
- 1559e17: The `preview_regrant` action now works over the CLI-backed MCP
  client: mint a fresh, origin-bound activation grant for an existing preview,
  optionally bound to an Observe session via `sessionId`. `preview_create` with
  a `siteUrl` now mints a real activation grant instead of returning no
  activation URL.
- 98801c9: Flow observation records now assemble into per-event journeys
  spanning web and server flows, each hop showing input, output, and status,
  with loss flagged; the `observe_journeys` MCP tool exposes the same journeys
  to agents. Batching destinations now emit per-event records, and live-web
  vendor calls are captured when a destination reaches its callable through
  `getEnv`, though batched sends stay uncaptured.
- f8408fd: Preview links are now app-signed and bound to your site's origin,
  verified locally in the bundle with no server round trip. Bundles that support
  preview activation import a new `browserSwapActivator` from `@walkeros/core`.
  The CLI wrap step's `preview` option replaces `previewOrigin`/`previewScope`,
  and a new `previewGrantTargets` option lets a preview forward its grant to
  server-bound destinations too.
- 907eed0: Observe-session activation URLs now carry a companion
  session-forwarding grant (`elbPreviewSession`). The browser activator stores
  it alongside the activation grant, and seamed preview bundles use it to
  forward events to the session container — so one preview link shows web and
  server journeys together.
- 9506e3e: Events now carry per-flow config provenance on
  `event.source.release`, a flow-name to release map that accumulates as an
  event crosses flows (web capture to server processing), so a delivered event
  shows which config handled it. The collector no longer stamps `source.version`
  (external source emitters may still set it). In this first version, aws and
  gcp crossings are not yet covered.

### Patch Changes

- 07f0255: Bundling a flow whose step `package` carries an inline version (e.g.
  `@walkeros/web-source-browser@2.1.0`) no longer fails package resolution: the
  version suffix is parsed and honored instead of being treated as part of the
  package name, and an explicit `config.bundle.packages` pin still wins. The
  elbPreview loader now activates previews via a script-element swap instead of
  a CORS-bound fetch probe, so previews work on any site regardless of CDN CORS
  headers. The flow runtime also buffers bundle archives fully before
  extraction, fixing a rare boot crash when the download stream ended while
  extraction had it paused.
- 06c93b4: Update the runtime Docker base image to Node.js 22.23.0, which
  patches the Node.js June 2026 security release. The `walkeros/flow` and
  `walkeros/cli` images now pin a fixed, digest-locked Node version.
- Updated dependencies [e01036e]
- Updated dependencies [e01036e]
- Updated dependencies [98801c9]
- Updated dependencies [f8408fd]
- Updated dependencies [907eed0]
- Updated dependencies [9506e3e]
  - @walkeros/collector@4.3.0
  - @walkeros/core@4.3.0
  - @walkeros/server-core@4.3.0
  - @walkeros/server-destination-api@4.3.0
  - @walkeros/transformer-validate@4.3.0

## 4.2.1

### Patch Changes

- b03bfce: `walkeros deploy` now waits long enough to cover a full server deploy
  by default, so a slow but healthy deploy is no longer aborted early and
  reported as a failure. Each run sends a fresh idempotency key, so retrying
  after a failure starts a new deploy instead of replaying the previous result.
  Failures print a stable, machine-readable error code (with a `Retry-After`
  hint on rate limits), and `deploy create` no longer prints an empty token
  placeholder.
- ec84331: The managed flow runner now retries its bundle, config, and secret
  fetches on transient failures (timeouts, network errors, 5xx) with bounded,
  jittered backoff capped well inside the container health window, and the
  secret fetch is now bounded by a timeout. A brief outage while a flow
  container starts no longer hard-fails the run.
- 4809699: The managed flow runner now reports its recent errors and recent log
  output in its heartbeat, so deployed flows can surface runtime errors and logs
  in the app without any external log tooling. Secrets are redacted before
  leaving the runner.
- 5cbcd23: `walkeros run` reads two new environment variables.
  `WALKEROS_OBSERVE_LEVEL` sets the runtime's baseline telemetry level (`off`,
  `standard`, or `trace`). `WALKEROS_CONFIG_FROZEN` (`1` or `true`) serves the
  bundle as an immutable snapshot: secrets are still injected at boot, but
  config hot-swap and heartbeat are disabled.
- 5cbcd23: All four simulate functions (`simulateSource`, `simulateTransformer`,
  `simulateCollector`, `simulateDestination`) accept a new `data` option to run
  an existing bundle with updated configuration values, without rebundling. The
  new `buildDataPayload`, `classifyStepProperties`, and `containsCodeMarkers`
  exports build and inspect that payload. Destination simulation results now
  include `mappingKey`, the entity-action key of the matched mapping rule.
- 8afb7cc: The runner registers its process-error guards before startup and
  degrades its readiness check after repeated out-of-band errors, so a wedged
  container is recycled instead of silently hot-looping. Heartbeats now flush
  immediately on a new error and on shutdown, persist errors to disk so a
  failure cause survives a restart, and report their configured interval.
- Updated dependencies [bd9188d]
- Updated dependencies [d8aebd1]
- Updated dependencies [5cbcd23]
- Updated dependencies [31c6858]
- Updated dependencies [d1b41ca]
- Updated dependencies [0a8a08b]
- Updated dependencies [8afb7cc]
- Updated dependencies [8afb7cc]
  - @walkeros/collector@4.2.1
  - @walkeros/core@4.2.1
  - @walkeros/server-core@4.2.1
  - @walkeros/server-destination-api@4.2.1
  - @walkeros/transformer-validate@4.2.1

## 4.2.0

### Minor Changes

- 654ba38: `walkeros run` now accepts a `.tar.gz`/`.tgz` flow archive (URL or
  local file): it extracts the bundle and its `node_modules/` and runs it, so
  server flows with external step packages resolve them at runtime.
  `walkeros bundle -o flow.tar.gz` packs a server bundle directory into that
  archive. Web single-file bundles do not support archive output.
- 6a72a32: The MCP `flow_simulate` and `flow_bundle` tools now accept a cloud
  flow id as `configPath`, so you can simulate or bundle a saved flow without a
  manual file round-trip, and repeated simulations reuse a prebuilt bundle for
  faster runs. Loading or fetching a flow with no default project set now
  returns a clear "no default project" error, and `flow_examples` surfaces a
  referenced package's shipped examples when a step has none inline. Bundle
  stats now report the real total bundle size and list package names instead of
  a per-package estimate, and the GA4 transformer documents its wiring contract
  via package hints.
- 9d066cc: Preview creation can now target a deployed version: pass
  `source: { kind: 'deployment-version', deploymentVersionId }` to
  `createPreview` (CLI) or the MCP `flow_manage` `preview_create` action to
  preview what's live instead of the flow's draft. Deleting a preview no longer
  errors on the empty `204 No Content` response and resolves to a confirmation
  record.
- 654ba38: Trace telemetry now activates at runtime by polling the deployment's
  trace window, so web and server flows start and stop full-payload recording
  without a redeploy. A future trace window upgrades a flow to full inbound and
  outbound recording, and a null or past window reverts to the flow's `observe`
  baseline and self-expires.
- e8f6909: Add a `secret_manage` MCP tool (and matching CLI functions) to manage
  a flow's secrets. List secret metadata, create, rotate, and delete secrets
  that flow steps reference as `$env.<NAME>`. Values are write-only: encrypted
  at rest and never returned or logged.
- 6a72a32: Source simulation gains a `collector` step that runs the real
  collector enrichment and returns the fully enriched event. Transformer
  simulation now accepts an optional raw `ingest` so request decoders like GA4
  can be tested standalone by supplying a `url`. The `flow_simulate` MCP tool
  accepts the new collector step and the transformer `ingest` input.

### Patch Changes

- e8f6909: The bundled API contract (`spec.json` and the generated
  `api.gen.d.ts`) now covers the full served surface, adding typed paths for
  service accounts, invitations, billing, deployments and their sub-resources,
  custom domains, entitlements, LLM settings, chat sessions, MCP tokens,
  runners, and the package catalog. No runtime behavior change; clients gain
  accurate types for these endpoints.
- 5b1a134: Browser flow bundles are now emitted as an IIFE so all internal code
  stays inside a private scope. Previously the bundled helper functions could
  leak onto the global `window` object and collide with other scripts on the
  page, such as Google Analytics or a consent manager. Server bundles are
  unchanged and still emit ESM.
- b98474f: Source-level mapping examples for the dataLayer source now key on the
  prefix as entity and the gtag action as action: `mapping.<prefix>.<action>`.
  The shipped `examples/mapping.ts`, the comprehensive `flow-complete.json`
  example, and the related docs reflect the convention, including the
  special-cased actions `consent`, `config`, and `set` whose trailing token is
  dropped by the entity/action split.
- 59aa9e1: Refresh runtime dependencies to their latest majors: Express 5,
  Commander 15, better-sqlite3 12, @libsql/client 0.17, Google Cloud
  functions-framework 5, mixpanel 0.22, and jsdom 29. No public API changes;
  installs now pull the current versions of these SDKs.
- e8f6909: Documentation fix: server source `config.ingest` examples now use the
  `map` operator with direct request field paths instead of a bare object. A
  bare object like `{ url: 'req.url' }` is silently inert, so the ingest stayed
  empty and downstream `ingest.*` fields never resolved. Affects package hints,
  READMEs, the core source type docs, and the bundled CLI example.
- d39a6a1: Bundle skeletons now expose each package's dev exports through a lazy
  loader. Production deploy bundles drop it entirely, so a shipped `walker.js`
  never carries the dev schema graph, while in-process simulate and push inline
  the dev exports so they resolve on a minimal runtime without the source
  packages installed alongside. This fixes a browser deploy bundle that could
  fail to build or retain dev schemas, and web simulation that could not find
  the dev exports.
- 9d066cc: The MCP now loads flows by ID, requires the `flow_simulate` `step`
  parameter it always enforced, and adds a `diagnostics` tool reporting client
  and CLI versions plus backend reachability. Package discovery returns a
  complete catalog with a warning when a source degrades, instead of silently
  caching partial results, and returned flow configs are round-trip safe
  (structural values stay literal). The demo source can now be simulated as a
  source step; the CLI also exports `VERSION` and `resolveAppUrl` and clears a
  deleted default project.
- e2a60ae: The wrapped browser bundle can now install a telemetry observer
  without a trace poll. When the telemetry options omit `traceUrl`, the bundle
  emits at a fixed level with no polling, suited to short-lived, URL-opted-in
  sessions. Bundles that pass `traceUrl` keep the existing poll behavior.
- 23d4b86: New `@walkeros/transformer-validate` transformer validates events
  against JSON Schema contracts. It runs in both web and server flows, supports
  strict and pass modes, and writes the verdict and error list to configurable
  paths so you can gate or observe event quality.

  The declarative per-step `validate` field on sources, transformers, and
  destinations is removed. Define event shapes in the top-level `contract` and
  enforce them at runtime by adding a `transformer-validate` step that
  references them via `$contract.<name>`; `format: true` still checks an event
  is a valid `WalkerOS.PartialEvent`. Design-time validation now checks step
  examples against the resolved contract.

- Updated dependencies [76d32c1]
- Updated dependencies [5b1a134]
- Updated dependencies [908d6f0]
- Updated dependencies [654ba38]
- Updated dependencies [c27d3c1]
- Updated dependencies [e8f6909]
- Updated dependencies [f4a9013]
- Updated dependencies [d65bbde]
- Updated dependencies [2d64ed2]
- Updated dependencies [e8f6909]
- Updated dependencies [776e5f9]
- Updated dependencies [c27d3c1]
- Updated dependencies [126c0f1]
- Updated dependencies [654ba38]
- Updated dependencies [6a72a32]
- Updated dependencies [3eb2467]
- Updated dependencies [5b1a134]
- Updated dependencies [23d4b86]
- Updated dependencies [18c9469]
- Updated dependencies [0cad016]
  - @walkeros/core@4.2.0
  - @walkeros/collector@4.2.0
  - @walkeros/server-core@4.2.0
  - @walkeros/server-destination-api@4.2.0
  - @walkeros/transformer-validate@4.2.0

## 4.1.2

### Patch Changes

- @walkeros/collector@4.1.2
- @walkeros/core@4.1.2
- @walkeros/server-core@4.1.2
- @walkeros/server-destination-api@4.1.2

## 4.1.1

### Patch Changes

- c1a4188: The simulate functions (`simulateSource`, `simulateTransformer`,
  `simulateDestination`) now return the unified `Simulation.Result` shape with
  captured `events` and intercepted `calls`, instead of the internal push
  result. `PushResult` no longer carries the simulate-only `captured`, `usage`,
  and `perDestination` fields.
- b0279ee: Rename the contract inheritance key from `extends` to `extend` for
  consistency with the rest of the flow config vocabulary. Contracts that
  inherit from another named contract now use `"extend": "<name>"`.
- ddcd56e: The project, flow, and deployment list operations now accept optional
  `cursor` and `limit` arguments and return a `nextCursor` to fetch the next
  page. Listing without these arguments is unchanged and returns all results. In
  the MCP, the `project_manage`, `flow_manage`, and `deploy_manage` tools expose
  `cursor` and `limit` on their `list` action.
- 0b7f494: The collector exposes `observers: Set<ObserverFn>` so any subscriber
  can watch every step of the pipeline. Each source, transformer, destination,
  and store call emits a `FlowState` record with timings, mapping match, consent
  state, and skip reasons. `createTelemetryObserver` from `@walkeros/core`
  batches emissions to an HTTP endpoint, and the CLI runtime picks up the
  `traceUntil` flag from its heartbeat so trace mode toggles take effect without
  a redeploy.
- Updated dependencies [b0279ee]
- Updated dependencies [b0279ee]
- Updated dependencies [0b7f494]
  - @walkeros/core@4.1.1
  - @walkeros/collector@4.1.1
  - @walkeros/server-core@4.1.1
  - @walkeros/server-destination-api@4.1.1

## 4.1.0

### Minor Changes

- b276173: **Breaking:** `code: "<exportName>"` is no longer accepted on any
  step. Replace with `import: "<exportName>"` alongside `package`.

  **New:** Every step (source, transformer, destination, store) accepts
  `import?: string`. With `package`, it selects a named export. `package` alone
  still loads the default export. Inline code stays
  `code: { push, type?, init? }`. Empty steps are valid no-ops. `flow_validate`
  and the CLI bundler raise `OBSOLETE_CODE_STRING` on the legacy shape with a
  precise rename hint.

- dd9f5ad: Pass-through transformer steps + closed-schema validation.

  **Validation:** `validateTransformerEntry` in `@walkeros/core` is now the
  single source of truth. Bundler, `flow_validate`, and collector runtime all
  delegate. Closed schema: unknown top-level keys are errors. `code` + `package`
  together is a `CONFLICT`.

  **Pass-through steps:** A transformer entry with no `code` and no `package` is
  valid; the collector synthesizes its push. Three variants:
  - before/next chain only (named hop)
  - cache only (e.g. dedup)
  - mapping only (event-to-event transform via `Mapping.Config`)

  **Mapping at the transformer position:** new `mapping?: Mapping.Config` field
  on `Transformer.Config` / `InitTransformer`. Same shape as
  `Destination.Config.mapping`, event-to-event semantic. `data` / `silent` are
  ignored at the transformer position with a one-time warning.

  **Engine tag:** synthesized instance now uses `type: 'pass'` (was `'path'`).
  Hard cut.

  **Runtime fixes:**
  - `compileNext` handles mixed-shape `next` arrays (`["a", { case }]`) via a
    new `'sequence'` variant.
  - A destination's `before` referencing a pass-through transformer now walks
    that transformer's own `before` / `next`.
  - `cache.stop: true` at a pre-collector transformer halts the pipeline
    (matches `cache.mdx`).

  **Migration:** Typo keys on a step now fail validation.
  `instance.type === 'path'` consumers must read `'pass'`. `runTransformerChain`
  consumers should branch on the new `stopped` flag.

### Patch Changes

- 1a8f2d7: Flow v4 routing & cache cleanup.

  **Cache:**
  - `cache.full` is renamed to `cache.stop`. Search-and-replace.
  - `cacheRule.match` is now optional. Omitted means always-match. The literal
    `'*'` is dropped from the schema and the TypeScript types; `compileMatcher`
    still tolerates the string at runtime for migration.
  - New `cache.namespace?: string` field. Omit to write keys directly to the
    store. Same store + same key + same namespace = same cache entry.
  - Implicit per-step namespace prefixes (`s:`, `t:`, `d:`) are removed. If you
    relied on them to separate same-keyed caches across
    sources/transformers/destinations using the same store, set
    `cache.namespace` explicitly.

  **Routing:**
  - Unified recursive `Route` type. A Route is `string | Route[] | RouteConfig`.
  - New `case` operator replaces the legacy `Route[]` first-match shape. The
    legacy shape is compiled as an implicit `{ case: [...] }` for runtime
    compatibility, but new configs should use `case` explicitly.
  - `RouteConfig` is a disjoint union enforced at the TypeScript type level via
    `never` fields: a single RouteConfig sets at most one of `next` / `case`. A
    bare `{ match }` is a gate (pass-through when the match fires, fall-through
    when it fails). JSON Schema validation currently emits `anyOf` and does not
    enforce disjointness at runtime — see follow-up notes.
  - Sequence sugar (`next: [A, B, C]`) is preserved.

  **Path:**
  - A transformer entry with no `code` is a `path` — a code-less passthrough.
    The engine synthesizes `(e) => ({ event: e })`. Use paths to name and share
    `before` chains across destinations. Validation: a path must declare at
    least one of `package`, `before`, `next`, or `cache`.

  **Schema & tooling:**
  - Updated Zod schemas (cache, route, matcher).
  - Updated MCP tool descriptions and resource references.
  - Updated `flow_validate` to enforce the new constraints (`EMPTY_TRANSFORMER`
    error code added).

  **Migration:** Hard cut at the schema/type level. Configs using `cache.full`
  will fail validation — rename to `stop`. Configs using `match: "*"` will fail
  validation — omit `match`. Configs using `Route[]` first-match still work at
  runtime (compiled as implicit `case`) but new configs should use `case`
  explicitly.

  `$schema: "v4"` is preserved. No version bump.

- adeebea: Route grammar: rename `case` to `one` (first-match dispatch) and add
  `many` (all-match parallel fan-out, pre-collector only). `many` terminates the
  main chain and is rejected at post-collector positions (`destination.before`,
  `destination.next`); use multiple destinations for post-collector fan-out.
  `RouteCaseConfig` is renamed to `RouteOneConfig`; no aliases.
- Updated dependencies [e155ff8]
- Updated dependencies [e800974]
- Updated dependencies [e155ff8]
- Updated dependencies [1a8f2d7]
- Updated dependencies [1a8f2d7]
- Updated dependencies [b276173]
- Updated dependencies [dd9f5ad]
- Updated dependencies [c60ef35]
- Updated dependencies [adeebea]
- Updated dependencies [13aaeaa]
- Updated dependencies [e800974]
- Updated dependencies [adeebea]
- Updated dependencies [6cdc362]
- Updated dependencies [e800974]
- Updated dependencies [e800974]
- Updated dependencies [058f7ed]
- Updated dependencies [28a8ac2]
- Updated dependencies [fd6076e]
  - @walkeros/core@4.1.0
  - @walkeros/collector@4.1.0
  - @walkeros/server-core@4.1.0
  - @walkeros/server-destination-api@4.1.0

## 4.0.2

### Patch Changes

- a6a0ea7: Rename routing types: `NextRule` to `Route`, `Next` to `RouteSpec`
  (Zod schemas and `MatcherNext*` IDs renamed in step). Widen
  `Flow.*.before/next` to `RouteSpec` so `Route[]` conditional routing
  type-checks at the JSON layer. Fix the CLI bundler dropping `Route[]` data via
  a narrowing cast on the inline path. Hard cut, no aliases; flow.json shape
  unchanged.
- Updated dependencies [a6a0ea7]
  - @walkeros/core@4.0.2
  - @walkeros/collector@4.0.2
  - @walkeros/server-core@4.0.2
  - @walkeros/server-destination-api@4.0.2

## 4.0.1

### Patch Changes

- abfb0bb: @walkeros/cli: Server bundles now use @vercel/nft to trace
  dependencies and copy only files actually used into dist/node_modules/. Pacote
  remains the install layer (driven by flow.json's config.bundle.packages field;
  users do not run npm install for step packages). The walkerOS.bundle.external
  annotation field on package manifests is no longer recognized (deprecation
  warning if seen). The flow.<name>.config.bundle.external sub-field on flow
  configs is also no longer supported (warned and stripped during load). The
  flow.<name>.config.bundle.traceInclude field is the escape hatch for cases nft
  cannot statically trace. Server output is always a directory: dist/{flow.mjs,
  package.json, node_modules/}. Default output filename changed from bundle.mjs
  to flow.mjs. The runtime image expects /app/flow/flow.mjs. flow.json schema is
  unchanged (still v4); only @walkeros/cli bumps. Migration: see
  https://walkeros.io/docs/migrate/cli-4x.

  @walkeros/server-destination-gcp: removed obsolete walkerOS.bundle.external
  annotation from package manifest. nft handles externalization automatically.
  No behavior change for consumers.

- ed304b4: Bundler honors `walkerOS.bundle.external` declared in step-package
  package.json files. Listed packages are externalized from the ESM bundle and
  the bundler always installs them (plus their full transitive deps) into
  `<outputDir>/node_modules/` via pacote — no `npm install` shell-out, no manual
  deploy step. When externals is empty, output remains a single `bundle.mjs`
  (backward compatible). When non-empty, output is a self-contained directory:
  `bundle.mjs`, `package.json`, `package-lock.json`, `node_modules/`.

  The bundler reads npm config (registry, scope tokens) from `.npmrc`,
  parallelizes manifest fetches with retry, atomically stages each package
  extraction (no half-populated `node_modules/` on failure), and reuses the
  closure resolution from the existing `collectAllSpecs` BFS so peerDependencies
  are honored.

  Hard-errors when:
  - A package in the install closure declares a `pre/install/postinstall` script
    (pacote.extract does not run them).
  - A step package names an external in `walkerOS.bundle.external` but does not
    list it in `dependencies` or `peerDependencies`.
  - Two step packages declare the same external and the resolved version does
    not satisfy all consumers' constraints.

  Warns (not errors) when:
  - Bundle output contains unresolved `__dirname` / `__filename` references
    (with package attribution by hit count).
  - A step package's `walkerOS.bundle.*` block contains unknown keys (typo
    guard).

  New sibling export `downloadPackagesWithResolution` returns both the package
  paths and the full `ResolutionResult`. Existing `downloadPackages` keeps its
  return shape unchanged.

- e4b6cf4: Fix `walkeros bundle` failing on Windows when stage 2 import paths
  contained backslashes that JS parsed as escape sequences.
- 381dfe7: Add an optional `setup` lifecycle to destinations, sources, and
  stores.

  Each package may now implement `setup?: SetupFn` to provision external
  resources (BigQuery datasets and tables, Pub/Sub topics and subscriptions,
  SQLite tables, webhook registrations, etc.). Setup is triggered only by the
  new `walkeros setup <kind>.<name>` CLI command, never automatically by the
  runtime, push, or deploy. Idempotency, ordering, and error semantics are the
  package's responsibility; the framework provides the type slot, the CLI
  invocation, and a `resolveSetup(value, defaults)` helper.

  `LifecycleContext<C, E>` is the new shared context type used by both `setup`
  and `destroy`. `DestroyContext` remains as a deprecated type alias for one
  minor cycle. The `Types` bundle on `Destination`, `Source`, and `Store` gains
  a 5th/6th/4th positional slot for setup options; existing aliases compile
  unchanged because the slot defaults to `unknown`.
  `Config<T>.setup?: boolean | SetupOptions<T>` is added across all three kinds
  and validated by the corresponding Zod `ConfigSchema` plus the flow component
  schemas in `@walkeros/core/schemas/flow.ts`.

  CLI:
  - `walkeros setup <kind>.<name>` runs a single component's `setup()` function.
  - `<kind>` is `source`, `destination`, or `store` (transformers have no
    provisioning).
  - `--config <path>` (default `./flow.json`), `--flow <name>` for multi-flow
    configs, plus standard `--json` / `--verbose` / `--silent`.
  - Exit 0 on success or skip; non-zero on failure. Skip narration covers three
    cases: no `setup()` on the package, `config.setup === false`, or
    `config.setup` unset.
  - When the package's `setup()` returns a non-undefined value, the CLI emits it
    as JSON on stdout for `jq` piping.

- 03d7055: Merge `definitions` into `variables`. Single concept, single syntax
  `$var.name(.deep.path)?`. Whole-string references preserve native type; inline
  interpolation requires scalars. Deep paths and recursive resolution with cycle
  detection now supported. `Flow.Definitions`, `Flow.Primitive`, and the `$def.`
  reference syntax are removed.
- Updated dependencies [cb265eb]
- Updated dependencies [381dfe7]
- Updated dependencies [1524275]
- Updated dependencies [03d7055]
  - @walkeros/collector@4.0.1
  - @walkeros/core@4.0.1
  - @walkeros/server-core@4.0.1
  - @walkeros/server-destination-api@4.0.1

## 4.0.0

### Major Changes

- 0ffb1d3: Remove dead `bundleRemote()` and add OpenAPI drift detection.

  Breaking changes:
  - Removed `bundleRemote()` export from `@walkeros/cli`. The corresponding
    `/api/bundle` endpoint was removed from the walkerOS app on 2026-04-08, so
    this function had been silently broken in production for ~3 weeks. Local
    bundling via `bundle()` is unaffected.
  - Removed `remote` and `content` options from the MCP `flow_bundle` tool. The
    tool now bundles locally only.

  New:
  - Added `npm run -w @walkeros/cli validate:openapi-spec` script that diffs the
    checked-in `packages/cli/openapi/spec.json` against the live app's OpenAPI
    document. Detects drift between the walkerOS-side type contract and the
    actual API. Wired into PR-time CI, daily cron, and a pre-commit lint-staged
    hook. All layers are gated on a `WALKEROS_APP_URL` secret and skip silently
    when unset, so the change ships safely without configuration. To activate:
    set `WALKEROS_APP_URL` in repo secrets pointing to a deployed app instance.

- 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
  `Entity` shapes.
  - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
    collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
  - `event.version`, `event.group`, `event.count` are removed.
  - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
    New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
  - `source.id` and `source.previous_id` are removed.
  - Browser source now sets `source.url` and `source.referrer`.
  - MCP source sets `source.tool` per emission. CLI source sets
    `source.command`.
  - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
    and `event.context` remain required.
  - Each source self-registers via TypeScript module augmentation of `SourceMap`
    in `@walkeros/core`.
  - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
    part of this release. Telemetry from v4 CLI/MCP will not validate against
    the existing app schema until that follow-up ships.
  - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
    configs using `skip: true` in mapping rules must rename to `silent: true`.
    Hard cut: no legacy alias, the field is gone.

- 942a7fe: Flow v4: type redesign and cross-flow references.

  Breaking changes:
  - Renamed `Flow.Settings` (single-flow shape) to `Flow`. The new
    `Flow.Settings` is the arbitrary kv-bag inside `Flow.Config` (matches
    `Destination.Settings` semantics).
  - Renamed `Flow.Config` (root file shape) to `Flow.Json`.
  - Removed `Flow.Web` and `Flow.Server`. Replaced by
    `config.platform: 'web' | 'server'` (a string discriminator).
  - Renamed `Flow.InlineCode` to `Flow.Code`.
  - Renamed `Flow.SourceReference` / `DestinationReference` /
    `TransformerReference` / `StoreReference` to `Flow.Source` / `Destination` /
    `Transformer` / `Store` (Reference suffix dropped).
  - Renamed `Flow.ContractEntry` to `Flow.ContractRule`.
  - Lifted `bundle` and platform fields into the per-flow `config` block.
  - `flow.json` `version` bumped from 3 to 4. v3 input is rejected (no compat
    shim).

  New:
  - `$flow.X.Y` reference resolves to `flows.X.config.Y` in the same file.
    Useful for linking a web flow's API destination to a server flow's deployed
    URL without duplicating values.
  - Per-flow `Flow.Config` block: `{ platform, url, settings, bundle }`.
  - `walkeros validate` warns on unresolved `$flow.X.Y` (use `--strict` to
    error). `walkeros bundle` and `walkeros deploy` always error on unresolved
    refs.
  - See `docs/migrating/v3-to-v4.mdx` on the website for the manual migration
    steps. No automated codemod is shipped.

- 1ef33d9: **BREAKING:** Unified callback signatures across mapping and on.\*
  subscriptions.

  Every callback in walkerOS now reads `(data, context) => result`. Sources,
  transformers, destinations, and stores already conformed; mapping and on.\*
  join the family in v4.1.

  ### Mapping callbacks

  `fn`, `condition`, and `validate` now share a single shape:

  `(value, context: Mapping.Context) => result`

  `Mapping.Options` is removed. Replaced by `Mapping.Context`:

  ```ts
  interface Context {
    event: WalkerOS.DeepPartialEvent;
    mapping: Value | Rule;
    collector: Collector.Instance; // required
    logger: Logger.Instance; // required
    consent?: WalkerOS.Consent; // resolved consent
  }
  ```

  Rule-level `condition` is now `(event, context) => boolean`.
  `Mapping.Options.props` is removed (no production callers).

  #### Mapping upgrade

  ```ts
  // before
  const fn: Mapping.Fn = (value, mapping, options) => /* … */;
  const cond: Mapping.Condition = (value, mapping, collector) => /* … */;
  const val: Mapping.Validate = (value) => /* … */;

  // after
  const fn: Mapping.Fn = (value, context) => /* … */;
  const cond: Mapping.Condition = (value, context) => /* … */;
  const val: Mapping.Validate = (value, context) => /* … */;
  ```

  In `$code:` strings (flow.json):

  ```json
  // before
  "fn": "$code:(value, mapping, options) => …"
  "condition": "$code:(value, mapping, collector) => …"

  // after
  "fn": "$code:(value, context) => …"
  "condition": "$code:(value, context) => …"
  ```

  `context.mapping` replaces the second positional arg; `context.collector`,
  `context.logger`, and `context.consent` are all available.

  One-arg callbacks like `(value) => value.toUpperCase()` continue to work
  unchanged.

  ### On.\* subscription callbacks

  `walker.on('consent', …)`, `walker.on('ready', …)`, etc. now receive
  `(data, context: On.Context) => void | Promise<void>`. The legacy `Context`
  interface, `*Config` aliases, and `Options` discriminated union are removed.

  ```ts
  interface Context {
    collector: Collector.Instance; // required
    logger: Logger.Instance; // required
  }

  type Fn<TData = unknown> = (
    data: TData,
    context: Context,
  ) => void | Promise<void>;

  type ConsentFn = Fn<WalkerOS.Consent>;
  type SessionFn = Fn<Collector.SessionData | undefined>;
  type UserFn = Fn<WalkerOS.User>;
  type ReadyFn = Fn<void>;
  type RunFn = Fn<void>;
  type GenericFn = Fn<unknown>;
  ```

  The new `On.Subscription` alias is the registerable union for
  `walker.on(action, X)`.

  #### On.\* upgrade

  ```ts
  // before
  walker.on('consent', { marketing: (collector, consent) => /* … */ });
  walker.on('ready', (collector) => /* … */);
  walker.on('session', (collector, session) => /* … */);

  // after
  walker.on('consent', { marketing: (consent, ctx) => /* … */ });
  walker.on('ready', (_, ctx) => /* … */);
  walker.on('session', (session, ctx) => /* … */);
  ```

  `ctx.collector` replaces the positional first arg; `ctx.logger` is also
  available.

  ### Why both at once

  Both refactors follow the same `(data, context)` pattern. Shipping them in one
  release means consumers do one search-and-replace pass instead of two, and the
  codebase reaches full callback-signature consistency in v4.1.

### Minor Changes

- cfc7469: **Breaking — `@walkeros/core`:** `fetchPackage(name, { baseUrl })`
  now expects the host app to expose the v2 `/api/packages/[name]` endpoint that
  returns the merged `WalkerOSPackage` shape directly (single round-trip,
  `?expand=all`). The previous two-fetch pattern (`?path=package.json` +
  `?path=dist/walkerOS.json`) is removed. Hosts must serve the v2 shape; the
  offline jsdelivr fallback is unchanged.

  **Feature — CLI/MCP/explorer:** Outbound walkerOS-aware HTTP clients now
  identify themselves to the configured app origin via
  `X-Walkeros-Client: walkeros-{cli|mcp}/{version}`. `@walkeros/explorer`
  exports `setPackageTypesBaseUrl(url?)` so host apps can proxy `.d.ts` through
  their own origin (used by the walkerOS Tag Manager app to drop the jsdelivr
  CDN allowance entirely).

- 8e06b1f: **BREAKING:** Unified reference syntax: `$store:id` and
  `$secret:NAME` now use the dot separator: `$store.id` and `$secret.NAME`.

  The coherent rule across every walkerOS reference is:
  - **`.`** key or path (resolver looks up or walks what follows)
  - **`:`** literal value or raw-code payload (resolver uses what follows
    verbatim)

  `$var.`, `$def.`, `$env.NAME[:default]`, `$contract.`, and `$code:(…)` are
  unchanged, they already fit the rule.

  Every shipped example, published `walkerOS.json` metadata, doc page, and skill
  has been updated. A new canonical reference-syntax guide lives at
  `/docs/guides/reference-syntax`. Regex constants (`REF_VAR`, `REF_DEF`,
  `REF_ENV`, `REF_CONTRACT`, `REF_STORE`, `REF_SECRET`, `REF_CODE_PREFIX`) are
  exported from `@walkeros/core` import these instead of hand-rolling regexes.

  ### Upgrade

  Search-and-replace across your flow configs:

  ```
  $store:<id>      → $store.<id>
  $secret:<NAME>   → $secret.<NAME>
  ```

  Everything else stays the same. Your `$var.*`, `$def.*`, `$env.*`,
  `$contract.*`, and `$code:*` references need no changes.

### Patch Changes

- ca237ef: Fix `walkeros push` deadlock for web flows whose destinations await
  real timers during init.

  Previously, async-drain timer interception captured every `setTimeout` into a
  pending map and only fired them via a post-`fn` flush. If a destination's init
  awaited one of those captured timers (e.g.,
  `@walkeros/web-destination-amplitude`'s engagement plugin awaits a 10s
  setTimeout to give up on a CDN script load), `init` never resolved,
  `await collector.push` deadlocked, and Node exited with
  `Detected unsettled top-level await` (exit 13).

  A drain pump now runs alongside `fn(flowModule)` for non-`--simulate` runs:
  each tick fires every captured non-cleared timer using a real `setImmediate`
  reference. Timers fire in delay-ascending order, intervals re-register,
  callback errors are reported via `console.warn`. Bounded by max-iterations
  (1000) and wall-clock (30s) caps.

  `--simulate <step>` continues to use the post-`fn` flush path so snapshot
  ordering remains stable.

  Behavior change (edge case): a destination using `setTimeout` for retry
  backoff under `walkeros push` (real, non-simulate) now sees its timer fire
  instantly. This was already the documented contract for `--simulate <step>`
  snapshots; it now extends to real `push` for consistency.

- 6422b9b: Validate device-code and token responses from the auth server with
  Zod schemas at the trust boundary in `login/index.ts`. Malformed responses now
  surface as structured errors instead of being trusted into config writes or
  browser launches. Replaces the hand-rolled type guards for Items 1 and 3 of
  the cli-auth feedback review. No public API change.
- 78b651a: Explicit opt-in anonymous usage telemetry for CLI and MCP. Telemetry
  is off by default; users opt in with `walkeros telemetry enable` and out with
  `walkeros telemetry disable`. No persistent identifier is written before
  opt-in. No ingest endpoint ships in this release: opting in records consent
  locally; emission begins when a managed endpoint is released. The data
  contract lives at `packages/cli/src/telemetry/flow.json`.
- 6422b9b: Add `flowId` filter to CLI `listDeployments` and redesign the MCP
  `deploy_manage` tool around it.

  **CLI (`@walkeros/cli`):**
  - `listDeployments({ projectId?, type?, status?, flowId? })` now forwards
    `flowId` as a query parameter to `GET /api/projects/{id}/deployments`.
  - New helper `deleteDeploymentByFlowId({ projectId?, flowId, slug? })` deletes
    the active deployment for a flow, surfacing a `DeploymentAmbiguityError`
    (code `MULTIPLE_DEPLOYMENTS`, with a `details[]` list) when a flow has more
    than one active deployment and no slug was supplied.

  **MCP (`@walkeros/mcp`) breaking:**
  - `deploy_manage`'s `get`, `delete`, and `list` actions now take
    `{ projectId?, flowId, slug? }`. The old `id` parameter has been removed.
    `flowId` is required for `get`/`delete` and optional for `list`.
    Soft-deleted deployments are always excluded.
  - When a flow has multiple active deployments and `slug` is not provided,
    `get`/`delete` return a `MULTIPLE_DEPLOYMENTS` error with a `details[]` list
    of `{ slug, type, status, updatedAt }` entries so the caller can pick one.
    `deploy` action is unchanged.

- Updated dependencies [93ea9c4]
- Updated dependencies [465775c]
- Updated dependencies [942a7fe]
- Updated dependencies [cfc7469]
- Updated dependencies [8e06b1f]
- Updated dependencies [3d50dd6]
- Updated dependencies [1ef33d9]
  - @walkeros/core@4.0.0
  - @walkeros/collector@4.0.0
  - @walkeros/server-destination-api@4.0.0
  - @walkeros/server-core@4.0.0

## 3.4.2

### Patch Changes

- 2d25eda: Replace `api` mega-tool with four focused management tools: `auth`
  (device code login), `project_manage`, `flow_manage`, and `deploy_manage`.
  Enforce strict CLI/MCP separation of concern — MCP no longer reads config
  files or checks env vars directly. All tools are always registered regardless
  of auth state.

  CLI exports new functions: `requestDeviceCode`, `pollForToken`,
  `setDefaultProject`, `getDefaultProject`, `listAllFlows`,
  `setFeedbackPreference`, `getFeedbackPreference`, `resolveToken`,
  `deleteConfig`.

  Preview CRUD (`preview_list`, `preview_get`, `preview_create`,
  `preview_delete`) is now part of `flow_manage` — previews are a flow-scoped
  concern and belong alongside the flow lifecycle actions rather than in a
  separate tool.

- cb4c069: Runtime fetchers (`fetchConfig`, `fetchSecrets`) now classify 401/403
  responses from the app as a typed `RunnerAuthError` with a structured `reason`
  (`'unauthorised' | 'flow' | 'scope' | 'forbidden'`) and the app's error `code`
  (`FORBIDDEN_FLOW` / `FORBIDDEN_SCOPE`). Callers can log a specific reason
  instead of a generic "token may have expired" message, and exit cleanly rather
  than retry on scope/flow mismatches.
  - @walkeros/core@3.4.2
  - @walkeros/server-core@3.4.2

## 3.4.1

### Patch Changes

- caea905: Add `walkeros previews {list|get|create|delete}` commands for
  managing preview bundles. `create` supports `--flow <name>` or
  `--settings-id <id>` to target a flow settings entry, and `--url <siteUrl>` to
  produce a ready-to-open activation URL. Use `--open` to launch it in your
  default browser.
- caea905: Preview preflight now self-heals when a preview bundle is deleted.
  Instead of injecting the preview script directly and letting it 404, the
  preflight does a `fetch(HEAD)` first. If the bundle is missing, it clears the
  `elbPreview` cookie and loads the production walker, so visitors never see
  silent analytics breakage.
- Updated dependencies [12adf24]
- Updated dependencies [75aa26b]
  - @walkeros/core@3.4.1
  - @walkeros/server-core@3.4.1

## 3.4.0

### Minor Changes

- 1a0f8f2: Add `target` option to `bundle()`:
  `cdn | cdn-skeleton | runner | simulate | push`. Replaces
  `buildOverrides.skipWrapper` (deprecated) to stop dev schemas leaking into
  production CDN bundles. Stage 2 entry generators gain `platform` option and
  inject `env.window`/`env.document` for browser targets, fixing
  `window.elbLayer` in deployed walker.js.
- 9f97bdd: Clients now send `User-Agent`, `X-WalkerOS-Client`, and
  `X-WalkerOS-Client-Version` on every request to the walkerOS app. When the app
  returns `426 Upgrade Required`, the CLI prints the required version + upgrade
  instruction and exits with code 2; the MCP surfaces the same info in tool
  errors. Set `WALKEROS_CLIENT_TYPE=runner` to have the CLI binary identify as a
  long-lived runner instead of an interactive CLI (used by the runtime image so
  runners are distinguishable from interactive sessions).

### Patch Changes

- Updated dependencies [74940cc]
- Updated dependencies [525f5d9]
  - @walkeros/core@3.4.0
  - @walkeros/server-core@3.4.0

## 3.3.1

### Patch Changes

- 62f6a38: Force collector.run=true during push and simulate so flows with
  run:false work in CLI
  - @walkeros/server-core@3.3.1
  - @walkeros/core@3.3.1

## 3.3.0

### Minor Changes

- 2849acb: **BREAKING CHANGE:** The `packages` block has moved from
  `flow.<name>.packages` to `flow.<name>.bundle.packages`. Flow files using the
  old shape fail fast with a migration error pointing to the new location.

  Also adds `flow.<name>.bundle.overrides` — a `Record<string, string>` for
  pinning transitive dependency versions, matching npm's `overrides` semantics.
  Use this to resolve version conflicts when a transitive dependency's declared
  range conflicts with another required version in the same tree (the original
  motivating case: `@amplitude/engagement-browser` pins
  `@amplitude/analytics-types@^1.0.0` while `@amplitude/analytics-browser`
  transitively requires `analytics-types@2.11.1` exact — previously an
  unresolvable bundler conflict).

  **Migration:** move the existing `packages` block one level deeper into a new
  `bundle` wrapper.

  ```diff
    {
      "version": 3,
      "flows": {
        "default": {
          "web": {},
  -       "packages": {
  -         "@walkeros/collector": {}
  -       },
  +       "bundle": {
  +         "packages": {
  +           "@walkeros/collector": {}
  +         }
  +       },
          "sources": { },
          "destinations": { }
        }
      }
    }
  ```

  **Overrides example:**

  ```json
  {
    "flows": {
      "default": {
        "web": {},
        "bundle": {
          "packages": {
            "@walkeros/web-destination-amplitude": {}
          },
          "overrides": {
            "@amplitude/analytics-types": "2.11.1"
          }
        }
      }
    }
  }
  ```

  Overrides only substitute **transitive** dependencies during resolution —
  direct package specs declared in `bundle.packages` always win. Overrides
  targeting a direct local-path package emit a warning and are ignored. Peer
  constraint mismatches against the chosen override emit a warning but do not
  error (the override is an explicit user directive).

- 08c365a: Add preview mode preflight to web bundles
  - `WrapSkeletonOptions` accepts optional `previewOrigin` and `previewScope`
    fields
  - `generateWrapEntry` injects a preflight snippet before `startFlow` when both
    are set: checks `?elbPreview` param / cookie, loads preview bundle from
    `{previewOrigin}/preview/{previewScope}/walker.{token}.js`, skips production
    flow. Zero overhead when preview options are absent.
  - Input validation rejects path-traversal in `previewScope` and special
    characters in `previewOrigin`.

- 08c365a: Bundle /dev exports into stage 1 skeleton for environment-agnostic
  simulation
  - `/dev` exports from packages are included in the skipWrapper bundle as
    `__devExports`
  - Stage 2 production bundles tree-shake dev exports (no size impact)
  - `prepareFlow()` accepts `Flow.Config` object or pre-built `bundlePath`
  - Simulate functions read env/createTrigger from bundle instead of filesystem

### Patch Changes

- ae02457: Fix bare filename resolution in bundle command —
  `walkeros bundle flow.json` now resolves relative to cwd instead of CLI
  examples directory. Add TTY hint when writing to stdout
- Updated dependencies [2849acb]
- Updated dependencies [08c365a]
- Updated dependencies [08c365a]
- Updated dependencies [08c365a]
- Updated dependencies [08c365a]
  - @walkeros/core@3.3.0
  - @walkeros/server-core@3.3.0

## 3.2.0

### Minor Changes

- eb865e1: Add chainPath to ingest metadata and support path-specific mocks via
  --mock destination.ga4.before.redact='...'
- f007c9f: Wire initConfig.hooks into collector instance. Simulation uses
  prePush/postDestinationPush hooks for event capture. Hooks are wired by
  startFlow before events fire.
- da0b640: Add include/exclude destination filter to collector.push PushOptions.
  Sources can now control which destinations receive their events. Destination
  simulation uses the full collector pipeline with include filter, giving
  production-identical event enrichment, consent, and mapping.
- a0b019f: Add --snapshot flag to push command for setting up global state
  before bundle execution
- 431be04: Refactor bundler to two-step compilation: ESM code compilation +
  platform wrapper. Config changes no longer require full rebuilds. Production
  bundles carry zero dev/simulate code.
- 884527d: Unify simulation for sources, destinations, and transformers through
  the push command.
  - All step types simulate via `push` with auto-env loading and call tracking
  - Add `--simulate transformer.X` to invoke a transformer directly with an
    event
  - Before chains run as mandatory preparation; next chains are skipped
  - Source simulation captures at the collector.push boundary, preserving the
    full before chain
  - Hooks (prePush/postDestinationPush) capture events instead of manual
    overrides
  - Timer interception flushes setTimeout/setInterval deterministically for
    async patterns (debounced batches, detached Promise chains)
  - MCP migrated to the push-based simulation pipeline
  - Legacy simulate code removed

### Patch Changes

- f55fc1d: Unify duplicated CLI patterns for reliability and consistency
  - Add unified event validator with graduated levels (strict/standard/minimal)
  - Fix package resolution in simulate to respect packages.path from flow config
  - Extract shared readStdinToTempFile utility, remove copy-paste dynamic
    imports
  - Standardize duration output to milliseconds (matching MCP schema contract)
  - Fix temp file cleanup in run command (hot-swap accumulation, shutdown
    handler)
  - Fix simulator bare /tmp cleanup bug
  - Unify URL fetching into shared fetchContentString, eliminate temp file
    roundtrip
  - Refactor loadJsonFromSource as thin wrapper around loadJsonConfig
  - Remove unused downloadFromUrl function

- bbbeba1: Replace externalServer hack with typed sourceSettings override in
  bundle wrapper
- 7d1a268: Polyfill fetch and navigator.sendBeacon in JSDOM during web
  simulation to prevent throws and capture network calls
- 616b9b2: Resolve transitive dependencies from local path packages
  automatically
- 91159be: Support path-based package: references on flow config components
- 2cc1b54: Support single .ts files and directories without package.json as
  local packages in flow.json
- Updated dependencies [eb865e1]
- Updated dependencies [c0a53f9]
- Updated dependencies [f007c9f]
- Updated dependencies [bf2dc5b]
- Updated dependencies [da0b640]
  - @walkeros/core@3.2.0
  - @walkeros/server-core@3.2.0

## 3.1.1

### Patch Changes

- a5d98d2: Fix inline JSON config support in detectInput for MCP tools
  (flow_simulate, flow_push)
  - @walkeros/core@3.1.1
  - @walkeros/server-core@3.1.1

## 3.1.0

### Minor Changes

- 357aa95: Consolidate HTTP patterns into core/http.ts: apiFetch
  (authenticated), publicFetch (unauthenticated), deployFetch (deploy token
  priority), and mergeAuthHeaders. Remove duplicated resolveBaseUrl alias and
  legacy authenticatedFetch/deployAuthenticatedFetch from auth.ts.
- 8e687a6: Server bundles are now fully self-contained — all npm dependencies
  (including express and cors) are bundled into the output. No node_modules
  needed at runtime.
- df990d4: Unified source simulation input. All source simulation uses
  SourceInput { content, trigger?, env? } — one format for CLI, MCP, and tests.
  Removes legacy runSourceLegacy and deprecated SimulateSource fields. CLI gains
  --step flag. MCP flow_simulate drops example parameter (use flow_examples to
  discover, then provide event). flow_examples now returns trigger metadata.
  StepExample Zod schema aligned with TypeScript type.

### Patch Changes

- fc67b30: Auto-add npm packages from flow steps (sources, destinations,
  transformers, stores) to build packages, eliminating the need for a redundant
  `packages` section
- dfc6738: MCP api tool: replace overloaded `id` param with explicit `projectId`
  and `flowId`. CLI functions now throw structured ApiError with code and
  details from the API response. mcpError forwards structured error data to MCP
  clients.
- 5799262: Fix MCP issues from user feedback: add 'entry' to validate output
  type, include version in feedback payload, require Node >=20, support inline
  JSON in loadJsonConfig for sandboxed environments
- Updated dependencies [dfc6738]
- Updated dependencies [966342b]
- Updated dependencies [bee8ba7]
- Updated dependencies [966342b]
- Updated dependencies [df990d4]
  - @walkeros/core@3.1.0
  - @walkeros/server-core@3.1.0

## 3.0.2

### Patch Changes

- afd4d07: Add feedback command and MCP tool for sending user feedback
  - @walkeros/core@3.0.2
  - @walkeros/server-core@3.0.2

## 3.0.1

### Patch Changes

- 86c81d1: Regenerate OpenAPI spec and types from app v3
  - @walkeros/core@3.0.1
  - @walkeros/server-core@3.0.1

## 3.0.0

### Major Changes

- d11f574: Rename Flow.Setup to Flow.Config and Flow.Config to Flow.Settings for
  consistent Config/Settings naming convention at every level. Breaking change:
  all type names, function names, schema names, and API URL paths (/configs →
  /settings) updated.
- 23f218a: Replace flat/v2 contract format with named contracts supporting
  extends inheritance.

  BREAKING CHANGES:
  - `contract` is now a map of named contract entries (e.g.,
    `{ "default": { ... }, "web": { ... } }`)
  - `version` field inside contracts removed
  - `$tagging` renamed to `tagging`
  - Legacy flat contract format removed
  - `$globals`, `$context`, `$custom`, `$user`, `$consent` references removed
  - Settings-level `contract` field removed (use named contracts at config
    level)
  - Auto-injection of `$tagging` into `collector.tagging` removed (use
    `$contract.name.tagging` explicitly)
  - Validator `contract` setting renamed to `events` (receives raw schemas, not
    `{ schema: ... }` wrappers)

  NEW FEATURES:
  - Named contracts with `extends` for inheritance (additive merge)
  - Generalized dot-path resolution: `$def.name.nested.path`,
    `$contract.name.section`
  - `$contract` as first-class reference type with path access
  - `$def` inside contracts supported via two-pass resolution
  - `$def` aliasing for reducing repetition: `{ "c": "$contract.web" }` then
    `$def.c.events`

- d5af3cf: Unified CLI and Docker runner into single `walkeros run` code path
  with built-in health server, heartbeat, polling, and secrets support. Added
  `--flow-id` and `--project` flags. Removed legacy `--deploy`, `--url`,
  `--health-endpoint`, `--heartbeat-interval`, and `-h/--host` flags.

### Minor Changes

- 6ae0ee3: Add v2 structured contract format with globals, context, custom,
  user, and consent sections.

  Contracts can now describe cross-event properties (globals, consent, etc.)
  alongside entity-action event schemas. Top-level sections are JSON Schemas
  that merge additively into per-event validation.

  Breaking: None. Legacy flat contracts continue working unchanged. v2 is opt-in
  via `version: 2` field.

- b6c8fa8: Add stores as a first-class component type in Flow.Config. Stores get
  their own `stores` section in flow settings, a `collector.stores` registry,
  and `$store:storeId` env wiring in the bundler. Includes `storeMemoryInit` for
  Flow.Config compatibility and type widening in cache/file transformers.

### Patch Changes

- 2b259b6: Fix deterministic package version resolution in bundler.
  - Two-phase resolve-then-install prevents version overwrites
  - peerDependencies resolved at lowest priority (not equal to deps)
  - Per-build temp directories prevent cross-build interference
  - Optional peerDeps (peerDependenciesMeta) correctly skipped
  - Prerelease versions handled with includePrerelease flag
  - Package names validated against npm naming rules

- ddd6a21: Generated Dockerfiles now include COPY lines for `include` folders,
  enabling fs store support in Docker containers.
- 5cb84c1: Replace hand-written MCP resources with auto-generated JSON Schemas
  from @walkeros/core. Add walkerOS.json to 5 transformer packages. Variables
  resource remains hand-maintained (runtime interpolation patterns).
- 67dd7c8: Standardize command pattern: all three commands (validate, simulate,
  push) now route through their programmatic APIs for string resolution and
  orchestration. Extract shared createCollectorLoggerConfig utility. Pass
  missing silent/step options through simulate() API.
- 499e27a: Add sideEffects declarations to all packages for bundler tree-shaking
  support.
- 55ce33e: Fix $store: forward reference bug in bundler codegen — stores are now
  hoisted into a separate variable declaration before the config object,
  ensuring store references resolve correctly at runtime
- Updated dependencies [2b259b6]
- Updated dependencies [2614014]
- Updated dependencies [6ae0ee3]
- Updated dependencies [37299a9]
- Updated dependencies [499e27a]
- Updated dependencies [0e5eede]
- Updated dependencies [d11f574]
- Updated dependencies [d11f574]
- Updated dependencies [1fe337a]
- Updated dependencies [5cb84c1]
- Updated dependencies [23f218a]
- Updated dependencies [499e27a]
- Updated dependencies [c83d909]
- Updated dependencies [b6c8fa8]
  - @walkeros/core@3.0.0
  - @walkeros/server-core@3.0.0

## 2.1.1

### Patch Changes

- Updated dependencies [fab477d]
  - @walkeros/core@2.1.1
  - @walkeros/server-core@2.1.1

## 2.1.0

### Minor Changes

- cb2da05: Add data contracts for centralized event validation and documentation
- fed78f0: Replace deployment polling with SSE streaming for real-time status
  updates
- 3eb6416: Add unified `env.respond` capability. Any step (transformer,
  destination) can now customize HTTP responses via
  `env.respond({ body, status?, headers? })`. Sources configure the response
  handler — Express source uses createRespond for idempotent first-call-wins
  semantics. CLI serve mode removed (superseded by response-capable flows).
- 39780b0: Add event usage counters to heartbeat reporting
- dd53425: Simplify `walkeros run collect` to `walkeros run` — the mode concept
  has been removed
- 66aaf2d: Runner-owned health server: The runner now provides /health and
  /ready endpoints independently of flow sources. Express source's `status`
  setting and fetch source's `healthPath` setting have been removed — health
  endpoints are no longer source responsibilities.
- 97df0b2: Simplify validate command: file-first argument, --type defaults to
  flow, deep validation merged into flow, entry validation moved to --path
- 026c412: Unified simulation API: single simulate() function replaces
  simulateSource/simulateDestination/simulateTransformer/simulateFlow. Built-in
  call tracking for destinations via wrapEnv. No bundling required for
  simulation.

### Patch Changes

- fed78f0: Show logo only on bare `walkeros` call, not before every command
- 7b7e37b: Consolidate flow validation to use core's validateFlowSetup, adding
  $var/$def reference checking and IntelliSense context extraction
- 5145662: Use os.tmpdir() as default temp directory to fix permission errors in
  containers
- 02a7958: Add WARN log level (ERROR=0, WARN=1, INFO=2, DEBUG=3). Logger
  instances expose `warn()` method routed to `console.warn` and `json()` method
  for structured output. Config accepts optional `jsonHandler`. MockLogger
  includes both as jest mocks. CLI logger unified with core logger via
  `createCLILogger()` factory.
- 3bc32de: Surface mapping field in examples_list and ExampleLookupResult
- 5145662: Add --output URL support, -f shorthand for --flow, and lazy-load
  esbuild in runtime
- 7fc4cee: Fix server bundle port forwarding from runtime context to source
  configs
- 1876bb9: Remove unused bundle simulation path, CallTracker, and executor files
  from simulate command. Simulate now only accepts Flow.Setup config JSON files.
- Updated dependencies [7fc4cee]
- Updated dependencies [7fc4cee]
- Updated dependencies [cb2da05]
- Updated dependencies [2bbe8c8]
- Updated dependencies [3eb6416]
- Updated dependencies [02a7958]
- Updated dependencies [97df0b2]
- Updated dependencies [97df0b2]
- Updated dependencies [026c412]
- Updated dependencies [7d38d9d]
  - @walkeros/core@2.1.0
  - @walkeros/server-core@2.1.0

## 2.0.1

## 2.0.0

### Minor Changes

- a2f27d4: Add deploy command for web and server deployments
- 7b2d750: Add walkerOS.json package convention for CDN-based schema discovery

### Patch Changes

- 1ae6972: Fix missing trailing newline in JSON output
- Updated dependencies [7b2d750]
  - @walkeros/core@1.4.0
  - @walkeros/server-core@2.0.0

## 1.3.0

### Minor Changes

- 087eb2d: Restructure CLI with auth, projects, flows command groups; MCP wraps
  CLI functions instead of reimplementing API logic
- 087eb2d: Add Unix-standard stdio support: results to stdout, logs to stderr,
  stdin auto-detection, -o for file output

### Patch Changes

- Updated dependencies [a4cc1ea]
  - @walkeros/core@1.3.0
  - @walkeros/server-core@1.0.5

## 1.2.0

### Minor Changes

- cc68f50: Add validate command for events, flows, and mappings
  - `walkeros validate event` - validates event structure using
    PartialEventSchema
  - `walkeros validate flow` - validates flow configurations using SetupSchema
  - `walkeros validate mapping` - validates mapping event patterns

  Includes programmatic API via `import { validate } from '@walkeros/cli'`

## 1.1.3

### Patch Changes

- 6fcfaf5: Fix chain property handling for all component types in bundler.
  Sources now correctly output `next` property for pre-collector transformer
  chains. Unified inline code generation for sources, destinations, and
  transformers. Standardized transformer `next` as top-level property
  (consistent with destination `before`).

## 1.1.2

### Patch Changes

- Updated dependencies [7ad6cfb]
  - @walkeros/core@1.2.2
  - @walkeros/server-core@1.0.4

## 1.1.1

### Patch Changes

- 6256c12: Add inline code support for sources, transformers, and destinations
  - Add `InlineCodeSchema` with `push`, `type`, and `init` fields for embedding
    JavaScript in flow configs
  - Make `package` field optional in reference schemas (either `package` or
    `code` required at runtime)
  - Update `flow-complete.json` example with inline code demonstrations
    including enricher transformer, debug destination, and conditional mappings

- Updated dependencies [6256c12]
  - @walkeros/core@1.2.1
  - @walkeros/server-core@1.0.3

## 1.1.0

### Minor Changes

- 888bbdf: Add inline code syntax for sources, transformers, and destinations

  Enables defining custom logic directly in flow.json using `code` objects
  instead of requiring external packages. This is ideal for simple one-liner
  transformations.

  **Example:**

  ```json
  {
    "transformers": {
      "enrich": {
        "code": {
          "push": "$code:(event) => ({ ...event, data: { ...event.data, enriched: true } })"
        },
        "config": {}
      }
    }
  }
  ```

  **Code object properties:**
  - `push` - The push function with `$code:` prefix (required)
  - `type` - Optional instance type identifier
  - `init` - Optional init function with `$code:` prefix

  **Rules:**
  - Use `package` OR `code`, never both (CLI validates this)
  - `config` stays separate from `code`
  - `$code:` prefix outputs raw JavaScript at bundle time

### Patch Changes

- fdf6e7b: Add transformer support to CLI bundler
  - Detect and bundle transformer packages from flow.json configuration
  - Support transformer chaining via `next` field
  - Handle `$code:` prefix for inline JavaScript in transformer config
  - Generate proper import statements and config objects for transformers
  - Document transformer configuration in flow.json

- Updated dependencies [f39d9fb]
- Updated dependencies [888bbdf]
  - @walkeros/core@1.2.0
  - @walkeros/server-core@1.0.2

## 1.0.2

### Patch Changes

- 2709933: Add `$code:` prefix support for inline JavaScript in flow.json

  Values prefixed with `$code:` are output as raw JavaScript instead of quoted
  strings in the bundled output. This enables features like `fn:` callbacks and
  `condition:` predicates directly in JSON configuration files.

  Example:

  ```json
  { "fn": "$code:(value) => value.toUpperCase()" }
  ```

  Outputs:

  ```javascript
  {
    fn: (value) => value.toUpperCase();
  }
  ```

- 04469bb: Auto-detect default export for sources and destinations

  Sources and destinations now automatically use their package's default export,
  eliminating the need to specify `imports` for the main function.

  Before (verbose):

  ```json
  "@walkeros/web-source-browser": { "imports": ["sourceBrowser"] }
  ```

  After (simpler):

  ```json
  "@walkeros/web-source-browser": {}
  ```

  The `imports` field is now only needed for utility functions. Explicit `code`
  still works for packages without default exports.

- 544a79e: Implicit collector: auto-add @walkeros/collector when
  sources/destinations exist

  The CLI now automatically adds `@walkeros/collector` and imports `startFlow`
  when your flow has sources or destinations. No need to declare the collector
  package.

  Before (verbose):

  ```json
  "packages": {
    "@walkeros/collector": { "imports": ["startFlow"] },
    "@walkeros/web-source-browser": {},
    "@walkeros/destination-demo": {}
  }
  ```

  After (simpler):

  ```json
  "packages": {
    "@walkeros/web-source-browser": {},
    "@walkeros/destination-demo": {}
  }
  ```

  You only need to specify `@walkeros/collector` when you want to pin a specific
  version or use a local path for development.

- 4da2ef3: Fix CLI commands hanging after completion

  Commands (`bundle`, `simulate`, `push`) would hang indefinitely after
  completing successfully due to open handles keeping the Node.js event loop
  alive.

  Root cause: esbuild worker threads and pacote HTTP keep-alive connections were
  not being cleaned up.

  Fixes:
  - Add `esbuild.stop()` after builds to terminate worker threads
  - Add explicit `process.exit(0)` on successful completion for all CLI commands

- 2f82a2e: Fix simulate command JSON output to use consistent `result` property
  instead of `elbResult`
- Updated dependencies [b65b773]
- Updated dependencies [20eca6e]
  - @walkeros/core@1.1.0
  - @walkeros/server-core@1.0.1

## 1.0.1

### Patch Changes

- eb878df: Improved CLI option consistency and added `--dockerfile` flag
  improvements

  **Option consistency:**
  - Added `--flow` option to simulate command for multi-flow configs
  - Standardized `-v/--verbose` and `-s/--silent` shortcuts across all commands
  - Removed non-functional `--dry-run` option from all commands
  - Removed `-f` shortcut from bundle (use `--flow` for consistency)
  - Unified option description casing (lowercase)

  **Dockerfile improvements:**
  - Generate correct `MODE=serve` for web flows and `MODE=collect` for server
    flows
  - Support copying custom Dockerfiles with `--dockerfile path/to/Dockerfile`
  - Respects `--flow` parameter for multi-flow configurations

## 1.0.0

### Major Changes

- 67c9e1d: Hello World! walkerOS v1.0.0

  Open-source event data collection. Collect event data for digital analytics in
  a unified and privacy-centric way.

### Patch Changes

- Updated dependencies [67c9e1d]
  - @walkeros/core@1.0.0
  - @walkeros/server-core@1.0.0