yaml-flow 2.0.0 → 2.2.0

package/dist/batch/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Batch Runner — Types
+ *
+ * Generic concurrent batch processor.
+ * Works with both step-machine and event-graph (or any async processor).
+ */
+interface BatchOptions<TItem, TResult> {
+    /**
+     * Max concurrent items in flight (slots).
+     * @default 5
+     */
+    concurrency?: number;
+    /**
+     * The async function that processes a single item.
+     * Receives the item and its 0-based index.
+     */
+    processor: (item: TItem, index: number) => Promise<TResult>;
+    /**
+     * Called when a single item completes successfully.
+     */
+    onItemComplete?: (item: TItem, result: TResult, index: number) => void;
+    /**
+     * Called when a single item fails (processor threw).
+     * If not provided, the error is captured in BatchItemResult.
+     */
+    onItemError?: (item: TItem, error: Error, index: number) => void;
+    /**
+     * Called after every item settles (success or failure).
+     * Receives a snapshot of progress.
+     */
+    onProgress?: (progress: BatchProgress) => void;
+    /**
+     * AbortSignal — if aborted, no new items are started.
+     * Items already in-flight are NOT cancelled (your processor should check its own signal).
+     */
+    signal?: AbortSignal;
+}
+interface BatchProgress {
+    /** Items completed successfully so far */
+    completed: number;
+    /** Items that threw an error */
+    failed: number;
+    /** Items currently in-flight */
+    active: number;
+    /** Items not yet started */
+    pending: number;
+    /** Total items */
+    total: number;
+    /** Percentage complete (0–100) */
+    percent: number;
+    /** Elapsed time in ms since batch started */
+    elapsedMs: number;
+}
+interface BatchResult<TItem, TResult> {
+    /** All item results in original order */
+    items: BatchItemResult<TItem, TResult>[];
+    /** Summary counts */
+    completed: number;
+    failed: number;
+    total: number;
+    /** Total wall-clock time in ms */
+    durationMs: number;
+}
+interface BatchItemResult<TItem, TResult> {
+    /** Original item */
+    item: TItem;
+    /** 0-based index in the input array */
+    index: number;
+    /** 'completed' or 'failed' */
+    status: 'completed' | 'failed';
+    /** Result if completed */
+    result?: TResult;
+    /** Error if failed */
+    error?: Error;
+    /** Per-item wall-clock time in ms */
+    durationMs: number;
+}
+
+/**
+ * Batch Runner — Core
+ *
+ * Slot-based concurrent processor. Pure control flow — no I/O opinions.
+ *
+ * @example Step Machine batch
+ * ```ts
+ * import { batch } from 'yaml-flow/batch';
+ * import { createStepMachine, loadStepFlow } from 'yaml-flow/step-machine';
+ *
+ * const flow = await loadStepFlow('./support-ticket.yaml');
+ * const results = await batch(tickets, {
+ *   concurrency: 5,
+ *   processor: async (ticket) => {
+ *     const machine = createStepMachine(flow, handlers);
+ *     return machine.run(ticket);
+ *   },
+ * });
+ * ```
+ *
+ * @example Event Graph batch
+ * ```ts
+ * import { batch } from 'yaml-flow/batch';
+ * import { next, apply, createInitialExecutionState } from 'yaml-flow/event-graph';
+ *
+ * const results = await batch(items, {
+ *   concurrency: 3,
+ *   processor: async (item, index) => {
+ *     let state = createInitialExecutionState(graph, `exec-${index}`);
+ *     state = apply(state, { type: 'inject-tokens', tokens: [item.token], timestamp: new Date().toISOString() }, graph);
+ *     // ... drive the graph loop
+ *     return state;
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Run an array of items through an async processor with concurrency control.
+ *
+ * - Items are started in order, up to `concurrency` at a time.
+ * - Results are returned in the original item order.
+ * - If a processor throws, the item is marked as failed; other items continue.
+ * - An AbortSignal prevents new items from starting (in-flight items are not cancelled).
+ */
+declare function batch<TItem, TResult>(items: TItem[], options: BatchOptions<TItem, TResult>): Promise<BatchResult<TItem, TResult>>;
+
+export { type BatchItemResult, type BatchOptions, type BatchProgress, type BatchResult, batch };

package/dist/batch/index.js

