@flowdrop/flowdrop 1.4.0 → 1.5.0

package/dist/utils/edgeStyling.js

@@ -0,0 +1,176 @@
+/**
+ * Edge Styling Utility
+ *
+ * Standalone functions for determining edge categories and applying
+ * visual styling to workflow edges based on source port data types.
+ * Used by both the visual editor and the command DSL system.
+ */
+import { MarkerType } from "@xyflow/svelte";
+import { extractPortId } from "../utils/handleIds.js";
+import { isLoopbackEdge } from "../utils/connections.js";
+import { EDGE_MARKER_SIZES } from "../config/constants.js";
+/**
+ * Check if a port ID matches a dynamic branch in a Gateway node.
+ * Gateway nodes store branches in config.branches array.
+ */
+export function isGatewayBranch(node, portId) {
+    const nodeType = node.data?.metadata?.type || node.type;
+    if (nodeType !== "gateway") {
+        return false;
+    }
+    const branches = node.data?.config?.branches;
+    if (!branches || !Array.isArray(branches)) {
+        return false;
+    }
+    return branches.some((branch) => branch.name === portId);
+}
+/**
+ * Get the data type of a port from a node's metadata.
+ * Also handles dynamic ports like Gateway branches.
+ */
+export function getPortDataType(node, portId, portType) {
+    // First, check static ports in metadata
+    const ports = portType === "output"
+        ? node.data?.metadata?.outputs
+        : node.data?.metadata?.inputs;
+    if (ports && Array.isArray(ports)) {
+        const port = ports.find((p) => p.id === portId);
+        if (port?.dataType) {
+            return port.dataType;
+        }
+    }
+    // Check dynamic ports from config (dynamicInputs/dynamicOutputs)
+    const dynamicKey = portType === "output" ? "dynamicOutputs" : "dynamicInputs";
+    const dynamicPorts = node.data?.config?.[dynamicKey];
+    if (dynamicPorts && Array.isArray(dynamicPorts)) {
+        const dynamicPort = dynamicPorts.find((p) => p.name === portId);
+        if (dynamicPort?.dataType) {
+            return dynamicPort.dataType;
+        }
+    }
+    // For output ports, also check dynamic Gateway branches
+    // Gateway branches are always trigger type (control flow)
+    if (portType === "output" && isGatewayBranch(node, portId)) {
+        return "trigger";
+    }
+    return null;
+}
+/**
+ * Determine the edge category based on source port data type.
+ * Note: This does not check for loopback edges — use getEdgeCategoryWithLoopback() for that.
+ */
+export function getEdgeCategory(sourcePortDataType) {
+    if (sourcePortDataType === "trigger") {
+        return "trigger";
+    }
+    if (sourcePortDataType === "tool") {
+        return "tool";
+    }
+    return "data";
+}
+/**
+ * Determine the full edge category including loopback detection.
+ * Loopback edges take precedence over source port data type.
+ */
+export function getEdgeCategoryWithLoopback(edge, sourcePortDataType) {
+    if (isLoopbackEdge(edge)) {
+        return "loopback";
+    }
+    return getEdgeCategory(sourcePortDataType);
+}
+/**
+ * Apply custom styling to a connection edge based on its source/target nodes.
+ *
+ * Sets:
+ * - edge.data.metadata.edgeType (trigger/tool/loopback/data)
+ * - edge.style, edge.class, edge.markerEnd based on category
+ * - edge.data.targetNodeType and edge.data.targetCategory
+ */
+export function applyConnectionStyling(edge, sourceNode, targetNode) {
+    // Extract port ID from sourceHandle
+    const sourcePortId = extractPortId(edge.sourceHandle);
+    // Get the source port's data type
+    const sourcePortDataType = sourcePortId
+        ? getPortDataType(sourceNode, sourcePortId, "output")
+        : null;
+    // Determine edge category (loopback takes precedence)
+    const edgeCategory = getEdgeCategoryWithLoopback(edge, sourcePortDataType);
+    // Apply styling based on edge category
+    // Marker colors use CSS custom properties so they respond to theme changes automatically
+    switch (edgeCategory) {
+        case "loopback":
+            edge.style =
+                "stroke: var(--fd-edge-loopback); stroke-dasharray: var(--fd-edge-loopback-dasharray); stroke-width: var(--fd-edge-loopback-width); opacity: var(--fd-edge-loopback-opacity);";
+            edge.class = "flowdrop--edge--loopback";
+            edge.markerEnd = {
+                type: MarkerType.ArrowClosed,
+                ...EDGE_MARKER_SIZES.loopback,
+                color: "var(--fd-edge-loopback)",
+            };
+            break;
+        case "trigger":
+            edge.style =
+                "stroke: var(--fd-edge-trigger); stroke-width: var(--fd-edge-trigger-width);";
+            edge.class = "flowdrop--edge--trigger";
+            edge.markerEnd = {
+                type: MarkerType.ArrowClosed,
+                ...EDGE_MARKER_SIZES.trigger,
+                color: "var(--fd-edge-trigger)",
+            };
+            break;
+        case "tool":
+            edge.style = "stroke: var(--fd-edge-tool); stroke-dasharray: 5 3;";
+            edge.class = "flowdrop--edge--tool";
+            edge.markerEnd = {
+                type: MarkerType.ArrowClosed,
+                ...EDGE_MARKER_SIZES.tool,
+                color: "var(--fd-edge-tool)",
+            };
+            break;
+        case "data":
+        default:
+            edge.style = "stroke: var(--fd-edge-data);";
+            edge.class = "flowdrop--edge--data";
+            edge.markerEnd = {
+                type: MarkerType.ArrowClosed,
+                ...EDGE_MARKER_SIZES.data,
+                color: "var(--fd-edge-data)",
+            };
+            break;
+    }
+    // Store metadata in edge data for API and persistence
+    edge.data = {
+        ...edge.data,
+        metadata: {
+            ...(edge.data?.metadata || {}),
+            edgeType: edgeCategory,
+            sourcePortDataType: sourcePortDataType ?? undefined,
+        },
+        targetNodeType: targetNode.type,
+        targetCategory: targetNode.data.metadata.category,
+    };
+}
+/**
+ * Update existing edges with custom styling rules.
+ * Batch operation that applies styling to all edges using a node map for O(1) lookup.
+ */
+export function updateEdgeStyles(edges, nodes) {
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    return edges.map((edge) => {
+        const sourceNode = nodeMap.get(edge.source);
+        const targetNode = nodeMap.get(edge.target);
+        const updatedEdge = { ...edge };
+        if (!sourceNode || !targetNode) {
+            updatedEdge.data = {
+                ...updatedEdge.data,
+                metadata: {
+                    ...(updatedEdge.data?.metadata || {}),
+                    edgeType: "data",
+                },
+            };
+            return updatedEdge;
+        }
+        applyConnectionStyling(updatedEdge, sourceNode, targetNode);
+        return updatedEdge;
+    });
+}

