@synergenius/flow-weaver 0.2.0

package/dist/constants.js

@@ -0,0 +1,125 @@
+/**
+ * # Flow Weaver Constants
+ *
+ * This module defines reserved names and constants used throughout the Flow Weaver system.
+ *
+ * ## Scoped Port Architecture
+ *
+ * Scoped ports enable iteration patterns (forEach, map) WITHOUT graph cycles.
+ * The key insight is that port directions are INVERTED for scoped ports:
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │                    SCOPED PORT DIRECTION MAPPING                    │
+ * ├─────────────────┬──────────┬────────────────────────────────────────┤
+ * │ Scoped OUTPUT   │ Parent→  │ Parameters TO children (start, item)   │
+ * │ Scoped INPUT    │ →Parent  │ Returns FROM children (success, result)│
+ * └─────────────────┴──────────┴────────────────────────────────────────┘
+ * ```
+ *
+ * **Why this inversion?**
+ * - Scoped OUTPUT ports (like `start`, `item`) are data the parent SENDS to nested nodes
+ * - Scoped INPUT ports (like `success`, `result`) are data the parent RECEIVES from nested nodes
+ * - The loop iteration happens in the parent's imperative code, not as graph cycles
+ *
+ * ## Mandatory Scoped Ports
+ *
+ * Every scoped node must have these ports for each scope it declares:
+ * - `start` (OUTPUT) - Triggers scope execution, passed as first param
+ * - `success` (INPUT) - Signals successful completion from child
+ * - `failure` (INPUT) - Signals failure from child
+ *
+ * ## Example: forEach Node
+ *
+ * ```typescript
+ * @scope processItem
+ * @output start scope:processItem    // OUTPUT → function param (triggers iteration)
+ * @output item scope:processItem     // OUTPUT → function param (current item)
+ * @input success scope:processItem   // INPUT → return value (completion signal)
+ * @input processed scope:processItem // INPUT → return value (processed data)
+ *
+ * function forEach(execute, items, processItem) {
+ *   const results = [];
+ *   for (const item of items) {
+ *     const r = processItem(true, item); // Calls generated closure
+ *     if (r.success) results.push(r.processed);
+ *   }
+ *   return { onSuccess: true, results };
+ * }
+ * ```
+ */
+export const RESERVED_NODE_NAMES = {
+    START: "Start",
+    EXIT: "Exit",
+};
+export const RESERVED_PORT_NAMES = {
+    EXECUTE: "execute",
+    ON_SUCCESS: "onSuccess",
+    ON_FAILURE: "onFailure",
+};
+// Scoped mandatory ports (different from external)
+export const SCOPED_PORT_NAMES = {
+    START: "start", // OUTPUT - starts scope iteration
+    SUCCESS: "success", // INPUT - success signal from scope
+    FAILURE: "failure", // INPUT - failure signal from scope
+};
+export const EXECUTION_STRATEGIES = {
+    CONJUNCTION: "CONJUNCTION",
+    DISJUNCTION: "DISJUNCTION",
+    CUSTOM: "CUSTOM",
+};
+export const BRANCHING_STRATEGIES = {
+    VALUE_BASED: "value-based",
+    EXCEPTION_BASED: "exception-based",
+    NONE: "none",
+};
+export function isReservedNodeName(name) {
+    return Object.values(RESERVED_NODE_NAMES).includes(name);
+}
+export function isReservedPortName(name) {
+    return Object.values(RESERVED_PORT_NAMES).includes(name);
+}
+export function isStartNode(nodeName) {
+    return nodeName === RESERVED_NODE_NAMES.START;
+}
+export function isExitNode(nodeName) {
+    return nodeName === RESERVED_NODE_NAMES.EXIT;
+}
+export function isSpecialNode(nodeName) {
+    return isStartNode(nodeName) || isExitNode(nodeName);
+}
+export function isExecutePort(portName) {
+    return portName === RESERVED_PORT_NAMES.EXECUTE;
+}
+export function isSuccessPort(portName) {
+    return portName === RESERVED_PORT_NAMES.ON_SUCCESS;
+}
+export function isFailurePort(portName) {
+    return portName === RESERVED_PORT_NAMES.ON_FAILURE;
+}
+// Scoped port checks
+export function isScopedStartPort(portName) {
+    return portName === SCOPED_PORT_NAMES.START;
+}
+export function isScopedSuccessPort(portName) {
+    return portName === SCOPED_PORT_NAMES.SUCCESS;
+}
+export function isScopedFailurePort(portName) {
+    return portName === SCOPED_PORT_NAMES.FAILURE;
+}
+export function isScopedMandatoryPort(portName) {
+    return isScopedStartPort(portName) || isScopedSuccessPort(portName) || isScopedFailurePort(portName);
+}
+export function isControlFlowPort(portName) {
+    return (isExecutePort(portName) ||
+        isSuccessPort(portName) ||
+        isFailurePort(portName));
+}
+/**
+ * Check if a port definition represents a scoped port
+ * Scoped ports are FUNCTION type with a scope attribute
+ */
+export function isScopedPort(portDef) {
+    return portDef.dataType === "FUNCTION" && portDef.scope !== undefined;
+}
+//# sourceMappingURL=constants.js.map

