@flowdrop/flowdrop 2.0.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -0
- package/dist/commands/executor.js +4 -1
- package/dist/commands/types.d.ts +4 -0
- package/dist/components/App.svelte +122 -12
- package/dist/components/WorkflowInterfaceEditor.svelte +941 -0
- package/dist/components/WorkflowInterfaceEditor.svelte.d.ts +14 -0
- package/dist/components/form/FormPorts.svelte +34 -2
- package/dist/components/nodes/GatewayNode.svelte +13 -1
- package/dist/components/nodes/SimpleNode.svelte +11 -0
- package/dist/components/nodes/SquareNode.svelte +11 -0
- package/dist/components/nodes/TerminalNode.svelte +11 -0
- package/dist/components/nodes/WorkflowNode.svelte +11 -2
- package/dist/core/index.d.ts +1 -1
- package/dist/messages/defaults.d.ts +42 -0
- package/dist/messages/defaults.js +34 -0
- package/dist/openapi/v1/openapi.yaml +105 -0
- package/dist/schemas/v1/workflow.schema.json +109 -0
- package/dist/services/workflowLaunchService.d.ts +13 -1
- package/dist/services/workflowLaunchService.js +8 -0
- package/dist/stores/workflowStore.svelte.d.ts +22 -0
- package/dist/stores/workflowStore.svelte.js +18 -0
- package/dist/styles/base.css +10 -0
- package/dist/types/index.d.ts +58 -4
- package/dist/utils/colors.d.ts +1 -2
- package/dist/utils/colors.js +1 -2
- package/dist/utils/connections.d.ts +5 -0
- package/dist/utils/connections.js +1 -1
- package/dist/utils/nodeSwap.d.ts +9 -0
- package/dist/utils/nodeSwap.js +50 -2
- package/dist/utils/portUtils.d.ts +0 -2
- package/dist/utils/portUtils.js +0 -2
- package/dist/utils/workflowInterface.d.ts +199 -0
- package/dist/utils/workflowInterface.js +382 -0
- package/package.json +1 -1
|
@@ -41,6 +41,16 @@
|
|
|
41
41
|
"type": "object",
|
|
42
42
|
"description": "Custom workflow-level configuration values. Populated when a workflowSettingsSchema is provided to the editor.",
|
|
43
43
|
"additionalProperties": true
|
|
44
|
+
},
|
|
45
|
+
"interface": {
|
|
46
|
+
"allOf": [
|
|
47
|
+
{
|
|
48
|
+
"$ref": "#/$defs/WorkflowInterface"
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"description": "Public contract for callers. Absent = the workflow declares no interface."
|
|
52
|
+
}
|
|
53
|
+
]
|
|
44
54
|
}
|
|
45
55
|
},
|
|
46
56
|
"required": [
|
|
@@ -784,6 +794,25 @@
|
|
|
784
794
|
"const"
|
|
785
795
|
]
|
|
786
796
|
},
|
|
797
|
+
"PortBinding": {
|
|
798
|
+
"type": "object",
|
|
799
|
+
"description": "A resolved pointer to one inner node port, used by `WorkflowInterfaceEntry.bindings`.\n",
|
|
800
|
+
"properties": {
|
|
801
|
+
"nodeId": {
|
|
802
|
+
"type": "string",
|
|
803
|
+
"format": "uuid",
|
|
804
|
+
"description": "Node instance UUID (references `WorkflowNode.id`)"
|
|
805
|
+
},
|
|
806
|
+
"portId": {
|
|
807
|
+
"type": "string",
|
|
808
|
+
"description": "Port ID on that node (references a `NodePort.id` in the node's metadata)"
|
|
809
|
+
}
|
|
810
|
+
},
|
|
811
|
+
"required": [
|
|
812
|
+
"nodeId",
|
|
813
|
+
"portId"
|
|
814
|
+
]
|
|
815
|
+
},
|
|
787
816
|
"PortDataSchema": {
|
|
788
817
|
"type": "object",
|
|
789
818
|
"description": "JSON Schema describing the structure of data on an output port.\nFollows JSON Schema draft-07 specification.\n\n## Purpose\n\nEnables template variable autocomplete in downstream nodes by describing\nthe shape of data that flows through the port.\n\n## Supported Features\n\n- **Objects**: Define `properties` to enable dot notation drilling\n- **Arrays**: Define `items` to enable index access and item property drilling\n- **Nested structures**: Combine objects and arrays for deep drilling\n- **Metadata**: Use `title` and `description` for autocomplete tooltips\n\n## Example\n\nA schema describing an API response with user data and orders:\n\n```yaml\ntype: object\nproperties:\n user:\n type: object\n title: User\n description: The authenticated user\n properties:\n id: { type: integer }\n name: { type: string, description: \"User's full name\" }\n email: { type: string }\n address:\n type: object\n properties:\n city: { type: string }\n country: { type: string }\n orders:\n type: array\n title: Orders\n description: User's order history\n items:\n type: object\n properties:\n order_id: { type: string }\n total: { type: number }\n status: { type: string }\n```\n\nThis enables template patterns like:\n- `{{ user.name }}` - Access user's name\n- `{{ user.address.city }}` - Nested property access\n- `{{ orders[0].total }}` - First order's total\n- `{{ orders[0].status }}` - First order's status\n",
|
|
@@ -1056,6 +1085,86 @@
|
|
|
1056
1085
|
"target"
|
|
1057
1086
|
]
|
|
1058
1087
|
},
|
|
1088
|
+
"WorkflowInterface": {
|
|
1089
|
+
"type": "object",
|
|
1090
|
+
"description": "A workflow's public contract: named inputs/outputs that external callers supply\nor receive, each pointing at an inner node port via a binding. Array order is\nthe caller-facing order. Absent on a `Workflow` means the workflow declares no\ninterface, not an empty one.\n",
|
|
1091
|
+
"properties": {
|
|
1092
|
+
"inputs": {
|
|
1093
|
+
"type": "array",
|
|
1094
|
+
"items": {
|
|
1095
|
+
"$ref": "#/$defs/WorkflowInterfaceEntry"
|
|
1096
|
+
},
|
|
1097
|
+
"description": "Named inputs external callers supply."
|
|
1098
|
+
},
|
|
1099
|
+
"outputs": {
|
|
1100
|
+
"type": "array",
|
|
1101
|
+
"items": {
|
|
1102
|
+
"$ref": "#/$defs/WorkflowInterfaceEntry"
|
|
1103
|
+
},
|
|
1104
|
+
"description": "Named outputs external callers receive."
|
|
1105
|
+
}
|
|
1106
|
+
}
|
|
1107
|
+
},
|
|
1108
|
+
"WorkflowInterfaceEntry": {
|
|
1109
|
+
"type": "object",
|
|
1110
|
+
"description": "One entry in a workflow's public contract (see `WorkflowInterface`). Owns its own\nidentity: `id` is stable and unique within its direction (inputs and outputs are\nscoped separately), independent of whichever inner port it currently binds to —\nswapping or renaming a node does not silently break callers.\n\nOn export toward a server manifest the entry's `id` maps to the manifest's `name`\n— the server's wire identity. Renaming an `id` is therefore a breaking change for\ncallers, not a cosmetic one.\n\nEvery entry — input or output — must resolve to exactly one binding; more than\none is reported as `over-bound`. An empty `bindings` list is a valid *draft*\nstate, reported as `unbound`.\n",
|
|
1111
|
+
"properties": {
|
|
1112
|
+
"id": {
|
|
1113
|
+
"type": "string",
|
|
1114
|
+
"description": "Stable public name. Unique within its direction (inputs vs outputs)."
|
|
1115
|
+
},
|
|
1116
|
+
"name": {
|
|
1117
|
+
"type": "string",
|
|
1118
|
+
"description": "Display label for callers and UI. Defaults to `id` when absent."
|
|
1119
|
+
},
|
|
1120
|
+
"description": {
|
|
1121
|
+
"type": "string",
|
|
1122
|
+
"description": "Help text describing what this entry represents to external callers."
|
|
1123
|
+
},
|
|
1124
|
+
"dataType": {
|
|
1125
|
+
"$ref": "#/$defs/NodeDataType"
|
|
1126
|
+
},
|
|
1127
|
+
"required": {
|
|
1128
|
+
"type": "boolean",
|
|
1129
|
+
"description": "Whether callers must supply a value. Inputs only; ignored on outputs."
|
|
1130
|
+
},
|
|
1131
|
+
"defaultValue": {
|
|
1132
|
+
"description": "Default value used when no external value is supplied. Inputs only."
|
|
1133
|
+
},
|
|
1134
|
+
"examples": {
|
|
1135
|
+
"type": "array",
|
|
1136
|
+
"items": {},
|
|
1137
|
+
"description": "Example values a caller could supply — author metadata for documentation\nand launch forms, mirroring the server manifest's `examples`. Inputs\nonly; ignored on outputs. Never validated against `schema`.\n"
|
|
1138
|
+
},
|
|
1139
|
+
"schema": {
|
|
1140
|
+
"allOf": [
|
|
1141
|
+
{
|
|
1142
|
+
"$ref": "#/$defs/PortDataSchema"
|
|
1143
|
+
},
|
|
1144
|
+
{
|
|
1145
|
+
"description": "JSON Schema describing the structure of data carried by this entry."
|
|
1146
|
+
}
|
|
1147
|
+
]
|
|
1148
|
+
},
|
|
1149
|
+
"bindings": {
|
|
1150
|
+
"type": "array",
|
|
1151
|
+
"items": {
|
|
1152
|
+
"$ref": "#/$defs/PortBinding"
|
|
1153
|
+
},
|
|
1154
|
+
"description": "Inner ports this entry maps to. Every entry must resolve to exactly one\nbinding; more than one is reported as `over-bound` (the list shape is kept\nso input fan-out can become additive later). An empty list is a valid\ndraft state, reported as `unbound`. The bound port must also be\ncanvas-exposed (see `NodePort.exposedByDefault` / `config.ports`) — a\nbound-but-hidden port is reported as `hidden`.\n"
|
|
1155
|
+
},
|
|
1156
|
+
"meta": {
|
|
1157
|
+
"type": "object",
|
|
1158
|
+
"additionalProperties": true,
|
|
1159
|
+
"description": "Opaque consumer metadata. The library never reads or interprets this field\n— it round-trips verbatim on every read/write. Servers use it to say what\n\"external\" means for them, e.g. `{\"http\": {\"in\": \"query\"}}` or\n`{\"mcp\": {\"toolParam\": true}}`.\n\nKeys under the `fd.` prefix are reserved for future library use — consumers\nmust not write keys starting with `fd.`.\n"
|
|
1160
|
+
}
|
|
1161
|
+
},
|
|
1162
|
+
"required": [
|
|
1163
|
+
"id",
|
|
1164
|
+
"dataType",
|
|
1165
|
+
"bindings"
|
|
1166
|
+
]
|
|
1167
|
+
},
|
|
1059
1168
|
"WorkflowMetadata": {
|
|
1060
1169
|
"type": "object",
|
|
1061
1170
|
"properties": {
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
*/
|
|
18
18
|
import type { EndpointConfig } from '../config/endpoints.js';
|
|
19
19
|
import type { AuthProvider } from '../types/auth.js';
|
|
20
|
+
import type { Workflow } from '../types/index.js';
|
|
20
21
|
/** A single per-input validation failure reported by the backend. */
|
|
21
22
|
export interface LaunchInputError {
|
|
22
23
|
/** Machine-readable error code. */
|
|
@@ -54,10 +55,21 @@ export type LaunchResult =
|
|
|
54
55
|
status: 'unsupported';
|
|
55
56
|
};
|
|
56
57
|
export interface LaunchOptions {
|
|
57
|
-
/**
|
|
58
|
+
/**
|
|
59
|
+
* Named inputs, resolved server-side against the workflow's declared
|
|
60
|
+
* manifest. Keys are `WorkflowInterfaceEntry.id`s — the same identity the
|
|
61
|
+
* server matches on as the manifest's `name`.
|
|
62
|
+
*/
|
|
58
63
|
inputs?: Record<string, unknown>;
|
|
59
64
|
/** Attribute the run to a session, so its messages land in that conversation. */
|
|
60
65
|
sessionId?: string;
|
|
66
|
+
/**
|
|
67
|
+
* The workflow being launched. When it declares an `interface`, inputs are
|
|
68
|
+
* pre-validated against it client-side — unknown keys and missing required
|
|
69
|
+
* inputs return `invalid-input` without a network round-trip, mirroring the
|
|
70
|
+
* server's own refusal. Value type/schema checking stays with the server.
|
|
71
|
+
*/
|
|
72
|
+
workflow?: Workflow;
|
|
61
73
|
}
|
|
62
74
|
declare class WorkflowLaunchService {
|
|
63
75
|
/** True when this configuration exposes an explicit launch verb. */
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
*/
|
|
18
18
|
import { buildEndpointUrl } from '../config/endpoints.js';
|
|
19
19
|
import { authenticatedFetch } from '../utils/fetchWithAuth.js';
|
|
20
|
+
import { validateLaunchInputs } from '../utils/workflowInterface.js';
|
|
20
21
|
import { logger } from '../utils/logger.js';
|
|
21
22
|
class WorkflowLaunchService {
|
|
22
23
|
/** True when this configuration exposes an explicit launch verb. */
|
|
@@ -33,6 +34,13 @@ class WorkflowLaunchService {
|
|
|
33
34
|
const endpoint = config?.endpoints?.workflows?.run;
|
|
34
35
|
if (!config || !endpoint)
|
|
35
36
|
return { status: 'unsupported' };
|
|
37
|
+
const preflight = validateLaunchInputs(options.workflow?.interface, options.inputs ?? {});
|
|
38
|
+
if (preflight.length > 0) {
|
|
39
|
+
return {
|
|
40
|
+
status: 'invalid-input',
|
|
41
|
+
message: preflight.map((issue) => issue.message).join(' ')
|
|
42
|
+
};
|
|
43
|
+
}
|
|
36
44
|
const url = buildEndpointUrl(config, endpoint, { workflowId });
|
|
37
45
|
const body = {};
|
|
38
46
|
if (options.inputs && Object.keys(options.inputs).length > 0)
|
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
import type { Workflow, WorkflowNode, WorkflowEdge } from '../types';
|
|
14
14
|
import type { WorkflowChangeType } from '../types/events.js';
|
|
15
15
|
import type { HistoryService } from '../services/historyService.js';
|
|
16
|
+
import type { PortMapping } from '../utils/nodeSwap.js';
|
|
17
|
+
import type { WorkflowInterfaceEntry } from '../types/index.js';
|
|
16
18
|
type WorkflowMetadata = Workflow['metadata'];
|
|
17
19
|
/**
|
|
18
20
|
* Loosely-typed shape a workflow may arrive in before healing — a 1.x document
|
|
@@ -68,11 +70,19 @@ export interface WorkflowStoreActions {
|
|
|
68
70
|
description?: string;
|
|
69
71
|
metadata?: Partial<Workflow['metadata']>;
|
|
70
72
|
config?: Record<string, unknown>;
|
|
73
|
+
/** The workflow's public contract. Omit to leave it untouched. */
|
|
74
|
+
interface?: Workflow['interface'];
|
|
71
75
|
}) => void;
|
|
72
76
|
swapNode: (updates: {
|
|
73
77
|
nodes: WorkflowNode[];
|
|
74
78
|
edges: WorkflowEdge[];
|
|
75
79
|
description?: string;
|
|
80
|
+
/** The swapped-out node's id and its replacement — together with
|
|
81
|
+
* `portMappings`, drives the `workflow.interface` binding rewrite. Omit
|
|
82
|
+
* either to leave `interface` untouched. */
|
|
83
|
+
oldNodeId?: string;
|
|
84
|
+
newNodeId?: string;
|
|
85
|
+
portMappings?: PortMapping[];
|
|
76
86
|
}) => void;
|
|
77
87
|
pushHistory: (description?: string, workflow?: Workflow) => void;
|
|
78
88
|
}
|
|
@@ -136,6 +146,14 @@ export declare class WorkflowStore {
|
|
|
136
146
|
* Handle IDs are formatted `{nodeId}-{direction}-{portId}`.
|
|
137
147
|
*/
|
|
138
148
|
get connectedHandles(): Set<string>;
|
|
149
|
+
/**
|
|
150
|
+
* Handle IDs bound to a `workflow.interface` entry, mapped to the entry
|
|
151
|
+
* itself — one memoized pass over `resolveInterface`, shared by every node
|
|
152
|
+
* component and `FormPorts` instead of each re-deriving it per port. See
|
|
153
|
+
* `utils/workflowInterface.ts#interfaceBoundHandles` for what counts as
|
|
154
|
+
* "bound" (only bindings that resolve to a live port).
|
|
155
|
+
*/
|
|
156
|
+
get interfaceBoundHandles(): Map<string, WorkflowInterfaceEntry>;
|
|
139
157
|
/**
|
|
140
158
|
* The current monotonic edit version.
|
|
141
159
|
*
|
|
@@ -265,6 +283,7 @@ export declare class WorkflowStore {
|
|
|
265
283
|
description?: string;
|
|
266
284
|
metadata?: Partial<Workflow['metadata']>;
|
|
267
285
|
config?: Record<string, unknown>;
|
|
286
|
+
interface?: Workflow['interface'];
|
|
268
287
|
}): void;
|
|
269
288
|
/**
|
|
270
289
|
* Swap a node — atomically replaces nodes and edges with a descriptive history entry.
|
|
@@ -276,6 +295,9 @@ export declare class WorkflowStore {
|
|
|
276
295
|
nodes: WorkflowNode[];
|
|
277
296
|
edges: WorkflowEdge[];
|
|
278
297
|
description?: string;
|
|
298
|
+
oldNodeId?: string;
|
|
299
|
+
newNodeId?: string;
|
|
300
|
+
portMappings?: PortMapping[];
|
|
279
301
|
}): void;
|
|
280
302
|
/**
|
|
281
303
|
* Push the current (post-change) state to history manually.
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
*/
|
|
13
13
|
import { DEFAULT_WORKFLOW_FORMAT } from '../types/index.js';
|
|
14
14
|
import { WORKFLOW_SCHEMA_VERSION } from '../schemas/index.js';
|
|
15
|
+
import { interfaceBoundHandles, rewriteInterfaceBindings } from '../utils/workflowInterface.js';
|
|
15
16
|
/**
|
|
16
17
|
* Safely build updated workflow metadata, providing defaults for required fields.
|
|
17
18
|
*
|
|
@@ -268,6 +269,16 @@ export class WorkflowStore {
|
|
|
268
269
|
});
|
|
269
270
|
return handles;
|
|
270
271
|
}
|
|
272
|
+
/**
|
|
273
|
+
* Handle IDs bound to a `workflow.interface` entry, mapped to the entry
|
|
274
|
+
* itself — one memoized pass over `resolveInterface`, shared by every node
|
|
275
|
+
* component and `FormPorts` instead of each re-deriving it per port. See
|
|
276
|
+
* `utils/workflowInterface.ts#interfaceBoundHandles` for what counts as
|
|
277
|
+
* "bound" (only bindings that resolve to a live port).
|
|
278
|
+
*/
|
|
279
|
+
get interfaceBoundHandles() {
|
|
280
|
+
return this.#workflow ? interfaceBoundHandles(this.#workflow) : new Map();
|
|
281
|
+
}
|
|
271
282
|
/**
|
|
272
283
|
* The current monotonic edit version.
|
|
273
284
|
*
|
|
@@ -656,6 +667,7 @@ export class WorkflowStore {
|
|
|
656
667
|
description: updates.description
|
|
657
668
|
}),
|
|
658
669
|
...(updates.config !== undefined && { config: updates.config }),
|
|
670
|
+
...(updates.interface !== undefined && { interface: updates.interface }),
|
|
659
671
|
metadata: buildMetadata(this.#workflow.metadata, updates.metadata ?? undefined)
|
|
660
672
|
};
|
|
661
673
|
this.#pushToHistory('Batch update');
|
|
@@ -671,10 +683,16 @@ export class WorkflowStore {
|
|
|
671
683
|
swapNode(updates) {
|
|
672
684
|
if (!this.#workflow)
|
|
673
685
|
return;
|
|
686
|
+
// Node swap is the one mutation that actively moves interface bindings —
|
|
687
|
+
// every other mutation (including delete) leaves them untouched.
|
|
688
|
+
const interfaceAfterSwap = updates.oldNodeId && updates.newNodeId
|
|
689
|
+
? rewriteInterfaceBindings(this.#workflow.interface, updates.oldNodeId, updates.newNodeId, updates.portMappings ?? [])
|
|
690
|
+
: this.#workflow.interface;
|
|
674
691
|
this.#workflow = {
|
|
675
692
|
...this.#workflow,
|
|
676
693
|
nodes: updates.nodes,
|
|
677
694
|
edges: updates.edges,
|
|
695
|
+
interface: interfaceAfterSwap,
|
|
678
696
|
metadata: buildMetadata(this.#workflow.metadata)
|
|
679
697
|
};
|
|
680
698
|
this.#pushToHistory(updates.description ?? 'Swap node');
|
package/dist/styles/base.css
CHANGED
|
@@ -130,6 +130,16 @@ p {
|
|
|
130
130
|
outline-offset: var(--fd-ring-offset);
|
|
131
131
|
}
|
|
132
132
|
|
|
133
|
+
/* Interface-bound marker: a port bound to a `workflow.interface` entry
|
|
134
|
+
(see utils/workflowInterface.ts#interfaceBoundHandles) gets a subtle ring
|
|
135
|
+
around its visible dot. One shared class, applied by every node component
|
|
136
|
+
that renders a Handle, rather than five per-component styles. Reuses the
|
|
137
|
+
same --fd-ring token as the focus ring so it reads consistently — and
|
|
138
|
+
stays correct automatically — in both light and dark skins. */
|
|
139
|
+
.svelte-flow .svelte-flow__handle.flowdrop-handle--bound::before {
|
|
140
|
+
box-shadow: 0 0 0 var(--fd-ring-width) color-mix(in srgb, var(--fd-ring) 55%, transparent);
|
|
141
|
+
}
|
|
142
|
+
|
|
133
143
|
/* Centralized handle edge positioning — offset derived from --fd-handle-size */
|
|
134
144
|
.svelte-flow .svelte-flow__handle-left {
|
|
135
145
|
left: var(--fd-handle-offset);
|
package/dist/types/index.d.ts
CHANGED
|
@@ -121,8 +121,7 @@ export interface NodePort {
|
|
|
121
121
|
* Whether this port is exposed when the instance sets no explicit exposure
|
|
122
122
|
* for it. Defaults to `true` (a missing flag reads as exposed). Reserved ports
|
|
123
123
|
* that ship hidden until an author opts in (e.g. the `error` output) carry
|
|
124
|
-
* `false`. The instance's `ports` config can override it per port.
|
|
125
|
-
* `.claude/plans/exposed-ports.md`.
|
|
124
|
+
* `false`. The instance's `ports` config can override it per port.
|
|
126
125
|
*/
|
|
127
126
|
exposedByDefault?: boolean;
|
|
128
127
|
/**
|
|
@@ -161,8 +160,7 @@ export interface PortConfigEntry {
|
|
|
161
160
|
* order relative to the metadata default, and the optional `exposed` flag
|
|
162
161
|
* overrides the port's `exposedByDefault`. A port the author never touched is
|
|
163
162
|
* absent from the list; an untouched node stores no `ports` key at all. Order
|
|
164
|
-
* is cosmetic (the engine ignores it); exposure is semantic.
|
|
165
|
-
* `.claude/plans/exposed-ports.md`.
|
|
163
|
+
* is cosmetic (the engine ignores it); exposure is semantic.
|
|
166
164
|
*/
|
|
167
165
|
export interface PortsConfig {
|
|
168
166
|
inputs?: PortConfigEntry[];
|
|
@@ -1232,6 +1230,60 @@ export interface WorkflowEdge extends Edge {
|
|
|
1232
1230
|
targetCategory?: string;
|
|
1233
1231
|
};
|
|
1234
1232
|
}
|
|
1233
|
+
/**
|
|
1234
|
+
* A resolved pointer to one inner node port. Mirrors the handle-id triple in
|
|
1235
|
+
* `utils/handleIds.ts` without depending on its string encoding.
|
|
1236
|
+
*/
|
|
1237
|
+
export interface PortBinding {
|
|
1238
|
+
nodeId: string;
|
|
1239
|
+
portId: string;
|
|
1240
|
+
}
|
|
1241
|
+
/**
|
|
1242
|
+
* One entry in a workflow's public contract. Owns its own identity: `id` is
|
|
1243
|
+
* stable and workflow-scoped, independent of whichever inner port it currently
|
|
1244
|
+
* binds to, so swapping or renaming a node does not silently break callers.
|
|
1245
|
+
*
|
|
1246
|
+
* On export toward a server manifest the entry's `id` maps to the manifest's
|
|
1247
|
+
* `name` — the server's wire identity. Renaming an `id` is therefore a breaking
|
|
1248
|
+
* change for callers, not a cosmetic one.
|
|
1249
|
+
*/
|
|
1250
|
+
export interface WorkflowInterfaceEntry {
|
|
1251
|
+
/** Stable public name. Unique within its direction. */
|
|
1252
|
+
id: string;
|
|
1253
|
+
/** Display label for callers and UI. Defaults to `id` when absent. */
|
|
1254
|
+
name?: string;
|
|
1255
|
+
description?: string;
|
|
1256
|
+
dataType: NodeDataType;
|
|
1257
|
+
/** Inputs only; ignored on outputs. */
|
|
1258
|
+
required?: boolean;
|
|
1259
|
+
defaultValue?: unknown;
|
|
1260
|
+
/**
|
|
1261
|
+
* Example values a caller could supply — author metadata for docs and launch
|
|
1262
|
+
* forms, mirroring the server manifest's `examples`. Inputs only; ignored on
|
|
1263
|
+
* outputs. Never validated against `schema`.
|
|
1264
|
+
*/
|
|
1265
|
+
examples?: unknown[];
|
|
1266
|
+
schema?: InputSchema | OutputSchema;
|
|
1267
|
+
/**
|
|
1268
|
+
* Inner ports this entry maps to. Every entry — input or output — must
|
|
1269
|
+
* resolve to exactly one binding; more than one is reported as `over-bound`.
|
|
1270
|
+
* (The list shape is kept so input fan-out can become additive later.) An
|
|
1271
|
+
* empty list is a valid *draft* state, reported as `unbound`.
|
|
1272
|
+
*/
|
|
1273
|
+
bindings: PortBinding[];
|
|
1274
|
+
/**
|
|
1275
|
+
* Opaque consumer metadata. The library never reads or interprets this — it
|
|
1276
|
+
* round-trips verbatim. Servers use it to say what "external" means for them
|
|
1277
|
+
* (`{"http": {"in": "query"}}`, `{"mcp": {"toolParam": true}}`, …).
|
|
1278
|
+
* Keys under the `fd.` prefix are reserved for future library use.
|
|
1279
|
+
*/
|
|
1280
|
+
meta?: Record<string, unknown>;
|
|
1281
|
+
}
|
|
1282
|
+
/** A workflow's public contract. Array order is the caller-facing order. */
|
|
1283
|
+
export interface WorkflowInterface {
|
|
1284
|
+
inputs?: WorkflowInterfaceEntry[];
|
|
1285
|
+
outputs?: WorkflowInterfaceEntry[];
|
|
1286
|
+
}
|
|
1235
1287
|
/**
|
|
1236
1288
|
* Complete workflow definition
|
|
1237
1289
|
*/
|
|
@@ -1255,6 +1307,8 @@ export interface Workflow {
|
|
|
1255
1307
|
};
|
|
1256
1308
|
/** Custom workflow-level configuration values, populated via workflowSettingsSchema. */
|
|
1257
1309
|
config?: Record<string, unknown>;
|
|
1310
|
+
/** Public contract for callers. Absent = the workflow declares no interface. */
|
|
1311
|
+
interface?: WorkflowInterface;
|
|
1258
1312
|
}
|
|
1259
1313
|
/**
|
|
1260
1314
|
* API response types
|
package/dist/utils/colors.d.ts
CHANGED
|
@@ -245,8 +245,7 @@ export declare function getPortBorderColor(checker: PortCompatibilityChecker, da
|
|
|
245
245
|
* Whether a port is the reserved `error` output port.
|
|
246
246
|
*
|
|
247
247
|
* The reserved error output carries an arbitrary data type (json) but should
|
|
248
|
-
* read as an error affordance (red) wherever it surfaces.
|
|
249
|
-
* `.claude/plans/exposed-ports.md`.
|
|
248
|
+
* read as an error affordance (red) wherever it surfaces.
|
|
250
249
|
*/
|
|
251
250
|
export declare function isErrorPort(port: {
|
|
252
251
|
id: string;
|
package/dist/utils/colors.js
CHANGED
|
@@ -433,8 +433,7 @@ export function getPortBorderColor(checker, dataType) {
|
|
|
433
433
|
* Whether a port is the reserved `error` output port.
|
|
434
434
|
*
|
|
435
435
|
* The reserved error output carries an arbitrary data type (json) but should
|
|
436
|
-
* read as an error affordance (red) wherever it surfaces.
|
|
437
|
-
* `.claude/plans/exposed-ports.md`.
|
|
436
|
+
* read as an error affordance (red) wherever it surfaces.
|
|
438
437
|
*/
|
|
439
438
|
export function isErrorPort(port) {
|
|
440
439
|
return port.id === 'error' && port.type !== 'input';
|
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
* Connection validation utilities for FlowDrop
|
|
3
3
|
*/
|
|
4
4
|
import type { NodeMetadata, NodePort, NodeDataType, WorkflowNode, WorkflowEdge, PortConfig, PortDataTypeConfig } from '../types/index.js';
|
|
5
|
+
/**
|
|
6
|
+
* Loopback port name constant
|
|
7
|
+
* This is the standard input port name used for loop iteration triggers
|
|
8
|
+
*/
|
|
9
|
+
export declare const LOOPBACK_PORT_NAME = "loop_back";
|
|
5
10
|
/**
|
|
6
11
|
* Determines if an edge is a loopback edge.
|
|
7
12
|
* Loopback edges target the special `loop_back` input port on ForEach nodes.
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* Loopback port name constant
|
|
6
6
|
* This is the standard input port name used for loop iteration triggers
|
|
7
7
|
*/
|
|
8
|
-
const LOOPBACK_PORT_NAME = 'loop_back';
|
|
8
|
+
export const LOOPBACK_PORT_NAME = 'loop_back';
|
|
9
9
|
/**
|
|
10
10
|
* Determines if an edge is a loopback edge.
|
|
11
11
|
* Loopback edges target the special `loop_back` input port on ForEach nodes.
|
package/dist/utils/nodeSwap.d.ts
CHANGED
|
@@ -45,6 +45,15 @@ export interface SwapPreview {
|
|
|
45
45
|
configCarriedOver: string[];
|
|
46
46
|
/** Config keys reset to defaults on the new node */
|
|
47
47
|
configReset: string[];
|
|
48
|
+
/**
|
|
49
|
+
* Old-port → new-port resolution for every declared port on the old node,
|
|
50
|
+
* not just the ones a connected edge happens to touch — an interface
|
|
51
|
+
* binding can point at an exposed-but-unconnected port. Used to rewrite
|
|
52
|
+
* `workflow.interface` bindings through the swap (see
|
|
53
|
+
* `utils/workflowInterface.ts#rewriteInterfaceBindings`). A port the
|
|
54
|
+
* cascade drops has no entry here.
|
|
55
|
+
*/
|
|
56
|
+
portMappings: PortMapping[];
|
|
48
57
|
}
|
|
49
58
|
/**
|
|
50
59
|
* Result of executing a node swap.
|
package/dist/utils/nodeSwap.js
CHANGED
|
@@ -355,6 +355,35 @@ export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNo
|
|
|
355
355
|
}
|
|
356
356
|
keptEdges.push({ edge, newEdge });
|
|
357
357
|
}
|
|
358
|
+
// Resolve every declared port on the old node — not just the ones touched
|
|
359
|
+
// by a connected edge above — through the same override/strategy/matching
|
|
360
|
+
// cascade, reusing cached resolutions so an edge-driven port isn't matched
|
|
361
|
+
// twice. This is what workflow.interface bindings rewrite through; an
|
|
362
|
+
// interface binding may point at a port with no edge at all.
|
|
363
|
+
const portMappings = [];
|
|
364
|
+
for (const direction of ['input', 'output']) {
|
|
365
|
+
const oldPorts = direction === 'input' ? oldNode.data.metadata.inputs : oldNode.data.metadata.outputs;
|
|
366
|
+
const usedPorts = direction === 'input' ? usedInputPortIds : usedOutputPortIds;
|
|
367
|
+
for (const oldPort of oldPorts) {
|
|
368
|
+
const matchKey = `${direction}:${oldPort.id}`;
|
|
369
|
+
let resolved = portResolutions.get(matchKey);
|
|
370
|
+
if (!resolved) {
|
|
371
|
+
resolved = resolveNewPort(oldPort, direction, usedPorts);
|
|
372
|
+
portResolutions.set(matchKey, resolved);
|
|
373
|
+
if (resolved.port)
|
|
374
|
+
usedPorts.add(resolved.port.id);
|
|
375
|
+
}
|
|
376
|
+
if (resolved.port) {
|
|
377
|
+
portMappings.push({
|
|
378
|
+
oldHandleId: buildHandleId(oldNodeId, direction, oldPort.id),
|
|
379
|
+
newHandleId: buildHandleId(newNodeId, direction, resolved.port.id),
|
|
380
|
+
oldPortId: oldPort.id,
|
|
381
|
+
newPortId: resolved.port.id,
|
|
382
|
+
direction
|
|
383
|
+
});
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
}
|
|
358
387
|
// Config mapping — apply strategy then overrides
|
|
359
388
|
const { carriedOver, reset } = mapConfig(oldNode.data.config, newMetadata.configSchema, newMetadata.config);
|
|
360
389
|
// Apply strategy config overrides
|
|
@@ -406,7 +435,8 @@ export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNo
|
|
|
406
435
|
hasDataLoss: droppedEdges.length > 0,
|
|
407
436
|
newNodeId,
|
|
408
437
|
configCarriedOver: carriedOver,
|
|
409
|
-
configReset: reset
|
|
438
|
+
configReset: reset,
|
|
439
|
+
portMappings
|
|
410
440
|
};
|
|
411
441
|
}
|
|
412
442
|
/**
|
|
@@ -537,13 +567,31 @@ export function buildSwapPreviewFromState(state, _allEdges) {
|
|
|
537
567
|
configReset.push(cm.key);
|
|
538
568
|
}
|
|
539
569
|
}
|
|
570
|
+
// Port mappings for interface-binding rewrite. Unlike
|
|
571
|
+
// computeSwapPreviewWithOptions, this only covers ports the interactive
|
|
572
|
+
// editor surfaced — i.e. ports with a connected edge — since that is the
|
|
573
|
+
// full extent of what the user reviewed; an exposed-but-unconnected bound
|
|
574
|
+
// port isn't part of this state and its binding goes dangling on swap.
|
|
575
|
+
const portMappings = [];
|
|
576
|
+
for (const mapping of state.portMappings) {
|
|
577
|
+
if (!mapping.selectedNewPortId)
|
|
578
|
+
continue;
|
|
579
|
+
portMappings.push({
|
|
580
|
+
oldHandleId: buildHandleId(state.oldNode.id, mapping.direction, mapping.oldPort.id),
|
|
581
|
+
newHandleId: buildHandleId(state.newNodeId, mapping.direction, mapping.selectedNewPortId),
|
|
582
|
+
oldPortId: mapping.oldPort.id,
|
|
583
|
+
newPortId: mapping.selectedNewPortId,
|
|
584
|
+
direction: mapping.direction
|
|
585
|
+
});
|
|
586
|
+
}
|
|
540
587
|
return {
|
|
541
588
|
keptEdges,
|
|
542
589
|
droppedEdges,
|
|
543
590
|
hasDataLoss: droppedEdges.length > 0,
|
|
544
591
|
newNodeId: state.newNodeId,
|
|
545
592
|
configCarriedOver,
|
|
546
|
-
configReset
|
|
593
|
+
configReset,
|
|
594
|
+
portMappings
|
|
547
595
|
};
|
|
548
596
|
}
|
|
549
597
|
/**
|
|
@@ -54,7 +54,5 @@ export declare function getPortTop(index: number, count: number): number;
|
|
|
54
54
|
* wireable, and not runtime-overridable. Effective exposure is the instance's
|
|
55
55
|
* explicit `data.config.ports` override for the port, falling back to the port's
|
|
56
56
|
* metadata `exposedByDefault` (which itself defaults to exposed).
|
|
57
|
-
*
|
|
58
|
-
* @see .claude/plans/exposed-ports.md
|
|
59
57
|
*/
|
|
60
58
|
export declare function isPortVisible(port: NodePort, direction: 'input' | 'output', ports: PortsConfig | undefined): boolean;
|
package/dist/utils/portUtils.js
CHANGED
|
@@ -86,8 +86,6 @@ export function getPortTop(index, count) {
|
|
|
86
86
|
* wireable, and not runtime-overridable. Effective exposure is the instance's
|
|
87
87
|
* explicit `data.config.ports` override for the port, falling back to the port's
|
|
88
88
|
* metadata `exposedByDefault` (which itself defaults to exposed).
|
|
89
|
-
*
|
|
90
|
-
* @see .claude/plans/exposed-ports.md
|
|
91
89
|
*/
|
|
92
90
|
export function isPortVisible(port, direction, ports) {
|
|
93
91
|
const entries = direction === 'input' ? ports?.inputs : ports?.outputs;
|