@flowdrop/flowdrop 2.0.1 → 2.1.1

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