package/dist/defaults.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_PORT: number;
+export declare const DEFAULT_SERVER_URL: string;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.js

@@ -0,0 +1,3 @@
+export const DEFAULT_PORT = parseInt(process.env.FW_PORT || '6546', 10);
+export const DEFAULT_SERVER_URL = `http://localhost:${DEFAULT_PORT}`;
+//# sourceMappingURL=defaults.js.map

package/dist/deployment/config/defaults.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Default configuration values for the deployment system
+ */
+import type { DeploymentConfig, ServerConfig, ExecutionConfig, SecretsConfig } from './types.js';
+/**
+ * Default server configuration
+ */
+export declare const DEFAULT_SERVER_CONFIG: ServerConfig;
+/**
+ * Default execution configuration
+ */
+export declare const DEFAULT_EXECUTION_CONFIG: ExecutionConfig;
+/**
+ * Default secrets configuration
+ */
+export declare const DEFAULT_SECRETS_CONFIG: SecretsConfig;
+/**
+ * Default deployment configuration
+ */
+export declare const DEFAULT_CONFIG: DeploymentConfig;
+/**
+ * Production configuration overrides
+ */
+export declare const PRODUCTION_OVERRIDES: Partial<DeploymentConfig>;
+/**
+ * Get default configuration for a given environment
+ */
+export declare function getDefaultConfig(environment: 'development' | 'staging' | 'production'): DeploymentConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/deployment/config/defaults.js

@@ -0,0 +1,98 @@
+/**
+ * Default configuration values for the deployment system
+ */
+/**
+ * Default server configuration
+ */
+export const DEFAULT_SERVER_CONFIG = {
+    port: 3000,
+    host: '0.0.0.0',
+    cors: {
+        origin: '*',
+        methods: ['GET', 'POST', 'OPTIONS'],
+        headers: ['Content-Type', 'Authorization', 'X-Request-Id'],
+        credentials: false,
+    },
+    swagger: false,
+    watch: true,
+};
+/**
+ * Default execution configuration
+ */
+export const DEFAULT_EXECUTION_CONFIG = {
+    timeout: 30000,
+    includeTrace: true,
+    maxConcurrent: 10,
+    retry: {
+        maxRetries: 0,
+        initialDelay: 100,
+        maxDelay: 5000,
+        backoffMultiplier: 2,
+    },
+};
+/**
+ * Default secrets configuration
+ */
+export const DEFAULT_SECRETS_CONFIG = {
+    fromEnv: [],
+    files: ['.env', '.env.local'],
+};
+/**
+ * Default deployment configuration
+ */
+export const DEFAULT_CONFIG = {
+    environment: 'development',
+    server: DEFAULT_SERVER_CONFIG,
+    execution: DEFAULT_EXECUTION_CONFIG,
+    secrets: DEFAULT_SECRETS_CONFIG,
+};
+/**
+ * Production configuration overrides
+ */
+export const PRODUCTION_OVERRIDES = {
+    environment: 'production',
+    server: {
+        ...DEFAULT_SERVER_CONFIG,
+        watch: false,
+        cors: {
+            ...DEFAULT_SERVER_CONFIG.cors,
+            origin: [], // Must be explicitly configured in production
+        },
+    },
+    execution: {
+        ...DEFAULT_EXECUTION_CONFIG,
+        includeTrace: false,
+        timeout: 60000,
+    },
+};
+/**
+ * Get default configuration for a given environment
+ */
+export function getDefaultConfig(environment) {
+    if (environment === 'production') {
+        return {
+            ...DEFAULT_CONFIG,
+            ...PRODUCTION_OVERRIDES,
+            server: {
+                ...DEFAULT_CONFIG.server,
+                ...PRODUCTION_OVERRIDES.server,
+            },
+            execution: {
+                ...DEFAULT_CONFIG.execution,
+                ...PRODUCTION_OVERRIDES.execution,
+            },
+        };
+    }
+    if (environment === 'staging') {
+        return {
+            ...DEFAULT_CONFIG,
+            environment: 'staging',
+            execution: {
+                ...DEFAULT_CONFIG.execution,
+                includeTrace: true, // Keep traces in staging for debugging
+            },
+        };
+    }
+    return DEFAULT_CONFIG;
+}
+//# sourceMappingURL=defaults.js.map

