@walkeros/cli 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# @walkeros/cli
+
+## 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,285 @@
+# @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
+```
+
+## Commands
+
+### bundle
+
+Generate optimized JavaScript bundles from flow configurations.
+
+```bash
+walkeros bundle --config flow.json [options]
+```
+
+**Options:**
+
+- `-c, --config <path>` - Flow configuration file (required)
+- `-e, --env <name>` - Build specific environment (multi-env configs)
+- `--all` - Build all environments
+- `-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 --config examples/server-collect.json --stats
+```
+
+The output path is specified in the config's `build.output` field.
+
+### simulate
+
+Test event processing with simulated events.
+
+```bash
+walkeros simulate --config flow.json --event '{"name":"page view"}' [options]
+```
+
+**Options:**
+
+- `-c, --config <path>` - Bundle configuration file (required)
+- `-e, --event <json>` - Event JSON string (required)
+- `--json` - Output results as JSON
+- `-v, --verbose` - Verbose output
+
+**Example:**
+
+```bash
+# Simulate page view
+walkeros simulate \
+  --config examples/web-serve.json \
+  --event '{"name":"page view","data":{"title":"Home"}}' \
+  --json
+```
+
+### run
+
+Run flows locally using @walkeros/docker as a library (no Docker daemon
+required).
+
+```bash
+walkeros run <mode> --config <path> [options]
+```
+
+**Modes:**
+
+- `collect` - HTTP event collection server
+- `serve` - Static file server
+
+**Options:**
+
+- `-c, --config <path>` - Flow config (.json) or bundle (.mjs)
+- `-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 --config examples/server-collect.json --port 3000
+
+# Run with pre-built bundle
+walkeros run collect --config examples/server-collect.mjs --port 3000
+
+# Serve static files
+walkeros run serve --config flow.json --port 8080 --static-dir ./dist
+```
+
+**How it works:**
+
+1. JSON configs are bundled to temp `.mjs` automatically
+2. `.mjs` bundles are used directly
+3. Runs in current Node.js process (no containers)
+4. Press Ctrl+C for graceful shutdown
+
+## Flow Configuration
+
+Minimal example:
+
+```json
+{
+  "flow": {
+    "platform": "server",
+    "sources": {
+      "http": {
+        "code": "sourceExpress",
+        "config": {
+          "settings": {
+            "path": "/collect",
+            "port": 8080
+          }
+        }
+      }
+    },
+    "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"
+  }
+}
+```
+
+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 --config examples/server-collect.json --stats
+
+# Simulate
+walkeros simulate \
+  --config examples/web-serve.json \
+  --event '{"name":"product view","data":{"id":"P123"}}'
+
+# Run server
+walkeros run collect --config examples/server-collect.json --port 3000
+```
+
+## Development Workflow
+
+Typical development cycle:
+
+```bash
+# 1. Create/edit config
+vim my-flow.json
+
+# 2. Bundle and check stats
+walkeros bundle --config my-flow.json --stats
+
+# 3. Test with simulation
+walkeros simulate \
+  --config my-flow.json \
+  --event '{"name":"test event"}' \
+  --verbose
+
+# 4. Run locally
+walkeros run collect --config my-flow.json --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 → import @walkeros/docker + execute bundle
+```
+
+**Key principle**: CLI handles build-time, Docker handles runtime.
+
+## Requirements
+
+- **Node.js**: 18+ or 22+
+- **Docker**: Not required for CLI (only for production deployment)
+
+## Documentation
+
+Detailed guides in [docs/](./docs/):
+
+- [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
+
+## License
+
+MIT © elbwalker

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

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

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

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

package/dist/__tests__/bundle/bundler-integration.test.js

@@ -0,0 +1,106 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { parseBundleConfig } from '../../config';
+import { createLogger } from '../../core';
+import { getId } from '@walkeros/core';
+describe('Bundler Integration', () => {
+    const testOutputDir = path.resolve('.tmp', `bundler-integration-${Date.now()}-${getId()}`);
+    let logger;
+    beforeEach(async () => {
+        // Ensure test output directory exists
+        await fs.ensureDir(testOutputDir);
+        // Create a silent logger for tests
+        logger = createLogger({ silent: true });
+        // Mock console.log to suppress output during tests
+        jest.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(async () => {
+        // Clean up test output
+        await fs.remove(testOutputDir);
+        // Restore console.log
+        jest.restoreAllMocks();
+    });
+    it('should handle configuration parsing correctly', async () => {
+        const rawConfig = {
+            flow: {
+                platform: 'web',
+            },
+            build: {
+                packages: {
+                    '@walkeros/core': {
+                        imports: ['getId'],
+                    },
+                },
+                code: 'export const test = getId(8);',
+                platform: 'browser',
+                format: 'esm',
+                output: path.join(testOutputDir, 'test-config.js'),
+            },
+        };
+        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
+        expect(Object.keys(buildOptions.packages)).toHaveLength(1);
+        expect('@walkeros/core' in buildOptions.packages).toBe(true);
+        expect(buildOptions.code).toContain('getId');
+        expect(buildOptions.platform).toBe('browser');
+        expect(buildOptions.output).toBe(path.join(testOutputDir, 'test-config.js'));
+    });
+    it('should handle template configuration', async () => {
+        const rawConfig = {
+            flow: {
+                platform: 'web',
+            },
+            build: {
+                packages: {
+                    '@walkeros/core': {
+                        imports: ['getId'],
+                    },
+                },
+                code: 'export const test = getId(8);',
+                template: 'templates/web.hbs',
+                output: path.join(testOutputDir, 'template-test.js'),
+            },
+        };
+        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
+        expect(buildOptions.template).toBeDefined();
+        expect(buildOptions.template).toBe('templates/web.hbs');
+    });
+    it('should validate custom build configuration', async () => {
+        const rawConfig = {
+            flow: {
+                platform: 'server',
+            },
+            build: {
+                packages: {},
+                code: 'export const test = "hello";',
+                platform: 'node',
+                format: 'esm',
+                minify: true,
+                sourcemap: true,
+                target: 'node18',
+                output: path.join(testOutputDir, 'build-test.mjs'),
+            },
+        };
+        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
+        expect(buildOptions.platform).toBe('node');
+        expect(buildOptions.format).toBe('esm');
+        expect(buildOptions.minify).toBe(true);
+        expect(buildOptions.sourcemap).toBe(true);
+        expect(buildOptions.target).toBe('node18');
+    });
+    it('should handle error conditions gracefully', async () => {
+        // Test with invalid syntax in content
+        const { flowConfig, buildOptions } = parseBundleConfig({
+            flow: {
+                platform: 'web',
+            },
+            build: {
+                packages: {},
+                code: 'export const badCode = () => { return [1,2,3] x => x * 2; };',
+                output: path.join(testOutputDir, 'error-test.js'),
+            },
+        });
+        // Should not throw during configuration parsing
+        expect(buildOptions.code).toContain('badCode');
+    });
+});
+//# sourceMappingURL=bundler-integration.test.js.map

package/dist/__tests__/bundle/bundler-integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler-integration.test.js","sourceRoot":"","sources":["../../../src/__tests__/bundle/bundler-integration.test.ts"],"names":[],"mappings":"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"}

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

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

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

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