flow

Author: alexanderkirtzel

packages/cli/README.md

@@ -43,8 +43,8 @@ walkeros bundle https://example.com/config.json                  # Remote URL
 
 **Options:**
 
-- `-e, --env <name>` - Build specific environment (multi-env configs)
-- `--all` - Build all environments
+- `-f, --flow <name>` - Build specific flow (multi-flow configs)
+- `--all` - Build all flows
 - `-s, --stats` - Show bundle statistics
 - `--json` - Output stats as JSON
 - `--no-cache` - Disable package caching
@@ -58,7 +58,8 @@ walkeros bundle https://example.com/config.json                  # Remote URL
 walkeros bundle examples/server-collect.json --stats
 ```
 
-The output path is specified in the config's `build.output` field.
+The output path uses convention-based defaults: `./dist/bundle.mjs` for server,
+`./dist/walker.js` for web.
 
 ### simulate
 
@@ -165,59 +166,43 @@ walkeros bundle flow.json --no-cache
 
 ## Flow Configuration
 
-Minimal example:
+Flow configs use the `Flow.Setup` format with `version` and `flows`:
 
 ```json
 {
-  "flow": {
-    "platform": "server",
-    "sources": {
-      "http": {
-        "code": "sourceExpress",
-        "config": {
-          "settings": {
-            "path": "/collect",
-            "port": 8080
+  "version": 1,
+  "flows": {
+    "default": {
+      "server": {},
+      "packages": {
+        "@walkeros/collector": { "imports": ["startFlow"] },
+        "@walkeros/server-source-express": { "imports": ["sourceExpress"] },
+        "@walkeros/destination-demo": { "imports": ["destinationDemo"] }
+      },
+      "sources": {
+        "http": {
+          "code": "sourceExpress",
+          "config": {
+            "settings": { "path": "/collect", "port": 8080 }
           }
         }
-      }
-    },
-    "destinations": {
-      "demo": {
-        "code": "destinationDemo",
-        "config": {
-          "settings": {
-            "name": "Demo"
+      },
+      "destinations": {
+        "demo": {
+          "code": "destinationDemo",
+          "config": {
+            "settings": { "name": "Demo" }
           }
         }
-      }
-    },
-    "collector": {
-      "run": true
-    }
-  },
-  "build": {
-    "packages": {
-      "@walkeros/collector": {
-        "version": "latest",
-        "imports": ["startFlow"]
       },
-      "@walkeros/server-source-express": {
-        "version": "latest",
-        "imports": ["sourceExpress"]
-      },
-      "@walkeros/destination-demo": {
-        "version": "latest",
-        "imports": ["destinationDemo"]
-      }
-    },
-    "code": "// Custom code here\n",
-    "output": "bundle.mjs",
-    "template": "./templates/base.hbs"
+      "collector": { "run": true }
+    }
   }
 }
 ```
 
+Platform is determined by the `web: {}` or `server: {}` key presence.
+
 See [examples/](./examples/) for complete working configurations.
 
 ## Programmatic API

packages/cli/examples/README.md

@@ -229,44 +229,57 @@ Browser → destinationAPI (POST /collect) → sourceExpress → destinationData
 
 ### Flow Configuration Structure
 
+Flow configs use the `Flow.Setup` format:
+
 ```json
 {
-  "flow": {
-    "platform": "web" | "server",
-    "sources": {
-      "<source_name>": {
-        "code": "<imported_function_name>",
-        "config": { "settings": { /* source config */ } }
-      }
-    },
-    "destinations": {
-      "<destination_name>": {
-        "code": "<imported_function_name>",
-        "config": {
-          "settings": { /* destination config */ },
-          "mapping": { /* event mappings */ }
+  "version": 1,
+  "flows": {
+    "default": {
+      "web": {},
+      "packages": {
+        "<package_name>": { "imports": ["<function_name>"] }
+      },
+      "sources": {
+        "<source_name>": {
+          "code": "<imported_function_name>",
+          "config": {
+            "settings": {
+              /* source config */
+            }
+          }
+        }
+      },
+      "destinations": {
+        "<destination_name>": {
+          "code": "<imported_function_name>",
+          "config": {
+            "settings": {
+              /* destination config */
+            },
+            "mapping": {
+              /* event mappings */
+            }
+          }
+        }
+      },
+      "collector": {
+        "run": true,
+        "globals": {
+          /* global properties */
         }
       }
-    },
-    "collector": {
-      "run": true,
-      "globals": { /* global properties */ }
     }
-  },
-  "build": {
-    "packages": {
-      "<package_name>": {
-        "version": "latest",
-        "imports": ["<function_name>"]
-      }
-    },
-    "code": "// Optional custom code\n",
-    "template": "templates/base.hbs",
-    "output": "./dist/bundle.js"
   }
 }
 ```
 
+**Key points:**
+
+- Platform via `web: {}` or `server: {}` key (not `platform: "web"`)
+- Output path is convention-based: `./dist/walker.js` (web) or
+  `./dist/bundle.mjs` (server)
+
 ### Available Sources
 
 **Web**:

packages/cli/examples/flow-order-complete.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "environments": {
+  "flows": {
     "default": {
       "web": {},
       "packages": {

packages/cli/examples/flow-simple.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "environments": {
+  "flows": {
     "default": {
       "web": {},
       "packages": {

packages/cli/examples/flow.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "environments": {
+  "flows": {
     "default": {
       "web": {},
       "packages": {

packages/cli/examples/server-collect.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "environments": {
+  "flows": {
     "default": {
       "server": {},
       "packages": {

packages/cli/examples/web-serve.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "environments": {
+  "flows": {
     "default": {
       "web": {
         "windowCollector": "collector",

packages/cli/src/__tests__/bundle/bundler.test.ts

@@ -17,7 +17,7 @@ function createFlowSetup(
 ): Flow.Setup {
   return {
     version: 1,
-    environments: {
+    flows: {
       default: {
         ...(platform === 'web' ? { web: {} } : { server: {} }),
         packages,

packages/cli/src/__tests__/bundle/programmatic.test.ts

@@ -38,7 +38,7 @@ describe('Programmatic Bundle API', () => {
   it('should bundle with Flow.Setup config object', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -66,7 +66,7 @@ describe('Programmatic Bundle API', () => {
   it('should return stats when requested', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -87,7 +87,7 @@ describe('Programmatic Bundle API', () => {
   it('should return undefined when stats not requested', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -105,7 +105,7 @@ describe('Programmatic Bundle API', () => {
   it('should handle cache option', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -123,7 +123,7 @@ describe('Programmatic Bundle API', () => {
   it('should handle verbose option', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -146,10 +146,10 @@ describe('Programmatic Bundle API', () => {
     );
   });
 
-  it('should select environment from multi-env config', async () => {
+  it('should select flow from multi-flow config', async () => {
     const config: Flow.Setup = {
       version: 1,
-      environments: {
+      flows: {
         production: {
           web: {},
           packages: {
@@ -166,7 +166,7 @@ describe('Programmatic Bundle API', () => {
     };
 
     await expect(
-      bundle(config, { silent: true, environment: 'production' }),
+      bundle(config, { silent: true, flowName: 'production' }),
     ).resolves.not.toThrow();
   });
 

packages/cli/src/__tests__/cli.test.ts

@@ -51,7 +51,7 @@ describe('CLI Bundle Command', () => {
     // Flow.Setup format
     const testConfig = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -71,9 +71,9 @@ describe('CLI Bundle Command', () => {
     expect(output).toMatchObject({
       success: true,
       data: {
-        environments: expect.arrayContaining([
+        flows: expect.arrayContaining([
           {
-            environment: 'default',
+            flowName: 'default',
             success: true,
             stats: {
               totalSize: expect.any(Number),
@@ -92,8 +92,8 @@ describe('CLI Bundle Command', () => {
       duration: expect.any(Number),
     });
 
-    expect(output.data.environments[0].stats.packages).toHaveLength(1);
-    expect(output.data.environments[0].stats.packages[0].name).toBe(
+    expect(output.data.flows[0].stats.packages).toHaveLength(1);
+    expect(output.data.flows[0].stats.packages[0].name).toBe(
       '@walkeros/core@latest',
     );
   });
@@ -102,7 +102,7 @@ describe('CLI Bundle Command', () => {
     // Flow.Setup format - but bundler will fail on invalid destination code
     const testConfig = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -142,7 +142,7 @@ describe('CLI Bundle Command', () => {
     // Flow.Setup format
     const testConfig = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {
@@ -160,14 +160,14 @@ describe('CLI Bundle Command', () => {
 
     const output = JSON.parse(result.stdout);
     expect(output.success).toBe(true);
-    expect(output.data.environments[0].stats.treeshakingEffective).toBe(true);
+    expect(output.data.flows[0].stats.treeshakingEffective).toBe(true);
   });
 
   it('should suppress decorative output in JSON mode', async () => {
     // Flow.Setup format
     const testConfig = {
       version: 1,
-      environments: {
+      flows: {
         default: {
           web: {},
           packages: {