@walkeros/cli 0.0.0-next-20251219153324

package/CHANGELOG.md

@@ -0,0 +1,175 @@
+# @walkeros/cli
+
+## 0.0.0-next-20251219153324
+
+### Minor Changes
+
+- 42d06c8: CLI simplification - removed Docker mode for build commands, merged
+  runtime from @walkeros/docker into CLI, single walkeros/flow image for
+  production
+
+### Patch Changes
+
+- 71b615f: Fix URL handling in resolveAsset - URLs are now passed through
+  unchanged instead of being mangled into invalid filesystem paths
+- Updated dependencies [5163b01]
+  - @walkeros/core@0.0.0-next-20251219153324
+  - @walkeros/server-core@0.0.0-next-20251219153324
+
+## 0.7.0-next.0
+
+### Minor Changes
+
+- 42d06c8: Fix Docker runtime version display - versions now read reliably from
+  package.json at runtime instead of fragile build-time injection
+
+### Patch Changes
+
+- Updated dependencies [42d06c8]
+  - @walkeros/docker@0.7.0-next.0
+
+## 0.5.1-next.1
+
+### Patch Changes
+
+- 71b615f: Fix URL handling in resolveAsset - URLs are now passed through
+  unchanged instead of being mangled into invalid filesystem paths
+
+## 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
+
+- simulate server and local packages
+- cli cache
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @walkeros/core@0.4.2
+  - @walkeros/docker@0.2.2
+  - @walkeros/server-core@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- dev entry
+- Updated dependencies
+  - @walkeros/server-core@0.4.1
+  - @walkeros/docker@0.2.1
+  - @walkeros/core@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- Consolidate schemas and examples under `/dev` export
+
+### Patch Changes
+
+- Updated dependencies
+  - @walkeros/docker@0.2.0
+  - @walkeros/core@0.4.0
+
+## 0.3.6
+
+### Patch Changes
+
+- port path and name
+- df4b2a1: Read CLI version dynamically from package.json instead of hardcoded
+  value
+- Updated dependencies
+  - @walkeros/docker@0.1.5
+
+## 0.3.5
+
+### Patch Changes
+
+- cli usage
+- Updated dependencies
+  - @walkeros/docker@0.1.4
+
+## 0.3.4
+
+### Patch Changes
+
+- main module exec
+
+## 0.3.3
+
+### Patch Changes
+
+- force local
+
+## 0.3.2
+
+### Patch Changes
+
+- walkeros cli with docker
+- Updated dependencies
+  - @walkeros/docker@0.1.2
+
+## 0.3.1
+
+### Patch Changes
+
+- 25f7e10: Fix bundle command template path resolution to support relative paths
+
+  **CLI Changes:**
+  - Template paths starting with `./` or `../` in config files are now resolved
+    relative to the config file's directory
+  - Maintains backward compatibility for other relative paths (resolved from
+    cwd)
+  - Enables portable flow configs that reference templates next to them
+
+  **Docker Changes:**
+  - Updated demo.json and express-console.json to include template and output
+    fields
+  - Flow files can now be bundled standalone using the CLI bundle command
+  - Templates are referenced using `../templates/base.hbs` relative to flow file
+
+  **Example:**
+
+  ```bash
+  # Now works from any directory
+  node dist/index.mjs bundle -c packages/docker/flows/demo.json
+  ```
+
+- hello
+- Updated dependencies [25f7e10]
+- Updated dependencies
+- Updated dependencies
+  - @walkeros/docker@0.1.1
+  - @walkeros/core@0.3.1
+
+## 0.2.0
+
+### Minor Changes
+
+- env
+
+### Patch Changes
+
+- Updated dependencies
+  - @walkeros/core@0.2.0

package/README.md

