@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.
- package/CHANGELOG.md +26 -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/globalSave.js +9 -2
- 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 +208 -0
- package/dist/utils/workflowInterface.js +391 -0
- 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.
|
|
6
|
+
"version": "2.1.1",
|
|
7
7
|
"author": "Shibin Das (D34dMan)",
|
|
8
8
|
"bugs": {
|
|
9
9
|
"url": "https://github.com/flowdrop-io/flowdrop/issues"
|