@ema.co/mcp-toolkit 2026.2.13 → 2026.2.19

package/dist/mcp/domain/workflow-merge.js

@@ -1,449 +0,0 @@
-/**
- * Workflow Merge Module
- *
- * Provides workflow comparison, merging, and validation utilities for
- * brownfield workflow updates. Extracted from server.ts for better
- * testability and separation of concerns.
- *
- * @module sdk/workflow-merge
- */
-// ─────────────────────────────────────────────────────────────────────────────
-// Internal Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Extract a clean enum name from the nested structure.
- * Handles: {name: {name: {name: "foo"}}} or {name: {name: "foo"}} or "foo"
- */
-function extractEnumName(enumNameObj) {
-    if (typeof enumNameObj === "string")
-        return enumNameObj;
-    if (!enumNameObj || typeof enumNameObj !== "object")
-        return "";
-    const obj = enumNameObj;
-    if (obj.name)
-        return extractEnumName(obj.name);
-    return "";
-}
-/**
- * Extract node action type from the action structure.
- * Handles: {name: {namespaces: [...], name: "type"}} or {name: {name: "type"}}
- */
-function extractActionType(action) {
-    if (!action || typeof action !== "object")
-        return "";
-    const obj = action;
-    // Try action.name.name (nested structure)
-    if (obj.name && typeof obj.name === "object") {
-        const nameObj = obj.name;
-        if (typeof nameObj.name === "string")
-            return nameObj.name;
-    }
-    // Try direct name
-    if (typeof obj.name === "string")
-        return obj.name;
-    return "";
-}
-/**
- * Parse a workflow into normalized node structures.
- * @internal Used by compareWorkflows and mergeWorkflows
- */
-function parseWorkflowNodes(workflow) {
-    const nodes = new Map();
-    if (!workflow)
-        return nodes;
-    const actions = workflow.actions;
-    if (!actions)
-        return nodes;
-    for (const action of actions) {
-        const name = String(action.name ?? "");
-        if (!name)
-            continue;
-        nodes.set(name, {
-            name,
-            actionType: extractActionType(action.action ?? action.actionType),
-            inputs: action.inputs ?? {},
-            runIf: action.runIf,
-            typeArguments: action.typeArguments,
-        });
-    }
-    return nodes;
-}
-/**
- * Parse a workflow's enum types into normalized structures.
- * @internal Used by compareWorkflows and mergeWorkflows
- */
-function parseWorkflowEnums(workflow) {
-    const enums = new Map();
-    if (!workflow)
-        return enums;
-    const enumTypes = workflow.enumTypes;
-    if (!enumTypes)
-        return enums;
-    for (const enumType of enumTypes) {
-        const fullName = enumType.name;
-        const name = extractEnumName(fullName);
-        if (!name)
-            continue;
-        const options = enumType.options ?? [];
-        enums.set(name, {
-            name,
-            fullName,
-            options,
-        });
-    }
-    return enums;
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Public API
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Compare two workflows and produce a diff.
- *
- * @param existing - The existing workflow to compare against
- * @param incoming - The incoming workflow with changes
- * @returns A diff object describing all changes between the workflows
- */
-export function compareWorkflows(existing, incoming) {
-    // Guard against null/undefined inputs
-    if (!existing || typeof existing !== "object") {
-        existing = {};
-    }
-    if (!incoming || typeof incoming !== "object") {
-        incoming = {};
-    }
-    const existingNodes = parseWorkflowNodes(existing);
-    const incomingNodes = parseWorkflowNodes(incoming);
-    const existingEnums = parseWorkflowEnums(existing);
-    const incomingEnums = parseWorkflowEnums(incoming);
-    // Node comparison
-    const nodesAdded = [];
-    const nodesRemoved = [];
-    const nodesModified = [];
-    const nodesUnchanged = [];
-    const conflicts = [];
-    // Check existing nodes
-    for (const [name, existingNode] of existingNodes) {
-        const incomingNode = incomingNodes.get(name);
-        if (!incomingNode) {
-            nodesRemoved.push(name);
-        }
-        else if (existingNode.actionType !== incomingNode.actionType) {
-            // Type mismatch - this is a conflict
-            conflicts.push({
-                type: "node_type_mismatch",
-                node: name,
-                message: `Node "${name}" has different types: existing="${existingNode.actionType}", incoming="${incomingNode.actionType}"`,
-            });
-            nodesModified.push(name);
-        }
-        else if (JSON.stringify(existingNode) !== JSON.stringify(incomingNode)) {
-            nodesModified.push(name);
-        }
-        else {
-            nodesUnchanged.push(name);
-        }
-    }
-    // Check for new nodes
-    for (const [name] of incomingNodes) {
-        if (!existingNodes.has(name)) {
-            nodesAdded.push(name);
-        }
-    }
-    // Enum comparison
-    const enumsAdded = [];
-    const enumsRemoved = [];
-    const enumsModified = [];
-    const enumsUnchanged = [];
-    for (const [name, existingEnum] of existingEnums) {
-        const incomingEnum = incomingEnums.get(name);
-        if (!incomingEnum) {
-            enumsRemoved.push(name);
-        }
-        else {
-            // Compare options
-            const existingOpts = existingEnum.options.map((o) => o.name).sort().join(",");
-            const incomingOpts = incomingEnum.options.map((o) => o.name).sort().join(",");
-            if (existingOpts !== incomingOpts) {
-                enumsModified.push(name);
-            }
-            else {
-                enumsUnchanged.push(name);
-            }
-        }
-    }
-    for (const [name] of incomingEnums) {
-        if (!existingEnums.has(name)) {
-            enumsAdded.push(name);
-        }
-    }
-    // Results comparison
-    const existingResults = Object.keys(existing.results ?? {});
-    const incomingResults = Object.keys(incoming.results ?? {});
-    const resultsAdded = incomingResults.filter((r) => !existingResults.includes(r));
-    const resultsRemoved = existingResults.filter((r) => !incomingResults.includes(r));
-    // Structural analysis
-    const hasHitlNodes = [...incomingNodes.values()].some((n) => n.actionType.includes("hitl") || n.actionType.includes("general_hitl")) || nodesAdded.some((name) => name.includes("hitl"));
-    const hasCategorizerChanges = enumsAdded.length > 0 || enumsModified.length > 0;
-    // Check for broken references (nodes referencing removed nodes)
-    for (const [name, node] of incomingNodes) {
-        const inputs = node.inputs;
-        for (const [inputKey, binding] of Object.entries(inputs)) {
-            const actionOutput = binding?.actionOutput;
-            if (actionOutput) {
-                const refNodeName = String(actionOutput.actionName ?? "");
-                if (refNodeName && !incomingNodes.has(refNodeName)) {
-                    conflicts.push({
-                        type: "reference_broken",
-                        node: name,
-                        message: `Node "${name}" references non-existent node "${refNodeName}" in input "${inputKey}"`,
-                    });
-                }
-            }
-        }
-        // Check runIf references
-        if (node.runIf) {
-            const lhs = node.runIf.lhs;
-            const actionOutput = lhs?.actionOutput;
-            if (actionOutput) {
-                const refNodeName = String(actionOutput.actionName ?? "");
-                if (refNodeName && !incomingNodes.has(refNodeName)) {
-                    conflicts.push({
-                        type: "reference_broken",
-                        node: name,
-                        message: `Node "${name}" runIf references non-existent node "${refNodeName}"`,
-                    });
-                }
-            }
-        }
-    }
-    return {
-        nodesAdded,
-        nodesRemoved,
-        nodesModified,
-        nodesUnchanged,
-        enumsAdded,
-        enumsRemoved,
-        enumsModified,
-        enumsUnchanged,
-        resultsAdded,
-        resultsRemoved,
-        hasHitlNodes,
-        hasCategorizerChanges,
-        conflicts,
-    };
-}
-/**
- * Merge an incoming workflow into an existing one intelligently.
- *
- * Strategy:
- * - Preserve existing workflowName (required by backend)
- * - For nodes: add new nodes, update modified nodes, keep unchanged nodes
- * - For enums: merge enum options (add new options, keep existing)
- * - For results: merge result mappings
- * - Detect conflicts and route to Autobuilder if HITL involved
- *
- * @param existing - The existing workflow
- * @param incoming - The incoming workflow with changes
- * @param options - Merge options
- * @returns The merge result including the merged workflow and any conflicts
- */
-export function mergeWorkflows(existing, incoming, options = {}) {
-    // Guard against null/undefined inputs
-    if (!existing || typeof existing !== "object") {
-        existing = {};
-    }
-    if (!incoming || typeof incoming !== "object") {
-        incoming = {};
-    }
-    const diff = compareWorkflows(existing, incoming);
-    const warnings = [];
-    const errors = [];
-    // Check for fatal conflicts
-    const fatalConflicts = diff.conflicts.filter((c) => c.type === "node_type_mismatch");
-    if (fatalConflicts.length > 0 && !options.forceReplace) {
-        return {
-            success: false,
-            mergedWorkflow: existing,
-            diff,
-            warnings,
-            errors: fatalConflicts.map((c) => c.message),
-            requiresAutobuilder: true,
-            description: `Cannot merge: ${fatalConflicts.length} node type mismatch(es)`,
-        };
-    }
-    // Start with a deep copy of the incoming workflow
-    const merged = JSON.parse(JSON.stringify(incoming));
-    // Preserve existing workflowName (critical for backend validation)
-    if (existing.workflowName) {
-        merged.workflowName = JSON.parse(JSON.stringify(existing.workflowName));
-    }
-    // Get parsed structures
-    const existingNodes = parseWorkflowNodes(existing);
-    const existingEnums = parseWorkflowEnums(existing);
-    const incomingEnums = parseWorkflowEnums(incoming);
-    // === ENUM MERGING ===
-    // Merge enum types: keep existing structure but add new options
-    const mergedEnumTypes = [];
-    const processedEnums = new Set();
-    // Process existing enums first
-    for (const [name, existingEnum] of existingEnums) {
-        const incomingEnum = incomingEnums.get(name);
-        processedEnums.add(name);
-        if (incomingEnum) {
-            // Merge options: keep all existing, add any new from incoming
-            const existingOptNames = new Set(existingEnum.options.map((o) => o.name));
-            const mergedOptions = [...existingEnum.options];
-            for (const opt of incomingEnum.options) {
-                if (!existingOptNames.has(opt.name)) {
-                    mergedOptions.push(opt);
-                    warnings.push(`Added new option "${opt.name}" to enum "${name}"`);
-                }
-            }
-            mergedEnumTypes.push({
-                name: existingEnum.fullName, // Use existing nested structure
-                options: mergedOptions,
-            });
-        }
-        else {
-            // Keep existing enum as-is
-            mergedEnumTypes.push({
-                name: existingEnum.fullName,
-                options: existingEnum.options,
-            });
-            warnings.push(`Kept existing enum "${name}" (not in incoming workflow)`);
-        }
-    }
-    // Add new enums from incoming
-    for (const [name, incomingEnum] of incomingEnums) {
-        if (!processedEnums.has(name)) {
-            mergedEnumTypes.push({
-                name: incomingEnum.fullName,
-                options: incomingEnum.options,
-            });
-            warnings.push(`Added new enum "${name}"`);
-        }
-    }
-    merged.enumTypes = mergedEnumTypes;
-    // === NODE MERGING ===
-    // If preserveExistingNodes is true, keep existing nodes that aren't in incoming
-    if (options.preserveExistingNodes && diff.nodesRemoved.length > 0) {
-        const existingActions = existing.actions;
-        const mergedActions = merged.actions;
-        if (existingActions && mergedActions) {
-            for (const nodeName of diff.nodesRemoved) {
-                const existingAction = existingActions.find((a) => String(a.name) === nodeName);
-                if (existingAction) {
-                    mergedActions.push(JSON.parse(JSON.stringify(existingAction)));
-                    warnings.push(`Preserved existing node "${nodeName}" (not in incoming workflow)`);
-                }
-            }
-        }
-    }
-    // === RESULTS MERGING ===
-    // Merge results: combine both existing and incoming
-    const existingResults = existing.results ?? {};
-    const incomingResults = incoming.results ?? {};
-    const mergedResults = {
-        ...existingResults,
-        ...incomingResults, // Incoming takes precedence
-    };
-    merged.results = mergedResults;
-    // Check for broken references after merge
-    const brokenRefs = diff.conflicts.filter((c) => c.type === "reference_broken");
-    if (brokenRefs.length > 0) {
-        errors.push(...brokenRefs.map((c) => c.message));
-    }
-    // Generate description
-    const descParts = [];
-    if (diff.nodesAdded.length > 0)
-        descParts.push(`+${diff.nodesAdded.length} nodes`);
-    if (diff.nodesRemoved.length > 0)
-        descParts.push(`-${diff.nodesRemoved.length} nodes`);
-    if (diff.nodesModified.length > 0)
-        descParts.push(`~${diff.nodesModified.length} modified`);
-    if (diff.enumsAdded.length > 0)
-        descParts.push(`+${diff.enumsAdded.length} enums`);
-    if (diff.enumsModified.length > 0)
-        descParts.push(`~${diff.enumsModified.length} enums`);
-    const description = descParts.length > 0
-        ? `Brownfield merge: ${descParts.join(", ")}`
-        : "No changes detected";
-    return {
-        success: errors.length === 0,
-        mergedWorkflow: merged,
-        diff,
-        warnings,
-        errors,
-        requiresAutobuilder: diff.hasHitlNodes,
-        description,
-    };
-}
-/**
- * Validate a merged workflow for deployment readiness.
- *
- * @param merged - The merged workflow to validate
- * @returns Validation result with any issues found
- */
-export function validateMergedWorkflow(merged) {
-    const issues = [];
-    // Guard against null/undefined input
-    if (!merged || typeof merged !== "object") {
-        return { valid: false, issues: ["Workflow is null or undefined"] };
-    }
-    const nodes = parseWorkflowNodes(merged);
-    const enums = parseWorkflowEnums(merged);
-    // Check 1: All referenced nodes exist
-    for (const [name, node] of nodes) {
-        // Check input references
-        for (const [inputKey, binding] of Object.entries(node.inputs)) {
-            const actionOutput = binding?.actionOutput;
-            if (actionOutput) {
-                const refNodeName = String(actionOutput.actionName ?? "");
-                if (refNodeName && !nodes.has(refNodeName) && refNodeName !== "trigger") {
-                    // Special case: "trigger" is always valid
-                    issues.push(`Node "${name}" references non-existent node "${refNodeName}" in input "${inputKey}"`);
-                }
-            }
-        }
-        // Check runIf references
-        if (node.runIf) {
-            const lhs = node.runIf.lhs;
-            const actionOutput = lhs?.actionOutput;
-            if (actionOutput) {
-                const refNodeName = String(actionOutput.actionName ?? "");
-                if (refNodeName && !nodes.has(refNodeName) && refNodeName !== "trigger") {
-                    issues.push(`Node "${name}" runIf references non-existent node "${refNodeName}"`);
-                }
-            }
-        }
-        // Check typeArguments enum references
-        if (node.typeArguments) {
-            const categories = node.typeArguments.categories;
-            const enumType = categories?.enumType;
-            if (enumType) {
-                const enumName = extractEnumName(enumType.name);
-                if (enumName && !enums.has(enumName)) {
-                    issues.push(`Node "${name}" references non-existent enum "${enumName}"`);
-                }
-            }
-        }
-    }
-    // Check 2: At least one trigger node exists
-    const hasTrigger = [...nodes.values()].some((n) => n.actionType.includes("trigger") || n.name === "trigger");
-    if (!hasTrigger && nodes.size > 0) {
-        issues.push("Workflow has no trigger node");
-    }
-    // Check 3: Results reference existing nodes
-    const results = merged.results;
-    if (results) {
-        for (const [resultKey, mapping] of Object.entries(results)) {
-            if (mapping.actionName && !nodes.has(mapping.actionName)) {
-                issues.push(`Result "${resultKey}" references non-existent node "${mapping.actionName}"`);
-            }
-        }
-    }
-    return {
-        valid: issues.length === 0,
-        issues,
-    };
-}