@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.
Files changed (34) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/commands/executor.js +4 -1
  3. package/dist/commands/types.d.ts +4 -0
  4. package/dist/components/App.svelte +122 -12
  5. package/dist/components/WorkflowInterfaceEditor.svelte +941 -0
  6. package/dist/components/WorkflowInterfaceEditor.svelte.d.ts +14 -0
  7. package/dist/components/form/FormPorts.svelte +34 -2
  8. package/dist/components/nodes/GatewayNode.svelte +13 -1
  9. package/dist/components/nodes/SimpleNode.svelte +11 -0
  10. package/dist/components/nodes/SquareNode.svelte +11 -0
  11. package/dist/components/nodes/TerminalNode.svelte +11 -0
  12. package/dist/components/nodes/WorkflowNode.svelte +11 -2
  13. package/dist/core/index.d.ts +1 -1
  14. package/dist/messages/defaults.d.ts +42 -0
  15. package/dist/messages/defaults.js +34 -0
  16. package/dist/openapi/v1/openapi.yaml +105 -0
  17. package/dist/schemas/v1/workflow.schema.json +109 -0
  18. package/dist/services/workflowLaunchService.d.ts +13 -1
  19. package/dist/services/workflowLaunchService.js +8 -0
  20. package/dist/stores/workflowStore.svelte.d.ts +22 -0
  21. package/dist/stores/workflowStore.svelte.js +18 -0
  22. package/dist/styles/base.css +10 -0
  23. package/dist/types/index.d.ts +58 -4
  24. package/dist/utils/colors.d.ts +1 -2
  25. package/dist/utils/colors.js +1 -2
  26. package/dist/utils/connections.d.ts +5 -0
  27. package/dist/utils/connections.js +1 -1
  28. package/dist/utils/nodeSwap.d.ts +9 -0
  29. package/dist/utils/nodeSwap.js +50 -2
  30. package/dist/utils/portUtils.d.ts +0 -2
  31. package/dist/utils/portUtils.js +0 -2
  32. package/dist/utils/workflowInterface.d.ts +199 -0
  33. package/dist/utils/workflowInterface.js +382 -0
  34. package/package.json +1 -1
