@walkeros/cli 0.0.0-next-20251219153324

package/dist/config/utils.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Configuration Utility Functions
+ */
+/**
+ * Check if a string is a valid URL
+ *
+ * @param str - String to check
+ * @returns True if string is a valid HTTP/HTTPS URL
+ */
+export declare function isUrl(str: string): boolean;
+/**
+ * Download a file from a URL to a temporary location
+ *
+ * @param url - HTTP/HTTPS URL to download
+ * @returns Path to downloaded temporary file
+ * @throws Error if download fails or response is not OK
+ *
+ * @example
+ * ```typescript
+ * const tempPath = await downloadFromUrl('https://example.com/config.json')
+ * // Returns: "/tmp/walkeros-download-1647261462000-abc123.json"
+ * ```
+ */
+export declare function downloadFromUrl(url: string): Promise<string>;
+/**
+ * Substitute environment variables in a string.
+ *
+ * @param value - String with ${VAR} placeholders
+ * @returns String with environment variables substituted
+ * @throws Error if environment variable is not found
+ *
+ * @example
+ * ```typescript
+ * substituteEnvVariables('${HOME}/config') // "/Users/name/config"
+ * ```
+ */
+export declare function substituteEnvVariables(value: string): string;
+/**
+ * Load and parse JSON configuration file from local path or URL.
+ *
+ * @param configPath - Path to JSON file or HTTP/HTTPS URL
+ * @returns Parsed configuration object and cleanup function
+ * @throws Error if file not found, download fails, or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * // Local file
+ * const config = await loadJsonConfig('./config.json')
+ *
+ * // Remote URL
+ * const config = await loadJsonConfig('https://example.com/config.json')
+ * ```
+ */
+export declare function loadJsonConfig<T>(configPath: string): Promise<T>;
+/**
+ * Load JSON from inline string, file path, or URL.
+ *
+ * Supports three input formats:
+ * 1. Inline JSON string - parsed directly
+ * 2. Local file path - read and parsed
+ * 3. HTTP/HTTPS URL - downloaded and parsed
+ *
+ * Detection priority:
+ * 1. URL (http://, https://) → download and parse
+ * 2. Existing file path → read and parse
+ * 3. Valid JSON string → parse directly
+ * 4. Simple string → treat as {name: string} for backward compatibility
+ *
+ * @param source - JSON string, file path, or URL
+ * @param options - Optional configuration
+ * @param options.name - Parameter name for error messages (e.g., "event", "config")
+ * @param options.required - Throw error if source is empty (default: false)
+ * @param options.fallback - Default value if source is empty
+ * @returns Parsed JSON object
+ * @throws Error if source is required but empty, or if loading/parsing fails
+ *
+ * @example
+ * ```typescript
+ * // Inline JSON
+ * await loadJsonFromSource('{"name":"order complete","data":{}}')
+ *
+ * // File path
+ * await loadJsonFromSource('./examples/event.json')
+ *
+ * // URL
+ * await loadJsonFromSource('https://example.com/event.json')
+ *
+ * // With options
+ * await loadJsonFromSource(input, {
+ *   name: 'event',
+ *   required: true,
+ *   fallback: { name: 'default' }
+ * })
+ * ```
+ */
+export declare function loadJsonFromSource<T = unknown>(source: string | undefined, options?: {
+    name?: string;
+    required?: boolean;
+    fallback?: T;
+}): Promise<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/config/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/config/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAmCtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,CAAC;CACd,GACA,OAAO,CAAC,CAAC,CAAC,CAmEZ"}

package/dist/config/utils.js