@@ -0,0 +1,107 @@
+// src/batch/runner.ts
+async function batch(items, options) {
+  const {
+    concurrency = 5,
+    processor,
+    onItemComplete,
+    onItemError,
+    onProgress,
+    signal
+  } = options;
+  const total = items.length;
+  const results = new Array(total);
+  const batchStart = Date.now();
+  let completed = 0;
+  let failed = 0;
+  let nextIndex = 0;
+  function makeProgress(active) {
+    const done = completed + failed;
+    return {
+      completed,
+      failed,
+      active,
+      pending: total - done - active,
+      total,
+      percent: total === 0 ? 100 : Math.round(done / total * 100),
+      elapsedMs: Date.now() - batchStart
+    };
+  }
+  if (total === 0) {
+    return { items: [], completed: 0, failed: 0, total: 0, durationMs: 0 };
+  }
+  return new Promise((resolve) => {
+    let active = 0;
+    function tryStartNext() {
+      while (active < concurrency && nextIndex < total) {
+        if (signal?.aborted) {
+          while (nextIndex < total) {
+            const idx2 = nextIndex++;
+            results[idx2] = {
+              item: items[idx2],
+              index: idx2,
+              status: "failed",
+              error: new Error("Batch aborted"),
+              durationMs: 0
+            };
+            failed++;
+          }
+          if (active === 0 && completed + failed === total) {
+            resolve({
+              items: results,
+              completed,
+              failed,
+              total,
+              durationMs: Date.now() - batchStart
+            });
+          }
+          break;
+        }
+        const idx = nextIndex++;
+        const item = items[idx];
+        active++;
+        const itemStart = Date.now();
+        processor(item, idx).then((result) => {
+          results[idx] = {
+            item,
+            index: idx,
+            status: "completed",
+            result,
+            durationMs: Date.now() - itemStart
+          };
+          completed++;
+          onItemComplete?.(item, result, idx);
+        }).catch((err) => {
+          const error = err instanceof Error ? err : new Error(String(err));
+          results[idx] = {
+            item,
+            index: idx,
+            status: "failed",
+            error,
+            durationMs: Date.now() - itemStart
+          };
+          failed++;
+          onItemError?.(item, error, idx);
+        }).finally(() => {
+          active--;
+          onProgress?.(makeProgress(active));
+          if (completed + failed === total) {
+            resolve({
+              items: results,
+              completed,
+              failed,
+              total,
+              durationMs: Date.now() - batchStart
+            });
+          } else {
+            tryStartNext();
+          }
+        });
+      }
+    }
+    tryStartNext();
+  });
+}
+
+export { batch };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/batch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/batch/runner.ts"],"names":["idx"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Batch Runner — Core\n *\n * Slot-based concurrent processor. Pure control flow — no I/O opinions.\n *\n * @example Step Machine batch\n * ```ts\n * import { batch } from 'yaml-flow/batch';\n * import { createStepMachine, loadStepFlow } from 'yaml-flow/step-machine';\n *\n * const flow = await loadStepFlow('./support-ticket.yaml');\n * const results = await batch(tickets, {\n *   concurrency: 5,\n *   processor: async (ticket) => {\n *     const machine = createStepMachine(flow, handlers);\n *     return machine.run(ticket);\n *   },\n * });\n * ```\n *\n * @example Event Graph batch\n * ```ts\n * import { batch } from 'yaml-flow/batch';\n * import { next, apply, createInitialExecutionState } from 'yaml-flow/event-graph';\n *\n * const results = await batch(items, {\n *   concurrency: 3,\n *   processor: async (item, index) => {\n *     let state = createInitialExecutionState(graph, `exec-${index}`);\n *     state = apply(state, { type: 'inject-tokens', tokens: [item.token], timestamp: new Date().toISOString() }, graph);\n *     // ... drive the graph loop\n *     return state;\n *   },\n * });\n * ```\n */\n\nimport type {\n  BatchOptions,\n  BatchResult,\n  BatchItemResult,\n  BatchProgress,\n} from './types.js';\n\n/**\n * Run an array of items through an async processor with concurrency control.\n *\n * - Items are started in order, up to `concurrency` at a time.\n * - Results are returned in the original item order.\n * - If a processor throws, the item is marked as failed; other items continue.\n * - An AbortSignal prevents new items from starting (in-flight items are not cancelled).\n */\nexport async function batch<TItem, TResult>(\n  items: TItem[],\n  options: BatchOptions<TItem, TResult>\n): Promise<BatchResult<TItem, TResult>> {\n  const {\n    concurrency = 5,\n    processor,\n    onItemComplete,\n    onItemError,\n    onProgress,\n    signal,\n  } = options;\n\n  const total = items.length;\n  const results: BatchItemResult<TItem, TResult>[] = new Array(total);\n  const batchStart = Date.now();\n\n  let completed = 0;\n  let failed = 0;\n  let nextIndex = 0;\n\n  function makeProgress(active: number): BatchProgress {\n    const done = completed + failed;\n    return {\n      completed,\n      failed,\n      active,\n      pending: total - done - active,\n      total,\n      percent: total === 0 ? 100 : Math.round((done / total) * 100),\n      elapsedMs: Date.now() - batchStart,\n    };\n  }\n\n  // Empty input — short-circuit\n  if (total === 0) {\n    return { items: [], completed: 0, failed: 0, total: 0, durationMs: 0 };\n  }\n\n  return new Promise<BatchResult<TItem, TResult>>((resolve) => {\n    let active = 0;\n\n    function tryStartNext() {\n      while (active < concurrency && nextIndex < total) {\n        // Respect abort signal — don't start new items\n        if (signal?.aborted) {\n          // Mark remaining as failed with abort error\n          while (nextIndex < total) {\n            const idx = nextIndex++;\n            results[idx] = {\n              item: items[idx],\n              index: idx,\n              status: 'failed',\n              error: new Error('Batch aborted'),\n              durationMs: 0,\n            };\n            failed++;\n          }\n          // If nothing is in-flight, resolve immediately\n          if (active === 0 && completed + failed === total) {\n            resolve({\n              items: results,\n              completed,\n              failed,\n              total,\n              durationMs: Date.now() - batchStart,\n            });\n          }\n          break;\n        }\n\n        const idx = nextIndex++;\n        const item = items[idx];\n        active++;\n        const itemStart = Date.now();\n\n        processor(item, idx)\n          .then((result) => {\n            results[idx] = {\n              item,\n              index: idx,\n              status: 'completed',\n              result,\n              durationMs: Date.now() - itemStart,\n            };\n            completed++;\n            onItemComplete?.(item, result, idx);\n          })\n          .catch((err) => {\n            const error = err instanceof Error ? err : new Error(String(err));\n            results[idx] = {\n              item,\n              index: idx,\n              status: 'failed',\n              error,\n              durationMs: Date.now() - itemStart,\n            };\n            failed++;\n            onItemError?.(item, error, idx);\n          })\n          .finally(() => {\n            active--;\n            onProgress?.(makeProgress(active));\n\n            if (completed + failed === total) {\n              resolve({\n                items: results,\n                completed,\n                failed,\n                total,\n                durationMs: Date.now() - batchStart,\n              });\n            } else {\n              tryStartNext();\n            }\n          });\n      }\n    }\n\n    tryStartNext();\n  });\n}\n"]}