package/dist/deployment/config/loader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Configuration loader
+ *
+ * Loads configuration from files, environment variables, and CLI arguments,
+ * merging them in order of precedence.
+ */
+import type { DeploymentConfig, CliConfigOverrides } from './types.js';
+/**
+ * Load configuration with the following precedence (highest to lowest):
+ * 1. CLI arguments
+ * 2. Environment variables
+ * 3. Config file
+ * 4. Default values
+ */
+export declare function loadConfig(cliOverrides?: CliConfigOverrides, configPath?: string): Promise<DeploymentConfig>;
+/**
+ * Synchronous config loading (for simpler use cases)
+ */
+export declare function loadConfigSync(cliOverrides?: CliConfigOverrides): DeploymentConfig;
+/**
+ * Get a specific config value with fallback to default
+ */
+export declare function getConfigValue<K extends keyof DeploymentConfig>(key: K, config?: Partial<DeploymentConfig>): DeploymentConfig[K];
+//# sourceMappingURL=loader.d.ts.map

package/dist/deployment/config/loader.js

@@ -0,0 +1,236 @@
+/**
+ * Configuration loader
+ *
+ * Loads configuration from files, environment variables, and CLI arguments,
+ * merging them in order of precedence.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as YAML from 'js-yaml';
+import { DEFAULT_CONFIG, getDefaultConfig } from './defaults.js';
+/**
+ * Configuration file names to search for
+ */
+const CONFIG_FILE_NAMES = ['flow-weaver.config.ts', 'flow-weaver.config.yaml'];
+/**
+ * Environment variable prefix
+ */
+const ENV_PREFIX = 'FW_';
+/**
+ * Load configuration with the following precedence (highest to lowest):
+ * 1. CLI arguments
+ * 2. Environment variables
+ * 3. Config file
+ * 4. Default values
+ */
+export async function loadConfig(cliOverrides, configPath) {
+    // Start with environment-specific defaults
+    const environment = detectEnvironment(cliOverrides);
+    let config = getDefaultConfig(environment);
+    // Load config file if it exists
+    const fileConfig = await loadConfigFile(configPath);
+    if (fileConfig) {
+        config = mergeConfig(config, fileConfig);
+    }
+    // Apply environment variable overrides
+    const envConfig = loadEnvConfig();
+    config = mergeConfig(config, envConfig);
+    // Apply CLI overrides (highest precedence)
+    if (cliOverrides) {
+        const cliConfig = convertCliOverrides(cliOverrides);
+        config = mergeConfig(config, cliConfig);
+    }
+    return config;
+}
+/**
+ * Detect environment from CLI, env vars, or defaults
+ */
+function detectEnvironment(cliOverrides) {
+    // CLI override takes precedence
+    if (cliOverrides?.env) {
+        return cliOverrides.env;
+    }
+    // Check environment variables
+    const envValue = process.env[`${ENV_PREFIX}ENV`] || process.env.NODE_ENV;
+    if (envValue) {
+        if (envValue === 'production' || envValue === 'prod') {
+            return 'production';
+        }
+        if (envValue === 'staging' || envValue === 'stage') {
+            return 'staging';
+        }
+    }
+    return 'development';
+}
+/**
+ * Load configuration from file
+ */
+async function loadConfigFile(configPath) {
+    // If a specific path is provided, try to load it
+    if (configPath) {
+        return loadConfigFromPath(configPath);
+    }
+    // Search for config file in current directory
+    const cwd = process.cwd();
+    for (const fileName of CONFIG_FILE_NAMES) {
+        const configFilePath = path.join(cwd, fileName);
+        if (fs.existsSync(configFilePath)) {
+            return loadConfigFromPath(configFilePath);
+        }
+    }
+    return null;
+}
+/**
+ * Load configuration from a specific file path
+ */
+async function loadConfigFromPath(filePath) {
+    const absolutePath = path.resolve(filePath);
+    if (!fs.existsSync(absolutePath)) {
+        return null;
+    }
+    const ext = path.extname(absolutePath);
+    // YAML files
+    if (ext === '.yaml' || ext === '.yml') {
+        try {
+            const content = fs.readFileSync(absolutePath, 'utf8');
+            return YAML.load(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    // TypeScript files - dynamic import
+    if (ext === '.ts') {
+        try {
+            const module = await import(absolutePath);
+            return (module.default || module);
+        }
+        catch {
+            // Config file loading failed, skip it
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Load configuration from environment variables
+ */
+function loadEnvConfig() {
+    const config = {};
+    // Server config
+    const port = process.env[`${ENV_PREFIX}PORT`];
+    const host = process.env[`${ENV_PREFIX}HOST`];
+    const cors = process.env[`${ENV_PREFIX}CORS_ORIGIN`];
+    if (port || host || cors) {
+        config.server = {};
+        if (port)
+            config.server.port = parseInt(port, 10);
+        if (host)
+            config.server.host = host;
+        if (cors)
+            config.server.cors = { origin: cors };
+    }
+    // Execution config
+    const timeout = process.env[`${ENV_PREFIX}TIMEOUT`];
+    const trace = process.env[`${ENV_PREFIX}TRACE`];
+    if (timeout || trace) {
+        config.execution = {};
+        if (timeout)
+            config.execution.timeout = parseInt(timeout, 10);
+        if (trace)
+            config.execution.includeTrace = trace === 'true' || trace === '1';
+    }
+    return config;
+}
+/**
+ * Convert CLI overrides to partial config
+ */
+function convertCliOverrides(overrides) {
+    const config = {};
+    if (overrides.env) {
+        config.environment = overrides.env;
+    }
+    // Server overrides
+    if (overrides.port ||
+        overrides.host ||
+        overrides.cors ||
+        overrides.watch !== undefined ||
+        overrides.swagger !== undefined) {
+        config.server = {};
+        if (overrides.port)
+            config.server.port = overrides.port;
+        if (overrides.host)
+            config.server.host = overrides.host;
+        if (overrides.cors)
+            config.server.cors = { origin: overrides.cors };
+        if (overrides.watch !== undefined)
+            config.server.watch = overrides.watch;
+        if (overrides.swagger !== undefined)
+            config.server.swagger = overrides.swagger;
+    }
+    // Execution overrides
+    if (overrides.timeout || overrides.trace !== undefined || overrides.production !== undefined) {
+        config.execution = {};
+        if (overrides.timeout)
+            config.execution.timeout = overrides.timeout;
+        if (overrides.trace !== undefined)
+            config.execution.includeTrace = overrides.trace;
+        if (overrides.production)
+            config.execution.includeTrace = false;
+    }
+    return config;
+}
+/**
+ * Deep merge two configuration objects
+ */
+function mergeConfig(base, override) {
+    return {
+        environment: override.environment ?? base.environment,
+        server: {
+            ...base.server,
+            ...override.server,
+            cors: {
+                ...base.server.cors,
+                ...(override.server?.cors || {}),
+            },
+        },
+        execution: {
+            ...base.execution,
+            ...override.execution,
+            retry: {
+                ...(base.execution.retry || {}),
+                ...(override.execution?.retry || {}),
+            },
+        },
+        secrets: {
+            ...base.secrets,
+            ...override.secrets,
+        },
+    };
+}
+/**
+ * Synchronous config loading (for simpler use cases)
+ */
+export function loadConfigSync(cliOverrides) {
+    const environment = detectEnvironment(cliOverrides);
+    let config = getDefaultConfig(environment);
+    // Apply environment variable overrides
+    const envConfig = loadEnvConfig();
+    config = mergeConfig(config, envConfig);
+    // Apply CLI overrides
+    if (cliOverrides) {
+        const cliConfig = convertCliOverrides(cliOverrides);
+        config = mergeConfig(config, cliConfig);
+    }
+    return config;
+}
+/**
+ * Get a specific config value with fallback to default
+ */
+export function getConfigValue(key, config) {
+    if (config && config[key] !== undefined) {
+        return config[key];
+    }
+    return DEFAULT_CONFIG[key];
+}
+//# sourceMappingURL=loader.js.map

package/dist/deployment/config/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Configuration types for the deployment system
+ */
+import type { Environment } from '../types.js';
+/**
+ * Complete deployment configuration
+ */
+export interface DeploymentConfig {
+    /** Runtime environment */
+    environment: Environment;
+    /** Server configuration */
+    server: ServerConfig;
+    /** Execution configuration */
+    execution: ExecutionConfig;
+    /** Secrets and environment variable configuration */
+    secrets: SecretsConfig;
+}
+/**
+ * Server configuration options
+ */
+export interface ServerConfig {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to */
+    host: string;
+    /** CORS configuration */
+    cors: CorsConfig;
+    /** Enable Swagger UI */
+    swagger: boolean;
+    /** Enable file watching for hot reload */
+    watch: boolean;
+}
+/**
+ * CORS configuration
+ */
+export interface CorsConfig {
+    /** Allowed origins (string or array of strings) */
+    origin: string | string[];
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    headers?: string[];
+    /** Expose headers */
+    exposeHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Max age for preflight cache */
+    maxAge?: number;
+}
+/**
+ * Execution configuration
+ */
+export interface ExecutionConfig {
+    /** Default timeout in milliseconds */
+    timeout: number;
+    /** Include execution trace by default */
+    includeTrace: boolean;
+    /** Maximum concurrent executions */
+    maxConcurrent?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+}
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Initial delay in milliseconds */
+    initialDelay: number;
+    /** Maximum delay in milliseconds */
+    maxDelay: number;
+    /** Backoff multiplier */
+    backoffMultiplier: number;
+}
+/**
+ * Secrets and environment variable configuration
+ */
+export interface SecretsConfig {
+    /** Environment variables to inject into execution context */
+    fromEnv: string[];
+    /** .env files to load */
+    files: string[];
+}
+/**
+ * Partial configuration for merging
+ */
+export type PartialDeploymentConfig = {
+    environment?: Environment;
+    server?: Partial<ServerConfig>;
+    execution?: Partial<ExecutionConfig>;
+    secrets?: Partial<SecretsConfig>;
+};
+/**
+ * CLI argument overrides
+ */
+export interface CliConfigOverrides {
+    /** Override port */
+    port?: number;
+    /** Override host */
+    host?: string;
+    /** Override environment */
+    env?: Environment;
+    /** Override CORS origin */
+    cors?: string;
+    /** Override timeout */
+    timeout?: number;
+    /** Override trace inclusion */
+    trace?: boolean;
+    /** Override file watching */
+    watch?: boolean;
+    /** Enable swagger */
+    swagger?: boolean;
+    /** Production mode */
+    production?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/deployment/config/types.js

@@ -0,0 +1,5 @@
+/**
+ * Configuration types for the deployment system
+ */
+export {};
+//# sourceMappingURL=types.js.map