@walkeros/cli 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @walkeros/cli
 
+## 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

package/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
 
@@ -128,61 +129,130 @@ walkeros run serve flow.json --port 8080 --static-dir ./dist
 3. Runs in current Node.js process (no containers)
 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
 
-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 }
+    }
+  }
+}
+```
+
+Platform is determined by the `web: {}` or `server: {}` key presence.
+
+### Local Packages
+
+Use local packages instead of npm for development or testing unpublished
+packages:
+
+```json
+{
+  "packages": {
+    "@walkeros/collector": {
+      "path": "../packages/collector",
+      "imports": ["startFlow"]
     },
-    "collector": {
-      "run": true
+    "@my/custom-destination": {
+      "path": "./my-destination",
+      "imports": ["myDestination"]
     }
-  },
-  "build": {
-    "packages": {
-      "@walkeros/collector": {
-        "version": "latest",
-        "imports": ["startFlow"]
-      },
-      "@walkeros/server-source-express": {
-        "version": "latest",
-        "imports": ["sourceExpress"]
-      },
-      "@walkeros/destination-demo": {
-        "version": "latest",
-        "imports": ["destinationDemo"]
-      }
+  }
+}
+```
+
+**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": []
     },
-    "code": "// Custom code here\n",
-    "output": "bundle.mjs",
-    "template": "./templates/base.hbs"
+    "@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

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

@@ -1,16 +1,50 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { bundleCore as bundle } from '../../commands/bundle/bundler.js';
-import { parseBundleConfig } from '../../config/index.js';
+import { loadBundleConfig } from '../../config/index.js';
 import { createLogger } from '../../core/index.js';
 import { getId } from '@walkeros/core';
 // No mocks - test with real package downloads and bundling
+/**
+ * Helper to create a Flow.Setup config for testing.
+ */
+function createFlowSetup(platform, packages) {
+    return {
+        version: 1,
+        flows: {
+            default: {
+                ...(platform === 'web' ? { web: {} } : { server: {} }),
+                packages,
+            },
+        },
+    };
+}
+/**
+ * Helper to create build options for testing.
+ * Uses minimal defaults with test-specific overrides.
+ */
+function createBuildOptions(overrides) {
+    return {
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2020',
+        minify: false,
+        sourcemap: false,
+        cache: true,
+        tempDir: '.tmp',
+        packages: {},
+        code: '',
+        ...overrides,
+    };
+}
 describe('Bundler', () => {
     const testOutputDir = path.resolve('.tmp', `bundler-${Date.now()}-${getId()}`);
     let logger;
     beforeEach(async () => {
         // Ensure test output directory exists
         await fs.ensureDir(testOutputDir);
+        // Clean build cache to ensure each test starts fresh
+        await fs.remove(path.join('.tmp', 'cache', 'builds'));
         // Create a silent logger for tests
         logger = createLogger({ silent: true });
         // Mock console.log to suppress output during tests
@@ -32,96 +66,82 @@ describe('Bundler', () => {
         jest.restoreAllMocks();
     });
     it('should bundle minimal config successfully', async () => {
-        // Inline minimal configuration to avoid path dependencies
-        const rawConfig = {
-            flow: {
-                platform: 'web',
-            },
-            build: {
-                packages: {
-                    '@walkeros/core': {
-                        imports: ['getId'],
-                    },
+        const flowConfig = {
+            web: {},
+            packages: {
+                '@walkeros/core': {
+                    imports: ['getId'],
                 },
-                code: 'export const test = getId(8);',
-                template: '', // Explicitly disable template for raw code bundling
-                platform: 'browser',
-                format: 'esm',
-                output: path.join(testOutputDir, 'minimal.js'),
             },
         };
-        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
-        // Run bundler with real dependencies
+        const buildOptions = createBuildOptions({
+            packages: flowConfig.packages || {},
+            code: 'export const test = getId(8);',
+            template: '',
+            platform: 'browser',
+            format: 'esm',
+            output: path.join(testOutputDir, 'minimal.js'),
+        });
         await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
     });
     it('should bundle server config with ESM format', async () => {
-        // Inline server configuration
-        const rawConfig = {
-            flow: {
-                platform: 'server',
-            },
-            build: {
-                packages: {
-                    '@walkeros/core': {
-                        imports: ['trim', 'isString'],
-                    },
+        const flowConfig = {
+            server: {},
+            packages: {
+                '@walkeros/core': {
+                    imports: ['trim', 'isString'],
                 },
-                code: 'export default { processText: (text) => trim(text) };',
-                template: '', // Explicitly disable template for raw code bundling
-                platform: 'node',
-                format: 'esm',
-                output: path.join(testOutputDir, 'server-bundle.mjs'),
             },
         };
-        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
-        // Run bundler with real dependencies
+        const buildOptions = createBuildOptions({
+            packages: flowConfig.packages || {},
+            code: 'export default { processText: (text) => trim(text) };',
+            template: '',
+            platform: 'node',
+            format: 'esm',
+            output: path.join(testOutputDir, 'server-bundle.mjs'),
+        });
         await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
     });
     it('should bundle advanced config with minification', async () => {
-        // Inline advanced configuration
-        const rawConfig = {
-            flow: {
-                platform: 'web',
-            },
-            build: {
-                packages: {
-                    '@walkeros/core': {
-                        imports: ['getId', 'getByPath', 'clone', 'trim', 'isObject'],
-                    },
+        const flowConfig = {
+            web: {},
+            packages: {
+                '@walkeros/core': {
+                    imports: ['getId', 'getByPath', 'clone', 'trim', 'isObject'],
                 },
-                code: "export function processData(data) {\n  return data.map(item => ({\n    ...item,\n    id: getId(8),\n    timestamp: new Date().toISOString().split('T')[0],\n    processed: true\n  }));\n}\n\nexport function extractNestedValues(data, path) {\n  return data.map(item => getByPath(item, path, null)).filter(val => val !== null);\n}\n\nexport function deepCloneData(data) {\n  return clone(data);\n}\n\nexport function cleanStringData(data) {\n  return data.map(item => ({\n    ...item,\n    name: typeof item.name === 'string' ? trim(item.name) : item.name\n  }));\n}\n\n// Re-export walkerOS utilities\nexport { getId, getByPath, clone, trim, isObject };",
-                template: '', // Explicitly disable template for raw code bundling
-                platform: 'browser',
-                format: 'esm',
-                target: 'es2020',
-                minify: true,
-                sourcemap: true,
-                output: path.join(testOutputDir, 'advanced-bundle.js'),
             },
         };
-        const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
-        // Run bundler with real dependencies
+        const buildOptions = createBuildOptions({
+            packages: flowConfig.packages || {},
+            code: "export function processData(data) {\n  return data.map(item => ({\n    ...item,\n    id: getId(8),\n    timestamp: new Date().toISOString().split('T')[0],\n    processed: true\n  }));\n}\n\nexport function extractNestedValues(data, path) {\n  return data.map(item => getByPath(item, path, null)).filter(val => val !== null);\n}\n\nexport function deepCloneData(data) {\n  return clone(data);\n}\n\nexport function cleanStringData(data) {\n  return data.map(item => ({\n    ...item,\n    name: typeof item.name === 'string' ? trim(item.name) : item.name\n  }));\n}\n\n// Re-export walkerOS utilities\nexport { getId, getByPath, clone, trim, isObject };",
+            template: '',
+            platform: 'browser',
+            format: 'esm',
+            target: 'es2020',
+            minify: true,
+            sourcemap: true,
+            output: path.join(testOutputDir, 'advanced-bundle.js'),
+        });
         await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
     });
     describe('Stats Collection', () => {
         it('should collect bundle stats when requested', async () => {
-            const rawConfig = {
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': {
-                            imports: ['getId'],
-                        },
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': {
+                        imports: ['getId'],
                     },
-                    code: 'export const test = getId(8);',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    output: path.join(testOutputDir, 'stats-test.js'),
                 },
             };
-            const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const test = getId(8);',
+                template: '',
+                format: 'esm',
+                output: path.join(testOutputDir, 'stats-test.js'),
+            });
             const stats = await bundle(flowConfig, buildOptions, logger, true);
             expect(stats).toBeDefined();
             expect(stats.totalSize).toBe(1024); // From mocked fs.stat
@@ -131,39 +151,36 @@ describe('Bundler', () => {
             expect(stats.packages[0].name).toBe('@walkeros/core@latest');
         });
         it('should detect ineffective tree-shaking with wildcard imports', async () => {
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: { '@walkeros/core': {} },
-                    code: 'import * as walkerCore from "@walkeros/core";\nexport const test = walkerCore.getId;',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    output: path.join(testOutputDir, 'test.js'),
-                },
+            const flowConfig = {
+                web: {},
+                packages: { '@walkeros/core': {} },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'import * as walkerCore from "@walkeros/core";\nexport const test = walkerCore.getId;',
+                template: '',
+                format: 'esm',
+                output: path.join(testOutputDir, 'test.js'),
             });
             const stats = await bundle(flowConfig, buildOptions, logger, true);
             expect(stats.treeshakingEffective).toBe(false);
         });
         it('should return undefined when stats not requested', async () => {
-            const rawConfig = {
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': {
-                            imports: ['getId'],
-                        },
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': {
+                        imports: ['getId'],
                     },
-                    code: 'export const test = getId(8);',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    output: path.join(testOutputDir, 'no-stats.js'),
                 },
             };
-            const { flowConfig, buildOptions } = parseBundleConfig(rawConfig);
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const test = getId(8);',
+                template: '',
+                format: 'esm',
+                output: path.join(testOutputDir, 'no-stats.js'),
+            });
             const result = await bundle(flowConfig, buildOptions, logger, false);
             expect(result).toBeUndefined();
         });
@@ -173,110 +190,103 @@ describe('Bundler', () => {
             // Create a test template file
             const templatePath = path.join(testOutputDir, 'test.hbs');
             await fs.writeFile(templatePath, '{{{CODE}}}\n// Template footer');
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': { imports: ['getId'] },
-                    },
-                    code: 'export const generateId = () => getId(8);',
-                    template: templatePath,
-                    output: path.join(testOutputDir, 'template-test.js'),
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': { imports: ['getId'] },
                 },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const generateId = () => getId(8);',
+                template: templatePath,
+                output: path.join(testOutputDir, 'template-test.js'),
             });
             await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
         });
         it('should handle missing template variables gracefully', async () => {
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': { imports: ['trim'] },
-                    },
-                    code: 'export const test = trim("hello");',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    output: path.join(testOutputDir, 'missing-vars.js'),
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': { imports: ['trim'] },
                 },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const test = trim("hello");',
+                template: '',
+                format: 'esm',
+                output: path.join(testOutputDir, 'missing-vars.js'),
             });
             await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
         });
         it('should append bundle code when placeholder not found', async () => {
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': { imports: ['getId'] },
-                    },
-                    code: 'export const test = getId(6);',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    output: path.join(testOutputDir, 'append-test.js'),
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': { imports: ['getId'] },
                 },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const test = getId(6);',
+                template: '',
+                format: 'esm',
+                output: path.join(testOutputDir, 'append-test.js'),
             });
             await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
         });
     });
     describe('Configuration Scenarios', () => {
         it('should handle custom temp directory configuration', async () => {
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': { imports: ['getId'] },
-                    },
-                    code: 'export const test = getId();',
-                    template: '', // Explicitly disable template for raw code bundling
-                    format: 'esm',
-                    tempDir: '/tmp/my-custom-bundler-temp',
-                    output: path.join(testOutputDir, 'custom-temp-example.js'),
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': { imports: ['getId'] },
                 },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: 'export const test = getId();',
+                template: '',
+                format: 'esm',
+                tempDir: '/tmp/my-custom-bundler-temp',
+                output: path.join(testOutputDir, 'custom-temp-example.js'),
             });
             await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
         });
         it('should handle version pinning correctly', async () => {
-            const { flowConfig, buildOptions } = parseBundleConfig({
-                flow: {
-                    platform: 'web',
-                },
-                build: {
-                    packages: {
-                        '@walkeros/core': { version: '0.0.7', imports: ['getId'] },
-                    },
-                    code: '// Test version pinning\nexport const test = getId();',
-                    template: '', // Explicitly disable template for raw code bundling
-                    platform: 'browser',
-                    format: 'esm',
-                    target: 'es2020',
-                    output: path.join(testOutputDir, 'version-test.js'),
+            const flowConfig = {
+                web: {},
+                packages: {
+                    '@walkeros/core': { version: '0.0.7', imports: ['getId'] },
                 },
+            };
+            const buildOptions = createBuildOptions({
+                packages: flowConfig.packages || {},
+                code: '// Test version pinning\nexport const test = getId();',
+                template: '',
+                platform: 'browser',
+                format: 'esm',
+                target: 'es2020',
+                output: path.join(testOutputDir, 'version-test.js'),
             });
             await expect(bundle(flowConfig, buildOptions, logger)).resolves.not.toThrow();
         });
     });
     describe('Error Handling', () => {
-        it('should validate configuration properly', async () => {
-            // Test configuration validation instead of runtime errors
+        it('should reject invalid config structure', async () => {
+            // Test that loader rejects invalid config structure
             expect(() => {
-                parseBundleConfig({
+                loadBundleConfig({
                     flow: {
                         platform: 'web',
                     },
                     build: {
-                        packages: 'invalid', // should be object
-                        code: 'test',
-                        output: path.join(testOutputDir, 'test.js'),
+                        packages: {},
                     },
-                });
-            }).toThrow();
+                }, { configPath: '/test/config.json' });
+            }).toThrow(/Invalid configuration/);
         });
     });
 });