@flowdrop/flowdrop 1.4.0 → 1.6.0

package/dist/commands/executor.js

@@ -0,0 +1,1133 @@
+/**
+ * Command Executor
+ *
+ * Executes parsed Command objects against a CommandContext,
+ * dispatching mutations to the workflow store.
+ *
+ * @module commands/executor
+ */
+import { generateNodeId } from '../utils/nodeIds.js';
+import { extractConfigDefaults } from '../utils/nodeIds.js';
+import { computeAutoPosition } from './positioner.js';
+import { buildHandleId, extractPortId } from '../utils/handleIds.js';
+import { applyConnectionStyling } from '../utils/edgeStyling.js';
+import { computeSwapPreview, executeSwap } from '../utils/nodeSwap.js';
+import { computeAutoLayout, computeBeautifyLayout } from '../adapters/agentspec/autoLayout.js';
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Convert an internal namespaced node ID to a DSL short ID.
+ * "agentspec.llm_node.1" → "llm_node.1"
+ * "llm_node.1" → "llm_node.1" (no namespace, unchanged)
+ */
+export function toShortId(internalId) {
+    // Node IDs are <namespace>.<typeId>.<number> or <typeId>.<number>
+    // The namespace is the first segment if there are 3+ dot-separated parts
+    // and the last segment is a number
+    const parts = internalId.split('.');
+    if (parts.length >= 3) {
+        const lastPart = parts[parts.length - 1];
+        if (/^\d+$/.test(lastPart)) {
+            // Strip the first segment (namespace)
+            return parts.slice(1).join('.');
+        }
+    }
+    return internalId;
+}
+/**
+ * Convert a namespaced type ID to a short type ID.
+ * "agentspec.llm_node" → "llm_node"
+ * "llm_node" → "llm_node" (no namespace, unchanged)
+ */
+export function toShortTypeId(typeId) {
+    const dotIndex = typeId.indexOf('.');
+    if (dotIndex !== -1) {
+        return typeId.substring(dotIndex + 1);
+    }
+    return typeId;
+}
+/**
+ * Resolve a DSL short ID (e.g. "llm_node.1") to the actual workflow node.
+ * Tries direct match first, then looks for a namespaced match.
+ */
+export function resolveNode(shortId, nodes) {
+    // Direct match
+    const direct = nodes.find((n) => n.id === shortId);
+    if (direct)
+        return direct;
+    // Namespaced match: node ID ends with ".<shortId>"
+    return nodes.find((n) => n.id.endsWith(`.${shortId}`));
+}
+// ============================================================================
+// Command Handlers
+// ============================================================================
+function executeAddNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const metadata = context.typeMap.get(command.nodeTypeId);
+    if (!metadata) {
+        return {
+            ok: false,
+            error: `Unknown node type: ${command.nodeTypeId}`,
+            code: 'NODE_TYPE_NOT_FOUND'
+        };
+    }
+    const position = command.position ?? computeAutoPosition(workflow.nodes);
+    const nodeId = generateNodeId(metadata.id, workflow.nodes);
+    const config = extractConfigDefaults(metadata.configSchema);
+    const node = {
+        id: nodeId,
+        type: 'universalNode',
+        position,
+        deletable: true,
+        data: {
+            label: metadata.name,
+            config,
+            metadata,
+            nodeId
+        }
+    };
+    context.dispatch.addNode(node);
+    const shortId = toShortId(nodeId);
+    const resultData = {
+        nodeId: shortId,
+        type: command.nodeTypeId,
+        label: metadata.name,
+        position
+    };
+    return {
+        ok: true,
+        message: `Added ${metadata.name} as ${shortId}`,
+        data: resultData
+    };
+}
+function executeDeleteNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    context.dispatch.removeNode(node.id);
+    return {
+        ok: true,
+        message: `Deleted node ${toShortId(node.id)}`
+    };
+}
+function executeRenameNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    context.dispatch.updateNode(node.id, {
+        data: { ...node.data, label: command.label }
+    });
+    return {
+        ok: true,
+        message: `Renamed ${toShortId(node.id)} to "${command.label}"`
+    };
+}
+/**
+ * Parse a raw value string into the appropriate JS type.
+ * Priority: quoted string (preserved) > JSON > number > boolean > raw string
+ */
+function parseConfigValue(raw) {
+    // Double-quoted string — JSON-unescape so \n, \t, \\ etc. work
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw.slice(1, -1);
+        }
+    }
+    // Single-quoted string — strip quotes (no escape processing)
+    if (raw.startsWith("'") && raw.endsWith("'")) {
+        return raw.slice(1, -1);
+    }
+    // Try JSON (arrays, objects, null)
+    if (raw.startsWith('[') || raw.startsWith('{') || raw === 'null') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // fall through
+        }
+    }
+    // Number
+    if (raw !== '' && !isNaN(Number(raw))) {
+        return Number(raw);
+    }
+    // Boolean
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    // Raw string
+    return raw;
+}
+/**
+ * Validate a parsed config value against a ConfigProperty schema.
+ * Returns an array of validation warnings (empty if valid or no schema).
+ */
+function validateConfigValue(key, value, property) {
+    if (!property)
+        return [];
+    const warnings = [];
+    // Enum validation
+    if (property.enum && property.enum.length > 0) {
+        if (!property.enum.includes(value)) {
+            warnings.push({
+                type: 'enum',
+                message: `Value ${JSON.stringify(value)} is not in allowed values: ${property.enum.map((v) => JSON.stringify(v)).join(', ')}`,
+                allowedValues: property.enum
+            });
+        }
+    }
+    // Type validation
+    if (property.type) {
+        const actualType = Array.isArray(value) ? 'array' : typeof value;
+        const expectedType = property.type === 'integer' ? 'number' : property.type;
+        // Only warn if there's a genuine mismatch (null/object handled specially)
+        if (value !== null &&
+            actualType !== expectedType &&
+            !(expectedType === 'object' && actualType === 'object')) {
+            warnings.push({
+                type: 'type_mismatch',
+                message: `Expected type '${property.type}' but got '${actualType}'`,
+                expectedType: property.type,
+                actualType
+            });
+        }
+    }
+    return warnings;
+}
+function executeSetConfig(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const parsedValue = parseConfigValue(command.value);
+    // Validate against configSchema if present
+    const metadata = node.data.metadata;
+    const configSchema = metadata?.configSchema;
+    const property = configSchema?.properties?.[command.key];
+    const warnings = validateConfigValue(command.key, parsedValue, property);
+    // In strict mode, validation warnings become errors
+    if (command.strict && warnings && warnings.length > 0) {
+        const messages = warnings.map((w) => w.message).join('; ');
+        return {
+            ok: false,
+            error: `Config validation failed for ${toShortId(node.id)}:${command.key}: ${messages}`,
+            code: 'CONFIG_VALIDATION_ERROR'
+        };
+    }
+    const updatedConfig = { ...node.data.config, [command.key]: parsedValue };
+    context.dispatch.updateNode(node.id, {
+        data: { ...node.data, config: updatedConfig }
+    });
+    const resultData = {
+        nodeId: toShortId(node.id),
+        key: command.key,
+        value: parsedValue,
+        ...(warnings && warnings.length > 0 ? { warnings } : {})
+    };
+    const warningMsg = warnings && warnings.length > 0
+        ? ` (warning: ${warnings.map((w) => w.message).join('; ')})`
+        : '';
+    return {
+        ok: true,
+        message: `Set ${toShortId(node.id)}:${command.key} = ${JSON.stringify(parsedValue)}${warningMsg}`,
+        data: resultData
+    };
+}
+function executeGetConfig(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const config = node.data.config;
+    if (!config || !(command.key in config)) {
+        return {
+            ok: false,
+            error: `Config key not found: ${command.key} on ${toShortId(node.id)}`,
+            code: 'CONFIG_KEY_NOT_FOUND'
+        };
+    }
+    const resultData = {
+        nodeId: toShortId(node.id),
+        key: command.key,
+        value: config[command.key]
+    };
+    return {
+        ok: true,
+        message: `${toShortId(node.id)}:${command.key} = ${JSON.stringify(config[command.key])}`,
+        data: resultData
+    };
+}
+function executeInfo(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const metadata = node.data.metadata;
+    const shortId = toShortId(node.id);
+    const inputs = (metadata?.inputs ?? []).map((p) => ({
+        portId: p.id,
+        name: p.name,
+        dataType: p.dataType
+    }));
+    const staticOutputs = (metadata?.outputs ?? []).map((p) => ({
+        portId: p.id,
+        name: p.name,
+        dataType: p.dataType
+    }));
+    // Gateway nodes expose dynamic branch ports from config.branches
+    const branchOutputs = metadata?.type === 'gateway'
+        ? (node.data.config?.branches ?? []).map((b) => ({
+            portId: b.name,
+            name: b.name,
+            dataType: 'trigger'
+        }))
+        : [];
+    const outputs = [...staticOutputs, ...branchOutputs];
+    // Build connected edges info
+    const connectedEdges = [];
+    for (const edge of workflow.edges) {
+        if (edge.source === node.id) {
+            connectedEdges.push({
+                edgeId: edge.id,
+                direction: 'outgoing',
+                remoteNodeId: toShortId(edge.target),
+                remotePort: extractPortId(edge.targetHandle) ?? '',
+                localPort: extractPortId(edge.sourceHandle) ?? ''
+            });
+        }
+        else if (edge.target === node.id) {
+            connectedEdges.push({
+                edgeId: edge.id,
+                direction: 'incoming',
+                remoteNodeId: toShortId(edge.source),
+                remotePort: extractPortId(edge.sourceHandle) ?? '',
+                localPort: extractPortId(edge.targetHandle) ?? ''
+            });
+        }
+    }
+    const resultData = {
+        nodeId: shortId,
+        label: node.data.label ?? metadata?.name ?? '',
+        type: metadata?.id ? toShortTypeId(metadata.id) : '',
+        position: node.position,
+        config: node.data.config ?? {},
+        inputs,
+        outputs,
+        connectedEdges
+    };
+    return {
+        ok: true,
+        message: `Info for ${shortId}`,
+        data: resultData
+    };
+}
+// ============================================================================
+// Connection Operations
+// ============================================================================
+/**
+ * Find a port in a node's metadata by port ID, checking both inputs and outputs.
+ * Returns the port and its direction.
+ */
+function findPort(node, portId, preferDirection) {
+    const metadata = node.data?.metadata;
+    if (!metadata)
+        return null;
+    const outputPort = metadata.outputs?.find((p) => p.id === portId);
+    const inputPort = metadata.inputs?.find((p) => p.id === portId);
+    if (preferDirection === 'output') {
+        if (outputPort)
+            return { port: outputPort, direction: 'output' };
+        if (inputPort)
+            return { port: inputPort, direction: 'input' };
+    }
+    else if (preferDirection === 'input') {
+        if (inputPort)
+            return { port: inputPort, direction: 'input' };
+        if (outputPort)
+            return { port: outputPort, direction: 'output' };
+    }
+    else {
+        if (outputPort)
+            return { port: outputPort, direction: 'output' };
+        if (inputPort)
+            return { port: inputPort, direction: 'input' };
+    }
+    // Gateway nodes have dynamic branch ports stored in config.branches, not metadata.outputs
+    if (metadata.type === 'gateway') {
+        const branches = node.data.config?.branches;
+        if (branches?.some((b) => b.name === portId)) {
+            return {
+                port: { id: portId, name: portId, dataType: 'trigger' },
+                direction: 'output'
+            };
+        }
+    }
+    return null;
+}
+function executeConnect(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    // Resolve both nodes
+    const sourceNode = resolveNode(command.sourceNodeId, workflow.nodes);
+    if (!sourceNode) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.sourceNodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const targetNode = resolveNode(command.targetNodeId, workflow.nodes);
+    if (!targetNode) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.targetNodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    // Look up ports in metadata to determine direction.
+    // Since connections always flow output → input, prefer the output port on the
+    // source node and the input port on the target node when the same port name
+    // exists in both directions on a node.
+    const sourcePortInfo = findPort(sourceNode, command.sourcePort, 'output');
+    if (!sourcePortInfo) {
+        return {
+            ok: false,
+            error: `Port '${command.sourcePort}' not found on node ${toShortId(sourceNode.id)}`,
+            code: 'PORT_NOT_FOUND'
+        };
+    }
+    const targetPortInfo = findPort(targetNode, command.targetPort, 'input');
+    if (!targetPortInfo) {
+        return {
+            ok: false,
+            error: `Port '${command.targetPort}' not found on node ${toShortId(targetNode.id)}`,
+            code: 'PORT_NOT_FOUND'
+        };
+    }
+    // Validate directions: source port must be output, target port must be input
+    if (sourcePortInfo.direction !== 'output' || targetPortInfo.direction !== 'input') {
+        // Check if they're reversed
+        if (sourcePortInfo.direction === 'input' && targetPortInfo.direction === 'output') {
+            return {
+                ok: false,
+                error: `Connection direction reversed: '${command.sourcePort}' is an input on ${toShortId(sourceNode.id)} and '${command.targetPort}' is an output on ${toShortId(targetNode.id)}. Swap source and target.`,
+                code: 'INVALID_CONNECTION'
+            };
+        }
+        // One of them is the wrong direction
+        if (sourcePortInfo.direction !== 'output') {
+            return {
+                ok: false,
+                error: `Port '${command.sourcePort}' on ${toShortId(sourceNode.id)} is an input, not an output (per node metadata)`,
+                code: 'INVALID_CONNECTION'
+            };
+        }
+        return {
+            ok: false,
+            error: `Port '${command.targetPort}' on ${toShortId(targetNode.id)} is an output, not an input (per node metadata)`,
+            code: 'INVALID_CONNECTION'
+        };
+    }
+    // Build handle IDs
+    const sourceHandle = buildHandleId(sourceNode.id, 'output', command.sourcePort);
+    const targetHandle = buildHandleId(targetNode.id, 'input', command.targetPort);
+    // Generate edge ID
+    const edgeId = `${sourceNode.id}-${sourceHandle}-${targetNode.id}-${targetHandle}`;
+    // Build edge
+    const edge = {
+        id: edgeId,
+        source: sourceNode.id,
+        target: targetNode.id,
+        sourceHandle,
+        targetHandle
+    };
+    // Apply styling
+    applyConnectionStyling(edge, sourceNode, targetNode);
+    // Dispatch
+    context.dispatch.addEdge(edge);
+    return {
+        ok: true,
+        message: `Connected ${toShortId(sourceNode.id)}:${command.sourcePort} → ${toShortId(targetNode.id)}:${command.targetPort}`
+    };
+}
+function executeDisconnectPorts(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    // Resolve both nodes
+    const sourceNode = resolveNode(command.sourceNodeId, workflow.nodes);
+    if (!sourceNode) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.sourceNodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const targetNode = resolveNode(command.targetNodeId, workflow.nodes);
+    if (!targetNode) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.targetNodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    // Find the matching edge by checking source/target node IDs and port IDs
+    const edge = workflow.edges.find((e) => {
+        if (e.source !== sourceNode.id || e.target !== targetNode.id)
+            return false;
+        const sourcePort = extractPortId(e.sourceHandle);
+        const targetPort = extractPortId(e.targetHandle);
+        return sourcePort === command.sourcePort && targetPort === command.targetPort;
+    });
+    if (!edge) {
+        return {
+            ok: false,
+            error: `No edge found from ${toShortId(sourceNode.id)}:${command.sourcePort} to ${toShortId(targetNode.id)}:${command.targetPort}`,
+            code: 'EDGE_NOT_FOUND'
+        };
+    }
+    context.dispatch.removeEdge(edge.id);
+    return {
+        ok: true,
+        message: `Disconnected ${toShortId(sourceNode.id)}:${command.sourcePort} from ${toShortId(targetNode.id)}:${command.targetPort}`
+    };
+}
+function executeDisconnectNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    // Find all edges connected to this node
+    const connectedEdges = workflow.edges.filter((e) => e.source === node.id || e.target === node.id);
+    for (const edge of connectedEdges) {
+        context.dispatch.removeEdge(edge.id);
+    }
+    return {
+        ok: true,
+        message: `Disconnected ${connectedEdges.length} edge(s) from ${toShortId(node.id)}`
+    };
+}
+// ============================================================================
+// List & Help Operations
+// ============================================================================
+function executeListNodes(context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const nodes = workflow.nodes.map((n) => ({
+        nodeId: toShortId(n.id),
+        label: n.data.label ?? n.data.metadata?.name ?? '',
+        type: n.data.metadata?.id ? toShortTypeId(n.data.metadata.id) : ''
+    }));
+    const resultData = { nodes };
+    return {
+        ok: true,
+        message: nodes.length === 0
+            ? 'No nodes in workflow'
+            : `${nodes.length} node(s): ${nodes.map((n) => n.nodeId).join(', ')}`,
+        data: resultData
+    };
+}
+function executeListEdges(context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const edges = workflow.edges.map((e) => ({
+        edgeId: e.id,
+        sourceNodeId: toShortId(e.source),
+        sourcePort: extractPortId(e.sourceHandle) ?? '',
+        targetNodeId: toShortId(e.target),
+        targetPort: extractPortId(e.targetHandle) ?? ''
+    }));
+    const resultData = { edges };
+    return {
+        ok: true,
+        message: edges.length === 0 ? 'No edges in workflow' : `${edges.length} edge(s)`,
+        data: resultData
+    };
+}
+function executeListTypes(context) {
+    const types = context.nodeTypes.map((m) => ({
+        typeId: toShortTypeId(m.id),
+        name: m.name,
+        category: m.category
+    }));
+    const resultData = { types };
+    return {
+        ok: true,
+        message: `${types.length} type(s) available`,
+        data: resultData
+    };
+}
+/** All command help entries */
+export const COMMAND_HELP = [
+    {
+        name: 'add',
+        syntax: 'add <type> [at <x>,<y>]',
+        description: 'Add a new node of the specified type'
+    },
+    {
+        name: 'delete',
+        syntax: 'delete <nodeId>',
+        description: 'Delete a node and its connections'
+    },
+    {
+        name: 'rename',
+        syntax: 'rename <nodeId> <label>',
+        description: "Rename a node's display label"
+    },
+    {
+        name: 'set',
+        syntax: 'set <nodeId>:<key> <value>',
+        description: 'Set a config value on a node'
+    },
+    {
+        name: 'get',
+        syntax: 'get <nodeId>:<key>',
+        description: 'Get a config value from a node'
+    },
+    {
+        name: 'connect',
+        syntax: 'connect <nid>:<port> to <nid>:<port>',
+        description: 'Connect two node ports'
+    },
+    {
+        name: 'disconnect',
+        syntax: 'disconnect <nid>:<port> from <nid>:<port>',
+        description: 'Disconnect two node ports'
+    },
+    {
+        name: 'disconnect',
+        syntax: 'disconnect <nodeId>',
+        description: 'Disconnect all edges from a node'
+    },
+    {
+        name: 'list',
+        syntax: 'list nodes|edges|types',
+        description: 'List workflow nodes, edges, or available types'
+    },
+    {
+        name: 'info',
+        syntax: 'info <nodeId>',
+        description: 'Show detailed info about a node'
+    },
+    {
+        name: 'config',
+        syntax: 'config <nodeId>',
+        description: 'Open the config panel for a node'
+    },
+    {
+        name: 'select',
+        syntax: 'select <nodeId>',
+        description: 'Select a node on the canvas'
+    },
+    {
+        name: 'swap',
+        syntax: 'swap <nodeId> with <type>',
+        description: "Replace a node's type, preserving connections"
+    },
+    {
+        name: 'move',
+        syntax: 'move <nodeId> to <x>,<y>',
+        description: 'Move a node to a position'
+    },
+    {
+        name: 'layout',
+        syntax: 'layout auto [--direction horizontal|vertical]',
+        description: 'Auto-arrange all nodes'
+    },
+    {
+        name: 'layout',
+        syntax: 'layout beautify',
+        description: 'Normalize spacing while preserving node arrangement'
+    },
+    { name: 'undo', syntax: 'undo', description: 'Undo the last action' },
+    { name: 'redo', syntax: 'redo', description: 'Redo the last undone action' },
+    {
+        name: 'help',
+        syntax: 'help [<command>]',
+        description: 'Show help for all or a specific command'
+    },
+    { name: 'clear', syntax: 'clear', description: 'Remove all nodes and edges' },
+    {
+        name: 'canvas',
+        syntax: 'canvas fitview',
+        description: 'Fit all nodes into the viewport'
+    },
+    {
+        name: 'canvas',
+        syntax: 'canvas zoom in',
+        description: 'Zoom in on the canvas'
+    },
+    {
+        name: 'canvas',
+        syntax: 'canvas zoom out',
+        description: 'Zoom out on the canvas'
+    },
+    {
+        name: 'canvas',
+        syntax: 'canvas zoom <level>',
+        description: 'Set zoom to a specific level (e.g. 1.5)'
+    },
+    {
+        name: 'canvas',
+        syntax: 'canvas pan <x>,<y>',
+        description: 'Pan the canvas to center on a position'
+    },
+    {
+        name: 'canvas',
+        syntax: 'canvas reset',
+        description: 'Reset viewport to default position and zoom'
+    }
+];
+function executeHelp(command) {
+    let commands;
+    if (command.command) {
+        commands = COMMAND_HELP.filter((h) => h.name === command.command);
+        if (commands.length === 0) {
+            commands = COMMAND_HELP; // Unknown command name — show all
+        }
+    }
+    else {
+        commands = COMMAND_HELP;
+    }
+    const resultData = { commands };
+    const message = commands.map((c) => `  ${c.syntax} — ${c.description}`).join('\n');
+    return {
+        ok: true,
+        message: command.command
+            ? `Help for '${command.command}':\n${message}`
+            : `Available commands:\n${message}`,
+        data: resultData
+    };
+}
+// ============================================================================
+// Undo, Redo, Clear, Config, Select
+// ============================================================================
+function executeUndo(context) {
+    const success = context.dispatch.undo();
+    if (!success) {
+        return {
+            ok: false,
+            error: 'Nothing to undo',
+            code: 'UNDO_UNAVAILABLE'
+        };
+    }
+    return { ok: true, message: 'Undone' };
+}
+function executeRedo(context) {
+    const success = context.dispatch.redo();
+    if (!success) {
+        return {
+            ok: false,
+            error: 'Nothing to redo',
+            code: 'REDO_UNAVAILABLE'
+        };
+    }
+    return { ok: true, message: 'Redone' };
+}
+function executeClear(context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const nodeCount = workflow.nodes.length;
+    const edgeCount = workflow.edges.length;
+    context.dispatch.batchUpdate({ nodes: [], edges: [] });
+    return {
+        ok: true,
+        message: `Cleared ${nodeCount} node(s) and ${edgeCount} edge(s)`
+    };
+}
+function executeConfigOpen(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    if (context.dispatch.emitUIAction) {
+        context.dispatch.emitUIAction({ type: 'open_config', nodeId: node.id });
+        return {
+            ok: true,
+            message: `Opened config for ${toShortId(node.id)}`
+        };
+    }
+    return {
+        ok: true,
+        message: `Config open requested for ${toShortId(node.id)} (no UI handler)`,
+        uiActionPending: true
+    };
+}
+function executeSelectNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    if (context.dispatch.emitUIAction) {
+        context.dispatch.emitUIAction({ type: 'select_node', nodeId: node.id });
+        return {
+            ok: true,
+            message: `Selected ${toShortId(node.id)}`
+        };
+    }
+    return {
+        ok: true,
+        message: `Select requested for ${toShortId(node.id)} (no UI handler)`,
+        uiActionPending: true
+    };
+}
+function executeSwapNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    const newMetadata = context.typeMap.get(command.newTypeId);
+    if (!newMetadata) {
+        return {
+            ok: false,
+            error: `Unknown node type: ${command.newTypeId}`,
+            code: 'NODE_TYPE_NOT_FOUND'
+        };
+    }
+    const preview = computeSwapPreview(node, newMetadata, workflow.edges, workflow.nodes);
+    const swapResult = executeSwap(node, newMetadata, preview, workflow.nodes, workflow.edges);
+    if (context.dispatch.swapNode) {
+        context.dispatch.swapNode({
+            nodes: swapResult.updatedNodes,
+            edges: swapResult.updatedEdges
+        });
+    }
+    else {
+        context.dispatch.batchUpdate({
+            nodes: swapResult.updatedNodes,
+            edges: swapResult.updatedEdges
+        });
+    }
+    const resultData = {
+        oldNodeId: toShortId(node.id),
+        newNodeId: toShortId(preview.newNodeId),
+        newType: command.newTypeId,
+        keptEdges: preview.keptEdges.length,
+        droppedEdges: preview.droppedEdges.length,
+        hasDataLoss: preview.hasDataLoss,
+        configCarriedOver: preview.configCarriedOver,
+        configReset: preview.configReset
+    };
+    const droppedMsg = preview.droppedEdges.length > 0 ? ` (${preview.droppedEdges.length} edge(s) dropped)` : '';
+    return {
+        ok: true,
+        message: `Swapped ${toShortId(node.id)} → ${toShortId(preview.newNodeId)} (${command.newTypeId})${droppedMsg}`,
+        data: resultData
+    };
+}
+function executeMoveNode(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    const node = resolveNode(command.nodeId, workflow.nodes);
+    if (!node) {
+        return {
+            ok: false,
+            error: `Node not found: ${command.nodeId}`,
+            code: 'NODE_NOT_FOUND'
+        };
+    }
+    context.dispatch.updateNode(node.id, {
+        position: command.position
+    });
+    return {
+        ok: true,
+        message: `Moved ${toShortId(node.id)} to (${command.position.x}, ${command.position.y})`
+    };
+}
+function executeAutoLayout(command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    if (workflow.nodes.length === 0) {
+        return { ok: true, message: 'No nodes to layout' };
+    }
+    const isVertical = command.direction === 'vertical';
+    // Filter out loopback edges (loop_back port) — they go backwards and
+    // would reverse the layout direction if included.
+    const layoutEdges = workflow.edges.filter((e) => !(e.targetHandle ?? '').includes('-input-loop_back'));
+    // Determine start node via in-degree: a node with no incoming edges
+    // (from non-loopback edges) is a root. Fall back to leftmost position.
+    const inDegree = new Map();
+    for (const n of workflow.nodes)
+        inDegree.set(n.id, 0);
+    for (const e of layoutEdges) {
+        inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
+    }
+    const startNode = workflow.nodes.find((n) => (inDegree.get(n.id) ?? 0) === 0)?.id ??
+        workflow.nodes.reduce((leftmost, n) => (n.position.x < leftmost.position.x ? n : leftmost)).id;
+    const flow = {
+        component_type: 'flow',
+        name: 'layout',
+        start_node: startNode,
+        nodes: workflow.nodes.map((n) => ({
+            component_type: 'start_node',
+            name: n.id
+        })),
+        control_flow_connections: layoutEdges.map((e) => ({
+            name: e.id,
+            from_node: e.source,
+            to_node: e.target
+        }))
+    };
+    // Collect measured node dimensions when available
+    const nodeDimensions = new Map();
+    for (const n of workflow.nodes) {
+        const w = n.measured?.width ?? n.width;
+        const h = n.measured?.height ?? n.height;
+        if (w != null && h != null) {
+            nodeDimensions.set(n.id, { width: w, height: h });
+        }
+    }
+    const positions = computeAutoLayout(flow, {}, nodeDimensions.size > 0 ? nodeDimensions : undefined);
+    // Apply positions — swap x/y for vertical layout
+    const updatedNodes = workflow.nodes.map((n) => {
+        const pos = positions.get(n.id);
+        if (!pos)
+            return n;
+        return {
+            ...n,
+            position: isVertical ? { x: pos.y, y: pos.x } : pos
+        };
+    });
+    context.dispatch.batchUpdate({ nodes: updatedNodes });
+    const direction = command.direction ?? 'horizontal';
+    return {
+        ok: true,
+        message: `Auto-layout applied to ${workflow.nodes.length} nodes (${direction})`
+    };
+}
+function executeBeautifyLayout(_command, context) {
+    const workflow = context.getWorkflow();
+    if (!workflow) {
+        return { ok: false, error: 'No workflow loaded', code: 'NO_WORKFLOW' };
+    }
+    if (workflow.nodes.length === 0) {
+        return { ok: true, message: 'No nodes to beautify' };
+    }
+    // Collect current positions
+    const currentPositions = new Map();
+    for (const n of workflow.nodes) {
+        currentPositions.set(n.id, { x: n.position.x, y: n.position.y });
+    }
+    // Collect measured node dimensions when available
+    const nodeDimensions = new Map();
+    for (const n of workflow.nodes) {
+        const w = n.measured?.width ?? n.width;
+        const h = n.measured?.height ?? n.height;
+        if (w != null && h != null) {
+            nodeDimensions.set(n.id, { width: w, height: h });
+        }
+    }
+    const positions = computeBeautifyLayout(currentPositions, {}, nodeDimensions.size > 0 ? nodeDimensions : undefined);
+    // Apply positions
+    const updatedNodes = workflow.nodes.map((n) => {
+        const pos = positions.get(n.id);
+        if (!pos)
+            return n;
+        return { ...n, position: pos };
+    });
+    context.dispatch.batchUpdate({ nodes: updatedNodes });
+    return {
+        ok: true,
+        message: `Beautified layout for ${workflow.nodes.length} nodes`
+    };
+}
+// ============================================================================
+// Canvas Viewport Commands
+// ============================================================================
+function emitCanvasAction(context, action, successMessage) {
+    if (context.dispatch.emitUIAction) {
+        context.dispatch.emitUIAction(action);
+        return { ok: true, message: successMessage };
+    }
+    return {
+        ok: true,
+        message: `${successMessage} (no UI handler)`,
+        uiActionPending: true
+    };
+}
+function executeCanvasFitView(context) {
+    return emitCanvasAction(context, { type: 'canvas_fit_view' }, 'Fit view applied');
+}
+function executeCanvasZoomIn(context) {
+    return emitCanvasAction(context, { type: 'canvas_zoom_in' }, 'Zoomed in');
+}
+function executeCanvasZoomOut(context) {
+    return emitCanvasAction(context, { type: 'canvas_zoom_out' }, 'Zoomed out');
+}
+function executeCanvasZoomTo(command, context) {
+    return emitCanvasAction(context, { type: 'canvas_zoom_to', level: command.level }, `Zoom set to ${command.level}`);
+}
+function executeCanvasPanTo(command, context) {
+    return emitCanvasAction(context, { type: 'canvas_pan_to', position: command.position }, `Panned to (${command.position.x}, ${command.position.y})`);
+}
+function executeCanvasResetView(context) {
+    return emitCanvasAction(context, { type: 'canvas_reset_view' }, 'Viewport reset');
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Execute a parsed command against a workflow context.
+ */
+export function executeCommand(command, context) {
+    switch (command.type) {
+        case 'add_node':
+            return executeAddNode(command, context);
+        case 'delete_node':
+            return executeDeleteNode(command, context);
+        case 'rename_node':
+            return executeRenameNode(command, context);
+        case 'set_config':
+            return executeSetConfig(command, context);
+        case 'get_config':
+            return executeGetConfig(command, context);
+        case 'info':
+            return executeInfo(command, context);
+        case 'connect':
+            return executeConnect(command, context);
+        case 'disconnect_ports':
+            return executeDisconnectPorts(command, context);
+        case 'disconnect_node':
+            return executeDisconnectNode(command, context);
+        case 'list_nodes':
+            return executeListNodes(context);
+        case 'list_edges':
+            return executeListEdges(context);
+        case 'list_types':
+            return executeListTypes(context);
+        case 'help':
+            return executeHelp(command);
+        case 'undo':
+            return executeUndo(context);
+        case 'redo':
+            return executeRedo(context);
+        case 'clear':
+            return executeClear(context);
+        case 'config_open':
+            return executeConfigOpen(command, context);
+        case 'select_node':
+            return executeSelectNode(command, context);
+        case 'swap_node':
+            return executeSwapNode(command, context);
+        case 'move_node':
+            return executeMoveNode(command, context);
+        case 'auto_layout':
+            return executeAutoLayout(command, context);
+        case 'beautify_layout':
+            return executeBeautifyLayout(command, context);
+        case 'canvas_fit_view':
+            return executeCanvasFitView(context);
+        case 'canvas_zoom_in':
+            return executeCanvasZoomIn(context);
+        case 'canvas_zoom_out':
+            return executeCanvasZoomOut(context);
+        case 'canvas_zoom_to':
+            return executeCanvasZoomTo(command, context);
+        case 'canvas_pan_to':
+            return executeCanvasPanTo(command, context);
+        case 'canvas_reset_view':
+            return executeCanvasResetView(context);
+        default: {
+            const _exhaustive = command;
+            return {
+                ok: false,
+                error: `Command not yet implemented: ${_exhaustive.type}`,
+                code: 'UNKNOWN_COMMAND'
+            };
+        }
+    }
+}