@@ -0,0 +1,235 @@
+/**
+ * Configuration Utility Functions
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { getErrorMessage } from '../core/index.js';
+import { getTmpPath } from '../core/tmp.js';
+/**
+ * Check if a string is a valid URL
+ *
+ * @param str - String to check
+ * @returns True if string is a valid HTTP/HTTPS URL
+ */
+export function isUrl(str) {
+    try {
+        const url = new URL(str);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Download a file from a URL to a temporary location
+ *
+ * @param url - HTTP/HTTPS URL to download
+ * @returns Path to downloaded temporary file
+ * @throws Error if download fails or response is not OK
+ *
+ * @example
+ * ```typescript
+ * const tempPath = await downloadFromUrl('https://example.com/config.json')
+ * // Returns: "/tmp/walkeros-download-1647261462000-abc123.json"
+ * ```
+ */
+export async function downloadFromUrl(url) {
+    if (!isUrl(url)) {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+        }
+        const content = await response.text();
+        // Write to .tmp/downloads/ directory
+        const downloadsDir = getTmpPath(undefined, 'downloads');
+        await fs.ensureDir(downloadsDir);
+        // Use a consistent filename - always re-downloaded fresh anyway
+        const tempPath = path.join(downloadsDir, 'flow.json');
+        await fs.writeFile(tempPath, content, 'utf-8');
+        return tempPath;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to download from URL: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Substitute environment variables in a string.
+ *
+ * @param value - String with ${VAR} placeholders
+ * @returns String with environment variables substituted
+ * @throws Error if environment variable is not found
+ *
+ * @example
+ * ```typescript
+ * substituteEnvVariables('${HOME}/config') // "/Users/name/config"
+ * ```
+ */
+export function substituteEnvVariables(value) {
+    return value.replace(/\${([^}]+)}/g, (_, envVar) => {
+        const envValue = process.env[envVar];
+        if (!envValue) {
+            throw new Error(`Environment variable ${envVar} not found`);
+        }
+        return envValue;
+    });
+}
+/**
+ * Load and parse JSON configuration file from local path or URL.
+ *
+ * @param configPath - Path to JSON file or HTTP/HTTPS URL
+ * @returns Parsed configuration object and cleanup function
+ * @throws Error if file not found, download fails, or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * // Local file
+ * const config = await loadJsonConfig('./config.json')
+ *
+ * // Remote URL
+ * const config = await loadJsonConfig('https://example.com/config.json')
+ * ```
+ */
+export async function loadJsonConfig(configPath) {
+    let absolutePath;
+    let isTemporary = false;
+    // Check if input is a URL
+    if (isUrl(configPath)) {
+        // Download from URL to temp location
+        absolutePath = await downloadFromUrl(configPath);
+        isTemporary = true;
+    }
+    else {
+        // Local file path
+        absolutePath = path.resolve(configPath);
+        if (!(await fs.pathExists(absolutePath))) {
+            throw new Error(`Configuration file not found: ${absolutePath}`);
+        }
+    }
+    try {
+        const rawConfig = await fs.readJson(absolutePath);
+        return rawConfig;
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in config file: ${configPath}. ${error instanceof Error ? error.message : error}`);
+    }
+    finally {
+        // Clean up temporary downloaded file
+        if (isTemporary) {
+            try {
+                await fs.remove(absolutePath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+}
+/**
+ * Load JSON from inline string, file path, or URL.
+ *
+ * Supports three input formats:
+ * 1. Inline JSON string - parsed directly
+ * 2. Local file path - read and parsed
+ * 3. HTTP/HTTPS URL - downloaded and parsed
+ *
+ * Detection priority:
+ * 1. URL (http://, https://) → download and parse
+ * 2. Existing file path → read and parse
+ * 3. Valid JSON string → parse directly
+ * 4. Simple string → treat as {name: string} for backward compatibility
+ *
+ * @param source - JSON string, file path, or URL
+ * @param options - Optional configuration
+ * @param options.name - Parameter name for error messages (e.g., "event", "config")
+ * @param options.required - Throw error if source is empty (default: false)
+ * @param options.fallback - Default value if source is empty
+ * @returns Parsed JSON object
+ * @throws Error if source is required but empty, or if loading/parsing fails
+ *
+ * @example
+ * ```typescript
+ * // Inline JSON
+ * await loadJsonFromSource('{"name":"order complete","data":{}}')
+ *
+ * // File path
+ * await loadJsonFromSource('./examples/event.json')
+ *
+ * // URL
+ * await loadJsonFromSource('https://example.com/event.json')
+ *
+ * // With options
+ * await loadJsonFromSource(input, {
+ *   name: 'event',
+ *   required: true,
+ *   fallback: { name: 'default' }
+ * })
+ * ```
+ */
+export async function loadJsonFromSource(source, options) {
+    const paramName = options?.name || 'input';
+    // Handle empty/undefined input
+    if (!source || source.trim() === '') {
+        if (options?.required) {
+            throw new Error(`${paramName} is required`);
+        }
+        if (options?.fallback !== undefined) {
+            return options.fallback;
+        }
+        return {};
+    }
+    const trimmedSource = source.trim();
+    // 1. Check if URL
+    if (isUrl(trimmedSource)) {
+        try {
+            const tempPath = await downloadFromUrl(trimmedSource);
+            try {
+                const data = await fs.readJson(tempPath);
+                return data;
+            }
+            finally {
+                // Clean up temp file
+                try {
+                    await fs.remove(tempPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to load ${paramName} from URL ${trimmedSource}: ${getErrorMessage(error)}`);
+        }
+    }
+    // 2. Check if file path exists
+    const resolvedPath = path.resolve(trimmedSource);
+    if (await fs.pathExists(resolvedPath)) {
+        try {
+            const data = await fs.readJson(resolvedPath);
+            return data;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse ${paramName} from file ${trimmedSource}: ${getErrorMessage(error)}`);
+        }
+    }
+    // 3. Try to parse as inline JSON
+    try {
+        const parsed = JSON.parse(trimmedSource);
+        return parsed;
+    }
+    catch (jsonError) {
+        // 4. Fallback: treat as event name string for backward compatibility
+        // This allows simple strings like "page view" to work
+        if (!trimmedSource.startsWith('{') && !trimmedSource.startsWith('[')) {
+            return { name: trimmedSource };
+        }
+        // If it looks like JSON but failed to parse, throw helpful error
+        throw new Error(`Failed to parse ${paramName}. Input appears to be JSON but contains errors: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`);
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/config/utils.js.map

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

package/dist/config/validators.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration Type Guards and Validators
+ *
+ * Type checking utilities for configuration validation.
+ * Uses Zod schemas from @walkeros/core for Flow.Setup validation.
+ */
+import type { Flow } from '@walkeros/core';
+/**
+ * Type guard: Check if value is a plain object.
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Detect platform from flow config.
+ *
+ * Platform is determined by the presence of `web` or `server` key.
+ */
+export declare function detectPlatform(flowConfig: Record<string, unknown>): 'web' | 'server' | undefined;
+/**
+ * Type guard: Check if config is a valid Flow.Setup structure.
+ *
+ * @remarks
+ * Uses Zod validation from @walkeros/core.
+ * Returns false instead of throwing on invalid input.
+ *
+ * @example
+ * ```typescript
+ * if (isFlowSetup(config)) {
+ *   const flowConfig = getFlowConfig(config, 'production');
+ * }
+ * ```
+ */
+export declare function isFlowSetup(data: unknown): data is Flow.Setup;
+/**
+ * Validate Flow.Setup and throw descriptive error if invalid.
+ *
+ * @remarks
+ * Uses Zod validation from @walkeros/core.
+ * Provides detailed error messages from Zod.
+ *
+ * @param data - Raw configuration data
+ * @returns Validated Flow.Setup
+ * @throws Error with descriptive message if validation fails
+ */
+export declare function validateFlowSetup(data: unknown): Flow.Setup;
+/**
+ * Get available flow names from a Flow.Setup.
+ *
+ * @param setup - Flow.Setup configuration
+ * @returns Array of flow names
+ */
+export declare function getAvailableFlows(setup: Flow.Setup): string[];
+//# sourceMappingURL=validators.d.ts.map

package/dist/config/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/config/validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAK3C;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,KAAK,GAAG,QAAQ,GAAG,SAAS,CAQ9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAG7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAkB3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,MAAM,EAAE,CAE7D"}

package/dist/config/validators.js

@@ -0,0 +1,85 @@
+/**
+ * Configuration Type Guards and Validators
+ *
+ * Type checking utilities for configuration validation.
+ * Uses Zod schemas from @walkeros/core for Flow.Setup validation.
+ */
+import { schemas } from '@walkeros/core/dev';
+const { safeParseSetup } = schemas;
+/**
+ * Type guard: Check if value is a plain object.
+ */
+export function isObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.prototype.toString.call(value) === '[object Object]');
+}
+/**
+ * Detect platform from flow config.
+ *
+ * Platform is determined by the presence of `web` or `server` key.
+ */
+export function detectPlatform(flowConfig) {
+    if ('web' in flowConfig && flowConfig.web !== undefined) {
+        return 'web';
+    }
+    if ('server' in flowConfig && flowConfig.server !== undefined) {
+        return 'server';
+    }
+    return undefined;
+}
+/**
+ * Type guard: Check if config is a valid Flow.Setup structure.
+ *
+ * @remarks
+ * Uses Zod validation from @walkeros/core.
+ * Returns false instead of throwing on invalid input.
+ *
+ * @example
+ * ```typescript
+ * if (isFlowSetup(config)) {
+ *   const flowConfig = getFlowConfig(config, 'production');
+ * }
+ * ```
+ */
+export function isFlowSetup(data) {
+    const result = safeParseSetup(data);
+    return result.success;
+}
+/**
+ * Validate Flow.Setup and throw descriptive error if invalid.
+ *
+ * @remarks
+ * Uses Zod validation from @walkeros/core.
+ * Provides detailed error messages from Zod.
+ *
+ * @param data - Raw configuration data
+ * @returns Validated Flow.Setup
+ * @throws Error with descriptive message if validation fails
+ */
+export function validateFlowSetup(data) {
+    const result = safeParseSetup(data);
+    if (!result.success) {
+        // Format Zod errors for CLI display
+        const errors = result.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.map(String).join('.') : 'root';
+            return `  - ${path}: ${issue.message}`;
+        })
+            .join('\n');
+        throw new Error(`Invalid configuration:\n${errors}`);
+    }
+    // Cast to Flow.Setup since Zod's inferred type is compatible but not identical
+    return result.data;
+}
+/**
+ * Get available flow names from a Flow.Setup.
+ *
+ * @param setup - Flow.Setup configuration
+ * @returns Array of flow names
+ */
+export function getAvailableFlows(setup) {
+    return Object.keys(setup.flows);
+}
+//# sourceMappingURL=validators.js.map

package/dist/config/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/config/validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;AAEnC;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,CAC5D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAmC;IAEnC,IAAI,KAAK,IAAI,UAAU,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,QAAQ,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAEpC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,oCAAoC;QACpC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,MAAM,IAAI,GACR,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACpE,OAAO,OAAO,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QACzC,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,+EAA+E;IAC/E,OAAO,MAAM,CAAC,IAAkB,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/dist/core/asset-resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Asset Resolver
+ *
+ * Unified path resolution for package assets (examples) and user assets.
+ * Assets are always siblings to the CLI entry point (in dist/ for production).
+ */
+/**
+ * Get the directory containing CLI assets (examples).
+ *
+ * In production: assets are in dist/ alongside the bundled CLI
+ * In development: assets are at package root
+ *
+ * @returns Absolute path to assets directory
+ */
+export declare function getAssetDir(): string;
+/**
+ * Asset type for resolution strategy
+ */
+export type AssetType = 'config' | 'bundle';
+/**
+ * Resolve asset path using unified strategy
+ *
+ * Resolution rules:
+ * 1. Bare names (no / or \) → Package asset (examples)
+ * 2. Relative paths (./ or ../) → User asset relative to base directory
+ * 3. Absolute paths → Use as-is
+ *
+ * @param assetPath - Path to resolve
+ * @param assetType - Type of asset (determines package subdirectory)
+ * @param baseDir - Base directory for relative paths (defaults to cwd)
+ * @returns Absolute path to asset
+ */
+export declare function resolveAsset(assetPath: string, assetType: AssetType, baseDir?: string): string;
+//# sourceMappingURL=asset-resolver.d.ts.map

package/dist/core/asset-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-resolver.d.ts","sourceRoot":"","sources":["../../src/core/asset-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAkBpC;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAmBR"}

package/dist/core/asset-resolver.js

@@ -0,0 +1,70 @@
+/**
+ * Asset Resolver
+ *
+ * Unified path resolution for package assets (examples) and user assets.
+ * Assets are always siblings to the CLI entry point (in dist/ for production).
+ */
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+import path from 'path';
+import { isUrl } from '../config/utils.js';
+/**
+ * Cached asset directory to avoid repeated filesystem checks
+ */
+let cachedAssetDir;
+/**
+ * Get the directory containing CLI assets (examples).
+ *
+ * In production: assets are in dist/ alongside the bundled CLI
+ * In development: assets are at package root
+ *
+ * @returns Absolute path to assets directory
+ */
+export function getAssetDir() {
+    if (cachedAssetDir)
+        return cachedAssetDir;
+    const currentFile = fileURLToPath(import.meta.url);
+    let dir = path.dirname(currentFile);
+    // Walk up until we find a directory with examples/ sibling
+    while (dir !== path.dirname(dir)) {
+        if (existsSync(path.join(dir, 'examples'))) {
+            cachedAssetDir = dir;
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    // Fallback to current file's directory (shouldn't happen if build is correct)
+    cachedAssetDir = path.dirname(currentFile);
+    return cachedAssetDir;
+}
+/**
+ * Resolve asset path using unified strategy
+ *
+ * Resolution rules:
+ * 1. Bare names (no / or \) → Package asset (examples)
+ * 2. Relative paths (./ or ../) → User asset relative to base directory
+ * 3. Absolute paths → Use as-is
+ *
+ * @param assetPath - Path to resolve
+ * @param assetType - Type of asset (determines package subdirectory)
+ * @param baseDir - Base directory for relative paths (defaults to cwd)
+ * @returns Absolute path to asset
+ */
+export function resolveAsset(assetPath, assetType, baseDir) {
+    // URL → pass through unchanged
+    if (isUrl(assetPath)) {
+        return assetPath;
+    }
+    // Bare name → package asset (examples directory)
+    if (!assetPath.includes('/') && !assetPath.includes('\\')) {
+        const assetDir = getAssetDir();
+        return path.join(assetDir, 'examples', assetPath);
+    }
+    // Absolute path → use as-is
+    if (path.isAbsolute(assetPath)) {
+        return assetPath;
+    }
+    // Relative path → resolve from base directory
+    return path.resolve(baseDir || process.cwd(), assetPath);
+}
+//# sourceMappingURL=asset-resolver.js.map

package/dist/core/asset-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-resolver.js","sourceRoot":"","sources":["../../src/core/asset-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;GAEG;AACH,IAAI,cAAkC,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAE1C,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAEpC,2DAA2D;IAC3D,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;YAC3C,cAAc,GAAG,GAAG,CAAC;YACrB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,8EAA8E;IAC9E,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAOD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiB,EACjB,SAAoB,EACpB,OAAgB;IAEhB,+BAA+B;IAC/B,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,iDAAiD;IACjD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,4BAA4B;IAC5B,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,8CAA8C;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC"}

package/dist/core/build-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build artifact cache for flow.json configurations
+ *
+ * Caches compiled bundles based on configuration content + date.
+ * Enables intelligent cache reuse with daily rebuild guarantee.
+ */
+/**
+ * Get the cache file path for a flow.json configuration
+ */
+export declare function getBuildCachePath(configContent: string, tmpDir?: string): Promise<string>;
+/**
+ * Check if a cached build exists for the given configuration
+ */
+export declare function isBuildCached(configContent: string, tmpDir?: string): Promise<boolean>;
+/**
+ * Store a build artifact in the cache
+ */
+export declare function cacheBuild(configContent: string, buildOutput: string, tmpDir?: string): Promise<void>;
+/**
+ * Retrieve a cached build artifact
+ */
+export declare function getCachedBuild(configContent: string, tmpDir?: string): Promise<string | null>;
+//# sourceMappingURL=build-cache.d.ts.map

package/dist/core/build-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-cache.d.ts","sourceRoot":"","sources":["../../src/core/build-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB"}