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

package/CHANGELOG.md

@@ -1,6 +1,179 @@
 # @walkeros/cli
 
-## 4.0.0-next-1773967844643
+## 4.0.0-next-1776095573328
+
+### 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@4.0.0-next-1776095573328
+  - @walkeros/server-core@4.0.0-next-1776095573328
+
+## 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
 
@@ -35,8 +208,8 @@
 - Updated dependencies [bee8ba7]
 - Updated dependencies [966342b]
 - Updated dependencies [df990d4]
-  - @walkeros/core@4.0.0-next-1773967844643
-  - @walkeros/server-core@4.0.0-next-1773967844643
+  - @walkeros/core@3.1.0
+  - @walkeros/server-core@3.1.0
 
 ## 3.0.2
 

package/README.md

@@ -8,7 +8,7 @@ flows.
 The walkerOS CLI is a developer tool that:
 
 - **Bundles** flow configurations into optimized JavaScript
-- **Simulates** event processing for testing
+- **Simulates** event processing for testing (via `push --simulate`)
 - **Runs** flows locally without Docker daemon
 
 Think of it as your development toolchain for walkerOS - from config to running
@@ -46,7 +46,7 @@ npm install @walkeros/cli
 walkeros bundle flow.json
 
 # Test with simulated events (no real API calls)
-walkeros simulate flow.json --event '{"name":"product view"}'
+walkeros push flow.json --event '{"name":"product view"}' --simulate destination.demo
 
 # Push real events to destinations
 walkeros push flow.json --event '{"name":"product view"}'
@@ -99,41 +99,11 @@ walkeros bundle flow.json --dockerfile Dockerfile.custom
 The output path uses convention-based defaults: `./dist/bundle.mjs` for server,
 `./dist/walker.js` for web.
 
-### simulate
-
-Test event processing with simulated events. The config JSON gets bundled and
-executed with destination mocking.
-
-```bash
-walkeros simulate <config> --event '{"name":"page view"}' [options]
-```
-
-**Options:**
-
-- `-e, --event <json>` - Event to simulate (JSON string, file path, or URL)
-- `--flow <name>` - Flow name for multi-flow configs
-- `-p, --platform <platform>` - Platform override (`web` or `server`)
-- `--json` - Output as JSON
-- `-v, --verbose` - Verbose output
-- `-s, --silent` - Suppress output
-
-**Examples:**
-
-```bash
-# Simulate with config (auto-bundled)
-walkeros simulate examples/web-serve.json \
-  --event '{"name":"page view","data":{"title":"Home"}}' \
-  --json
-
-# Simulate specific flow from multi-flow config
-walkeros simulate flow.json --flow server --event '{"name":"test"}'
-```
-
 ### push
 
-Execute your flow with real API calls to configured destinations. Unlike
-`simulate` which mocks API calls, `push` performs actual HTTP requests. Accepts
-either a config JSON (which gets bundled) or a pre-built bundle.
+Execute your flow with real API calls, or simulate specific steps with
+`--simulate`. Accepts either a config JSON (which gets bundled) or a pre-built
+bundle.
 
 ```bash
 walkeros push <input> --event '<json>' [options]
@@ -149,9 +119,15 @@ The CLI auto-detects the input type by attempting to parse as JSON.
 **Options:**
 
 - `-e, --event <source>` - Event to push (JSON string, file path, or URL)
-  **Required**
+  **Required** (unless simulating a source)
 - `--flow <name>` - Flow name (for multi-flow configs)
 - `-p, --platform <platform>` - Platform override (`web` or `server`)
+- `--simulate <step>` - Simulate a step (repeatable). Mocks the step's push,
+  captures result. Use `destination.NAME` or `source.NAME`.
+- `--mock <step=value>` - Mock a step with a specific return value (repeatable).
+  Use `destination.NAME=VALUE`.
+- `--snapshot <source>` - JS file to eval before execution. Sets global state
+  (`window.dataLayer`, `process.env`, etc.).
 - `--json` - Output results as JSON
 - `-v, --verbose` - Verbose output
 - `-s, --silent` - Suppress output (for CI/CD)
@@ -169,6 +145,19 @@ walkeros push flow.json --event ./events/order.json
 walkeros push flow.json --event https://example.com/sample-event.json
 ```
 
