@walkeros/cli 0.4.2 → 0.5.1-next.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @walkeros/cli
 
+## 0.5.1-next.0
+
+### Patch Changes
+
+- Updated dependencies [5163b01]
+  - @walkeros/core@0.5.1-next.0
+  - @walkeros/docker@0.3.1-next.0
+  - @walkeros/server-core@0.5.1-next.0
+
+## 0.5.0
+
+### Minor Changes
+
+- just flow
+
+### Patch Changes
+
+- Updated dependencies
+  - @walkeros/core@0.5.0
+  - @walkeros/docker@0.3.0
+  - @walkeros/server-core@0.5.0
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -24,6 +24,22 @@ npm install -g @walkeros/cli
 npm install @walkeros/cli
 ```
 
+## Quick Start
+
+```bash
+# Bundle a flow configuration
+walkeros bundle flow.json
+
+# Test with simulated events (no real API calls)
+walkeros simulate flow.json --event '{"name":"page view"}'
+
+# Push real events to destinations
+walkeros push flow.json --event '{"name":"page view"}'
+
+# Run a collection server locally
+walkeros run collect flow.json --port 3000
+```
+
 ## Commands
 
 ### bundle
@@ -86,6 +102,49 @@ walkeros simulate \
   --json
 ```
 
+### push
+
+Execute your flow with real API calls to configured destinations. Unlike
+`simulate` which mocks API calls, `push` performs actual HTTP requests.
+
+```bash
+walkeros push <config-file> --event '<json>' [options]
+```
+
+**Options:**
+
+- `-e, --event <source>` - Event to push (JSON string, file path, or URL)
+  **Required**
+- `--flow <name>` - Flow name (for multi-flow configs)
+- `--json` - Output results as JSON
+- `-v, --verbose` - Verbose output
+- `-s, --silent` - Suppress output (for CI/CD)
+- `--local` - Execute locally without Docker
+
+**Event input formats:**
+
+```bash
+# Inline JSON
+walkeros push flow.json --event '{"name":"page view","data":{"title":"Home"}}'
+
+# File path
+walkeros push flow.json --event ./events/order.json
+
+# URL
+walkeros push flow.json --event https://example.com/sample-event.json
+```
+
+**Push vs Simulate:**
+
+| 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               |
+
+Use `simulate` first to validate configuration safely, then `push` to verify
+real integrations.
+
 ### run
 
 Run flows locally using @walkeros/docker as a library (no Docker daemon
@@ -176,12 +235,12 @@ Flow configs use the `Flow.Setup` format with `version` and `flows`:
       "server": {},
       "packages": {
         "@walkeros/collector": { "imports": ["startFlow"] },
-        "@walkeros/server-source-express": { "imports": ["sourceExpress"] },
-        "@walkeros/destination-demo": { "imports": ["destinationDemo"] }
+        "@walkeros/server-source-express": {},
+        "@walkeros/destination-demo": {}
       },
       "sources": {
         "http": {
-          "code": "sourceExpress",
+          "package": "@walkeros/server-source-express",
           "config": {
             "settings": { "path": "/collect", "port": 8080 }
           }
@@ -189,7 +248,7 @@ Flow configs use the `Flow.Setup` format with `version` and `flows`:
       },
       "destinations": {
         "demo": {
-          "code": "destinationDemo",
+          "package": "@walkeros/destination-demo",
           "config": {
             "settings": { "name": "Demo" }
           }
@@ -203,6 +262,76 @@ Flow configs use the `Flow.Setup` format with `version` and `flows`:
 
 Platform is determined by the `web: {}` or `server: {}` key presence.
 
+### Package Configuration Patterns
+
+The CLI automatically resolves imports based on how you configure packages:
+
+**1. Default exports (recommended for single-export packages):**
+
+```json
+{
+  "packages": {
+    "@walkeros/server-destination-api": {}
+  },
+  "destinations": {
+    "api": {
+      "package": "@walkeros/server-destination-api"
+    }
+  }
+}
+```
+
+The CLI generates:
+`import _walkerosServerDestinationApi from '@walkeros/server-destination-api';`
+
+**2. Named exports (for multi-export packages):**
+
+```json
+{
+  "packages": {
+    "@walkeros/server-destination-gcp": {}
+  },
+  "destinations": {
+    "bigquery": {
+      "package": "@walkeros/server-destination-gcp",
+      "code": "destinationBigQuery"
+    },
+    "analytics": {
+      "package": "@walkeros/server-destination-gcp",
+      "code": "destinationAnalytics"
+    }
+  }
+}
+```
+
+The CLI generates:
+`import { destinationBigQuery, destinationAnalytics } from '@walkeros/server-destination-gcp';`
+
+**3. Utility imports (for helper functions):**
+
+```json
+{
+  "packages": {
+    "lodash": { "imports": ["get", "set"] }
+  },
+  "mappings": {
+    "custom": {
+      "data": "({ data }) => get(data, 'user.email')"
+    }
+  }
+}
+```
+
+The CLI generates: `import { get, set } from 'lodash';`
+
+**Key points:**
+
+- Omit `packages.imports` for destinations/sources - the default export is used
+  automatically
+- Only specify `code` when using a specific named export from a multi-export
+  package
+- Use `packages.imports` only for utilities needed in mappings or custom code
+
 ### Local Packages
 
 Use local packages instead of npm for development or testing unpublished
@@ -364,13 +493,15 @@ walkeros bundle config.json
 - **Node.js**: 18+ or 22+
 - **Docker**: Not required for CLI (only for production deployment)
 
-## Documentation
+## Type Definitions
+
+See [src/types.ts](./src/types.ts) for TypeScript interfaces.
 
-Detailed guides in [docs/](./docs/):
+## Related
 
-- [RUN_COMMAND.md](./docs/RUN_COMMAND.md) - Run command details
-- [PUBLISHING.md](./docs/PUBLISHING.md) - Publishing guide
-- [MANUAL_TESTING_GUIDE.md](./docs/MANUAL_TESTING_GUIDE.md) - Testing guide
+- [Website Documentation](https://www.walkeros.io/docs/cli/)
+- [Flow Configuration](https://www.walkeros.io/docs/getting-started/flow/)
+- [Docker Package](../docker/) - Production runtime
 
 ## License
 

package/dist/examples/README.md

@@ -1,5 +1,17 @@
 # walkerOS Flow Examples
 
+## Installation
+
+These are example configurations - see the main [CLI README](../README.md) for
+installation.
+
+## Usage
+
+Use `walkeros bundle <example>.json` to build any example, then `walkeros run`
+to execute.
+
+---
+
 This directory contains example flow configurations demonstrating various
 walkerOS use cases.
 
@@ -340,4 +352,4 @@ The event name is parsed as: `const [entity, action] = event.split(' ')`
 1. Try each example with `walkeros bundle` and `walkeros simulate`
 2. Modify examples to match your tracking requirements
 3. Create custom flow files for your use case
-4. Deploy to production (see [PUBLISHING.md](../docs/PUBLISHING.md))
+4. Deploy to production

package/dist/examples/flow-order-complete.json

@@ -9,8 +9,7 @@
           "imports": ["startFlow"]
         },
         "@walkeros/destination-demo": {
-          "version": "latest",
-          "imports": ["destinationDemo"]
+          "version": "latest"
         }
       },
       "destinations": {

package/dist/examples/flow-simple.json

@@ -9,8 +9,7 @@
           "imports": ["startFlow"]
         },
         "@walkeros/destination-demo": {
-          "version": "latest",
-          "imports": ["destinationDemo"]
+          "version": "latest"
         }
       },
       "destinations": {

package/dist/examples/server-collect.json

@@ -9,17 +9,16 @@
           "imports": ["startFlow"]
         },
         "@walkeros/server-source-express": {
-          "version": "latest",
-          "imports": ["sourceExpress"]
+          "version": "latest"
         },
         "@walkeros/destination-demo": {
-          "version": "latest",
-          "imports": ["destinationDemo"]
+          "version": "latest"
         }
       },
       "sources": {
         "http": {
           "package": "@walkeros/server-source-express",
+          "code": "sourceExpress",
           "config": {
             "settings": {
               "path": "/collect",
@@ -33,6 +32,7 @@
       "destinations": {
         "demo": {
           "package": "@walkeros/destination-demo",
+          "code": "destinationDemo",
           "config": {
             "settings": {
               "name": "Server Collection Demo",

package/dist/index.d.ts

@@ -33,11 +33,6 @@ interface CLIBuildOptions extends Pick<BuildOptions$1, 'external'> {
      * @default ".tmp"
      */
     tempDir?: string;
-    /**
-     * Custom template file path.
-     * @default undefined (uses platform-specific default)
-     */
-    template?: string;
     /**
      * Enable package caching.
      * @default true
@@ -422,112 +417,4 @@ declare function runCommand(mode: string, options: RunCommandOptions): Promise<v
  */
 declare function run(mode: RunMode, options: RunOptions): Promise<RunResult>;
 
-/**
- * Template Configuration Types
- *
- * Type definitions for template processing and serialization.
- * Used by the template engine and serializer.
- *
- * @packageDocumentation
- */
-/**
- * Source or Destination configuration item for templates.
- *
- * @remarks
- * This type is used in template processing where config objects
- * are serialized to JavaScript code.
- */
-interface SourceDestinationItem {
-    /**
-     * JavaScript code reference (variable name or expression)
-     */
-    code: string;
-    /**
-     * Configuration object for the source/destination
-     */
-    config?: unknown;
-    /**
-     * Environment-specific variables
-     */
-    env?: unknown;
-    /**
-     * Allow additional properties for extensibility
-     */
-    [key: string]: unknown;
-}
-/**
- * Template variables that can be used in Handlebars templates.
- *
- * @remarks
- * These variables are available in template files for customization.
- */
-interface TemplateVariables {
-    /**
-     * Serialized sources configuration
-     */
-    sources: string;
-    /**
-     * Serialized destinations configuration
-     */
-    destinations: string;
-    /**
-     * Serialized collector configuration
-     */
-    collector: string;
-    /**
-     * User-provided code to be inserted
-     */
-    CODE: string;
-    /**
-     * Build configuration (optional)
-     */
-    build?: Record<string, unknown>;
-}
-/**
- * Processed template variables after serialization.
- *
- * @remarks
- * Internal type used by the serializer to represent processed configs.
- */
-interface ProcessedTemplateVariables {
-    /**
-     * Processed sources with serialized configs
-     */
-    sources?: Record<string, TemplateSource>;
-    /**
-     * Processed destinations with serialized configs
-     */
-    destinations?: Record<string, TemplateDestination>;
-    /**
-     * Processed collector configuration
-     */
-    collector?: Record<string, unknown> | string;
-    /**
-     * Allow additional properties
-     */
-    [key: string]: unknown;
-}
-/**
- * Template source after processing.
- *
- * @internal
- */
-interface TemplateSource {
-    code: string;
-    config?: unknown | string;
-    env?: unknown;
-    [key: string]: unknown;
-}
-/**
- * Template destination after processing.
- *
- * @internal
- */
-interface TemplateDestination {
-    code: string;
-    config?: unknown | string;
-    env?: unknown;
-    [key: string]: unknown;
-}
-
-export { type BuildOptions, type BundleStats, type CLIBuildOptions, type GlobalOptions, type MinifyOptions, type ProcessedTemplateVariables, type RunCommandOptions, type RunMode, type RunOptions, type RunResult, type SimulationResult, type SourceDestinationItem, type TemplateDestination, type TemplateSource, type TemplateVariables, bundle, bundleCommand, pushCommand, run, runCommand, simulate, simulateCommand };
+export { type BuildOptions, type BundleStats, type CLIBuildOptions, type GlobalOptions, type MinifyOptions, type RunCommandOptions, type RunMode, type RunOptions, type RunResult, type SimulationResult, bundle, bundleCommand, pushCommand, run, runCommand, simulate, simulateCommand };