@@ -0,0 +1,531 @@
+# @walkeros/cli
+
+Command-line tools for building, testing, and running walkerOS event collection
+flows.
+
+## What is this?
+
+The walkerOS CLI is a developer tool that:
+
+- **Bundles** flow configurations into optimized JavaScript
+- **Simulates** event processing for testing
+- **Runs** flows locally without Docker daemon
+
+Think of it as your development toolchain for walkerOS - from config to running
+production bundles.
+
+## Installation
+
+```bash
+# Global (recommended for CLI usage)
+npm install -g @walkeros/cli
+
+# Local (for programmatic usage)
+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":"product view"}'
+
+# Push real events to destinations
+walkeros push flow.json --event '{"name":"product view"}'
+
+# Run a collection server locally
+walkeros run collect dist/bundle.mjs --port 3000
+```
+
+## Commands
+
+### bundle
+
+Generate optimized JavaScript bundles from flow configurations.
+
+```bash
+walkeros bundle <config-file> [options]
+```
+
+Config files can be local paths or HTTP(S) URLs:
+
+```bash
+walkeros bundle ./config.json                                    # Local file
+walkeros bundle https://example.com/config.json                  # Remote URL
+```
+
+**Options:**
+
+- `-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
+- `-v, --verbose` - Verbose output
+
+**Example:**
+
+```bash
+# Bundle with stats
+walkeros bundle examples/server-collect.json --stats
+```
+
+The output path uses convention-based defaults: `./dist/bundle.mjs` for server,
+`./dist/walker.js` for web.
+
+### simulate
+
+Test event processing with simulated events.
+
+```bash
+walkeros simulate <config-file> --event '{"name":"page view"}' [options]
+```
+
+**Options:**
+
+- `-e, --event <json>` - Event JSON string (required)
+- `--json` - Output results as JSON
+- `-v, --verbose` - Verbose output
+
+**Example:**
+
+```bash
+# Simulate page view
+walkeros simulate \
+  examples/web-serve.json \
+  --event '{"name":"page view","data":{"title":"Home"}}' \
+  --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)
+
+**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 (no Docker daemon required).
+
+```bash
+walkeros run <mode> <config-file> [options]
+```
+
+**Modes:**
+
+- `collect` - HTTP event collection server
+- `serve` - Static file server
+
+**Options:**
+
+- `-p, --port <number>` - Server port
+- `-h, --host <host>` - Server host
+- `--static-dir <dir>` - Static directory (serve mode)
+- `--json` - JSON output
+- `-v, --verbose` - Verbose output
+
+**Examples:**
+
+```bash
+# Run collection server (auto-bundles JSON)
+walkeros run collect examples/server-collect.json --port 3000
+
+# Run with pre-built bundle
+walkeros run collect examples/server-collect.mjs --port 3000
+
+# Serve static files
+walkeros run serve flow.json --port 8080 --static-dir ./dist
+```
+
+**How it works:**
+
+1. JSON configs are auto-bundled to temp `.mjs`
+2. `.mjs` bundles are used directly
+3. Runs in current Node.js process
+4. Press Ctrl+C for graceful shutdown
+
+## Caching
+
+The CLI implements intelligent caching for faster builds:
+
+### Package Cache
+
+- NPM packages are cached in `.tmp/cache/packages/`
+- Mutable versions (`latest`, `^`, `~`) are re-checked daily
+- Exact versions (`0.4.1`) are cached indefinitely
+
+### Build Cache
+
+- Compiled bundles are cached in `.tmp/cache/builds/`
+- Cache key based on flow.json content + current date
+- Identical configs reuse cached build within the same day
+
+### Cache Management
+
+```bash
+# View cache info
+walkeros cache info
+
+# Clear all caches
+walkeros cache clear
+
+# Clear only package cache
+walkeros cache clear --packages
+
+# Clear only build cache
+walkeros cache clear --builds
+
+# Disable caching for a single build
+walkeros bundle flow.json --no-cache
+```
+
+## Flow Configuration
+
+Flow configs use the `Flow.Setup` format with `version` and `flows`:
+
+```json
+{
+  "version": 1,
+  "flows": {
+    "default": {
+      "server": {},
+      "packages": {
+        "@walkeros/collector": { "imports": ["startFlow"] },
+        "@walkeros/server-source-express": {},
+        "@walkeros/destination-demo": {}
+      },
+      "sources": {
+        "http": {
+          "package": "@walkeros/server-source-express",
+          "config": {
+            "settings": { "path": "/collect", "port": 8080 }
+          }
+        }
+      },
+      "destinations": {
+        "demo": {
+          "package": "@walkeros/destination-demo",
+          "config": {
+            "settings": { "name": "Demo" }
+          }
+        }
+      },
+      "collector": { "run": true }
+    }
+  }
+}
+```
+
+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
+packages:
+
+```json
+{
+  "packages": {
+    "@walkeros/collector": {
+      "path": "../packages/collector",
+      "imports": ["startFlow"]
+    },
+    "@my/custom-destination": {
+      "path": "./my-destination",
+      "imports": ["myDestination"]
+    }
+  }
+}
+```
+
+**Resolution rules:**
+
+- `path` takes precedence over `version`
+- Relative paths are resolved from the config file's directory
+- If `dist/` folder exists, it's used; otherwise package root is used
+
+**Dependency resolution:**
+
+When a local package has dependencies on other packages that are also specified
+with local paths, the CLI will use the local versions for those dependencies
+too. This prevents npm versions from overwriting your local packages.
+
+```json
+{
+  "packages": {
+    "@walkeros/core": {
+      "path": "../packages/core",
+      "imports": []
+    },
+    "@walkeros/collector": {
+      "path": "../packages/collector",
+      "imports": ["startFlow"]
+    }
+  }
+}
+```
+
+In this example, even though `@walkeros/collector` depends on `@walkeros/core`,
+the local version of core will be used (not downloaded from npm).
+
+See [examples/](./examples/) for complete working configurations.
+
+## Programmatic API
+
+Use commands programmatically:
+
+```typescript
+import { bundle, simulate, runCommand } from '@walkeros/cli';
+
+// Bundle
+await bundle({
+  config: './flow.json',
+  stats: true,
+});
+
+// Simulate
+const result = await simulate(
+  './flow.json',
+  { name: 'page view', data: { title: 'Test' } },
+  { json: true },
+);
+
+// Run
+await runCommand('collect', {
+  config: './flow.json',
+  port: 3000,
+  verbose: true,
+});
+```
+
+## Examples
+
+Working example configs in [examples/](./examples/):
+
+- **server-collect.json** - Basic server-side collection
+- **server-collection.json** - Advanced server setup
+- **web-serve.json** - Web demo with API destination
+- **web-tracking.json** - General web tracking
+
+Try them:
+
+```bash
+# Bundle example
+walkeros bundle examples/server-collect.json --stats
+
+# Simulate
+walkeros simulate \
+  examples/web-serve.json \
+  --event '{"name":"product view","data":{"id":"P123"}}'
+
+# Run server
+walkeros run collect examples/server-collect.json --port 3000
+```
+
+## Development Workflow
+
+Typical development cycle:
+
+```bash
+# 1. Create/edit config
+vim my-flow.json
+
+# 2. Test with simulation (no real API calls)
+walkeros simulate \
+  my-flow.json \
+  --event '{"name":"product view"}' \
+  --verbose
+
+# 3. Bundle and check stats
+walkeros bundle my-flow.json --stats
+
+# 4. Run locally
+walkeros run collect dist/bundle.mjs --port 3000
+
+# 5. In another terminal, test it
+curl -X POST http://localhost:3000/collect \
+  -H "Content-Type: application/json" \
+  -d '{"name":"page view","data":{"title":"Home"}}'
+```
+
+## Architecture
+
+```
+CLI (downloads packages + bundles with esbuild)
+ ├─ Bundle → optimized .mjs file
+ ├─ Simulate → test bundle with events
+ └─ Run → execute bundle with built-in runtime
+```
+
+**Key principle**: CLI handles both build-time and runtime operations.
+
+## Production Deployment
+
+Deploy your flows using Docker or Node.js.
+
+### Using Docker
+
+The `walkeros/flow` image runs pre-built bundles in production:
+
+```bash
+# Build your flow
+walkeros bundle flow.json
+
+# Run with Docker
+docker run -v ./dist:/flow -p 8080:8080 walkeros/flow
+```
+
+**Custom image:**
+
+```dockerfile
+FROM walkeros/flow
+COPY dist/bundle.mjs /flow/
+```
+
+**Environment variables:**
+
+- `MODE` - `collect` or `serve` (default: `collect`)
+- `PORT` - Server port (default: `8080`)
+- `FILE` - Bundle path (default: `/flow/bundle.mjs`)
+
+### Using Node.js
+
+Run the bundle directly with the CLI:
+
+```bash
+# Build your flow
+walkeros bundle flow.json
+
+# Run in production
+walkeros run collect dist/bundle.mjs --port 8080
+```
+
+This runs the flow in the current Node.js process, suitable for deployment on
+platforms like AWS Lambda, Google Cloud Run, or any Node.js hosting.
+
+## Requirements
+
+- **Node.js**: 18+ or 22+
+- **Docker**: Not required for CLI (only for production deployment)
+
+## Type Definitions
+
+See [src/types.ts](./src/types.ts) for TypeScript interfaces.
+
+## Related
+
+- [Website Documentation](https://www.walkeros.io/docs/cli/)
+- [Flow Configuration](https://www.walkeros.io/docs/getting-started/flow/)
+
+## License
+
+MIT © elbwalker

package/dist/__tests__/bundle/bundler-helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundler-helpers.test.d.ts.map

package/dist/__tests__/bundle/bundler-helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler-helpers.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/bundle/bundler-helpers.test.ts"],"names":[],"mappings":""}