package/dist/utils/nodeIds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared node ID generation and config defaults utilities.
+ * Used by both the visual editor and the workflow adapter to ensure
+ * consistent behavior across all code paths.
+ */
+import type { ConfigSchema } from "../types/index.js";
+/**
+ * Minimal node shape required for ID generation.
+ * Both WorkflowNode and StandardNode satisfy this interface.
+ */
+interface NodeWithMetadata {
+    id: string;
+    data?: {
+        metadata?: {
+            id?: string;
+        };
+    };
+}
+/**
+ * Generate a unique node ID based on node type and existing nodes.
+ * Format: <node_type>.<number>
+ * Example: boolean_gateway.1, calculator.2
+ */
+export declare function generateNodeId(nodeTypeId: string, existingNodes: NodeWithMetadata[]): string;
+/**
+ * Extract default config values from a node's configSchema.
+ * Iterates configSchema.properties and returns an object with each property's
+ * default value (if defined).
+ */
+export declare function extractConfigDefaults(configSchema?: ConfigSchema): Record<string, unknown>;
+export {};

package/dist/utils/nodeIds.js

@@ -0,0 +1,42 @@
+/**
+ * Shared node ID generation and config defaults utilities.
+ * Used by both the visual editor and the workflow adapter to ensure
+ * consistent behavior across all code paths.
+ */
+/**
+ * Generate a unique node ID based on node type and existing nodes.
+ * Format: <node_type>.<number>
+ * Example: boolean_gateway.1, calculator.2
+ */
+export function generateNodeId(nodeTypeId, existingNodes) {
+    // Count how many nodes of this type already exist
+    const existingNodeIds = existingNodes
+        .filter((node) => node.data?.metadata?.id === nodeTypeId)
+        .map((node) => node.id);
+    // Extract the numbers from existing IDs with the same prefix
+    const existingNumbers = existingNodeIds
+        .map((id) => {
+        const match = id.match(new RegExp(`^${nodeTypeId}\\.(\\d+)$`));
+        return match ? parseInt(match[1], 10) : 0;
+    })
+        .filter((num) => num > 0);
+    // Find the next available number (highest + 1)
+    const nextNumber = existingNumbers.length > 0 ? Math.max(...existingNumbers) + 1 : 1;
+    return `${nodeTypeId}.${nextNumber}`;
+}
+/**
+ * Extract default config values from a node's configSchema.
+ * Iterates configSchema.properties and returns an object with each property's
+ * default value (if defined).
+ */
+export function extractConfigDefaults(configSchema) {
+    const config = {};
+    if (!configSchema?.properties)
+        return config;
+    for (const [key, prop] of Object.entries(configSchema.properties)) {
+        if (prop && typeof prop === "object" && "default" in prop) {
+            config[key] = prop.default;
+        }
+    }
+    return config;
+}