package/dist/config/index.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+// src/config/resolve-variables.ts
+function interpolateString(template, vars) {
+  return template.replace(/\$\{([^}]+)\}/g, (match, key) => {
+    const value = vars[key.trim()];
+    return value !== void 0 ? String(value) : match;
+  });
+}
+function walkAndInterpolate(value, vars) {
+  if (typeof value === "string") {
+    return interpolateString(value, vars);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => walkAndInterpolate(item, vars));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = walkAndInterpolate(v, vars);
+    }
+    return result;
+  }
+  return value;
+}
+function resolveVariables(config, variables) {
+  return walkAndInterpolate(config, variables);
+}
+
+// src/config/resolve-config-templates.ts
+function mergeConfigs(template, taskConfig) {
+  const merged = { ...template };
+  for (const [key, value] of Object.entries(taskConfig)) {
+    if (key === "config-template") continue;
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && merged[key] !== null && typeof merged[key] === "object" && !Array.isArray(merged[key])) {
+      merged[key] = {
+        ...merged[key],
+        ...value
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function resolveConfigTemplates(config) {
+  const templates = config["configTemplates"] ?? config["config-templates"] ?? {};
+  const tasksKey = "tasks" in config ? "tasks" : "steps" in config ? "steps" : null;
+  if (!tasksKey) return config;
+  const tasks = config[tasksKey];
+  if (!tasks || typeof tasks !== "object") return config;
+  const resolvedTasks = {};
+  for (const [name, task] of Object.entries(tasks)) {
+    const taskConfig = task["config"];
+    const templateName = taskConfig?.["config-template"];
+    if (!templateName || !taskConfig) {
+      resolvedTasks[name] = task;
+      continue;
+    }
+    const template = templates[templateName];
+    if (!template) {
+      const { "config-template": _, ...rest } = taskConfig;
+      resolvedTasks[name] = { ...task, config: rest };
+      continue;
+    }
+    resolvedTasks[name] = {
+      ...task,
+      config: mergeConfigs(template, taskConfig)
+    };
+  }
+  const result = { ...config, [tasksKey]: resolvedTasks };
+  delete result["configTemplates"];
+  delete result["config-templates"];
+  return result;
+}
+
+exports.resolveConfigTemplates = resolveConfigTemplates;
+exports.resolveVariables = resolveVariables;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/config/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/resolve-variables.ts","../../src/config/resolve-config-templates.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Variable interpolation for workflow configs.\n *\n * Walks any object/array and replaces `${KEY}` patterns with values from\n * a variables map. Pure function — returns a new object, never mutates.\n *\n * Works on both GraphConfig and StepFlowConfig (or any plain object).\n *\n * @example\n * ```ts\n * const resolved = resolveVariables(config, {\n *   ENTITY_ID: 'ticket-42',\n *   TOOLS_DIR: '/opt/tools',\n * });\n * ```\n */\n\nexport type Variables = Record<string, string | number | boolean>;\n\n/**\n * Replace `${KEY}` patterns in a string with values from the variables map.\n * Unmatched variables are left as-is.\n */\nfunction interpolateString(template: string, vars: Variables): string {\n  return template.replace(/\\$\\{([^}]+)\\}/g, (match, key: string) => {\n    const value = vars[key.trim()];\n    return value !== undefined ? String(value) : match;\n  });\n}\n\n/**\n * Recursively walk a value and interpolate any `${KEY}` patterns found in strings.\n * Returns a new object/array — never mutates the input.\n */\nfunction walkAndInterpolate<T>(value: T, vars: Variables): T {\n  if (typeof value === 'string') {\n    return interpolateString(value, vars) as unknown as T;\n  }\n  if (Array.isArray(value)) {\n    return value.map((item) => walkAndInterpolate(item, vars)) as unknown as T;\n  }\n  if (value !== null && typeof value === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [k, v] of Object.entries(value)) {\n      result[k] = walkAndInterpolate(v, vars);\n    }\n    return result as T;\n  }\n  // numbers, booleans, null, undefined — pass through\n  return value;\n}\n\n/**\n * Resolve `${KEY}` variable references in a workflow config object.\n *\n * Pure function: config in → new config out. Works on any shape\n * (GraphConfig, StepFlowConfig, or arbitrary objects).\n *\n * @param config  - The config object to interpolate\n * @param variables - Key-value pairs to substitute\n * @returns A new config with all `${KEY}` patterns replaced\n */\nexport function resolveVariables<T extends Record<string, unknown>>(\n  config: T,\n  variables: Variables,\n): T {\n  return walkAndInterpolate(config, variables);\n}\n","/**\n * Config template resolution for workflow configs.\n *\n * In large graphs, many tasks share the same base config (cmd, timeout, cwd, headers, etc.).\n * Instead of duplicating, tasks reference a named template via `config-template`.\n * This function deep-merges the template into each task's config, then removes the reference.\n *\n * Pure function — returns a new config, never mutates.\n *\n * @example\n * ```ts\n * const config = {\n *   configTemplates: {\n *     PYTHON_TOOL: { cmd: 'python', timeout: 30000, cwd: '/workdata' }\n *   },\n *   tasks: {\n *     analyze: {\n *       provides: ['analysis'],\n *       config: { 'config-template': 'PYTHON_TOOL', 'cmd-args': 'analyze.py' }\n *     }\n *   }\n * };\n * const resolved = resolveConfigTemplates(config);\n * // analyze.config → { cmd: 'python', timeout: 30000, cwd: '/workdata', 'cmd-args': 'analyze.py' }\n * ```\n */\n\n/** Shape of a config-templates block */\nexport type ConfigTemplates = Record<string, Record<string, unknown>>;\n\n/**\n * Deep-merge template into task config.\n * Task-level values override template values.\n * Nested objects are merged one level deep (like SwarmX's pattern).\n */\nfunction mergeConfigs(\n  template: Record<string, unknown>,\n  taskConfig: Record<string, unknown>,\n): Record<string, unknown> {\n  const merged: Record<string, unknown> = { ...template };\n\n  for (const [key, value] of Object.entries(taskConfig)) {\n    if (key === 'config-template') continue; // strip the reference\n\n    // One-level deep merge for nested objects (both sides must be plain objects)\n    if (\n      value !== null &&\n      typeof value === 'object' &&\n      !Array.isArray(value) &&\n      merged[key] !== null &&\n      typeof merged[key] === 'object' &&\n      !Array.isArray(merged[key])\n    ) {\n      merged[key] = {\n        ...(merged[key] as Record<string, unknown>),\n        ...(value as Record<string, unknown>),\n      };\n    } else {\n      merged[key] = value;\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Resolve `config-template` references in task configs against a `configTemplates` map.\n *\n * Accepts any config object that may contain:\n *   - `configTemplates` (camelCase) or `config-templates` (kebab-case) at the top level\n *   - `tasks` (event-graph) or `steps` (step-machine) containing task/step objects\n *   - Each task/step may have a `config` sub-object with a `config-template` key\n *\n * Returns a new config with templates merged and references removed.\n * The `configTemplates` / `config-templates` key is also removed from the output.\n */\nexport function resolveConfigTemplates<T extends Record<string, unknown>>(config: T): T {\n  // Find templates — support both naming conventions\n  const templates: ConfigTemplates =\n    (config['configTemplates'] as ConfigTemplates) ??\n    (config['config-templates'] as ConfigTemplates) ??\n    {};\n\n  // Find the tasks/steps container\n  const tasksKey = 'tasks' in config ? 'tasks' : 'steps' in config ? 'steps' : null;\n  if (!tasksKey) return config; // nothing to resolve\n\n  const tasks = config[tasksKey] as Record<string, Record<string, unknown>> | undefined;\n  if (!tasks || typeof tasks !== 'object') return config;\n\n  const resolvedTasks: Record<string, Record<string, unknown>> = {};\n\n  for (const [name, task] of Object.entries(tasks)) {\n    const taskConfig = task['config'] as Record<string, unknown> | undefined;\n    const templateName = taskConfig?.['config-template'] as string | undefined;\n\n    if (!templateName || !taskConfig) {\n      resolvedTasks[name] = task;\n      continue;\n    }\n\n    const template = templates[templateName];\n    if (!template) {\n      // Template not found — leave as-is but strip the reference\n      const { 'config-template': _, ...rest } = taskConfig;\n      resolvedTasks[name] = { ...task, config: rest };\n      continue;\n    }\n\n    resolvedTasks[name] = {\n      ...task,\n      config: mergeConfigs(template, taskConfig),\n    };\n  }\n\n  // Build result — remove the templates key from output\n  const result = { ...config, [tasksKey]: resolvedTasks };\n  delete result['configTemplates'];\n  delete result['config-templates'];\n  return result as T;\n}\n"]}

package/dist/config/index.d.cts

@@ -0,0 +1,71 @@
+/**
+ * Variable interpolation for workflow configs.
+ *
+ * Walks any object/array and replaces `${KEY}` patterns with values from
+ * a variables map. Pure function — returns a new object, never mutates.
+ *
+ * Works on both GraphConfig and StepFlowConfig (or any plain object).
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveVariables(config, {
+ *   ENTITY_ID: 'ticket-42',
+ *   TOOLS_DIR: '/opt/tools',
+ * });
+ * ```
+ */
+type Variables = Record<string, string | number | boolean>;
+/**
+ * Resolve `${KEY}` variable references in a workflow config object.
+ *
+ * Pure function: config in → new config out. Works on any shape
+ * (GraphConfig, StepFlowConfig, or arbitrary objects).
+ *
+ * @param config  - The config object to interpolate
+ * @param variables - Key-value pairs to substitute
+ * @returns A new config with all `${KEY}` patterns replaced
+ */
+declare function resolveVariables<T extends Record<string, unknown>>(config: T, variables: Variables): T;
+
+/**
+ * Config template resolution for workflow configs.
+ *
+ * In large graphs, many tasks share the same base config (cmd, timeout, cwd, headers, etc.).
+ * Instead of duplicating, tasks reference a named template via `config-template`.
+ * This function deep-merges the template into each task's config, then removes the reference.
+ *
+ * Pure function — returns a new config, never mutates.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   configTemplates: {
+ *     PYTHON_TOOL: { cmd: 'python', timeout: 30000, cwd: '/workdata' }
+ *   },
+ *   tasks: {
+ *     analyze: {
+ *       provides: ['analysis'],
+ *       config: { 'config-template': 'PYTHON_TOOL', 'cmd-args': 'analyze.py' }
+ *     }
+ *   }
+ * };
+ * const resolved = resolveConfigTemplates(config);
+ * // analyze.config → { cmd: 'python', timeout: 30000, cwd: '/workdata', 'cmd-args': 'analyze.py' }
+ * ```
+ */
+/** Shape of a config-templates block */
+type ConfigTemplates = Record<string, Record<string, unknown>>;
+/**
+ * Resolve `config-template` references in task configs against a `configTemplates` map.
+ *
+ * Accepts any config object that may contain:
+ *   - `configTemplates` (camelCase) or `config-templates` (kebab-case) at the top level
+ *   - `tasks` (event-graph) or `steps` (step-machine) containing task/step objects
+ *   - Each task/step may have a `config` sub-object with a `config-template` key
+ *
+ * Returns a new config with templates merged and references removed.
+ * The `configTemplates` / `config-templates` key is also removed from the output.
+ */
+declare function resolveConfigTemplates<T extends Record<string, unknown>>(config: T): T;
+
+export { type ConfigTemplates, type Variables, resolveConfigTemplates, resolveVariables };

package/dist/config/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Variable interpolation for workflow configs.
+ *
+ * Walks any object/array and replaces `${KEY}` patterns with values from
+ * a variables map. Pure function — returns a new object, never mutates.
+ *
+ * Works on both GraphConfig and StepFlowConfig (or any plain object).
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveVariables(config, {
+ *   ENTITY_ID: 'ticket-42',
+ *   TOOLS_DIR: '/opt/tools',
+ * });
+ * ```
+ */
+type Variables = Record<string, string | number | boolean>;
+/**
+ * Resolve `${KEY}` variable references in a workflow config object.
+ *
+ * Pure function: config in → new config out. Works on any shape
+ * (GraphConfig, StepFlowConfig, or arbitrary objects).
+ *
+ * @param config  - The config object to interpolate
+ * @param variables - Key-value pairs to substitute
+ * @returns A new config with all `${KEY}` patterns replaced
+ */
+declare function resolveVariables<T extends Record<string, unknown>>(config: T, variables: Variables): T;
+
+/**
+ * Config template resolution for workflow configs.
+ *
+ * In large graphs, many tasks share the same base config (cmd, timeout, cwd, headers, etc.).
+ * Instead of duplicating, tasks reference a named template via `config-template`.
+ * This function deep-merges the template into each task's config, then removes the reference.
+ *
+ * Pure function — returns a new config, never mutates.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   configTemplates: {
+ *     PYTHON_TOOL: { cmd: 'python', timeout: 30000, cwd: '/workdata' }
+ *   },
+ *   tasks: {
+ *     analyze: {
+ *       provides: ['analysis'],
+ *       config: { 'config-template': 'PYTHON_TOOL', 'cmd-args': 'analyze.py' }
+ *     }
+ *   }
+ * };
+ * const resolved = resolveConfigTemplates(config);
+ * // analyze.config → { cmd: 'python', timeout: 30000, cwd: '/workdata', 'cmd-args': 'analyze.py' }
+ * ```
+ */
+/** Shape of a config-templates block */
+type ConfigTemplates = Record<string, Record<string, unknown>>;
+/**
+ * Resolve `config-template` references in task configs against a `configTemplates` map.
+ *
+ * Accepts any config object that may contain:
+ *   - `configTemplates` (camelCase) or `config-templates` (kebab-case) at the top level
+ *   - `tasks` (event-graph) or `steps` (step-machine) containing task/step objects
+ *   - Each task/step may have a `config` sub-object with a `config-template` key
+ *
+ * Returns a new config with templates merged and references removed.
+ * The `configTemplates` / `config-templates` key is also removed from the output.
+ */
+declare function resolveConfigTemplates<T extends Record<string, unknown>>(config: T): T;
+
+export { type ConfigTemplates, type Variables, resolveConfigTemplates, resolveVariables };

package/dist/config/index.js

@@ -0,0 +1,77 @@
+// src/config/resolve-variables.ts
+function interpolateString(template, vars) {
+  return template.replace(/\$\{([^}]+)\}/g, (match, key) => {
+    const value = vars[key.trim()];
+    return value !== void 0 ? String(value) : match;
+  });
+}
+function walkAndInterpolate(value, vars) {
+  if (typeof value === "string") {
+    return interpolateString(value, vars);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => walkAndInterpolate(item, vars));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = walkAndInterpolate(v, vars);
+    }
+    return result;
+  }
+  return value;
+}
+function resolveVariables(config, variables) {
+  return walkAndInterpolate(config, variables);
+}
+
+// src/config/resolve-config-templates.ts
+function mergeConfigs(template, taskConfig) {
+  const merged = { ...template };
+  for (const [key, value] of Object.entries(taskConfig)) {
+    if (key === "config-template") continue;
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && merged[key] !== null && typeof merged[key] === "object" && !Array.isArray(merged[key])) {
+      merged[key] = {
+        ...merged[key],
+        ...value
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function resolveConfigTemplates(config) {
+  const templates = config["configTemplates"] ?? config["config-templates"] ?? {};
+  const tasksKey = "tasks" in config ? "tasks" : "steps" in config ? "steps" : null;
+  if (!tasksKey) return config;
+  const tasks = config[tasksKey];
+  if (!tasks || typeof tasks !== "object") return config;
+  const resolvedTasks = {};
+  for (const [name, task] of Object.entries(tasks)) {
+    const taskConfig = task["config"];
+    const templateName = taskConfig?.["config-template"];
+    if (!templateName || !taskConfig) {
+      resolvedTasks[name] = task;
+      continue;
+    }
+    const template = templates[templateName];
+    if (!template) {
+      const { "config-template": _, ...rest } = taskConfig;
+      resolvedTasks[name] = { ...task, config: rest };
+      continue;
+    }
+    resolvedTasks[name] = {
+      ...task,
+      config: mergeConfigs(template, taskConfig)
+    };
+  }
+  const result = { ...config, [tasksKey]: resolvedTasks };
+  delete result["configTemplates"];
+  delete result["config-templates"];
+  return result;
+}
+
+export { resolveConfigTemplates, resolveVariables };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/resolve-variables.ts","../../src/config/resolve-config-templates.ts"],"names":[],"mappings":";AAuBA,SAAS,iBAAA,CAAkB,UAAkB,IAAA,EAAyB;AACpE,EAAA,OAAO,QAAA,CAAS,OAAA,CAAQ,gBAAA,EAAkB,CAAC,OAAO,GAAA,KAAgB;AAChE,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,GAAA,CAAI,IAAA,EAAM,CAAA;AAC7B,IAAA,OAAO,KAAA,KAAU,MAAA,GAAY,MAAA,CAAO,KAAK,CAAA,GAAI,KAAA;AAAA,EAC/C,CAAC,CAAA;AACH;AAMA,SAAS,kBAAA,CAAsB,OAAU,IAAA,EAAoB;AAC3D,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,IAAA,OAAO,iBAAA,CAAkB,OAAO,IAAI,CAAA;AAAA,EACtC;AACA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACxB,IAAA,OAAO,MAAM,GAAA,CAAI,CAAC,SAAS,kBAAA,CAAmB,IAAA,EAAM,IAAI,CAAC,CAAA;AAAA,EAC3D;AACA,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,QAAA,EAAU;AAC/C,IAAA,MAAM,SAAkC,EAAC;AACzC,IAAA,KAAA,MAAW,CAAC,CAAA,EAAG,CAAC,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AAC1C,MAAA,MAAA,CAAO,CAAC,CAAA,GAAI,kBAAA,CAAmB,CAAA,EAAG,IAAI,CAAA;AAAA,IACxC;AACA,IAAA,OAAO,MAAA;AAAA,EACT;AAEA,EAAA,OAAO,KAAA;AACT;AAYO,SAAS,gBAAA,CACd,QACA,SAAA,EACG;AACH,EAAA,OAAO,kBAAA,CAAmB,QAAQ,SAAS,CAAA;AAC7C;;;AChCA,SAAS,YAAA,CACP,UACA,UAAA,EACyB;AACzB,EAAA,MAAM,MAAA,GAAkC,EAAE,GAAG,QAAA,EAAS;AAEtD,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,UAAU,CAAA,EAAG;AACrD,IAAA,IAAI,QAAQ,iBAAA,EAAmB;AAG/B,IAAA,IACE,KAAA,KAAU,IAAA,IACV,OAAO,KAAA,KAAU,QAAA,IACjB,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,IACpB,MAAA,CAAO,GAAG,MAAM,IAAA,IAChB,OAAO,MAAA,CAAO,GAAG,CAAA,KAAM,QAAA,IACvB,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAA,CAAO,GAAG,CAAC,CAAA,EAC1B;AACA,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI;AAAA,QACZ,GAAI,OAAO,GAAG,CAAA;AAAA,QACd,GAAI;AAAA,OACN;AAAA,IACF,CAAA,MAAO;AACL,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,KAAA;AAAA,IAChB;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AAaO,SAAS,uBAA0D,MAAA,EAAc;AAEtF,EAAA,MAAM,YACH,MAAA,CAAO,iBAAiB,KACxB,MAAA,CAAO,kBAAkB,KAC1B,EAAC;AAGH,EAAA,MAAM,WAAW,OAAA,IAAW,MAAA,GAAS,OAAA,GAAU,OAAA,IAAW,SAAS,OAAA,GAAU,IAAA;AAC7E,EAAA,IAAI,CAAC,UAAU,OAAO,MAAA;AAEtB,EAAA,MAAM,KAAA,GAAQ,OAAO,QAAQ,CAAA;AAC7B,EAAA,IAAI,CAAC,KAAA,IAAS,OAAO,KAAA,KAAU,UAAU,OAAO,MAAA;AAEhD,EAAA,MAAM,gBAAyD,EAAC;AAEhE,EAAA,KAAA,MAAW,CAAC,IAAA,EAAM,IAAI,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AAChD,IAAA,MAAM,UAAA,GAAa,KAAK,QAAQ,CAAA;AAChC,IAAA,MAAM,YAAA,GAAe,aAAa,iBAAiB,CAAA;AAEnD,IAAA,IAAI,CAAC,YAAA,IAAgB,CAAC,UAAA,EAAY;AAChC,MAAA,aAAA,CAAc,IAAI,CAAA,GAAI,IAAA;AACtB,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,QAAA,GAAW,UAAU,YAAY,CAAA;AACvC,IAAA,IAAI,CAAC,QAAA,EAAU;AAEb,MAAA,MAAM,EAAE,iBAAA,EAAmB,CAAA,EAAG,GAAG,MAAK,GAAI,UAAA;AAC1C,MAAA,aAAA,CAAc,IAAI,CAAA,GAAI,EAAE,GAAG,IAAA,EAAM,QAAQ,IAAA,EAAK;AAC9C,MAAA;AAAA,IACF;AAEA,IAAA,aAAA,CAAc,IAAI,CAAA,GAAI;AAAA,MACpB,GAAG,IAAA;AAAA,MACH,MAAA,EAAQ,YAAA,CAAa,QAAA,EAAU,UAAU;AAAA,KAC3C;AAAA,EACF;AAGA,EAAA,MAAM,SAAS,EAAE,GAAG,QAAQ,CAAC,QAAQ,GAAG,aAAA,EAAc;AACtD,EAAA,OAAO,OAAO,iBAAiB,CAAA;AAC/B,EAAA,OAAO,OAAO,kBAAkB,CAAA;AAChC,EAAA,OAAO,MAAA;AACT","file":"index.js","sourcesContent":["/**\n * Variable interpolation for workflow configs.\n *\n * Walks any object/array and replaces `${KEY}` patterns with values from\n * a variables map. Pure function — returns a new object, never mutates.\n *\n * Works on both GraphConfig and StepFlowConfig (or any plain object).\n *\n * @example\n * ```ts\n * const resolved = resolveVariables(config, {\n *   ENTITY_ID: 'ticket-42',\n *   TOOLS_DIR: '/opt/tools',\n * });\n * ```\n */\n\nexport type Variables = Record<string, string | number | boolean>;\n\n/**\n * Replace `${KEY}` patterns in a string with values from the variables map.\n * Unmatched variables are left as-is.\n */\nfunction interpolateString(template: string, vars: Variables): string {\n  return template.replace(/\\$\\{([^}]+)\\}/g, (match, key: string) => {\n    const value = vars[key.trim()];\n    return value !== undefined ? String(value) : match;\n  });\n}\n\n/**\n * Recursively walk a value and interpolate any `${KEY}` patterns found in strings.\n * Returns a new object/array — never mutates the input.\n */\nfunction walkAndInterpolate<T>(value: T, vars: Variables): T {\n  if (typeof value === 'string') {\n    return interpolateString(value, vars) as unknown as T;\n  }\n  if (Array.isArray(value)) {\n    return value.map((item) => walkAndInterpolate(item, vars)) as unknown as T;\n  }\n  if (value !== null && typeof value === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [k, v] of Object.entries(value)) {\n      result[k] = walkAndInterpolate(v, vars);\n    }\n    return result as T;\n  }\n  // numbers, booleans, null, undefined — pass through\n  return value;\n}\n\n/**\n * Resolve `${KEY}` variable references in a workflow config object.\n *\n * Pure function: config in → new config out. Works on any shape\n * (GraphConfig, StepFlowConfig, or arbitrary objects).\n *\n * @param config  - The config object to interpolate\n * @param variables - Key-value pairs to substitute\n * @returns A new config with all `${KEY}` patterns replaced\n */\nexport function resolveVariables<T extends Record<string, unknown>>(\n  config: T,\n  variables: Variables,\n): T {\n  return walkAndInterpolate(config, variables);\n}\n","/**\n * Config template resolution for workflow configs.\n *\n * In large graphs, many tasks share the same base config (cmd, timeout, cwd, headers, etc.).\n * Instead of duplicating, tasks reference a named template via `config-template`.\n * This function deep-merges the template into each task's config, then removes the reference.\n *\n * Pure function — returns a new config, never mutates.\n *\n * @example\n * ```ts\n * const config = {\n *   configTemplates: {\n *     PYTHON_TOOL: { cmd: 'python', timeout: 30000, cwd: '/workdata' }\n *   },\n *   tasks: {\n *     analyze: {\n *       provides: ['analysis'],\n *       config: { 'config-template': 'PYTHON_TOOL', 'cmd-args': 'analyze.py' }\n *     }\n *   }\n * };\n * const resolved = resolveConfigTemplates(config);\n * // analyze.config → { cmd: 'python', timeout: 30000, cwd: '/workdata', 'cmd-args': 'analyze.py' }\n * ```\n */\n\n/** Shape of a config-templates block */\nexport type ConfigTemplates = Record<string, Record<string, unknown>>;\n\n/**\n * Deep-merge template into task config.\n * Task-level values override template values.\n * Nested objects are merged one level deep (like SwarmX's pattern).\n */\nfunction mergeConfigs(\n  template: Record<string, unknown>,\n  taskConfig: Record<string, unknown>,\n): Record<string, unknown> {\n  const merged: Record<string, unknown> = { ...template };\n\n  for (const [key, value] of Object.entries(taskConfig)) {\n    if (key === 'config-template') continue; // strip the reference\n\n    // One-level deep merge for nested objects (both sides must be plain objects)\n    if (\n      value !== null &&\n      typeof value === 'object' &&\n      !Array.isArray(value) &&\n      merged[key] !== null &&\n      typeof merged[key] === 'object' &&\n      !Array.isArray(merged[key])\n    ) {\n      merged[key] = {\n        ...(merged[key] as Record<string, unknown>),\n        ...(value as Record<string, unknown>),\n      };\n    } else {\n      merged[key] = value;\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Resolve `config-template` references in task configs against a `configTemplates` map.\n *\n * Accepts any config object that may contain:\n *   - `configTemplates` (camelCase) or `config-templates` (kebab-case) at the top level\n *   - `tasks` (event-graph) or `steps` (step-machine) containing task/step objects\n *   - Each task/step may have a `config` sub-object with a `config-template` key\n *\n * Returns a new config with templates merged and references removed.\n * The `configTemplates` / `config-templates` key is also removed from the output.\n */\nexport function resolveConfigTemplates<T extends Record<string, unknown>>(config: T): T {\n  // Find templates — support both naming conventions\n  const templates: ConfigTemplates =\n    (config['configTemplates'] as ConfigTemplates) ??\n    (config['config-templates'] as ConfigTemplates) ??\n    {};\n\n  // Find the tasks/steps container\n  const tasksKey = 'tasks' in config ? 'tasks' : 'steps' in config ? 'steps' : null;\n  if (!tasksKey) return config; // nothing to resolve\n\n  const tasks = config[tasksKey] as Record<string, Record<string, unknown>> | undefined;\n  if (!tasks || typeof tasks !== 'object') return config;\n\n  const resolvedTasks: Record<string, Record<string, unknown>> = {};\n\n  for (const [name, task] of Object.entries(tasks)) {\n    const taskConfig = task['config'] as Record<string, unknown> | undefined;\n    const templateName = taskConfig?.['config-template'] as string | undefined;\n\n    if (!templateName || !taskConfig) {\n      resolvedTasks[name] = task;\n      continue;\n    }\n\n    const template = templates[templateName];\n    if (!template) {\n      // Template not found — leave as-is but strip the reference\n      const { 'config-template': _, ...rest } = taskConfig;\n      resolvedTasks[name] = { ...task, config: rest };\n      continue;\n    }\n\n    resolvedTasks[name] = {\n      ...task,\n      config: mergeConfigs(template, taskConfig),\n    };\n  }\n\n  // Build result — remove the templates key from output\n  const result = { ...config, [tasksKey]: resolvedTasks };\n  delete result['configTemplates'];\n  delete result['config-templates'];\n  return result as T;\n}\n"]}