ugcinc 4.0.2 → 4.1.1

package/dist/graph-controller.js

@@ -0,0 +1,656 @@
+"use strict";
+/**
+ * Graph Controller
+ *
+ * Centralized logic for automation graph management including:
+ * - Port computation
+ * - Connection management
+ * - Type compatibility checking
+ * - Workflow validation
+ * - For-each context validation
+ *
+ * All functions work with WorkflowNodeDefinition[] (embedded connection format).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areTypesCompatible = areTypesCompatible;
+exports.computePortsForNode = computePortsForNode;
+exports.getAllNodes = getAllNodes;
+exports.getNodeByType = getNodeByType;
+exports.getOutputSchema = getOutputSchema;
+exports.deriveConnections = deriveConnections;
+exports.addConnection = addConnection;
+exports.removeConnection = removeConnection;
+exports.removeNodeConnections = removeNodeConnections;
+exports.cleanupStaleConnections = cleanupStaleConnections;
+exports.getForEachContext = getForEachContext;
+exports.checkCrossContextViolation = checkCrossContextViolation;
+exports.validateWorkflow = validateWorkflow;
+exports.getErrorNodeIds = getErrorNodeIds;
+exports.getPortErrorsForNode = getPortErrorsForNode;
+exports.hasMissingTriggerError = hasMissingTriggerError;
+exports.hasMissingTerminalError = hasMissingTerminalError;
+exports.resolveNodePreview = resolveNodePreview;
+const types_1 = require("./automations/types");
+const nodes_1 = require("./automations/nodes");
+// ===========================================================================
+// Internal Helpers (not exported)
+// ===========================================================================
+/**
+ * Helper to check if a port type is a union (array of BasePortTypes)
+ */
+function isTypeUnion(type) {
+    return Array.isArray(type);
+}
+/**
+ * Extract template variables from text (e.g., "Hello {{name}}" -> ["name"])
+ */
+function extractTemplateVariables(texts) {
+    const variables = new Set();
+    const regex = /\{\{(\w+)\}\}/g;
+    for (const text of texts) {
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            if (match[1])
+                variables.add(match[1]);
+        }
+    }
+    return Array.from(variables);
+}
+/**
+ * Derive Connection[] array from nodes for internal processing
+ * Connections are stored in the embedded inputs map format.
+ */
+function deriveConnectionsInternal(nodes) {
+    const connections = [];
+    nodes.forEach(node => {
+        if (!node.inputs)
+            return;
+        Object.entries(node.inputs).forEach(([inputId, mapping]) => {
+            connections.push({
+                id: `${mapping.sourceNodeId}-${mapping.sourceOutputId}-${node.id}-${inputId}`,
+                sourceNodeId: mapping.sourceNodeId,
+                sourceOutputId: mapping.sourceOutputId,
+                targetNodeId: node.id,
+                targetInputId: inputId,
+            });
+        });
+    });
+    return connections;
+}
+/**
+ * Get all nodes that are downstream of a for-each node (inside its context).
+ */
+function getDownstreamNodes(forEachNodeId, nodes) {
+    const connections = deriveConnectionsInternal(nodes);
+    const downstream = new Set();
+    const queue = [];
+    // Find direct outputs from for-each
+    for (const conn of connections) {
+        if (conn.sourceNodeId === forEachNodeId) {
+            if (!downstream.has(conn.targetNodeId)) {
+                downstream.add(conn.targetNodeId);
+                queue.push(conn.targetNodeId);
+            }
+        }
+    }
+    // BFS to find all downstream
+    while (queue.length > 0) {
+        const currentId = queue.shift();
+        for (const conn of connections) {
+            if (conn.sourceNodeId === currentId && !downstream.has(conn.targetNodeId)) {
+                downstream.add(conn.targetNodeId);
+                queue.push(conn.targetNodeId);
+            }
+        }
+    }
+    return downstream;
+}
+/**
+ * Check if a node would be "captured" by a for-each context after a proposed connection.
+ *
+ * A node is captured if ALL of its outputs go to nodes inside the for-each context
+ * (either downstream nodes or other captured nodes).
+ */
+function wouldBeCaptured(nodeId, forEachNodeId, downstreamNodes, nodes, proposedTargetNodeId) {
+    const node = nodes.find(n => n.id === nodeId);
+    if (!node)
+        return false;
+    // For-each nodes can't be captured
+    if (node.type === 'for-each')
+        return false;
+    // Already downstream = not captured (it's inside)
+    if (downstreamNodes.has(nodeId))
+        return false;
+    const connections = deriveConnectionsInternal(nodes);
+    // Get all targets this node outputs to (existing + proposed)
+    const outputTargets = new Set();
+    for (const conn of connections) {
+        if (conn.sourceNodeId === nodeId) {
+            outputTargets.add(conn.targetNodeId);
+        }
+    }
+    // Add the proposed connection target
+    outputTargets.add(proposedTargetNodeId);
+    // If no outputs, can't be captured
+    if (outputTargets.size === 0)
+        return false;
+    // Build captured set iteratively
+    const captured = new Set();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const n of nodes) {
+            if (n.id === forEachNodeId)
+                continue;
+            if (downstreamNodes.has(n.id))
+                continue;
+            if (captured.has(n.id))
+                continue;
+            // Get outputs for this node
+            const nodeOutputs = new Set();
+            for (const conn of connections) {
+                if (conn.sourceNodeId === n.id) {
+                    nodeOutputs.add(conn.targetNodeId);
+                }
+            }
+            // Include proposed connection if this is the source node
+            if (n.id === nodeId) {
+                nodeOutputs.add(proposedTargetNodeId);
+            }
+            if (nodeOutputs.size === 0)
+                continue;
+            // All outputs must go to downstream or captured
+            const allInside = [...nodeOutputs].every(targetId => downstreamNodes.has(targetId) || captured.has(targetId));
+            if (allInside) {
+                captured.add(n.id);
+                changed = true;
+            }
+        }
+    }
+    return captured.has(nodeId);
+}
+/**
+ * Find the for-each context a node belongs to by tracing backwards.
+ *
+ * A node is "inside" a for-each context if, when tracing backwards through
+ * connections, we reach a for-each node via one of its OUTPUT ports.
+ *
+ * Returns the for-each node ID if inside a context, or null if outside all contexts.
+ */
+function getForEachContextInternal(nodeId, nodes, connections, visited = new Set()) {
+    // Prevent infinite loops from circular references
+    if (visited.has(nodeId))
+        return null;
+    visited.add(nodeId);
+    const node = nodes.find(n => n.id === nodeId);
+    if (!node)
+        return null;
+    // Check all inputs to this node
+    for (const connection of connections) {
+        if (connection.targetNodeId !== nodeId)
+            continue;
+        const sourceNode = nodes.find(n => n.id === connection.sourceNodeId);
+        if (!sourceNode)
+            continue;
+        // If the source is a for-each node and we're connected to one of its outputs,
+        // then this node is inside that for-each context
+        if (sourceNode.type === 'for-each') {
+            return sourceNode.id;
+        }
+        // Otherwise, recursively check the source node's context
+        const sourceContext = getForEachContextInternal(connection.sourceNodeId, nodes, connections, visited);
+        if (sourceContext) {
+            return sourceContext;
+        }
+    }
+    return null;
+}
+// ===========================================================================
+// Type Compatibility
+// ===========================================================================
+/**
+ * Check if two port types are compatible for connection
+ * A connection is valid if:
+ * 1. The types match exactly (same base type and same isArray), OR
+ * 2. The source is an array type and target is 'object' (non-array), OR
+ * 3. The source is a union and includes a compatible type, OR
+ * 4. The target is a union and includes a compatible type, OR
+ * 5. Both are unions and have at least one common compatible type
+ *
+ * Note: Array inputs are strict - they only accept exact matches
+ */
+function areTypesCompatible({ sourceType, sourceIsArray, targetType, targetIsArray, }) {
+    const sourceTypes = isTypeUnion(sourceType) ? sourceType : [sourceType];
+    const targetTypes = isTypeUnion(targetType) ? targetType : [targetType];
+    return sourceTypes.some(st => {
+        return targetTypes.some(tt => {
+            // Exact match (same base type and same isArray)
+            if (st === tt && sourceIsArray === targetIsArray)
+                return true;
+            // Object inputs (non-array) accept any array type (backwards compatibility with for-each, etc.)
+            if (tt === 'object' && !targetIsArray && sourceIsArray) {
+                return true;
+            }
+            // Array inputs are strict - no other compatibility
+            if (targetIsArray) {
+                return false;
+            }
+            return false;
+        });
+    });
+}
+// ===========================================================================
+// Port Computation
+// ===========================================================================
+/**
+ * Compute ports for a node based on its type and config.
+ * Uses the node definition's computePorts function.
+ *
+ * @param nodeType - The type of the node
+ * @param config - The node's configuration object
+ * @param client - Optional AutomationsClient for nodes that need to fetch data
+ * @param getConnectedOutput - Optional function to get connected output port info (for dynamic ports)
+ */
+async function computePortsForNode({ nodeType, config, client, getConnectedOutput, }) {
+    const definition = (0, nodes_1.getNodeDefinition)(nodeType);
+    if (!definition) {
+        return { inputs: [], outputs: [] };
+    }
+    return await definition.computePorts({
+        config: config ?? definition.defaults,
+        client,
+        getConnectedOutput,
+    });
+}
+/**
+ * Get all available automation nodes.
+ * Converts node definitions from the registry into ComputedNode format.
+ */
+async function getAllNodes(client) {
+    const definitions = (0, nodes_1.getAllNodeDefinitions)();
+    const results = [];
+    for (const def of definitions) {
+        const { inputs, outputs } = await def.computePorts({ config: def.defaults, client });
+        results.push({
+            nodeId: def.nodeId,
+            label: def.label,
+            description: def.description,
+            category: def.category,
+            type: def.type,
+            inputs,
+            outputs,
+            outputModes: def.outputModes,
+            selectionModes: def.selectionModes,
+            defaults: def.defaults,
+        });
+    }
+    return results;
+}
+/**
+ * Get a specific node by nodeId
+ */
+async function getNodeByType(nodeId, client) {
+    const allNodes = await getAllNodes(client);
+    return allNodes.find(node => node.nodeId === nodeId);
+}
+// ===========================================================================
+// Output Schema
+// ===========================================================================
+/**
+ * Get the schema of array items for a node's output port.
+ * Returns null if schema is unknown or the output is not an array.
+ *
+ * @param nodeType - The type of the node (e.g., 'transcript', 'llm')
+ * @param nodeConfig - The node's configuration object
+ * @param outputPortId - The ID of the output port to get schema for
+ * @param client - Optional AutomationsClient for nodes that need to fetch data
+ * @returns The schema of array items, or null if unknown
+ */
+async function getOutputSchema({ nodeType, nodeConfig, outputPortId, client, }) {
+    // First check static node definitions
+    const nodeDefinition = await getNodeByType(nodeType, client);
+    const outputPort = nodeDefinition?.outputs.find(o => o.id === outputPortId);
+    if (outputPort?.objectSchema) {
+        return outputPort.objectSchema;
+    }
+    // Check resolvedPorts for nodes with dynamic outputs (compose-workflow, for-each, etc.)
+    if (nodeConfig?.resolvedPorts) {
+        const resolvedPorts = nodeConfig.resolvedPorts;
+        const resolvedOutput = resolvedPorts.outputs?.find(o => o.id === outputPortId);
+        if (resolvedOutput?.objectSchema) {
+            return resolvedOutput.objectSchema;
+        }
+    }
+    return null;
+}
+// ===========================================================================
+// Connection Management
+// ===========================================================================
+/**
+ * Derive Connection[] array from nodes for canvas rendering
+ *
+ * Connections are stored in the embedded inputs map format.
+ * This function extracts them into a flat array for canvas rendering.
+ */
+function deriveConnections({ nodes }) {
+    return deriveConnectionsInternal(nodes);
+}
+/**
+ * Add a connection to a node's inputs map
+ */
+function addConnection({ nodes, sourceNodeId, sourceOutputId, targetNodeId, targetInputId, }) {
+    return nodes.map(node => {
+        if (node.id !== targetNodeId)
+            return node;
+        return {
+            ...node,
+            inputs: {
+                ...node.inputs,
+                [targetInputId]: {
+                    sourceNodeId,
+                    sourceOutputId,
+                },
+            },
+        };
+    });
+}
+/**
+ * Remove a connection from a node's inputs map
+ */
+function removeConnection({ nodes, targetNodeId, targetInputId, }) {
+    return nodes.map(node => {
+        if (node.id !== targetNodeId)
+            return node;
+        const newInputs = { ...node.inputs };
+        delete newInputs[targetInputId];
+        return {
+            ...node,
+            inputs: newInputs,
+        };
+    });
+}
+/**
+ * Remove all connections to/from a node
+ */
+function removeNodeConnections({ nodes, nodeId, }) {
+    return nodes.map(node => {
+        // Remove inputs that come from the deleted node
+        const newInputs = { ...node.inputs };
+        let hasChanges = false;
+        Object.entries(newInputs).forEach(([inputId, mapping]) => {
+            if (mapping.sourceNodeId === nodeId) {
+                delete newInputs[inputId];
+                hasChanges = true;
+            }
+        });
+        if (hasChanges) {
+            return { ...node, inputs: newInputs };
+        }
+        return node;
+    });
+}
+/**
+ * Clean up stale connections on load.
+ *
+ * Removes entries from node.inputs that reference ports that no longer exist
+ * in the node's resolvedPorts.inputs. This handles cases where ports were
+ * renamed or deleted but the old connection data persisted.
+ */
+function cleanupStaleConnections({ nodes, }) {
+    return nodes.map(node => {
+        // Only compose-workflow nodes have resolvedPorts
+        if (node.type !== 'compose-workflow') {
+            return node;
+        }
+        const resolvedInputs = node.config.resolvedPorts?.inputs;
+        // If no resolvedPorts.inputs, we can't validate - skip cleanup for this node
+        if (!resolvedInputs || !Array.isArray(resolvedInputs)) {
+            return node;
+        }
+        const validInputIds = new Set(resolvedInputs.map(p => p.id));
+        const currentInputs = node.inputs ?? {};
+        // Check if any inputs are stale (reference non-existent ports)
+        const staleInputIds = Object.keys(currentInputs).filter(inputId => !validInputIds.has(inputId));
+        if (staleInputIds.length === 0) {
+            return node; // No cleanup needed
+        }
+        // Remove stale inputs
+        const cleanedInputs = { ...currentInputs };
+        staleInputIds.forEach(inputId => {
+            delete cleanedInputs[inputId];
+        });
+        return {
+            ...node,
+            inputs: cleanedInputs,
+        };
+    });
+}
+// ===========================================================================
+// For-Each Context Validation
+// ===========================================================================
+/**
+ * Find the for-each context a node belongs to by tracing backwards.
+ *
+ * A node is "inside" a for-each context if, when tracing backwards through
+ * connections, we reach a for-each node via one of its OUTPUT ports.
+ *
+ * Returns the for-each node ID if inside a context, or null if outside all contexts.
+ */
+function getForEachContext({ nodeId, nodes, }) {
+    const connections = deriveConnectionsInternal(nodes);
+    return getForEachContextInternal(nodeId, nodes, connections);
+}
+/**
+ * Check if a connection would violate for-each context boundaries.
+ *
+ * A violation occurs when:
+ * 1. Source is OUTSIDE a for-each context and target is INSIDE,
+ *    AND the source would NOT become a "captured" node after this connection
+ * 2. Source and target are in DIFFERENT for-each contexts
+ *    (can't connect across different loops)
+ *
+ * "Captured" nodes are allowed - they will be expanded at runtime to execute
+ * once per for-each iteration (e.g., Account selector → Auto Post inside for-each).
+ *
+ * Returns true if the connection is INVALID (violation), false if allowed.
+ */
+function checkCrossContextViolation({ sourceNodeId, targetNodeId, nodes, }) {
+    const connections = deriveConnectionsInternal(nodes);
+    const targetNode = nodes.find(n => n.id === targetNodeId);
+    if (!targetNode)
+        return false;
+    // If target is a for-each node, the connection is going INTO the for-each
+    // (to its array input or passthrough inputs), which is always allowed
+    if (targetNode.type === 'for-each') {
+        return false;
+    }
+    const sourceNode = nodes.find(n => n.id === sourceNodeId);
+    const targetContext = getForEachContextInternal(targetNodeId, nodes, connections);
+    // If source IS the for-each node that defines the target's context,
+    // allow the connection (for-each feeding its own loop body via passthrough outputs)
+    if (sourceNode?.type === 'for-each' && targetContext === sourceNodeId) {
+        return false;
+    }
+    const sourceContext = getForEachContextInternal(sourceNodeId, nodes, connections);
+    // If source is outside and target is inside a for-each context...
+    if (sourceContext === null && targetContext !== null) {
+        // Check if source would become a "captured" node after this connection
+        const downstreamNodes = getDownstreamNodes(targetContext, nodes);
+        if (wouldBeCaptured(sourceNodeId, targetContext, downstreamNodes, nodes, targetNodeId)) {
+            // Source will be captured - allow the connection
+            return false;
+        }
+        // Source has other outputs outside the context - violation
+        return true;
+    }
+    // If both are inside different for-each contexts, that's a violation
+    if (sourceContext !== null && targetContext !== null && sourceContext !== targetContext) {
+        return true;
+    }
+    return false;
+}
+// ===========================================================================
+// Workflow Validation
+// ===========================================================================
+const TRIGGER_TYPES = ['manual-trigger', 'recurrence'];
+const TERMINAL_TYPES = ['passthrough', 'auto-post', 'save-to-media'];
+/**
+ * Validate workflow and return structured errors for UI highlighting
+ */
+async function validateWorkflow({ nodes, }) {
+    const errors = [];
+    const connections = deriveConnectionsInternal(nodes);
+    // 1. Check for trigger node
+    const hasTrigger = nodes.some(n => TRIGGER_TYPES.includes(n.type));
+    if (!hasTrigger) {
+        errors.push({
+            type: 'missing_trigger',
+            message: 'Automation requires a trigger node (Manual Trigger or Recurrence)',
+        });
+    }
+    // 2. Check for terminal node
+    const hasTerminal = nodes.some(n => TERMINAL_TYPES.includes(n.type));
+    if (!hasTerminal) {
+        errors.push({
+            type: 'missing_terminal',
+            message: 'Automation requires an output node (Output, Auto Post, or Save to Media)',
+        });
+    }
+    // Build connection lookup: targetNodeId-targetInputId -> connection
+    const connectionsByTarget = new Map();
+    connections.forEach(conn => {
+        connectionsByTarget.set(`${conn.targetNodeId}-${conn.targetInputId}`, conn);
+    });
+    // Build node lookup by ID
+    const nodeById = new Map();
+    nodes.forEach(n => nodeById.set(n.id, n));
+    // 3. Check each node for missing required inputs and type mismatches
+    for (const node of nodes) {
+        // Use node definition's computePorts if available
+        const definition = (0, nodes_1.getNodeDefinition)(node.type);
+        const inputPorts = definition
+            ? (await definition.computePorts({ config: node.config ?? {} })).inputs
+            : [];
+        for (const port of inputPorts) {
+            if (!port.required)
+                continue;
+            const connectionKey = `${node.id}-${port.id}`;
+            const connection = connectionsByTarget.get(connectionKey);
+            if (!connection) {
+                // Missing required input
+                errors.push({
+                    type: 'missing_required_input',
+                    nodeId: node.id,
+                    portId: port.id,
+                    message: `Required input '${port.id}' is not connected`,
+                });
+            }
+            else {
+                // Check type compatibility
+                const sourceNode = nodeById.get(connection.sourceNodeId);
+                if (sourceNode) {
+                    const sourceDefinition = (0, nodes_1.getNodeDefinition)(sourceNode.type);
+                    const sourceOutputs = sourceDefinition
+                        ? (await sourceDefinition.computePorts({ config: sourceNode.config ?? {} })).outputs
+                        : [];
+                    const sourcePort = sourceOutputs.find(p => p.id === connection.sourceOutputId);
+                    if (sourcePort) {
+                        const compatible = areTypesCompatible({
+                            sourceType: sourcePort.type,
+                            sourceIsArray: sourcePort.isArray,
+                            targetType: port.type,
+                            targetIsArray: port.isArray,
+                        });
+                        if (!compatible) {
+                            errors.push({
+                                type: 'type_mismatch',
+                                nodeId: node.id,
+                                portId: port.id,
+                                message: `Type mismatch: expected ${formatPortType(port.type, port.isArray)}, got ${formatPortType(sourcePort.type, sourcePort.isArray)}`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // 4. Check for empty media pool
+        if (node.type === 'media') {
+            const configOutputs = node.config.outputs ?? [];
+            // Check if ANY output has media selected
+            const totalSelected = configOutputs.reduce((sum, o) => sum + o.selectedMediaIds.length, 0);
+            if (totalSelected === 0) {
+                errors.push({
+                    type: 'empty_media_pool',
+                    nodeId: node.id,
+                    message: 'Media node has no media selected',
+                });
+            }
+        }
+        // 5. Check for empty account pool
+        if (node.type === 'account') {
+            const accountIds = node.config.accountIds ?? [];
+            if (accountIds.length === 0) {
+                errors.push({
+                    type: 'empty_account_pool',
+                    nodeId: node.id,
+                    message: 'Account node has no accounts selected',
+                });
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Format a port type for display in error messages
+ */
+function formatPortType(type, isArray) {
+    return (0, types_1.formatPortType)(type, isArray);
+}
+/**
+ * Get node IDs that have errors
+ */
+function getErrorNodeIds({ errors }) {
+    return [...new Set(errors.filter(e => e.nodeId).map(e => e.nodeId))];
+}
+/**
+ * Get port errors for a specific node
+ */
+function getPortErrorsForNode({ nodeId, errors, }) {
+    return errors
+        .filter(e => e.nodeId === nodeId && e.portId)
+        .map(e => ({ portId: e.portId, message: e.message }));
+}
+/**
+ * Check if there's a missing trigger error
+ */
+function hasMissingTriggerError({ errors }) {
+    return errors.some(e => e.type === 'missing_trigger');
+}
+/**
+ * Check if there's a missing terminal error
+ */
+function hasMissingTerminalError({ errors }) {
+    return errors.some(e => e.type === 'missing_terminal');
+}
+// ===========================================================================
+// Preview Resolution
+// ===========================================================================
+/**
+ * Resolve preview data for a node.
+ * Converts node config with refs (inputId/textInputId) to render-ready format.
+ * Delegates to the node definition's resolvePreview function if available.
+ *
+ * @returns ResolvedPreview with render-ready config, sources, and textContent,
+ *          or null if the node doesn't support preview or config is invalid.
+ */
+function resolveNodePreview({ nodes, nodeId, }) {
+    const node = nodes.find(n => n.id === nodeId);
+    if (!node)
+        return null;
+    const definition = (0, nodes_1.getNodeDefinition)(node.type);
+    if (!definition)
+        return null;
+    if (!definition.resolvePreview)
+        return null;
+    return definition.resolvePreview(node.config);
+}