@walkeros/cli 4.0.0-next-1776095573328 → 4.0.0-next-1777882869103

package/CHANGELOG.md

@@ -1,6 +1,364 @@
 # @walkeros/cli
 
-## 4.0.0-next-1776095573328
+## 4.0.0-next-1777882869103
+
+### 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
+
+- 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-next-1777882869103
+  - @walkeros/collector@4.0.0-next-1777882869103
+  - @walkeros/server-destination-api@4.0.0-next-1777882869103
+  - @walkeros/server-core@4.0.0-next-1777882869103
+
+## 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
 
@@ -95,8 +453,8 @@
 - Updated dependencies [08c365a]
 - Updated dependencies [08c365a]
 - Updated dependencies [08c365a]
-  - @walkeros/core@4.0.0-next-1776095573328
-  - @walkeros/server-core@4.0.0-next-1776095573328
+  - @walkeros/core@3.3.0
+  - @walkeros/server-core@3.3.0
 
 ## 3.2.0