@generacy-ai/workflow-engine 0.0.0-preview-20260304013206

package/dist/loader/index.js

@@ -0,0 +1,190 @@
+/**
+ * Workflow YAML loader.
+ * Loads and parses workflow definition files.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { validateWorkflow } from './validator.js';
+import { mergeWorkflows } from './extends.js';
+import { BaseWorkflowNotFoundError } from '../errors/base-workflow-not-found.js';
+import { CircularExtendsError } from '../errors/circular-extends.js';
+import { WorkflowOverrideError } from '../errors/workflow-override.js';
+/**
+ * Load a workflow from a YAML file
+ * @param filePath Path to the workflow YAML file
+ * @returns Parsed and validated WorkflowDefinition
+ * @throws Error if file cannot be read or validation fails
+ */
+export async function loadWorkflow(filePath) {
+    // Read file content
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Workflow file not found: ${filePath}`);
+        }
+        throw new Error(`Failed to read workflow file: ${error.message}`);
+    }
+    // Parse YAML
+    let data;
+    try {
+        data = parseYaml(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse workflow YAML: ${error.message}`);
+    }
+    // Validate and return
+    return validateWorkflow(data);
+}
+/**
+ * Load a workflow from a YAML string
+ * @param content YAML content string
+ * @returns Parsed and validated WorkflowDefinition
+ */
+export function loadWorkflowFromString(content) {
+    // Parse YAML
+    let data;
+    try {
+        data = parseYaml(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse workflow YAML: ${error.message}`);
+    }
+    // Validate and return
+    return validateWorkflow(data);
+}
+/**
+ * Convert a WorkflowDefinition to an ExecutableWorkflow
+ * @param definition The workflow definition
+ * @param inputs Runtime input values
+ * @param env Additional environment variables
+ * @returns ExecutableWorkflow ready for execution
+ */
+export function prepareWorkflow(definition, inputs, env) {
+    // Merge environment variables
+    const mergedEnv = {
+        ...definition.env,
+        ...env,
+    };
+    // Resolve input defaults
+    const resolvedInputs = {};
+    if (definition.inputs) {
+        for (const inputDef of definition.inputs) {
+            const value = inputs?.[inputDef.name] ?? inputDef.default;
+            if (inputDef.required && value === undefined) {
+                throw new Error(`Required input missing: ${inputDef.name}`);
+            }
+            if (value !== undefined) {
+                resolvedInputs[inputDef.name] = value;
+            }
+        }
+    }
+    // Also include any inputs not defined in the schema
+    if (inputs) {
+        for (const [key, value] of Object.entries(inputs)) {
+            if (!(key in resolvedInputs)) {
+                resolvedInputs[key] = value;
+            }
+        }
+    }
+    return {
+        name: definition.name,
+        description: definition.description,
+        phases: definition.phases,
+        env: mergedEnv,
+        timeout: definition.timeout,
+    };
+}
+/**
+ * Load a workflow with `extends` inheritance support.
+ *
+ * Uses two-pass validation:
+ *   1. Parse YAML loosely (no schema validation)
+ *   2. If `extends` present, resolve base, recurse, merge
+ *   3. Validate final merged result against WorkflowDefinitionSchema
+ *
+ * @param filePath - Path to the workflow YAML file
+ * @param resolver - Function to resolve workflow names to file paths
+ * @param _seen - Internal: set of resolved file paths for circular detection
+ * @returns Parsed, merged, and validated WorkflowDefinition
+ */
+export async function loadWorkflowWithExtends(filePath, resolver, _seen) {
+    const resolvedPath = resolve(filePath);
+    // Circular detection
+    const seen = _seen ?? new Set();
+    if (seen.has(resolvedPath)) {
+        throw new CircularExtendsError([...seen, resolvedPath]);
+    }
+    seen.add(resolvedPath);
+    // Read and parse YAML loosely (no schema validation yet)
+    let content;
+    try {
+        content = await readFile(resolvedPath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Workflow file not found: ${resolvedPath}`);
+        }
+        throw new Error(`Failed to read workflow file: ${error.message}`);
+    }
+    let data;
+    try {
+        data = parseYaml(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse workflow YAML: ${error.message}`);
+    }
+    // Validate: `overrides` without `extends` is always a mistake
+    if (data.overrides && !data.extends) {
+        throw new WorkflowOverrideError('"overrides" block requires "extends" — cannot use overrides without a base workflow.');
+    }
+    // Validate: `extends` + both `phases` and `overrides.phases` is ambiguous
+    if (data.extends && data.phases && data.overrides?.phases) {
+        throw new WorkflowOverrideError('Cannot specify both "phases" and "overrides.phases" when using "extends" — use "phases" for full replacement or "overrides.phases" for selective override, not both.');
+    }
+    // No extends: validate with existing path and return
+    if (!data.extends) {
+        return validateWorkflow(data);
+    }
+    // Resolve the base workflow
+    const extendsName = data.extends;
+    let basePath;
+    try {
+        basePath = resolver(extendsName, resolvedPath);
+    }
+    catch (error) {
+        if (error instanceof BaseWorkflowNotFoundError) {
+            throw error;
+        }
+        throw new BaseWorkflowNotFoundError(extendsName, []);
+    }
+    // Recurse into the base workflow (may itself have extends)
+    const baseDefinition = await loadWorkflowWithExtends(basePath, resolver, seen);
+    // Extract override data from the extending workflow's YAML
+    const overrideData = {};
+    if (data.name !== undefined)
+        overrideData.name = data.name;
+    if (data.description !== undefined)
+        overrideData.description = data.description;
+    if (data.version !== undefined)
+        overrideData.version = data.version;
+    if (data.timeout !== undefined)
+        overrideData.timeout = data.timeout;
+    if (data.retry !== undefined)
+        overrideData.retry = data.retry;
+    if (data.phases !== undefined)
+        overrideData.phases = data.phases;
+    if (data.overrides !== undefined)
+        overrideData.overrides = data.overrides;
+    // Merge base + overrides
+    const merged = mergeWorkflows(baseDefinition, overrideData);
+    // Validate the merged result against the strict schema
+    return validateWorkflow(merged);
+}
+// Re-export validation utilities
+export { validateWorkflow, isValidWorkflow, WorkflowValidationError } from './validator.js';
+export { WorkflowDefinitionSchema, PhaseDefinitionSchema, StepDefinitionSchema, InputDefinitionSchema, RetryConfigSchema, } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/loader/index.js.map

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