@@ -0,0 +1,199 @@
1
+ /**
2
+ * Workflow interface resolution + validation
3
+ *
4
+ * A workflow's `interface` (see `types/index.ts`) is its public contract:
5
+ * named inputs/outputs a caller supplies or receives, each pointing at inner
6
+ * node ports via `PortBinding`. This module resolves those bindings against a
7
+ * workflow's live node graph and reports how well-formed the contract is.
8
+ *
9
+ * Everything here is a pure function: no store or component dependency, never
10
+ * throws, never mutates its arguments. `utils/validation.ts` is the precedent
11
+ * for advisory tone — issues are reported, not enforced.
12
+ *
13
+ * @module utils/workflowInterface
14
+ */
15
+ import type { NodePort, PortBinding, Workflow, WorkflowInterface, WorkflowInterfaceEntry, WorkflowNode } from '../types/index.js';
16
+ import type { PortMapping } from './nodeSwap.js';
17
+ /**
18
+ * A binding resolved against the live node graph: the node and port it
19
+ * points at, and which side of that node the port lives on.
20
+ */
21
+ export interface ResolvedBinding {
22
+ node: WorkflowNode;
23
+ port: NodePort;
24
+ /** The inner port's own direction — independent of the entry's direction. */
25
+ direction: 'input' | 'output';
26
+ }
27
+ /**
28
+ * Health of one interface entry, in order of severity (most severe first).
29
+ * Only one status is ever reported per entry — see `STATUS_PRECEDENCE`.
30
+ *
31
+ * - `ok` — every binding resolves, is exposed, and matches type.
32
+ * - `unbound` — `bindings` is empty. A valid draft state, not an error.
33
+ * - `dangling` — a binding's node or port no longer exists in the graph.
34
+ * - `hidden` — the bound port exists but is not canvas-exposed
35
+ * (per design decision 3: external ⊂ internal — see `isPortExposed`).
36
+ * - `type-mismatch` — the entry's declared `dataType` differs from the bound
37
+ * port's. Advisory only; the library does not coerce.
38
+ * - `over-bound` — more than one binding resolved.
39
+ *
40
+ * The design record scopes this to outputs only ("an output with >1
41
+ * binding"). This implementation extends the same rule to inputs per
42
+ * workspace decision R2: v1 ships input fan-out as a documented
43
+ * limitation, not a partial feature, so an input with multiple bindings is
44
+ * reported the same way an output is. `bindings` stays an array on both
45
+ * sides so fan-out can become additive later without a shape change.
46
+ */
47
+ export type InterfaceEntryStatus = 'ok' | 'unbound' | 'dangling' | 'hidden' | 'type-mismatch' | 'over-bound';
48
+ /** Precedence used to pick the single reported status when several apply. */
49
+ declare const STATUS_PRECEDENCE: readonly InterfaceEntryStatus[];
50
+ /** One interface entry plus its resolved targets and health. */
51
+ export interface ResolvedInterfaceEntry {
52
+ entry: WorkflowInterfaceEntry;
53
+ direction: 'input' | 'output';
54
+ /** Bindings that resolved to a live node port. Dangling bindings are omitted. */
55
+ targets: ResolvedBinding[];
56
+ status: InterfaceEntryStatus;
57
+ }
58
+ /** One advisory finding from `validateWorkflowInterface`. */
59
+ export interface InterfaceIssue {
60
+ entryId: string;
61
+ direction: 'input' | 'output';
62
+ severity: 'error' | 'warning';
63
+ code: string;
64
+ message: string;
65
+ }
66
+ /**
67
+ * Resolve one `PortBinding` against a workflow's live node graph.
68
+ *
69
+ * Walks `workflow.nodes` for the bound node, then that node's declared
70
+ * metadata ports (inputs and outputs) for the bound port. Returns `null` if
71
+ * the node no longer exists, or the port isn't among that node's metadata
72
+ * ports — the two ways a binding goes dangling.
73
+ */
74
+ export declare function resolveBinding(workflow: Workflow, binding: PortBinding): ResolvedBinding | null;
75
+ /**
76
+ * Resolve every entry of `workflow.interface` (inputs then outputs) against
77
+ * the live node graph, with a health status per entry.
78
+ *
79
+ * A workflow with no `interface` key returns `[]` — absent interface means
80
+ * "declares no contract," not "empty contract with issues."
81
+ */
82
+ export declare function resolveInterface(workflow: Workflow): ResolvedInterfaceEntry[];
83
+ /**
84
+ * Advisory validation for `workflow.interface`. Never throws, never mutates.
85
+ * Returns an empty array for a workflow with no `interface` key.
86
+ *
87
+ * Reports, per entry:
88
+ * - every non-`ok` status from `resolveInterface`;
89
+ * - a duplicate `id` within the same direction (inputs and outputs are
90
+ * scoped separately, matching the entry doc's "unique within its direction");
91
+ * - for input entries, a bound port that already has an incoming edge — two
92
+ * sources writing the same value;
93
+ * - a binding whose resolved port direction contradicts the entry's own
94
+ * direction (an "input" entry bound to a node's output port, or vice versa).
95
+ */
96
+ export declare function validateWorkflowInterface(workflow: Workflow): InterfaceIssue[];
97
+ /** One pre-launch input problem, mirroring the server's refusal semantics. */
98
+ export interface LaunchInputIssue {
99
+ /** The offending input key, when attributable to one. */
100
+ key?: string;
101
+ code: 'unknown-key' | 'missing-required';
102
+ message: string;
103
+ }
104
+ /**
105
+ * Pre-validate launch inputs against a declared interface, mirroring what the
106
+ * server's manifest check refuses: an unknown key (named against the accepted
107
+ * set) and a missing required input. Value type/enum checking stays with the
108
+ * server — the client does not re-implement schema validation.
109
+ *
110
+ * A workflow with no declared interface returns no issues: there is nothing
111
+ * to pre-validate against and the server remains the authority.
112
+ */
113
+ export declare function validateLaunchInputs(workflowInterface: WorkflowInterface | undefined, inputs: Record<string, unknown>): LaunchInputIssue[];
114
+ export { STATUS_PRECEDENCE };
115
+ /**
116
+ * Handle IDs bound to a workflow interface entry, mapped to the entry itself
117
+ * (so a caller can render the entry's public name — e.g. in a tooltip —
118
+ * without a second lookup).
119
+ *
120
+ * Built from `resolveInterface`, so it inherits the same resolution rules:
121
+ * only bindings that resolve to a *live* port contribute a handle id. A
122
+ * `dangling` binding has no live handle to mark, and an `unbound` entry has
123
+ * no bindings at all — neither appears here. A `hidden` binding does resolve
124
+ * (its handle id is included), but the node components filter not-exposed
125
+ * ports out of render entirely, so no handle ever exists for it to mark in
126
+ * practice. Every other status (`ok`, `type-mismatch`, `over-bound`)
127
+ * contributes its resolved target(s) — the ring is a "this port is part of
128
+ * the public contract" marker, not a "this entry is fully healthy" one; the
129
+ * canonical editor (Phase 3) is where health is explained in words.
130
+ *
131
+ * When a binding's target resolves to more than one caller (an `over-bound`
132
+ * output), each target's handle id maps to the same entry.
133
+ *
134
+ * Handle ids use the target *port's* own direction (`ResolvedBinding.direction`),
135
+ * matching the id every node component actually renders
136
+ * (`buildHandleId(nodeId, direction, portId)`) — not the entry's direction,
137
+ * which can differ from the bound port's for a misdirected binding.
138
+ */
139
+ export declare function interfaceBoundHandles(workflow: Workflow): Map<string, WorkflowInterfaceEntry>;
140
+ /**
141
+ * Tooltip text for a handle bound to an interface entry — `undefined` when
142
+ * `entry` is `undefined` (the port isn't bound), so callers can pass
143
+ * `interfaceBoundHandles(workflow).get(handleId)` straight through without an
144
+ * intermediate check. The single home for this string so all five node
145
+ * components and `FormPorts` render identical wording.
146
+ */
147
+ export declare function interfaceBoundTooltip(entry: WorkflowInterfaceEntry | undefined): string | undefined;
148
+ /**
149
+ * Rewrite `workflow.interface` bindings that point at a node swapped out by
150
+ * `nodeSwap.ts` — the one place bindings actively move (see
151
+ * `.claude/plans/workflow-interface.md` Phase 2). Every other mutation
152
+ * (including node deletion) leaves bindings untouched by design.
153
+ *
154
+ * A binding `{ nodeId: oldNodeId, portId }` on an input entry is rewritten
155
+ * when `portMappings` has a `direction: 'input'` mapping for that `portId`;
156
+ * output entries match against `direction: 'output'` mappings the same way —
157
+ * an entry's own direction (which array it lives in) picks which side of the
158
+ * mapping applies. A port the mapping drops (no matching entry) is left
159
+ * untouched; it resolves as `dangling` once the old node is gone, the same
160
+ * as any other dangling binding — no silent pruning.
161
+ *
162
+ * Pure: returns a new `WorkflowInterface`, never mutates its argument.
163
+ * Returns the input unchanged when there is no interface to rewrite.
164
+ */
165
+ export declare function rewriteInterfaceBindings(workflowInterface: WorkflowInterface | undefined, oldNodeId: string, newNodeId: string, portMappings: PortMapping[]): WorkflowInterface | undefined;
166
+ /** Plain-prose explanation for a resolved entry's health, covering every status. */
167
+ export declare function describeInterfaceEntryStatus(resolved: ResolvedInterfaceEntry): string;
168
+ /**
169
+ * Entry fields derivable from a bound port — the "pull details from port"
170
+ * convenience. Copies the port's display name, dataType, and (when the port
171
+ * declares them) description, required and defaultValue. Only fields the port
172
+ * actually provides appear in the patch, so applying it never blanks a value
173
+ * the author already wrote for a field the port is silent about.
174
+ *
175
+ * The public `id` is deliberately NOT derived — a contract keyed on internal
176
+ * port names is the failure mode DN1 exists to prevent.
177
+ */
178
+ export declare function pullEntryFieldsFromPort(port: NodePort): Partial<WorkflowInterfaceEntry>;
179
+ /** One inner port a `WorkflowInterfaceEntry` could bind to, plus its owning node. */
180
+ export interface BindablePort {
181
+ nodeId: string;
182
+ /** The node's display label, for a human-readable option list. */
183
+ nodeLabel: string;
184
+ port: NodePort;
185
+ }
186
+ /**
187
+ * Every canvas-exposed port of a workflow, for one direction — the candidate
188
+ * set a binding picker offers (design decision 3: external ⊂ internal, so an
189
+ * entry may only bind to a port that is already exposed).
190
+ *
191
+ * Mirrors `FormPorts.svelte`'s port list: a node's static metadata ports plus
192
+ * its user-defined dynamic ports, filtered by `isPortExposed`.
193
+ *
194
+ * Control-flow ports are excluded: the reserved `trigger`/`tool` dataTypes and
195
+ * the `loop_back` port are intra-graph control flow, not an external surface
196
+ * (DN1's grounded fact). The model and validation stay permissive — this only
197
+ * constrains what the authoring picker offers.
198
+ */
199
+ export declare function listBindablePorts(workflow: Workflow, direction: 'input' | 'output'): BindablePort[];
@@ -0,0 +1,382 @@
1
+ /**
2
+ * Workflow interface resolution + validation
3
+ *
4
+ * A workflow's `interface` (see `types/index.ts`) is its public contract:
5
+ * named inputs/outputs a caller supplies or receives, each pointing at inner
6
+ * node ports via `PortBinding`. This module resolves those bindings against a
7
+ * workflow's live node graph and reports how well-formed the contract is.
8
+ *
9
+ * Everything here is a pure function: no store or component dependency, never
10
+ * throws, never mutates its arguments. `utils/validation.ts` is the precedent
11
+ * for advisory tone — issues are reported, not enforced.
12
+ *
13
+ * @module utils/workflowInterface
14
+ */
15
+ import { dynamicPortToNodePort } from '../types/index.js';
16
+ import { isPortExposed } from './portUtils.js';
17
+ import { LOOPBACK_PORT_NAME } from './connections.js';
18
+ import { PORTS_CONFIG_KEY } from './nodeFormSchema.js';
19
+ import { buildHandleId } from './handleIds.js';
20
+ /** Precedence used to pick the single reported status when several apply. */
21
+ const STATUS_PRECEDENCE = [
22
+ 'dangling',
23
+ 'over-bound',
24
+ 'hidden',
25
+ 'type-mismatch',
26
+ 'unbound',
27
+ 'ok'
28
+ ];
29
+ /**
30
+ * Resolve one `PortBinding` against a workflow's live node graph.
31
+ *
32
+ * Walks `workflow.nodes` for the bound node, then that node's declared
33
+ * metadata ports (inputs and outputs) for the bound port. Returns `null` if
34
+ * the node no longer exists, or the port isn't among that node's metadata
35
+ * ports — the two ways a binding goes dangling.
36
+ */
37
+ export function resolveBinding(workflow, binding) {
38
+ const node = workflow.nodes.find((candidate) => candidate.id === binding.nodeId);
39
+ if (!node)
40
+ return null;
41
+ const metadata = node.data?.metadata;
42
+ const inputPort = metadata?.inputs?.find((port) => port.id === binding.portId);
43
+ if (inputPort)
44
+ return { node, port: inputPort, direction: 'input' };
45
+ const outputPort = metadata?.outputs?.find((port) => port.id === binding.portId);
46
+ if (outputPort)
47
+ return { node, port: outputPort, direction: 'output' };
48
+ return null;
49
+ }
50
+ /** The instance's `config.ports` entries for a resolved binding's own direction. */
51
+ function portConfigEntriesFor(target) {
52
+ const portsConfig = target.node.data?.config?.[PORTS_CONFIG_KEY];
53
+ return target.direction === 'input' ? portsConfig?.inputs : portsConfig?.outputs;
54
+ }
55
+ /** Whether a resolved binding's target port is canvas-exposed. */
56
+ function isBindingExposed(target) {
57
+ return isPortExposed(target.port, portConfigEntriesFor(target));
58
+ }
59
+ function resolveEntry(workflow, entry, direction) {
60
+ if (entry.bindings.length === 0) {
61
+ return { entry, direction, targets: [], status: 'unbound' };
62
+ }
63
+ const resolved = entry.bindings.map((binding) => resolveBinding(workflow, binding));
64
+ const targets = resolved.filter((target) => target !== null);
65
+ const isDangling = targets.length !== resolved.length;
66
+ let status;
67
+ if (isDangling) {
68
+ status = 'dangling';
69
+ }
70
+ else if (targets.length > 1) {
71
+ status = 'over-bound';
72
+ }
73
+ else if (!isBindingExposed(targets[0])) {
74
+ status = 'hidden';
75
+ }
76
+ else if (targets[0].port.dataType !== entry.dataType) {
77
+ status = 'type-mismatch';
78
+ }
79
+ else {
80
+ status = 'ok';
81
+ }
82
+ return { entry, direction, targets, status };
83
+ }
84
+ /**
85
+ * Resolve every entry of `workflow.interface` (inputs then outputs) against
86
+ * the live node graph, with a health status per entry.
87
+ *
88
+ * A workflow with no `interface` key returns `[]` — absent interface means
89
+ * "declares no contract," not "empty contract with issues."
90
+ */
91
+ export function resolveInterface(workflow) {
92
+ const inputs = workflow.interface?.inputs ?? [];
93
+ const outputs = workflow.interface?.outputs ?? [];
94
+ return [
95
+ ...inputs.map((entry) => resolveEntry(workflow, entry, 'input')),
96
+ ...outputs.map((entry) => resolveEntry(workflow, entry, 'output'))
97
+ ];
98
+ }
99
+ const STATUS_MESSAGE = {
100
+ unbound: (entry) => `Interface entry "${entry}" has no bindings yet — a valid draft state.`,
101
+ dangling: (entry) => `Interface entry "${entry}" is bound to a node or port that no longer exists in this workflow.`,
102
+ 'over-bound': (entry) => `Interface entry "${entry}" has more than one binding; v1 requires exactly one per entry.`,
103
+ hidden: (entry) => `Interface entry "${entry}" is bound to a port that is not exposed on the canvas, so external callers cannot reach it.`,
104
+ 'type-mismatch': (entry) => `Interface entry "${entry}" declares a data type that does not match its bound port's type.`
105
+ };
106
+ /** Severity assigned to each non-`ok` status when surfaced as a validation issue. */
107
+ const STATUS_SEVERITY = {
108
+ unbound: 'warning',
109
+ dangling: 'error',
110
+ 'over-bound': 'error',
111
+ hidden: 'error',
112
+ 'type-mismatch': 'warning'
113
+ };
114
+ /**
115
+ * Advisory validation for `workflow.interface`. Never throws, never mutates.
116
+ * Returns an empty array for a workflow with no `interface` key.
117
+ *
118
+ * Reports, per entry:
119
+ * - every non-`ok` status from `resolveInterface`;
120
+ * - a duplicate `id` within the same direction (inputs and outputs are
121
+ * scoped separately, matching the entry doc's "unique within its direction");
122
+ * - for input entries, a bound port that already has an incoming edge — two
123
+ * sources writing the same value;
124
+ * - a binding whose resolved port direction contradicts the entry's own
125
+ * direction (an "input" entry bound to a node's output port, or vice versa).
126
+ */
127
+ export function validateWorkflowInterface(workflow) {
128
+ if (!workflow.interface)
129
+ return [];
130
+ const issues = [];
131
+ const resolved = resolveInterface(workflow);
132
+ for (const resolvedEntry of resolved) {
133
+ const { entry, direction, targets, status } = resolvedEntry;
134
+ if (status !== 'ok') {
135
+ issues.push({
136
+ entryId: entry.id,
137
+ direction,
138
+ severity: STATUS_SEVERITY[status],
139
+ code: `interface-${status}`,
140
+ message: STATUS_MESSAGE[status](entry.id)
141
+ });
142
+ }
143
+ for (const target of targets) {
144
+ if (target.direction !== direction) {
145
+ issues.push({
146
+ entryId: entry.id,
147
+ direction,
148
+ severity: 'error',
149
+ code: 'interface-direction-mismatch',
150
+ message: `Interface ${direction} "${entry.id}" is bound to a node ${target.direction} port; the binding's direction must match the entry's.`
151
+ });
152
+ }
153
+ if (direction === 'input') {
154
+ const handleId = buildHandleId(target.node.id, 'input', target.port.id);
155
+ const hasIncomingEdge = workflow.edges.some((edge) => edge.targetHandle === handleId);
156
+ if (hasIncomingEdge) {
157
+ issues.push({
158
+ entryId: entry.id,
159
+ direction,
160
+ severity: 'error',
161
+ code: 'interface-input-already-connected',
162
+ message: `Interface input "${entry.id}" is bound to a port that already has an incoming edge; the port would receive two sources for one value.`
163
+ });
164
+ }
165
+ }
166
+ }
167
+ }
168
+ for (const direction of ['input', 'output']) {
169
+ const entries = (direction === 'input' ? workflow.interface.inputs : workflow.interface.outputs) ?? [];
170
+ const seenCounts = new Map();
171
+ for (const entry of entries) {
172
+ seenCounts.set(entry.id, (seenCounts.get(entry.id) ?? 0) + 1);
173
+ }
174
+ for (const [id, count] of seenCounts) {
175
+ if (count > 1) {
176
+ issues.push({
177
+ entryId: id,
178
+ direction,
179
+ severity: 'error',
180
+ code: 'interface-duplicate-id',
181
+ message: `Interface ${direction} id "${id}" is declared ${count} times; ids must be unique within their direction.`
182
+ });
183
+ }
184
+ }
185
+ }
186
+ return issues;
187
+ }
188
+ /**
189
+ * Pre-validate launch inputs against a declared interface, mirroring what the
190
+ * server's manifest check refuses: an unknown key (named against the accepted
191
+ * set) and a missing required input. Value type/enum checking stays with the
192
+ * server — the client does not re-implement schema validation.
193
+ *
194
+ * A workflow with no declared interface returns no issues: there is nothing
195
+ * to pre-validate against and the server remains the authority.
196
+ */
197
+ export function validateLaunchInputs(workflowInterface, inputs) {
198
+ const entries = workflowInterface?.inputs;
199
+ if (!entries)
200
+ return [];
201
+ const issues = [];
202
+ const accepted = entries.map((entry) => entry.id);
203
+ for (const key of Object.keys(inputs)) {
204
+ if (!accepted.includes(key)) {
205
+ issues.push({
206
+ key,
207
+ code: 'unknown-key',
208
+ message: accepted.length > 0
209
+ ? `Unknown input "${key}". Accepted inputs: ${accepted.join(', ')}.`
210
+ : `Unknown input "${key}". This workflow declares no inputs.`
211
+ });
212
+ }
213
+ }
214
+ for (const entry of entries) {
215
+ const supplied = entry.id in inputs && inputs[entry.id] !== undefined;
216
+ if (entry.required && !supplied && entry.defaultValue === undefined) {
217
+ issues.push({
218
+ key: entry.id,
219
+ code: 'missing-required',
220
+ message: `Missing required input "${entry.id}".`
221
+ });
222
+ }
223
+ }
224
+ return issues;
225
+ }
226
+ // Re-export the precedence order for callers/tests that want to assert it
227
+ // without duplicating the literal array.
228
+ export { STATUS_PRECEDENCE };
229
+ /**
230
+ * Handle IDs bound to a workflow interface entry, mapped to the entry itself
231
+ * (so a caller can render the entry's public name — e.g. in a tooltip —
232
+ * without a second lookup).
233
+ *
234
+ * Built from `resolveInterface`, so it inherits the same resolution rules:
235
+ * only bindings that resolve to a *live* port contribute a handle id. A
236
+ * `dangling` binding has no live handle to mark, and an `unbound` entry has
237
+ * no bindings at all — neither appears here. A `hidden` binding does resolve
238
+ * (its handle id is included), but the node components filter not-exposed
239
+ * ports out of render entirely, so no handle ever exists for it to mark in
240
+ * practice. Every other status (`ok`, `type-mismatch`, `over-bound`)
241
+ * contributes its resolved target(s) — the ring is a "this port is part of
242
+ * the public contract" marker, not a "this entry is fully healthy" one; the
243
+ * canonical editor (Phase 3) is where health is explained in words.
244
+ *
245
+ * When a binding's target resolves to more than one caller (an `over-bound`
246
+ * output), each target's handle id maps to the same entry.
247
+ *
248
+ * Handle ids use the target *port's* own direction (`ResolvedBinding.direction`),
249
+ * matching the id every node component actually renders
250
+ * (`buildHandleId(nodeId, direction, portId)`) — not the entry's direction,
251
+ * which can differ from the bound port's for a misdirected binding.
252
+ */
253
+ export function interfaceBoundHandles(workflow) {
254
+ const bound = new Map();
255
+ for (const resolvedEntry of resolveInterface(workflow)) {
256
+ for (const target of resolvedEntry.targets) {
257
+ const handleId = buildHandleId(target.node.id, target.direction, target.port.id);
258
+ if (!bound.has(handleId))
259
+ bound.set(handleId, resolvedEntry.entry);
260
+ }
261
+ }
262
+ return bound;
263
+ }
264
+ /**
265
+ * Tooltip text for a handle bound to an interface entry — `undefined` when
266
+ * `entry` is `undefined` (the port isn't bound), so callers can pass
267
+ * `interfaceBoundHandles(workflow).get(handleId)` straight through without an
268
+ * intermediate check. The single home for this string so all five node
269
+ * components and `FormPorts` render identical wording.
270
+ */
271
+ export function interfaceBoundTooltip(entry) {
272
+ return entry ? `Published as: ${entry.name ?? entry.id}` : undefined;
273
+ }
274
+ /**
275
+ * Rewrite `workflow.interface` bindings that point at a node swapped out by
276
+ * `nodeSwap.ts` — the one place bindings actively move (see
277
+ * `.claude/plans/workflow-interface.md` Phase 2). Every other mutation
278
+ * (including node deletion) leaves bindings untouched by design.
279
+ *
280
+ * A binding `{ nodeId: oldNodeId, portId }` on an input entry is rewritten
281
+ * when `portMappings` has a `direction: 'input'` mapping for that `portId`;
282
+ * output entries match against `direction: 'output'` mappings the same way —
283
+ * an entry's own direction (which array it lives in) picks which side of the
284
+ * mapping applies. A port the mapping drops (no matching entry) is left
285
+ * untouched; it resolves as `dangling` once the old node is gone, the same
286
+ * as any other dangling binding — no silent pruning.
287
+ *
288
+ * Pure: returns a new `WorkflowInterface`, never mutates its argument.
289
+ * Returns the input unchanged when there is no interface to rewrite.
290
+ */
291
+ export function rewriteInterfaceBindings(workflowInterface, oldNodeId, newNodeId, portMappings) {
292
+ if (!workflowInterface)
293
+ return workflowInterface;
294
+ const rewriteEntries = (entries, direction) => {
295
+ if (!entries)
296
+ return entries;
297
+ return entries.map((entry) => ({
298
+ ...entry,
299
+ bindings: entry.bindings.map((binding) => {
300
+ if (binding.nodeId !== oldNodeId)
301
+ return binding;
302
+ const mapping = portMappings.find((candidate) => candidate.direction === direction && candidate.oldPortId === binding.portId);
303
+ return mapping ? { nodeId: newNodeId, portId: mapping.newPortId } : binding;
304
+ })
305
+ }));
306
+ };
307
+ return {
308
+ inputs: rewriteEntries(workflowInterface.inputs, 'input'),
309
+ outputs: rewriteEntries(workflowInterface.outputs, 'output')
310
+ };
311
+ }
312
+ /** Plain-prose explanation for a resolved entry's health, covering every status. */
313
+ export function describeInterfaceEntryStatus(resolved) {
314
+ const { entry, status } = resolved;
315
+ if (status === 'ok') {
316
+ return `Interface entry "${entry.id}" is bound to an exposed port with a matching type — ready for callers.`;
317
+ }
318
+ return STATUS_MESSAGE[status](entry.id);
319
+ }
320
+ /**
321
+ * Entry fields derivable from a bound port — the "pull details from port"
322
+ * convenience. Copies the port's display name, dataType, and (when the port
323
+ * declares them) description, required and defaultValue. Only fields the port
324
+ * actually provides appear in the patch, so applying it never blanks a value
325
+ * the author already wrote for a field the port is silent about.
326
+ *
327
+ * The public `id` is deliberately NOT derived — a contract keyed on internal
328
+ * port names is the failure mode DN1 exists to prevent.
329
+ */
330
+ export function pullEntryFieldsFromPort(port) {
331
+ const patch = { name: port.name, dataType: port.dataType };
332
+ if (port.description !== undefined)
333
+ patch.description = port.description;
334
+ if (port.required !== undefined)
335
+ patch.required = port.required;
336
+ if (port.defaultValue !== undefined)
337
+ patch.defaultValue = port.defaultValue;
338
+ return patch;
339
+ }
340
+ /**
341
+ * Whether a port is intra-graph control flow — the reserved `trigger`/`tool`
342
+ * dataTypes or the loopback input — and therefore never publishable in a
343
+ * workflow's interface.
344
+ */
345
+ function isControlFlowPort(port) {
346
+ return port.dataType === 'trigger' || port.dataType === 'tool' || port.id === LOOPBACK_PORT_NAME;
347
+ }
348
+ /**
349
+ * Every canvas-exposed port of a workflow, for one direction — the candidate
350
+ * set a binding picker offers (design decision 3: external ⊂ internal, so an
351
+ * entry may only bind to a port that is already exposed).
352
+ *
353
+ * Mirrors `FormPorts.svelte`'s port list: a node's static metadata ports plus
354
+ * its user-defined dynamic ports, filtered by `isPortExposed`.
355
+ *
356
+ * Control-flow ports are excluded: the reserved `trigger`/`tool` dataTypes and
357
+ * the `loop_back` port are intra-graph control flow, not an external surface
358
+ * (DN1's grounded fact). The model and validation stay permissive — this only
359
+ * constrains what the authoring picker offers.
360
+ */
361
+ export function listBindablePorts(workflow, direction) {
362
+ const result = [];
363
+ for (const node of workflow.nodes) {
364
+ const metadata = node.data?.metadata;
365
+ if (!metadata)
366
+ continue;
367
+ const staticPorts = direction === 'input' ? (metadata.inputs ?? []) : (metadata.outputs ?? []);
368
+ const dynamicRaw = direction === 'input' ? node.data?.config?.dynamicInputs : node.data?.config?.dynamicOutputs;
369
+ const dynamicPorts = (dynamicRaw ?? []).map((port) => dynamicPortToNodePort(port, direction));
370
+ const portsConfigDirection = direction === 'input' ? 'inputs' : 'outputs';
371
+ const portsConfig = node.data?.config?.[PORTS_CONFIG_KEY];
372
+ const entries = portsConfig?.[portsConfigDirection];
373
+ for (const port of [...staticPorts, ...dynamicPorts]) {
374
+ if (isControlFlowPort(port))
375
+ continue;
376
+ if (isPortExposed(port, entries)) {
377
+ result.push({ nodeId: node.id, nodeLabel: node.data?.label ?? node.id, port });
378
+ }
379
+ }
380
+ }
381
+ return result;
382
+ }
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "A drop-in visual workflow editor for any web application. You own the backend. You own the data. You own the orchestration.",
4
4
  "license": "MIT",
5
5
  "private": false,
6
- "version": "2.0.1",
6
+ "version": "2.1.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"