package/dist/utils/nodeSwap.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Node Swap utilities for FlowDrop
+ *
+ * Provides logic for swapping a workflow node with a different node type
+ * while intelligently remapping compatible port connections.
+ *
+ * @module utils/nodeSwap
+ */
+import type { WorkflowNode, WorkflowEdge, NodeMetadata, NodePort, ConfigSchema, ConfigValues } from "../types/index.js";
+import type { WorkflowValidationResult } from "./validation.js";
+import type { PortCompatibilityChecker } from "./connections.js";
+/**
+ * Describes how a single port was remapped during a swap.
+ */
+export interface PortMapping {
+    oldHandleId: string;
+    newHandleId: string;
+    oldPortId: string;
+    newPortId: string;
+    direction: "input" | "output";
+}
+/**
+ * An edge that could not be remapped and will be dropped.
+ */
+export interface DroppedEdge {
+    edge: WorkflowEdge;
+    reason: string;
+}
+/**
+ * Preview of what a node swap will do before it is executed.
+ */
+export interface SwapPreview {
+    /** Edges that will be preserved with their rewritten versions */
+    keptEdges: Array<{
+        edge: WorkflowEdge;
+        newEdge: WorkflowEdge;
+    }>;
+    /** Edges that will be removed */
+    droppedEdges: DroppedEdge[];
+    /** True if any connected edges will be lost */
+    hasDataLoss: boolean;
+    /** The new node ID that will be generated */
+    newNodeId: string;
+    /** Config keys carried over from the old node */
+    configCarriedOver: string[];
+    /** Config keys reset to defaults on the new node */
+    configReset: string[];
+}
+/**
+ * Result of executing a node swap.
+ */
+export interface SwapResult {
+    updatedNodes: WorkflowNode[];
+    updatedEdges: WorkflowEdge[];
+}
+/** Quality annotation for how a port was matched. */
+export type MatchQuality = "id" | "name" | "type" | "manual" | "unmapped";
+/** Manual override for a single port mapping. */
+export interface PortMappingOverride {
+    oldPortId: string;
+    newPortId: string | null;
+    direction: "input" | "output";
+}
+/** Manual override for a single config mapping. */
+export interface ConfigMappingOverride {
+    key: string;
+    action: "carry" | "reset" | "set";
+    value?: unknown;
+}
+/** Options bag for advanced swap functions. */
+export interface SwapOptions {
+    checker?: PortCompatibilityChecker | null;
+    portOverrides?: PortMappingOverride[];
+    configOverrides?: ConfigMappingOverride[];
+    strategies?: SwapStrategy[];
+}
+/** Pluggable strategy passed per-call, not registered globally. */
+export interface SwapStrategy {
+    readonly id: string;
+    readonly name: string;
+    canHandle(ctx: SwapStrategyContext): boolean;
+    mapPorts?(ctx: SwapStrategyContext): Record<string, string | null> | undefined;
+    mapConfig?(ctx: SwapStrategyContext): Record<string, {
+        action: "carry" | "reset" | "set";
+        value?: unknown;
+    }> | undefined;
+}
+/** Context passed to swap strategies. */
+export interface SwapStrategyContext {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    edges: WorkflowEdge[];
+    allNodes: WorkflowNode[];
+    checker: PortCompatibilityChecker | null;
+}
+/** Stable, data-only event context for swap hooks. */
+export interface SwapEventContext {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    preview: SwapPreview;
+    portOverrides: PortMappingOverride[];
+    configOverrides: ConfigMappingOverride[];
+}
+/** Error class for swap validation failures. */
+export declare class SwapValidationError extends Error {
+    constructor(message: string);
+}
+/** Editable port mapping for the interactive mapping editor. */
+export interface EditablePortMapping {
+    oldPort: NodePort;
+    edge: WorkflowEdge;
+    direction: "input" | "output";
+    selectedNewPortId: string | null;
+    matchQuality: MatchQuality;
+    autoSuggestedPortId: string | null;
+    isOverridden: boolean;
+}
+/** Editable config mapping for the interactive mapping editor. */
+export interface EditableConfigMapping {
+    key: string;
+    title: string;
+    oldValue: unknown;
+    newDefault: unknown;
+    carryOver: boolean;
+    autoCarryOver: boolean;
+    /** false for nested objects/arrays — shown as read-only, always reset */
+    isFlat: boolean;
+}
+/** Full interactive swap state for the mapping editor. */
+export interface InteractiveSwapState {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    newNodeId: string;
+    portMappings: EditablePortMapping[];
+    configMappings: EditableConfigMapping[];
+    availableNewInputs: NodePort[];
+    availableNewOutputs: NodePort[];
+}
+/**
+ * Compare two semver-like version strings.
+ * Returns positive if a > b, negative if a < b, 0 if equal.
+ *
+ * Handles pre-release tags: "2.0.0-beta" < "2.0.0"
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Map config values from an old node to a new node's schema.
+ *
+ * - Keys present in both old config and new schema: carry over the old value
+ * - Keys only in the new schema: use the schema default or newDefaults
+ * - Keys only in the old config: discarded
+ * - Dynamic port keys (dynamicInputs, dynamicOutputs, branches): never carried over
+ */
+export declare function mapConfig(oldConfig: ConfigValues, newConfigSchema: ConfigSchema | undefined, newDefaults?: Record<string, unknown>): {
+    config: ConfigValues;
+    carriedOver: string[];
+    reset: string[];
+};
+/**
+ * Compute a preview of what will happen when swapping oldNode with newMetadata.
+ *
+ * This does NOT mutate anything — it returns a preview that can be displayed
+ * to the user for confirmation before executing the swap.
+ */
+export declare function computeSwapPreview(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], checker?: PortCompatibilityChecker | null): SwapPreview;
+/**
+ * Execute a node swap using a previously computed preview.
+ *
+ * Returns new nodes and edges arrays ready for `workflowActions.batchUpdate()`.
+ */
+export declare function executeSwap(oldNode: WorkflowNode, newMetadata: NodeMetadata, preview: SwapPreview, allNodes: WorkflowNode[], allEdges: WorkflowEdge[]): SwapResult;
+/**
+ * Check if a newer version of the same node type is available.
+ *
+ * Compares the node's embedded metadata.version against the same-ID entry
+ * in the available nodes list (API returns only the latest version).
+ *
+ * @returns The newer NodeMetadata if an upgrade is available, null otherwise
+ */
+export declare function getVersionUpgrade(currentMetadata: NodeMetadata, allNodeTypes: NodeMetadata[]): NodeMetadata | null;
+/**
+ * Compute a swap preview with full options support (strategies, overrides).
+ *
+ * Resolution order:
+ * 1. Check strategies — first canHandle() match wins for mapPorts()/mapConfig()
+ * 2. Fall through to built-in 3-pass for ports not covered by strategy
+ * 3. Apply portOverrides on top (highest priority — user's manual overrides)
+ * 4. Same cascade for config
+ */
+export declare function computeSwapPreviewWithOptions(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], options: SwapOptions): SwapPreview;
+/**
+ * Compute interactive state for the mapping editor UI.
+ *
+ * Returns EditablePortMapping and EditableConfigMapping entries
+ * with match quality annotations and isFlat flags.
+ */
+export declare function computeInteractiveState(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], options?: SwapOptions): InteractiveSwapState;
+/**
+ * Convert user-edited InteractiveSwapState back into a SwapPreview
+ * for executeSwap(). Pure function, no side effects.
+ */
+export declare function buildSwapPreviewFromState(state: InteractiveSwapState, allEdges: WorkflowEdge[]): SwapPreview;
+/**
+ * Headless one-shot swap with full validation.
+ *
+ * Guardrails:
+ * - Validates oldNode.id exists in allNodes
+ * - Validates format compatibility if newMetadata.formats is set
+ * - Computes preview → executes → validates → returns result
+ * - Throws SwapValidationError on invalid input
+ */
+export declare function performSwap(oldNode: WorkflowNode, newMetadata: NodeMetadata, allNodes: WorkflowNode[], allEdges: WorkflowEdge[], options?: SwapOptions): SwapResult;
+/**
+ * Validate a swap result for structural integrity.
+ *
+ * Checks:
+ * - No dangling edge references (every edge source/target exists in nodes)
+ * - No duplicate node IDs
+ * - No duplicate edge IDs
+ */
+export declare function validateSwapResult(result: SwapResult): WorkflowValidationResult;