@walkeros/cli 1.0.0 → 1.0.1

package/dist/examples/flow-complete.md

@@ -0,0 +1,247 @@
+# flow-complete.json - Comprehensive walkerOS Flow Example
+
+This example demonstrates **ALL JSON-compatible walkerOS features** with
+real-world patterns. It contains two named flows (`web` and `server`) showing a
+complete event tracking architecture.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ WEB FLOW                                                                    │
+│                                                                             │
+│   Browser Source ─┐                                                         │
+│   DataLayer Source ──▶ [Validator] ──▶ Collector ──▶ GA4 Destination        │
+│   Demo Source ────┘                               └──▶ API Destination      │
+│                                                              │              │
+└──────────────────────────────────────────────────────────────│──────────────┘
+                                                               ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ SERVER FLOW                                                                 │
+│                                                                             │
+│   HTTP Request ──▶ Express Source ──▶ Collector ──▶ [Fingerprint] ──────┐   │
+│                         │                          [Validator]          │   │
+│                         │                                               ▼   │
+│                         └── ingest: IP, user-agent ────────▶ Meta Destination
+│                                     language, referer       Demo Destination│
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### Run Web Flow
+
+```bash
+cd walkerOS
+npx walkeros serve packages/cli/examples/flow-complete.json --flow web
+# Open http://localhost:3000 - demo events fire automatically
+```
+
+### Run Server Flow
+
+```bash
+cd walkerOS
+npx walkeros run packages/cli/examples/flow-complete.json --flow server
+
+# Test health
+curl http://localhost:8080/health
+
+# Send test event
+curl -X POST http://localhost:8080/collect \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "order complete",
+    "data": {"id": "ORD-999", "total": 99.99, "currency": "EUR"},
+    "user": {"email": "test@example.com", "id": "U-123"},
+    "nested": [{"entity": "product", "data": {"id": "P1", "name": "Item", "price": 99.99, "quantity": 1}}]
+  }'
+```
+
+### Run Both (Full Pipeline)
+
+```bash
+# Terminal 1: Start server
+npx walkeros run packages/cli/examples/flow-complete.json --flow server
+
+# Terminal 2: Start web (sends to server via API destination)
+npx walkeros serve packages/cli/examples/flow-complete.json --flow web
+```
+
+---
+
+## Feature Inventory
+
+### Features Used (51)
+
+#### Mapping - Value Extraction
+
+| Feature           | Location          | Example                                                      |
+| ----------------- | ----------------- | ------------------------------------------------------------ |
+| Key extraction    | GA4 page_view     | `"page_title": "data.title"`                                 |
+| Static value      | Meta ViewContent  | `"content_type": { "value": "product" }`                     |
+| Key with fallback | GA4 add_to_cart   | `{ "key": "data.currency", "value": "$variables.currency" }` |
+| Nested key (deep) | dataLayer mapping | `"items.0.item_id"`                                          |
+
+#### Mapping - Structure
+
+| Feature               | Location           | Example                                                     |
+| --------------------- | ------------------ | ----------------------------------------------------------- |
+| Map (object)          | GA4 purchase       | `"data": { "map": { ... } }`                                |
+| Loop with "nested"    | GA4 purchase items | `{ "loop": ["nested", { "map": {...} }] }`                  |
+| Loop with "this"      | GA4 add_to_cart    | `{ "loop": ["this", { "map": {...} }] }`                    |
+| Set (single value)    | Meta ViewContent   | `"content_ids": { "set": ["data.id"] }`                     |
+| Set (multiple values) | Meta settings      | `"external_id": { "set": ["user.device", "user.session"] }` |
+| Direct passthrough    | Meta PageView      | `"data": "data"`                                            |
+
+#### Mapping - Control
+
+| Feature              | Location            | Example                                                     |
+| -------------------- | ------------------- | ----------------------------------------------------------- |
+| Consent-gated field  | API destination     | `{ "key": "user.email", "consent": { "marketing": true } }` |
+| Ignore rule          | GA4/API test events | `{ "ignore": true }`                                        |
+| Wildcard action (\*) | GA4 test, Meta      | `"test": { "*": { "ignore": true } }`                       |
+| Wildcard entity (\*) | Meta click handler  | `"*": { "click": { "name": "CustomEvent" } }`               |
+
+#### Definitions & Variables
+
+| Feature              | Location           | Example                                      |
+| -------------------- | ------------------ | -------------------------------------------- |
+| Root-level variables | Root               | `"currency": "EUR"`                          |
+| Flow-level variables | server.variables   | `"metaPixelId": "${META_PIXEL_ID:...}"`      |
+| Environment variable | Variables          | `"${GA4_MEASUREMENT_ID:G-DEMO123456}"`       |
+| Env with default     | Variables          | `"${API_URL:http://localhost:8080/collect}"` |
+| $variables reference | GA4 settings       | `"$variables.ga4MeasurementId"`              |
+| Definition (complex) | Root definitions   | `"ga4ItemsLoop": { "loop": [...] }`          |
+| $ref reference       | GA4 purchase items | `{ "$ref": "#/definitions/ga4ItemsLoop" }`   |
+
+#### Sources
+
+| Feature              | Location  | Example                               |
+| -------------------- | --------- | ------------------------------------- |
+| Primary source       | browser   | `"primary": true`                     |
+| Multiple sources     | web flow  | browser + dataLayer + demo            |
+| Source-level mapping | dataLayer | `"mapping": { "add_to_cart": {...} }` |
+| Pre-collector chain  | dataLayer | `"next": "dataLayerValidator"`        |
+| Demo source events   | demo      | Pre-configured test events            |
+
+#### Transformers
+
+| Feature                 | Location           | Example                            |
+| ----------------------- | ------------------ | ---------------------------------- |
+| Validator transformer   | dataLayerValidator | JSON Schema validation             |
+| Fingerprint transformer | server             | Hash context fields to `user.hash` |
+| Transformer chaining    | server             | `"next": "serverValidator"`        |
+| Post-collector chain    | Meta               | `"before": "fingerprint"`          |
+| Contract validation     | serverValidator    | Entity/action schemas              |
+| Format option           | serverValidator    | `"format": true`                   |
+
+#### Destinations
+
+| Feature               | Location         | Example                            |
+| --------------------- | ---------------- | ---------------------------------- |
+| Destination consent   | GA4              | `"consent": { "marketing": true }` |
+| Destination mapping   | All destinations | Entity/action to vendor events     |
+| Multiple destinations | Both flows       | GA4 + API, Meta + Demo             |
+| Batch option          | API              | `"batch": 5`                       |
+
+#### Collector
+
+| Feature           | Location        | Example                                 |
+| ----------------- | --------------- | --------------------------------------- |
+| Tagging           | Both collectors | `"tagging": 1`                          |
+| Consent defaults  | Both collectors | `"consent": { "functional": true }`     |
+| Globals           | Both collectors | `"environment": "demo"`                 |
+| Custom properties | web collector   | `"custom": { "campaign": "flow-demo" }` |
+| User defaults     | web collector   | `"user": { "id": "anonymous" }`         |
+
+#### Server-Specific
+
+| Feature              | Location    | Example                                         |
+| -------------------- | ----------- | ----------------------------------------------- |
+| Ingest metadata      | http source | `"context.ip": "ip"`                            |
+| Language header      | ingest      | `"context.language": "headers.accept-language"` |
+| Policy               | Meta        | Pre-processing field transformation             |
+| Policy consent-gated | Meta        | `"user_data.em"` with consent                   |
+| Policy nested map    | Meta        | `"custom_data.request_meta": { "map": {...} }`  |
+
+#### Browser Source
+
+| Feature         | Location | Example                            |
+| --------------- | -------- | ---------------------------------- |
+| Prefix          | browser  | `"prefix": "data-elb"`             |
+| Auto pageview   | browser  | `"pageview": true`                 |
+| Session consent | browser  | `"session": { "consent": {...} }`  |
+| ELB binding     | browser  | `"elb": "elb"`, `"elbLayer": true` |
+
+---
+
+### Features NOT Used (15)
+
+#### Requires JavaScript (7)
+
+These features cannot be used in pure JSON configurations:
+
+| Feature                     | Reason                        |
+| --------------------------- | ----------------------------- |
+| `fn:` function              | Requires JavaScript callback  |
+| `condition:`                | Requires JavaScript predicate |
+| Conditional mapping (array) | Requires condition functions  |
+| Custom transformer code     | Requires JavaScript           |
+| Custom source code          | Requires JavaScript           |
+| Custom destination code     | Requires JavaScript           |
+| Event handler callbacks     | Requires JavaScript           |
+
+#### Omitted for Clarity (8)
+
+These features could be added but were omitted to keep the example focused:
+
+| Feature                   | Why Omitted                   |
+| ------------------------- | ----------------------------- |
+| Multiple named flows (3+) | Two flows sufficient for demo |
+| Queue config              | Advanced batching scenario    |
+| Retry config              | Advanced error handling       |
+| Custom fetch options      | API destination advanced      |
+| Dynamic routing           | Requires condition logic      |
+| Transform before send     | Covered by policy             |
+| Custom headers in API     | Would add complexity          |
+| Multiple validators       | One per flow sufficient       |
+
+---
+
+## Data Flow Examples
+
+### Order Complete (Server Flow)
+
+1. **Ingest**: Request metadata extracted (IP, user-agent, referer) to
+   `context.*`
+2. **Policy**: Pre-processes event:
+   - `user_data.em` from `user.email` (only if marketing consent)
+   - `user_data.external_id` from `user.id`
+   - `custom_data.server_processed` = `true`
+   - `custom_data.request_meta` = `{ ip, ua }` from context
+3. **Fingerprint**: Hashes context fields to `user.hash`
+4. **Validator**: Checks products have `data.id`
+5. **Mapping**: Transforms to Meta format:
+   - `"name": "Purchase"`
+   - `value`, `currency`, `order_id` extracted
+   - `contents` via `$ref` to definition loop
+
+### Product Add (Web Flow)
+
+1. **DataLayer Source**: Captures `add_to_cart` event
+2. **Source Mapping**: Transforms to `product add` with walkerOS structure
+3. **Validator**: Checks `id` and `name` present
+4. **Collector**: Adds globals, consent, user data
+5. **GA4 Mapping**: Transforms to `add_to_cart` with items array
+6. **API Destination**: Batches and sends to server (if batch size reached)
+
+---
+
+## Environment Variables
+
+| Variable             | Default                         | Description                |
+| -------------------- | ------------------------------- | -------------------------- |
+| `GA4_MEASUREMENT_ID` | `G-DEMO123456`                  | Google Analytics 4 ID      |
+| `API_URL`            | `http://localhost:8080/collect` | Server collection endpoint |
+| `META_PIXEL_ID`      | `123456789012345`               | Meta Pixel ID              |
+| `META_ACCESS_TOKEN`  | `demo_token`                    | Meta Conversions API token |