+**Simulation examples:**
+
+```bash
+# Simulate a destination (mock its push, capture API calls)
+walkeros push flow.json -e event.json --simulate destination.ga4
+
+# Simulate a source (capture events, disable all destinations)
+walkeros push flow.json --simulate source.browser
+
+# Mock a destination with a specific return value
+walkeros push flow.json -e event.json --mock destination.ga4='{"status":"ok"}'
+```
+
 **Bundle input:**
 
 ```bash
@@ -179,16 +168,16 @@ walkeros push dist/bundle.mjs --event '{"name":"order complete"}'
 walkeros push dist/bundle.js --platform server --event '{"name":"order complete"}'
 ```
 
-**Push vs Simulate:**
+**Push modes:**
 
-| Feature      | `push`                              | `simulate`         |
-| ------------ | ----------------------------------- | ------------------ |
-| API Calls    | Real HTTP requests                  | Mocked (captured)  |
-| Use Case     | Integration testing                 | Safe local testing |
-| Side Effects | Full (writes to DBs, sends to APIs) | None               |
+| Mode | Flag | API Calls | Use Case |
+| ---- | ---- | --------- | -------- |
+| Real | (none) | Real HTTP requests | Integration testing |
+| Simulate | `--simulate` | Mocked (captured) | Safe local testing |
+| Mock | `--mock` | Returns mock value | Controlled testing |
 
-Use `simulate` first to validate configuration safely, then `push` to verify
-real integrations.
+Use `--simulate` first to validate safely, then push without flags for real
+integrations.
 
 ### run
 
@@ -503,7 +492,7 @@ See [examples/](./examples/) for complete working configurations.
 Use commands programmatically:
 
 ```typescript
-import { bundle, simulate, runCommand } from '@walkeros/cli';
+import { bundle, push, runCommand } from '@walkeros/cli';
 
 // Bundle
 await bundle({
@@ -511,11 +500,18 @@ await bundle({
   stats: true,
 });
 
-// Simulate
-const result = await simulate(
+// Push with simulation
+const result = await push(
+  './flow.json',
+  { name: 'page view', data: { title: 'Test' } },
+  { simulate: ['destination.ga4'], json: true },
+);
+// result.usage = API call tracking data
+
+// Push for real
+await push(
   './flow.json',
   { name: 'page view', data: { title: 'Test' } },
-  { json: true },
 );
 
 // Run
@@ -542,9 +538,10 @@ Try them:
 walkeros bundle examples/server-collect.json --stats
 
 # Simulate
-walkeros simulate \
+walkeros push \
   examples/web-serve.json \
-  --event '{"name":"product view","data":{"id":"P123"}}'
+  --event '{"name":"product view","data":{"id":"P123"}}' \
+  --simulate destination.demo
 
 # Run server
 walkeros run examples/server-collect.json --port 3000
@@ -559,9 +556,10 @@ Typical development cycle:
 vim my-flow.json
 
 # 2. Test with simulation (no real API calls)
-walkeros simulate \
+walkeros push \
   my-flow.json \
   --event '{"name":"product view"}' \
+  --simulate destination.demo \
   --verbose
 
 # 3. Bundle and check stats
@@ -581,7 +579,7 @@ curl -X POST http://localhost:3000/collect \
 ```
 CLI (downloads packages + bundles with esbuild)
  ├─ Bundle → optimized .mjs file
- ├─ Simulate → test bundle with events
+ ├─ Push → execute bundle (with optional --simulate for testing)
  └─ Run → execute bundle with built-in runtime
 ```