@d34dman/flowdrop 0.0.55 → 0.0.57

package/dist/adapters/agentspec/validator.js

@@ -0,0 +1,169 @@
+/**
+ * Agent Spec Validator
+ *
+ * Validates workflows against Agent Spec constraints for export,
+ * and validates imported Agent Spec documents for correctness.
+ */
+/**
+ * Validate a FlowDrop StandardWorkflow for Agent Spec export compatibility.
+ *
+ * Checks:
+ * - Must have exactly 1 start node (terminal/triggers)
+ * - Must have at least 1 end node (terminal/outputs)
+ * - Gateway nodes must have branches defined
+ */
+export function validateForAgentSpecExport(workflow) {
+    const errors = [];
+    const warnings = [];
+    if (workflow.nodes.length === 0) {
+        errors.push('Workflow has no nodes');
+        return { valid: false, errors, warnings };
+    }
+    // Check for start nodes
+    const startNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        if (ext === 'start_node')
+            return true;
+        return n.data.metadata.type === 'terminal' && n.data.metadata.category === 'triggers';
+    });
+    if (startNodes.length === 0) {
+        errors.push('Agent Spec requires exactly one StartNode. No start node found (terminal node with triggers category).');
+    }
+    else if (startNodes.length > 1) {
+        errors.push(`Agent Spec requires exactly one StartNode. Found ${startNodes.length}: ${startNodes.map((n) => n.id).join(', ')}`);
+    }
+    // Check for end nodes
+    const endNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        if (ext === 'end_node')
+            return true;
+        return n.data.metadata.type === 'terminal' && n.data.metadata.category === 'outputs';
+    });
+    if (endNodes.length === 0) {
+        errors.push('Agent Spec requires at least one EndNode. No end node found (terminal node with outputs category).');
+    }
+    // Check gateway nodes have branches
+    const gatewayNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        return ext === 'branching_node' || n.data.metadata.type === 'gateway';
+    });
+    for (const gw of gatewayNodes) {
+        const branches = gw.data.config?.branches;
+        if (!branches || !Array.isArray(branches) || branches.length === 0) {
+            warnings.push(`Gateway node "${gw.data.label || gw.id}" has no branches defined. Agent Spec BranchingNode requires at least one branch.`);
+        }
+    }
+    // Check for disconnected nodes
+    const connectedNodes = new Set();
+    for (const edge of workflow.edges) {
+        connectedNodes.add(edge.source);
+        connectedNodes.add(edge.target);
+    }
+    const disconnected = workflow.nodes.filter((n) => !connectedNodes.has(n.id));
+    if (disconnected.length > 0) {
+        warnings.push(`${disconnected.length} node(s) are not connected to any edges: ${disconnected.map((n) => n.data.label || n.id).join(', ')}`);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Validate an imported Agent Spec Flow document.
+ *
+ * Checks:
+ * - Has a start_node reference that exists
+ * - At least one end_node exists
+ * - All edge references point to existing nodes
+ * - BranchingNode has branches
+ * - Data flow edges reference valid properties
+ */
+export function validateAgentSpecFlow(flow) {
+    const errors = [];
+    const warnings = [];
+    if (!flow.nodes || flow.nodes.length === 0) {
+        errors.push('Flow has no nodes');
+        return { valid: false, errors, warnings };
+    }
+    // Build node name set
+    const nodeNames = new Set(flow.nodes.map((n) => n.name));
+    // Check start_node exists
+    if (!flow.start_node) {
+        errors.push('Flow is missing start_node reference');
+    }
+    else if (!nodeNames.has(flow.start_node)) {
+        errors.push(`start_node "${flow.start_node}" does not match any node name`);
+    }
+    // Check start_node is actually a start_node type
+    const startNode = flow.nodes.find((n) => n.name === flow.start_node);
+    if (startNode && startNode.component_type !== 'start_node') {
+        warnings.push(`start_node "${flow.start_node}" has component_type "${startNode.component_type}" instead of "start_node"`);
+    }
+    // Check for end nodes
+    const endNodes = flow.nodes.filter((n) => n.component_type === 'end_node');
+    if (endNodes.length === 0) {
+        warnings.push('Flow has no EndNode. Consider adding one for clarity.');
+    }
+    // Check for duplicate node names
+    const nameCount = new Map();
+    for (const node of flow.nodes) {
+        nameCount.set(node.name, (nameCount.get(node.name) || 0) + 1);
+    }
+    for (const [name, count] of nameCount) {
+        if (count > 1) {
+            errors.push(`Duplicate node name: "${name}" appears ${count} times`);
+        }
+    }
+    // Validate control-flow edges
+    for (const edge of flow.control_flow_connections) {
+        if (!nodeNames.has(edge.from_node)) {
+            errors.push(`Control flow edge "${edge.name}" references non-existent from_node "${edge.from_node}"`);
+        }
+        if (!nodeNames.has(edge.to_node)) {
+            errors.push(`Control flow edge "${edge.name}" references non-existent to_node "${edge.to_node}"`);
+        }
+        // Validate from_branch references
+        if (edge.from_branch) {
+            const fromNode = flow.nodes.find((n) => n.name === edge.from_node);
+            if (fromNode && fromNode.component_type === 'branching_node') {
+                const branchingNode = fromNode;
+                if (!branchingNode.branches?.some((b) => b.name === edge.from_branch)) {
+                    errors.push(`Control flow edge "${edge.name}" references branch "${edge.from_branch}" which doesn't exist on node "${edge.from_node}"`);
+                }
+            }
+        }
+    }
+    // Validate data-flow edges
+    if (flow.data_flow_connections) {
+        for (const edge of flow.data_flow_connections) {
+            if (!nodeNames.has(edge.source_node)) {
+                errors.push(`Data flow edge "${edge.name}" references non-existent source_node "${edge.source_node}"`);
+            }
+            if (!nodeNames.has(edge.destination_node)) {
+                errors.push(`Data flow edge "${edge.name}" references non-existent destination_node "${edge.destination_node}"`);
+            }
+            // Check that output/input properties exist on the nodes
+            const sourceNode = flow.nodes.find((n) => n.name === edge.source_node);
+            if (sourceNode?.outputs) {
+                const hasOutput = sourceNode.outputs.some((o) => o.title === edge.source_output);
+                if (!hasOutput) {
+                    warnings.push(`Data flow edge "${edge.name}": source node "${edge.source_node}" has no output named "${edge.source_output}"`);
+                }
+            }
+            const destNode = flow.nodes.find((n) => n.name === edge.destination_node);
+            if (destNode?.inputs) {
+                const hasInput = destNode.inputs.some((i) => i.title === edge.destination_input);
+                if (!hasInput) {
+                    warnings.push(`Data flow edge "${edge.name}": destination node "${edge.destination_node}" has no input named "${edge.destination_input}"`);
+                }
+            }
+        }
+    }
+    // Validate branching nodes have branches
+    for (const node of flow.nodes) {
+        if (node.component_type === 'branching_node') {
+            const bn = node;
+            if (!bn.branches || bn.branches.length === 0) {
+                warnings.push(`BranchingNode "${node.name}" has no branches defined`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/components/ConfigForm.svelte

@@ -28,7 +28,9 @@
 		ConfigEditOptions,
 		AuthProvider
 	} from '../types/index.js';
+	import type { UISchemaElement } from '../types/uischema.js';
 	import { FormField, FormFieldWrapper, FormToggle } from './form/index.js';
+	import FormUISchemaRenderer from './form/FormUISchemaRenderer.svelte';
 	import type { FieldSchema } from './form/index.js';
 	import {
 		getEffectiveConfigEditOptions,
@@ -45,6 +47,13 @@
 		node?: WorkflowNode;
 		/** Direct config schema (used when node is not provided) */
 		schema?: ConfigSchema;
+		/**
+		 * Optional UI Schema that controls field layout and grouping.
+		 * When provided, fields render according to the UISchema tree structure.
+		 * When absent, falls back to node.data.metadata.uiSchema, then flat rendering.
+		 * @see https://jsonforms.io/docs/uischema
+		 */
+		uiSchema?: UISchemaElement;
 		/** Direct config values (used when node is not provided) */
 		values?: Record<string, unknown>;
 		/** Whether to show UI extension settings section */
@@ -76,6 +85,7 @@
 	let {
 		node,
 		schema,
+		uiSchema,
 		values,
 		showUIExtensions = true,
 		workflowId,
@@ -141,6 +151,14 @@
 		return schema ?? (node?.data.metadata?.configSchema as ConfigSchema | undefined);
 	});
 
+	/**
+	 * Get the UI schema from direct prop or node metadata
+	 * Priority: direct uiSchema prop > node metadata uiSchema
+	 */
+	const configUISchema = $derived.by<UISchemaElement | undefined>(() => {
+		return uiSchema ?? (node?.data.metadata?.uiSchema as UISchemaElement | undefined);
+	});
+
 	/**
 	 * Check if the node needs dynamic schema loading
 	 * Loads when: no static schema OR preferDynamicSchema is true
@@ -548,24 +566,40 @@
 
 		{#if configSchema.properties}
 			<div class="config-form__fields">
-				{#each Object.entries(configSchema.properties) as [key, field], index (key)}
-					{@const fieldSchema = toFieldSchema(field as Record<string, unknown>)}
-					{@const required = isFieldRequired(key)}
-
-					<FormField
-						fieldKey={key}
-						schema={fieldSchema}
-						value={configValues[key]}
-						{required}
-						animationIndex={index}
+				{#if configUISchema}
+					<FormUISchemaRenderer
+						element={configUISchema}
+						schema={configSchema}
+						values={configValues}
+						requiredFields={configSchema.required ?? []}
+						onFieldChange={handleFieldChange}
+						{toFieldSchema}
 						{node}
 						nodes={workflowNodes}
 						edges={workflowEdges}
 						{workflowId}
 						{authProvider}
-						onChange={(val) => handleFieldChange(key, val)}
 					/>
-				{/each}
+				{:else}
+					{#each Object.entries(configSchema.properties) as [key, field], index (key)}
+						{@const fieldSchema = toFieldSchema(field as Record<string, unknown>)}
+						{@const required = isFieldRequired(key)}
+
+						<FormField
+							fieldKey={key}
+							schema={fieldSchema}
+							value={configValues[key]}
+							{required}
+							animationIndex={index}
+							{node}
+							nodes={workflowNodes}
+							edges={workflowEdges}
+							{workflowId}
+							{authProvider}
+							onChange={(val) => handleFieldChange(key, val)}
+						/>
+					{/each}
+				{/if}
 			</div>
 		{:else}
 			<!-- If no properties, show the raw schema for debugging -->

package/dist/components/ConfigForm.svelte.d.ts

@@ -1,9 +1,17 @@
 import type { ConfigSchema, WorkflowNode, WorkflowEdge, NodeUIExtensions, AuthProvider } from '../types/index.js';
+import type { UISchemaElement } from '../types/uischema.js';
 interface Props {
     /** Optional workflow node (if provided, schema and values are derived from it) */
     node?: WorkflowNode;
     /** Direct config schema (used when node is not provided) */
     schema?: ConfigSchema;
+    /**
+     * Optional UI Schema that controls field layout and grouping.
+     * When provided, fields render according to the UISchema tree structure.
+     * When absent, falls back to node.data.metadata.uiSchema, then flat rendering.
+     * @see https://jsonforms.io/docs/uischema
+     */
+    uiSchema?: UISchemaElement;
     /** Direct config values (used when node is not provided) */
     values?: Record<string, unknown>;
     /** Whether to show UI extension settings section */

package/dist/components/SchemaForm.svelte

@@ -53,7 +53,9 @@
 	import { setContext } from 'svelte';
 	import Icon from '@iconify/svelte';
 	import type { ConfigSchema, AuthProvider } from '../types/index.js';
+	import type { UISchemaElement } from '../types/uischema.js';
 	import { FormField } from './form/index.js';
+	import FormUISchemaRenderer from './form/FormUISchemaRenderer.svelte';
 	import type { FieldSchema } from './form/index.js';
 
 	/**
@@ -66,6 +68,14 @@
 		 */
 		schema: ConfigSchema;
 
+		/**
+		 * Optional UI Schema that controls field layout and grouping.
+		 * When provided, fields render according to the UISchema tree structure.
+		 * When absent, fields render in flat order from schema.properties.
+		 * @see https://jsonforms.io/docs/uischema
+		 */
+		uiSchema?: UISchemaElement;
+
 		/**
 		 * Current form values as key-value pairs.
 		 * Keys should correspond to properties defined in the schema.
@@ -142,6 +152,7 @@
 
 	let {
 		schema,
+		uiSchema,
 		values = {},
 		onChange,
 		showActions = false,
@@ -297,19 +308,30 @@
 		}}
 	>
 		<div class="schema-form__fields">
-			{#each Object.entries(schema.properties) as [key, field], index (key)}
-				{@const fieldSchema = toFieldSchema(field as Record<string, unknown>)}
-				{@const required = isFieldRequired(key)}
-
-				<FormField
-					fieldKey={key}
-					schema={fieldSchema}
-					value={formValues[key]}
-					{required}
-					animationIndex={index}
-					onChange={(val) => handleFieldChange(key, val)}
+			{#if uiSchema}
+				<FormUISchemaRenderer
+					element={uiSchema}
+					{schema}
+					values={formValues}
+					requiredFields={schema.required ?? []}
+					onFieldChange={handleFieldChange}
+					{toFieldSchema}
 				/>
-			{/each}
+			{:else}
+				{#each Object.entries(schema.properties) as [key, field], index (key)}
+					{@const fieldSchema = toFieldSchema(field as Record<string, unknown>)}
+					{@const required = isFieldRequired(key)}
+
+					<FormField
+						fieldKey={key}
+						schema={fieldSchema}
+						value={formValues[key]}
+						{required}
+						animationIndex={index}
+						onChange={(val) => handleFieldChange(key, val)}
+					/>
+				{/each}
+			{/if}
 		</div>
 
 		{#if showActions}

package/dist/components/SchemaForm.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { ConfigSchema, AuthProvider } from '../types/index.js';
+import type { UISchemaElement } from '../types/uischema.js';
 /**
  * Props interface for SchemaForm component
  */
@@ -8,6 +9,13 @@ interface Props {
      * Should follow JSON Schema draft-07 format with type: "object".
      */
     schema: ConfigSchema;
+    /**
+     * Optional UI Schema that controls field layout and grouping.
+     * When provided, fields render according to the UISchema tree structure.
+     * When absent, fields render in flat order from schema.properties.
+     * @see https://jsonforms.io/docs/uischema
+     */
+    uiSchema?: UISchemaElement;
     /**
      * Current form values as key-value pairs.
      * Keys should correspond to properties defined in the schema.

package/dist/components/form/FormFieldset.svelte

@@ -0,0 +1,142 @@
+<!--
+  FormFieldset Component
+  Renders a UISchema Group element as a collapsible or static fieldset.
+
+  Two rendering modes:
+  - Collapsible (default): Uses HTML5 <details>/<summary> with .flowdrop-details CSS
+  - Static (collapsible: false): Uses a styled <fieldset> with <legend>
+
+  Features:
+  - HTML5 <details> for native accessible collapse behavior
+  - Reuses existing .flowdrop-details CSS pattern from base.css
+  - Optional description text below the group title
+  - Chevron rotation animation on open/close
+-->
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { UISchemaGroup } from '../../types/uischema.js';
+	import Icon from '@iconify/svelte';
+
+	interface Props {
+		/** The UISchema Group element to render */
+		group: UISchemaGroup;
+		/** Slot content for the group's child elements */
+		children: Snippet;
+	}
+
+	let { group, children }: Props = $props();
+
+	const isCollapsible = $derived(group.collapsible !== false);
+	const isDefaultOpen = $derived(group.defaultOpen !== false);
+</script>
+
+{#if isCollapsible}
+	<details class="flowdrop-details form-fieldset" open={isDefaultOpen}>
+		<summary class="flowdrop-details__summary form-fieldset__summary">
+			<div class="form-fieldset__label">
+				<Icon icon="heroicons:chevron-right" class="form-fieldset__chevron" />
+				<span class="form-fieldset__title">{group.label}</span>
+			</div>
+			{#if group.description}
+				<span class="form-fieldset__badge">{group.description}</span>
+			{/if}
+		</summary>
+		<div class="flowdrop-details__content form-fieldset__content">
+			<div class="form-fieldset__fields">
+				{@render children()}
+			</div>
+		</div>
+	</details>
+{:else}
+	<fieldset class="form-fieldset form-fieldset--static">
+		<legend class="form-fieldset__legend">{group.label}</legend>
+		{#if group.description}
+			<p class="form-fieldset__description">{group.description}</p>
+		{/if}
+		<div class="form-fieldset__fields">
+			{@render children()}
+		</div>
+	</fieldset>
+{/if}
+
+<style>
+	/* ============================================
+	   COLLAPSIBLE FIELDSET
+	   Extends .flowdrop-details from base.css
+	   ============================================ */
+
+	.form-fieldset__summary {
+		gap: var(--fd-space-2);
+	}
+
+	.form-fieldset__label {
+		display: flex;
+		align-items: center;
+		gap: var(--fd-space-2);
+	}
+
+	.form-fieldset__title {
+		font-size: var(--fd-text-sm);
+		font-weight: 600;
+		color: var(--fd-foreground);
+	}
+
+	.form-fieldset :global(.form-fieldset__chevron) {
+		width: 1rem;
+		height: 1rem;
+		color: var(--fd-muted-foreground);
+		transition: transform var(--fd-transition-fast);
+		flex-shrink: 0;
+	}
+
+	/* Rotate chevron when details is open */
+	details.form-fieldset[open] :global(.form-fieldset__chevron) {
+		transform: rotate(90deg);
+	}
+
+	.form-fieldset__badge {
+		font-size: var(--fd-text-xs);
+		color: var(--fd-muted-foreground);
+		line-height: 1.4;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		max-width: 200px;
+	}
+
+	.form-fieldset__content {
+		padding-top: var(--fd-space-2);
+	}
+
+	.form-fieldset__fields {
+		display: flex;
+		flex-direction: column;
+		gap: var(--fd-space-5);
+	}
+
+	/* ============================================
+	   STATIC FIELDSET (non-collapsible)
+	   ============================================ */
+
+	.form-fieldset--static {
+		border: 1px solid var(--fd-border-muted);
+		border-radius: var(--fd-radius-lg);
+		padding: var(--fd-space-4);
+		margin: 0;
+	}
+
+	.form-fieldset__legend {
+		padding: 0 var(--fd-space-2);
+		font-size: var(--fd-text-sm);
+		font-weight: 600;
+		color: var(--fd-foreground);
+	}
+
+	.form-fieldset__description {
+		margin: 0 0 var(--fd-space-3) 0;
+		font-size: var(--fd-text-xs);
+		color: var(--fd-muted-foreground);
+		line-height: 1.4;
+	}
+</style>

package/dist/components/form/FormFieldset.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from 'svelte';
+import type { UISchemaGroup } from '../../types/uischema.js';
+interface Props {
+    /** The UISchema Group element to render */
+    group: UISchemaGroup;
+    /** Slot content for the group's child elements */
+    children: Snippet;
+}
+declare const FormFieldset: import("svelte").Component<Props, {}, "">;
+type FormFieldset = ReturnType<typeof FormFieldset>;
+export default FormFieldset;

package/dist/components/form/FormUISchemaRenderer.svelte

@@ -0,0 +1,140 @@
+<!--
+  FormUISchemaRenderer Component
+  Recursively renders UISchema elements: VerticalLayout, Group, and Control.
+
+  This component bridges the UISchema tree and the existing FormField components.
+  It resolves Control scopes to property keys and delegates field rendering to FormField.
+
+  Rendering logic:
+  - Control -> resolve scope to key, render FormField
+  - VerticalLayout -> vertical flex container with recursive children
+  - Group -> FormFieldset wrapping recursive children
+-->
+
+<script lang="ts">
+	import type { UISchemaElement } from '../../types/uischema.js';
+	import type {
+		ConfigSchema,
+		WorkflowNode,
+		WorkflowEdge,
+		AuthProvider
+	} from '../../types/index.js';
+	import type { FieldSchema } from './types.js';
+	import { resolveScopeToKey } from '../../utils/uischema.js';
+	import FormField from './FormField.svelte';
+	import FormFieldset from './FormFieldset.svelte';
+
+	interface Props {
+		/** The UISchema element to render */
+		element: UISchemaElement;
+		/** The data schema (for resolving field definitions) */
+		schema: ConfigSchema;
+		/** Current form values */
+		values: Record<string, unknown>;
+		/** Required field keys from the schema */
+		requiredFields?: string[];
+		/** Base animation index for staggered animations */
+		animationIndexBase?: number;
+		/** Callback when a field value changes */
+		onFieldChange: (key: string, value: unknown) => void;
+		/** Convert a property to FieldSchema (handles template variable injection etc.) */
+		toFieldSchema: (property: Record<string, unknown>) => FieldSchema;
+		/** Current workflow node (optional, passed through to FormField) */
+		node?: WorkflowNode;
+		/** All workflow nodes (optional, passed through to FormField) */
+		nodes?: WorkflowNode[];
+		/** All workflow edges (optional, passed through to FormField) */
+		edges?: WorkflowEdge[];
+		/** Workflow ID (optional, passed through to FormField) */
+		workflowId?: string;
+		/** Auth provider (optional, passed through to FormField) */
+		authProvider?: AuthProvider;
+	}
+
+	let {
+		element,
+		schema,
+		values,
+		requiredFields = [],
+		animationIndexBase = 0,
+		onFieldChange,
+		toFieldSchema,
+		node,
+		nodes,
+		edges,
+		workflowId,
+		authProvider
+	}: Props = $props();
+
+	function isRequired(key: string): boolean {
+		return requiredFields.includes(key);
+	}
+</script>
+
+{#if element.type === 'Control'}
+	{@const key = resolveScopeToKey(element.scope)}
+	{#if key && schema.properties[key]}
+		{@const fieldSchema = toFieldSchema(schema.properties[key] as Record<string, unknown>)}
+		<FormField
+			fieldKey={key}
+			schema={fieldSchema}
+			value={values[key]}
+			required={isRequired(key)}
+			animationIndex={animationIndexBase}
+			{node}
+			{nodes}
+			{edges}
+			{workflowId}
+			{authProvider}
+			onChange={(val) => onFieldChange(key, val)}
+		/>
+	{/if}
+{:else if element.type === 'VerticalLayout'}
+	<div class="form-uischema-layout form-uischema-layout--vertical">
+		{#each element.elements as child, idx (idx)}
+			<svelte:self
+				element={child}
+				{schema}
+				{values}
+				{requiredFields}
+				animationIndexBase={animationIndexBase + idx}
+				{onFieldChange}
+				{toFieldSchema}
+				{node}
+				{nodes}
+				{edges}
+				{workflowId}
+				{authProvider}
+			/>
+		{/each}
+	</div>
+{:else if element.type === 'Group'}
+	<FormFieldset group={element}>
+		<div class="form-uischema-layout form-uischema-layout--vertical">
+			{#each element.elements as child, idx (idx)}
+				<svelte:self
+					element={child}
+					{schema}
+					{values}
+					{requiredFields}
+					animationIndexBase={animationIndexBase + idx}
+					{onFieldChange}
+					{toFieldSchema}
+					{node}
+					{nodes}
+					{edges}
+					{workflowId}
+					{authProvider}
+				/>
+			{/each}
+		</div>
+	</FormFieldset>
+{/if}
+
+<style>
+	.form-uischema-layout--vertical {
+		display: flex;
+		flex-direction: column;
+		gap: var(--fd-space-5);
+	}
+</style>