package/dist/index.d.ts

@@ -160,11 +160,6 @@ interface GlobalOptions {
      * @default false
      */
     silent?: boolean;
-    /**
-     * Preview command without executing
-     * @default false
-     */
-    dryRun?: boolean;
 }
 
 interface BundleStats {
@@ -185,9 +180,8 @@ interface BundleCommandOptions {
     json?: boolean;
     cache?: boolean;
     verbose?: boolean;
-    dryRun?: boolean;
     silent?: boolean;
-    dockerfile?: boolean;
+    dockerfile?: boolean | string;
 }
 declare function bundleCommand(options: BundleCommandOptions): Promise<void>;
 /**
@@ -247,9 +241,9 @@ interface ApiCall {
 interface SimulateCommandOptions {
     config: string;
     event?: string;
+    flow?: string;
     json?: boolean;
     verbose?: boolean;
-    dryRun?: boolean;
     silent?: boolean;
     platform?: 'web' | 'server';
 }
@@ -352,8 +346,6 @@ interface RunCommandOptions {
     json?: boolean;
     /** Verbose logging */
     verbose?: boolean;
-    /** Dry-run mode */
-    dryRun?: boolean;
     /** Suppress output */
     silent?: boolean;
 }

package/dist/index.js

@@ -30,6 +30,7 @@ var VERSION = JSON.parse(findPackageJson()).version;
 // src/commands/bundle/index.ts
 import path9 from "path";
 import fs8 from "fs-extra";
