@walkeros/cli 3.1.1 → 3.2.0-next-1775064795590

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @walkeros/cli
 
+## 3.2.0-next-1775064795590
+
+### 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-next-1775064795590
+  - @walkeros/server-core@3.2.0-next-1775064795590
+
 ## 3.1.1
 
 ### Patch Changes

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
 ```