+import { getPlatform as getPlatform2 } from "@walkeros/core";
 
 // src/core/logger.ts
 import chalk from "chalk";
@@ -1335,10 +1336,6 @@ async function bundleCommand(options) {
   const timer = createTimer();
   timer.start();
   const logger2 = createCommandLogger(options);
-  if (options.dryRun) {
-    logger2.log(`[DRY-RUN] Would execute bundle with config: ${options.config}`);
-    return;
-  }
   try {
     if (options.flow && options.all) {
       throw new Error("Cannot use both --flow and --all flags together");
@@ -1385,11 +1382,12 @@ async function bundleCommand(options) {
           displayStats(stats, logger2);
         }
         if (options.dockerfile && !options.all) {
-          const dockerfilePath = path9.join(
-            path9.dirname(buildOptions.output),
-            "Dockerfile"
-          );
-          await generateDockerfile(dockerfilePath, buildOptions.output, logger2);
+          const platform = getPlatform2(flowConfig);
+          if (platform) {
+            const outputDir = path9.dirname(buildOptions.output);
+            const customFile = typeof options.dockerfile === "string" ? options.dockerfile : void 0;
+            await generateDockerfile(outputDir, platform, logger2, customFile);
+          }
         }
       } catch (error) {
         const errorMessage = getErrorMessage(error);
@@ -1473,26 +1471,34 @@ async function bundle(configOrPath, options = {}) {
     options.stats ?? false
   );
 }
-async function generateDockerfile(dockerfilePath, bundleOutput, logger2) {
-  const bundleFilename = path9.basename(bundleOutput);
+async function generateDockerfile(outputDir, platform, logger2, customFile) {
+  const destPath = path9.join(outputDir, "Dockerfile");
+  if (customFile && await fs8.pathExists(customFile)) {
+    await fs8.copy(customFile, destPath);
+    logger2.log(`Dockerfile: ${destPath} (copied from ${customFile})`);
+    return;
+  }
+  const isWeb = platform === "web";
+  const bundleFile = isWeb ? "walker.js" : "bundle.mjs";
+  const mode = isWeb ? "serve" : "collect";
   const dockerfile = `# Generated by walkeros CLI
 FROM walkeros/flow:latest
 
-COPY ${bundleFilename} /app/flow/bundle.mjs
+COPY ${bundleFile} /app/flow/${bundleFile}
 
-ENV MODE=collect
-ENV BUNDLE=/app/flow/bundle.mjs
+ENV MODE=${mode}
+ENV BUNDLE=/app/flow/${bundleFile}
 
 EXPOSE 8080
 `;
-  await fs8.writeFile(dockerfilePath, dockerfile);
-  logger2.log(`Dockerfile: ${dockerfilePath}`);
+  await fs8.writeFile(destPath, dockerfile);
+  logger2.log(`Dockerfile: ${destPath}`);
 }
 
 // src/commands/simulate/simulator.ts
 import path10 from "path";
 import fs10 from "fs-extra";
-import { getPlatform as getPlatform2 } from "@walkeros/core";
+import { getPlatform as getPlatform3 } from "@walkeros/core";
 
 // src/commands/simulate/tracker.ts
 var CallTracker = class {
@@ -1804,6 +1810,7 @@ async function simulateCore(inputPath, event, options = {}) {
   try {
     logger2.debug(`Simulating event: ${JSON.stringify(event)}`);
     const result = await executeSimulation(event, inputPath, options.platform, {
+      flow: options.flow,
       logger: logger2,
       verbose: options.verbose
     });
@@ -1851,7 +1858,8 @@ async function executeSimulation(event, inputPath, platformOverride, options = {
         typedEvent,
         tempDir,
         startTime,
-        collectorLoggerConfig
+        collectorLoggerConfig,
+        options.flow
       );
     } else {
       return await executeBundleSimulation(
@@ -1877,9 +1885,11 @@ async function executeSimulation(event, inputPath, platformOverride, options = {
     }
   }
 }
-async function executeConfigSimulation(_content, configPath, typedEvent, tempDir, startTime, loggerConfig2) {
-  const { flowConfig, buildOptions } = await loadFlowConfig(configPath);
-  const platform = getPlatform2(flowConfig);
+async function executeConfigSimulation(_content, configPath, typedEvent, tempDir, startTime, loggerConfig2, flowName) {
+  const { flowConfig, buildOptions } = await loadFlowConfig(configPath, {
+    flowName
+  });
+  const platform = getPlatform3(flowConfig);
   const tracker = new CallTracker();
   const tempOutput = path10.join(
     tempDir,
@@ -1979,18 +1989,13 @@ async function executeBundleSimulation(bundleContent, platform, typedEvent, temp
 // src/commands/simulate/index.ts
 async function simulateCommand(options) {
   const logger2 = createCommandLogger(options);
-  if (options.dryRun) {
-    logger2.log(
-      `[DRY-RUN] Would execute simulate with config: ${options.config}`
-    );
-    return;
-  }
   const startTime = Date.now();
   try {
     const event = await loadJsonFromSource(options.event, {
       name: "event"
     });
     const result = await simulateCore(options.config, event, {
+      flow: options.flow,
       json: options.json,
       verbose: options.verbose,
       silent: options.silent
@@ -2041,7 +2046,7 @@ import path11 from "path";
 import { JSDOM as JSDOM2, VirtualConsole as VirtualConsole2 } from "jsdom";
 import fs11 from "fs-extra";
 import {
-  getPlatform as getPlatform3
+  getPlatform as getPlatform4
 } from "@walkeros/core";
 import { schemas as schemas2 } from "@walkeros/core/dev";
 async function pushCommand(options) {
@@ -2153,7 +2158,7 @@ async function executeConfigPush(options, validatedEvent, logger2, setTempDir) {
     flowName: options.flow,
     logger: logger2
   });
-  const platform = getPlatform3(flowConfig);
+  const platform = getPlatform4(flowConfig);
   logger2.debug("Bundling flow configuration");
   const configDir = buildOptions.configDir || process.cwd();
   const tempDir = path11.join(
@@ -2587,10 +2592,6 @@ async function runCommand(mode, options) {
         logger2.debug("Bundle ready");
       }
     }
-    if (options.dryRun) {
-      logger2.log(`[DRY-RUN] Would execute locally: run ${mode}`);
-      return;
-    }
     const modeLabel = mode === "collect" ? "Collector" : "Server";
     logger2.log(`Starting ${modeLabel}...`);
     await executeRunLocal(mode, flowPath, {
@@ -2712,7 +2713,10 @@ program.hook("preAction", (thisCommand, actionCommand) => {
     console.log(`${chalk2.hex("#01b5e2")("walkerOS")} v${VERSION}`);
   }
 });
-program.command("bundle [file]").description("Bundle NPM packages with custom code").option("-f, --flow <name>", "flow to build (for multi-flow configs)").option("--all", "build all flows (for multi-flow configs)").option("-s, --stats", "show bundle statistics").option("--json", "output statistics in JSON format (implies --stats)").option("--no-cache", "disable package caching and download fresh packages").option("-v, --verbose", "verbose output").option("--dry-run", "preview command without executing").option("--silent", "suppress output").option("--dockerfile", "generate Dockerfile alongside bundle").action(async (file, options) => {
+program.command("bundle [file]").description("Bundle NPM packages with custom code").option("--flow <name>", "flow name for multi-flow configs").option("--all", "build all flows for multi-flow configs").option("--stats", "show bundle statistics").option("--json", "output as JSON (implies --stats)").option("--no-cache", "disable package caching").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").option(
+  "--dockerfile [file]",
+  "generate Dockerfile (or copy custom file) to dist/"
+).action(async (file, options) => {
   await bundleCommand({
     config: file || "bundle.config.json",
     flow: options.flow,
@@ -2721,29 +2725,28 @@ program.command("bundle [file]").description("Bundle NPM packages with custom co
     json: options.json,
     cache: options.cache,
     verbose: options.verbose,
-    dryRun: options.dryRun,
     silent: options.silent,
     dockerfile: options.dockerfile
   });
 });
 program.command("simulate [file]").description("Simulate event processing and capture API calls").option(
   "-e, --event <source>",
-  "Event to simulate (JSON string, file path, or URL)"
-).option("-p, --platform <platform>", "Platform override (web or server)").option("--json", "Output results as JSON").option("-v, --verbose", "Verbose output").option("--dry-run", "preview command without executing").option("--silent", "suppress output").action(async (file, options) => {
+  "event to simulate (JSON string, file path, or URL)"
+).option("--flow <name>", "flow name for multi-flow configs").option("-p, --platform <platform>", "platform override (web or server)").option("--json", "output as JSON").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").action(async (file, options) => {
   await simulateCommand({
     config: file || "bundle.config.json",
     event: options.event,
+    flow: options.flow,
     platform: options.platform,
     json: options.json,
     verbose: options.verbose,
-    dryRun: options.dryRun,
     silent: options.silent
   });
 });
 program.command("push [file]").description("Push an event through the flow with real API execution").requiredOption(
   "-e, --event <source>",
-  "Event to push (JSON string, file path, or URL)"
-).option("--flow <name>", "Flow name (for multi-flow configs)").option("-p, --platform <platform>", "Platform override (web or server)").option("--json", "Output results as JSON").option("-v, --verbose", "Verbose output").option("-s, --silent", "Suppress output").action(async (file, options) => {
+  "event to push (JSON string, file path, or URL)"
+).option("--flow <name>", "flow name for multi-flow configs").option("-p, --platform <platform>", "platform override (web or server)").option("--json", "output as JSON").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").action(async (file, options) => {
   await pushCommand({
     config: file || "bundle.config.json",
     event: options.event,
@@ -2757,20 +2760,19 @@ program.command("push [file]").description("Push an event through the flow with
 var runCmd = program.command("run").description("Run walkerOS flows in collect or serve mode");
 runCmd.command("collect [file]").description(
   "Run collector mode (event collection endpoint). Defaults to server-collect.mjs if no file specified."
-).option("-p, --port <number>", "Port to listen on (default: 8080)", parseInt).option("-h, --host <address>", "Host address (default: 0.0.0.0)").option("--json", "Output results as JSON").option("-v, --verbose", "Verbose output").option("--dry-run", "preview command without executing").option("--silent", "suppress output").action(async (file, options) => {
+).option("-p, --port <number>", "port to listen on (default: 8080)", parseInt).option("-h, --host <address>", "host address (default: 0.0.0.0)").option("--json", "output as JSON").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").action(async (file, options) => {
   await runCommand("collect", {
     config: file || "server-collect.mjs",
     port: options.port,
     host: options.host,
     json: options.json,
     verbose: options.verbose,
-    dryRun: options.dryRun,
     silent: options.silent
   });
 });
 runCmd.command("serve [file]").description(
   "Run serve mode (single-file server for browser bundles). Defaults to baked-in web-serve.js if no file specified."
-).option("-p, --port <number>", "Port to listen on (default: 8080)", parseInt).option("-h, --host <address>", "Host address (default: 0.0.0.0)").option("--name <filename>", "Filename in URL (default: walker.js)").option("--path <directory>", "URL directory path (e.g., libs/v1)").option("--json", "Output results as JSON").option("-v, --verbose", "Verbose output").option("--dry-run", "preview command without executing").option("--silent", "suppress output").action(async (file, options) => {
+).option("-p, --port <number>", "port to listen on (default: 8080)", parseInt).option("-h, --host <address>", "host address (default: 0.0.0.0)").option("--name <filename>", "filename in URL (default: walker.js)").option("--path <directory>", "URL directory path (e.g., libs/v1)").option("--json", "output as JSON").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").action(async (file, options) => {
   await runCommand("serve", {
     config: file || "web-serve.js",
     port: options.port,
@@ -2779,7 +2781,6 @@ runCmd.command("serve [file]").description(
     servePath: options.path,
     json: options.json,
     verbose: options.verbose,
-    dryRun: options.dryRun,
     silent: options.silent
   });
 });