@flowdrop/flowdrop 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [2.7.0] - 2026-09-09
11
+
12
+ ### Added
13
+
14
+ - **A browser agent can now _finish_ a workflow, not just edit one.** Building a four-node fetch-and-convert flow through the 2.6.0 tools showed the gaps: an agent could not learn a node type's ports or config without adding a node first, could not tell whether the result was valid, and could not run it. The editor-tool set closes them, on one rule — **the tools read only what the editor has already fetched** (the node type catalog and the open workflow); no new endpoints, no per-tool round trips.
15
+ - **`describe_type`** (new command and tool, read-only) describes a node type before it is used: input and output ports with data type and required flag, every config key with type, enum, default and description, and — when the host publishes them — the **confirmation policy** (`ask` means a run pauses for a person at this node), what the user may do with it (`can`) and host-written guidance (`agent`). Three new optional fields on `NodeMetadata` carry those: `confirmation`, `can`, `agent`; the library passes them through verbatim.
16
+ - **`search_types { query }`** (new command and tool, read-only) finds node types by a case-insensitive substring of id, name, description or tags; a blank query is refused with `EMPTY_QUERY` (new `CommandErrorCode`) instead of returning the catalog. **`list_types` rows now carry `description` and `tags`.** The text DSL gained `describe <type>` and `search <text>` to match, and the command console formats both.
17
+ - **`get_config` returns the schema next to the value**, and its `key` is optional: without one it answers every current value under `values` and the whole config schema. `get <nodeId>` works in the DSL too. The result is one of two shapes — `GetConfigKeyResultData` (`key`, `value`, `schema?`) or `GetConfigAllResultData` (`values`, `schema[]`) — narrow on `'key' in data`.
18
+ - **Errors teach.** A failure names the valid alternatives instead of stopping at "not found": an unknown node lists the workflow's nodes (or says to `add_node` first on an empty canvas); an unknown type names near misses and points at `list_types`; an unknown port lists the node's ports on both sides; a missing edge lists the edges leaving that node; an unknown config key lists the keys. Lists are capped at 15. `set_config` on a key the schema does not declare is still stored (hosts keep config open) but now carries an **`unknown_key` warning** with the declared keys — fatal only under `strict`.
19
+ - **Tool descriptions carry the call order.** `add_node`, `set_config`, `swap_node` and `batch` — the tools that take a type or a config key — end with "call `describe_type` before adding or configuring a type you have not seen; group several changes in one `batch`; `save` when done", and examples use type ids that exist (`http_request`, not `llm_node`).
20
+ - **`run` and `run_status`** tools, behind two new host hooks on `attachWebMCP` and the `webmcp` mount option: **`onRun(inputs) → Promise<HostEnvelope<RunStarted>>`** and **`onRunStatus(runId) → Promise<HostEnvelope<RunStatus>>`**. `run` is gated like `save` and flagged consequential; `run_status` is a read. A paused run is relayed as **`code: 'PENDING'`** with the node id and message it waits on — a person must act in the editor; no tool answers an interrupt, on purpose. `run_status` is registered only when both hooks are given; neither tool exists without its hook.
21
+ - **One result envelope for host hooks.** `onSave`, `onRun` and `onRunStatus` may answer `{ ok, code?, message?, data?, can? }` (`HostEnvelope`), with the codes `FORBIDDEN`, `UNAVAILABLE`, `NEEDS_APPROVAL`, `INVALID`, `CONFLICT`, `PENDING`, `NOT_FOUND` — aligned with fddo's API-8 `error_code` vocabulary where the two meet. The tool relays `code`, `message`, `data` and `can` untouched. `onSave` may still resolve to nothing (saved) or throw (`SAVE_FAILED`); a thrown error that is a 409 or carries `errorData.error_code === 'CONFLICT'` is relayed as **`CONFLICT`** with a reload hint.
22
+ - **The server stays the authority; the client pre-empts.** A workflow payload may now carry **`can: { save, run, … }`** and a **`revision`** (two new optional fields on `Workflow`). `save` and `run` answer `FORBIDDEN` before opening a dialog when `can` says no; when the host says nothing, the server decides. The save path sends the loaded `revision` back so a server that checks it can refuse a stale write, and takes the new `revision`/`can` from the response (`instance.workflow.acknowledgeServer()` — bookkeeping only, no history entry, no dirty flag).
23
+ - **The confirm dialog summarises a batch** — "4 changes — adds 2 nodes, connects 1 edge, sets 1 config key." — above the line list, and offers **"Apply further edits from any agent on this page without asking, until this page is closed"** — worded as what it does: the gate cannot tell one agent from another, so once ticked every caller on the page is covered. Ticked (and approved), later _edits_ run without the dialog; `save` and `run` always ask and never offer the box. Off with **`rememberEdits: false`**. Nine new strings under `defaultMessages.webmcp` (`runLine`, `runHint`, `summary*`, `batchSummary`, `rememberEdits`); Tab now cycles Apply → Reject → checkbox.
24
+ - **A browser agent can now save.** Feedback from the first WebMCP release: the first batch of nodes an agent added vanished on reload because nothing had persisted them — `flowdrop_add_node` and friends change the in-memory workflow, but only the editor's own Save button wrote it to the server. There is now a **`flowdrop_save`** tool: registered whenever `attachWebMCP` is given an **`onSave: () => Promise<void>`**, and automatically on the `mountFlowDropApp` path, where it defaults to the mount's own Save unless the host supplies its own `onSave`. Like any change, it asks — a save cannot be undone from the editor — and its `annotations` carry the new **`consequentialHint: true`** (added to the WebMCP spec 2026-09-03: "executing the tool will result in consequential actions that are significant, real-world, or non-reversible"). Approval callbacks (`WebMCPApproval` functions) now receive a second argument, `(commands, { tool })` — additive, existing one-argument callbacks keep working; for `save` the `commands` array is empty and `request.tool === 'save'`.
25
+ - **A bridge to desktop MCP clients, for browsers without the origin trial** (`installBridgedModelContext`, `createBridgedModelContext` in `@flowdrop/flowdrop/webmcp`). Presents the same `modelContext` surface over a page-side relay widget of the [`@jason.today/webmcp`](https://github.com/jasonjmcghee/webmcp) shape (`registerTool(name, description, inputSchema, execute)`), so Claude Code, Claude Desktop or Cursor can call the editor tools through a localhost MCP server the user runs and authorises with a token. Install it before the editor mounts; it is a no-op when a real runtime exists. The widget cannot unregister a tool, so after the editor is destroyed its tools answer a structured `UNAVAILABLE` until the page unloads. The relay's server times a tool call out after 30 seconds — a confirm dialog left open longer returns a timeout to the agent while the dialog stays up. The gate, `can` and the server's permissions apply unchanged; hosts should make the bridge an explicit opt-in.
26
+ - **New exported types** from `@flowdrop/flowdrop/core` and `/commands`: `DescribeTypeCommand`, `SearchTypesCommand`, `TypeSummary`, `PortDescription`, `ConfigKeyDescription`, `DescribeTypeResultData`, `SearchTypesResultData`, `GetConfigKeyResultData`, `GetConfigAllResultData`; from `/webmcp`: `HostCode`, `HostEnvelope`, `RunStarted`, `RunPending`, `RunStatus`, `WebMCPApprovalRequest`, `WebMCPWidgetLike`, `BridgedModelContext`. `NodeMetadata` gained `confirmation`, `can`, `agent` (`NodeConfirmation`, `NodeAgentGuidance`); `Workflow` gained `can`, `revision`.
27
+
28
+ ### Fixed
29
+
30
+ - **`mountFlowDropApp(...).save()` and `globalSaveWorkflow()` resolve `true` when the workflow was written and `false` when nothing was saved** (no workflow, or `onBeforeSave` cancelled). Before, both resolved to nothing either way, and the mount path's default `save` tool reported "Workflow saved" on a cancelled save. It now answers `{ ok: false, code: 'UNAVAILABLE' }`. Widening `void` to `boolean` is additive for callers.
31
+ - **The WebMCP confirm dialog no longer renders in the browser's serif fallback on Drupal.** The dialog mounts on `document.body`, outside the editor, and used `font-family: inherit` — on admin themes that scope their font to a wrapper, that is Times. It now uses a new public token **`--fd-font-sans`** (a system-ui stack), with an explicit size and line-height, so it reads like the editor wherever it is mounted. Hosts can override the token at `:root`.
32
+ - **`set_config` no longer warns "Expected type 'string,boolean' but got 'string'"** when a node config property declares several JSON Schema types; the warning now reads `Expected type 'string' or 'boolean' but got 'number'` and fires only when the value matches none of them.
33
+
8
34
  ## [2.6.0] - 2026-09-03
9
35
 
10
36
  ### Added
@@ -10,7 +10,8 @@
10
10
  /**
11
11
  * Determine whether a DSL command type is mutating (modifies workflow state).
12
12
  *
13
- * Read-only commands (list_nodes, list_edges, list_types, info, get_config, help)
13
+ * Read-only commands (list_nodes, list_edges, list_types, describe_type,
14
+ * search_types, info, get_config, help)
14
15
  * return false. All other commands are considered mutating and return true.
15
16
  *
16
17
  * @param commandType - The command type string (e.g., "add", "list_nodes")
@@ -12,6 +12,8 @@ const READ_ONLY_COMMANDS = new Set([
12
12
  'list_nodes',
13
13
  'list_edges',
14
14
  'list_types',
15
+ 'describe_type',
16
+ 'search_types',
15
17
  'info',
16
18
  'get_config',
17
19
  'help'
@@ -19,7 +21,8 @@ const READ_ONLY_COMMANDS = new Set([
19
21
  /**
20
22
  * Determine whether a DSL command type is mutating (modifies workflow state).
21
23
  *
22
- * Read-only commands (list_nodes, list_edges, list_types, info, get_config, help)
24
+ * Read-only commands (list_nodes, list_edges, list_types, describe_type,
25
+ * search_types, info, get_config, help)
23
26
  * return false. All other commands are considered mutating and return true.
24
27
  *
25
28
  * @param commandType - The command type string (e.g., "add", "list_nodes")
@@ -60,6 +60,141 @@ export function resolveNode(shortId, nodes) {
60
60
  return nodes.find((n) => n.id.endsWith(`.${shortId}`));
61
61
  }
62
62
  // ============================================================================
63
+ // Teaching errors (D7 of the browser-agent plan)
64
+ // ============================================================================
65
+ //
66
+ // A failed command names the valid alternatives, because for a browser agent
67
+ // the error text is the only channel there is: an unknown node lists the
68
+ // nodes, an unknown type points at list_types and names near misses, an
69
+ // unknown port lists the node's ports, an unknown config key lists the keys.
70
+ // Lists are capped so a large workflow cannot turn one error into a dump.
71
+ const MAX_LISTED = 15;
72
+ function listCapped(items) {
73
+ if (items.length === 0)
74
+ return 'none';
75
+ const shown = items.slice(0, MAX_LISTED);
76
+ const rest = items.length - shown.length;
77
+ return shown.join(', ') + (rest > 0 ? `, … and ${rest} more` : '');
78
+ }
79
+ /** Near misses for an unknown id: same prefix, or one contains the other. */
80
+ function nearMisses(needle, haystack) {
81
+ const n = needle.toLowerCase();
82
+ const stem = n.split(/[._-]/)[0];
83
+ return haystack
84
+ .filter((h) => {
85
+ const l = h.toLowerCase();
86
+ return l.includes(n) || n.includes(l) || (stem.length >= 3 && l.startsWith(stem));
87
+ })
88
+ .slice(0, 5);
89
+ }
90
+ function nodeNotFoundMessage(nodeId, nodes) {
91
+ const ids = nodes.map((n) => toShortId(n.id));
92
+ return nodes.length === 0
93
+ ? `Node not found: ${nodeId}. The workflow has no nodes yet — add_node first.`
94
+ : `Node not found: ${nodeId}. Nodes in this workflow: ${listCapped(ids)}.`;
95
+ }
96
+ function typeNotFoundMessage(typeId, context) {
97
+ const ids = context.nodeTypes.map((m) => toShortTypeId(m.node_type_id));
98
+ const near = nearMisses(typeId, ids);
99
+ const hint = near.length > 0
100
+ ? ` Did you mean: ${near.join(', ')}?`
101
+ : ' Call list_types (or search_types) for the ids this editor accepts.';
102
+ return `Unknown node type: ${typeId}.${hint}`;
103
+ }
104
+ /** Every port id a node exposes in one direction, static and config-driven. */
105
+ function portIds(node, direction) {
106
+ const metadata = node.data?.metadata;
107
+ const config = node.data?.config;
108
+ if (direction === 'output') {
109
+ return [
110
+ ...(metadata?.outputs ?? []).map((p) => p.id),
111
+ ...(config?.branches ?? []).map((b) => b.name),
112
+ ...(config?.dynamicOutputs ?? []).map((p) => p.name)
113
+ ];
114
+ }
115
+ return [
116
+ ...(metadata?.inputs ?? []).map((p) => p.id),
117
+ ...(config?.dynamicInputs ?? []).map((p) => p.name)
118
+ ];
119
+ }
120
+ function portNotFoundMessage(node, portId, direction) {
121
+ const short = toShortId(node.id);
122
+ const wanted = portIds(node, direction);
123
+ const other = portIds(node, direction === 'input' ? 'output' : 'input');
124
+ const otherWord = direction === 'input' ? 'outputs' : 'inputs';
125
+ return (`Port '${portId}' not found on node ${short}. ` +
126
+ `Its ${direction}s: ${listCapped(wanted)}; its ${otherWord}: ${listCapped(other)}.`);
127
+ }
128
+ function configKeys(node) {
129
+ const schemaKeys = Object.keys(node.data?.metadata?.configSchema?.properties ?? {});
130
+ const valueKeys = Object.keys(node.data?.config ?? {});
131
+ return Array.from(new Set([...schemaKeys, ...valueKeys]));
132
+ }
133
+ // ============================================================================
134
+ // Describing types (shared by list_types, search_types, describe_type, get_config)
135
+ // ============================================================================
136
+ function typeSummary(m) {
137
+ const row = {
138
+ typeId: toShortTypeId(m.node_type_id),
139
+ name: m.name,
140
+ category: m.category
141
+ };
142
+ if (m.description)
143
+ row.description = m.description;
144
+ if (m.tags && m.tags.length > 0)
145
+ row.tags = m.tags;
146
+ return row;
147
+ }
148
+ function describePort(p) {
149
+ const out = { portId: p.id, name: p.name, dataType: p.dataType };
150
+ if (p.required)
151
+ out.required = true;
152
+ if (p.description)
153
+ out.description = p.description;
154
+ return out;
155
+ }
156
+ function describeConfigKey(key, property, required) {
157
+ const out = { key };
158
+ if (property) {
159
+ // Host schemas may declare `type` as a JSON Schema array; keep it as sent.
160
+ const type = property.type;
161
+ if (type !== undefined)
162
+ out.type = type;
163
+ if (property.title)
164
+ out.title = property.title;
165
+ if (property.description)
166
+ out.description = property.description;
167
+ if (property.enum && property.enum.length > 0)
168
+ out.enum = property.enum;
169
+ if (property.default !== undefined)
170
+ out.default = property.default;
171
+ }
172
+ if (required)
173
+ out.required = true;
174
+ return out;
175
+ }
176
+ function describeConfigSchema(schema) {
177
+ if (!schema?.properties)
178
+ return [];
179
+ const required = new Set(schema.required ?? []);
180
+ return Object.entries(schema.properties).map(([key, property]) => describeConfigKey(key, property, required.has(key)));
181
+ }
182
+ function describeType(m) {
183
+ const out = {
184
+ ...typeSummary(m),
185
+ inputs: (m.inputs ?? []).map(describePort),
186
+ outputs: (m.outputs ?? []).map(describePort),
187
+ config: describeConfigSchema(m.configSchema)
188
+ };
189
+ if (m.confirmation)
190
+ out.confirmation = m.confirmation;
191
+ if (m.can)
192
+ out.can = m.can;
193
+ if (m.agent)
194
+ out.agent = m.agent;
195
+ return out;
196
+ }
197
+ // ============================================================================
63
198
  // Command Handlers
64
199
  // ============================================================================
65
200
  function executeAddNode(command, context) {
@@ -71,7 +206,7 @@ function executeAddNode(command, context) {
71
206
  if (!metadata) {
72
207
  return {
73
208
  ok: false,
74
- error: `Unknown node type: ${command.nodeTypeId}`,
209
+ error: typeNotFoundMessage(command.nodeTypeId, context),
75
210
  code: 'NODE_TYPE_NOT_FOUND'
76
211
  };
77
212
  }
@@ -112,7 +247,7 @@ function executeDeleteNode(command, context) {
112
247
  if (!node) {
113
248
  return {
114
249
  ok: false,
115
- error: `Node not found: ${command.nodeId}`,
250
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
116
251
  code: 'NODE_NOT_FOUND'
117
252
  };
118
253
  }
@@ -131,7 +266,7 @@ function executeRenameNode(command, context) {
131
266
  if (!node) {
132
267
  return {
133
268
  ok: false,
134
- error: `Node not found: ${command.nodeId}`,
269
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
135
270
  code: 'NODE_NOT_FOUND'
136
271
  };
137
272
  }
@@ -203,14 +338,20 @@ function validateConfigValue(key, value, property) {
203
338
  // Type validation
204
339
  if (property.type) {
205
340
  const actualType = Array.isArray(value) ? 'array' : typeof value;
206
- const expectedType = property.type === 'integer' ? 'number' : property.type;
341
+ // Node config schemas from the backend sometimes declare `type` as a JSON
342
+ // Schema array (e.g. ['string', 'boolean']) rather than a single literal;
343
+ // `ConfigProperty.type` stays a single literal (it drives the schema
344
+ // form elsewhere), so normalise here instead of widening that interface.
345
+ const rawType = property.type;
346
+ const declaredTypes = Array.isArray(rawType) ? rawType : [rawType];
347
+ const expectedTypes = declaredTypes.map((t) => (t === 'integer' ? 'number' : t));
207
348
  // Only warn if there's a genuine mismatch (null/object handled specially)
208
349
  if (value !== null &&
209
- actualType !== expectedType &&
210
- !(expectedType === 'object' && actualType === 'object')) {
350
+ !expectedTypes.includes(actualType) &&
351
+ !(expectedTypes.includes('object') && actualType === 'object')) {
211
352
  warnings.push({
212
353
  type: 'type_mismatch',
213
- message: `Expected type '${property.type}' but got '${actualType}'`,
354
+ message: `Expected type ${expectedTypes.map((t) => `'${t}'`).join(' or ')} but got '${actualType}'`,
214
355
  expectedType: property.type,
215
356
  actualType
216
357
  });
@@ -227,7 +368,7 @@ function executeSetConfig(command, context) {
227
368
  if (!node) {
228
369
  return {
229
370
  ok: false,
230
- error: `Node not found: ${command.nodeId}`,
371
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
231
372
  code: 'NODE_NOT_FOUND'
232
373
  };
233
374
  }
@@ -236,7 +377,19 @@ function executeSetConfig(command, context) {
236
377
  const metadata = node.data.metadata;
237
378
  const configSchema = metadata?.configSchema;
238
379
  const property = configSchema?.properties?.[command.key];
239
- const warnings = validateConfigValue(command.key, parsedValue, property);
380
+ const warnings = validateConfigValue(command.key, parsedValue, property) ?? [];
381
+ // A key the schema does not declare is stored anyway — hosts keep config
382
+ // open — but the caller is told, with the keys that do exist, so an agent
383
+ // that misspelt one finds out now rather than at run time. Silent when the
384
+ // node has no schema at all: there is nothing to compare against.
385
+ const declaredKeys = Object.keys(configSchema?.properties ?? {});
386
+ if (!property && declaredKeys.length > 0) {
387
+ warnings.push({
388
+ type: 'unknown_key',
389
+ message: `Key '${command.key}' is not in the config schema of ${toShortId(node.id)}. Declared keys: ${listCapped(declaredKeys)}`,
390
+ knownKeys: declaredKeys
391
+ });
392
+ }
240
393
  // In strict mode, validation warnings become errors
241
394
  if (command.strict && warnings && warnings.length > 0) {
242
395
  const messages = warnings.map((w) => w.message).join('; ');
@@ -274,26 +427,47 @@ function executeGetConfig(command, context) {
274
427
  if (!node) {
275
428
  return {
276
429
  ok: false,
277
- error: `Node not found: ${command.nodeId}`,
430
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
278
431
  code: 'NODE_NOT_FOUND'
279
432
  };
280
433
  }
281
- const config = node.data.config;
282
- if (!config || !(command.key in config)) {
434
+ const config = node.data.config ?? {};
435
+ const schema = node.data.metadata?.configSchema;
436
+ const shortId = toShortId(node.id);
437
+ // No key: every value, and the schema that explains them.
438
+ if (command.key === undefined) {
439
+ const resultData = {
440
+ nodeId: shortId,
441
+ values: config,
442
+ schema: describeConfigSchema(schema)
443
+ };
444
+ const keys = Object.keys(config);
445
+ return {
446
+ ok: true,
447
+ message: keys.length === 0
448
+ ? `${shortId} has no config values set`
449
+ : `${shortId} config: ${keys.map((k) => `${k} = ${JSON.stringify(config[k])}`).join(', ')}`,
450
+ data: resultData
451
+ };
452
+ }
453
+ const property = schema?.properties?.[command.key];
454
+ if (!(command.key in config) && !property) {
283
455
  return {
284
456
  ok: false,
285
- error: `Config key not found: ${command.key} on ${toShortId(node.id)}`,
457
+ error: `Config key not found: ${command.key} on ${shortId}. Keys: ${listCapped(configKeys(node))}.`,
286
458
  code: 'CONFIG_KEY_NOT_FOUND'
287
459
  };
288
460
  }
461
+ const required = new Set(schema?.required ?? []).has(command.key);
289
462
  const resultData = {
290
- nodeId: toShortId(node.id),
463
+ nodeId: shortId,
291
464
  key: command.key,
292
- value: config[command.key]
465
+ value: config[command.key],
466
+ ...(property ? { schema: describeConfigKey(command.key, property, required) } : {})
293
467
  };
294
468
  return {
295
469
  ok: true,
296
- message: `${toShortId(node.id)}:${command.key} = ${JSON.stringify(config[command.key])}`,
470
+ message: `${shortId}:${command.key} = ${JSON.stringify(config[command.key])}`,
297
471
  data: resultData
298
472
  };
299
473
  }
@@ -306,7 +480,7 @@ function executeInfo(command, context) {
306
480
  if (!node) {
307
481
  return {
308
482
  ok: false,
309
- error: `Node not found: ${command.nodeId}`,
483
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
310
484
  code: 'NODE_NOT_FOUND'
311
485
  };
312
486
  }
@@ -433,7 +607,7 @@ function executeConnect(command, context) {
433
607
  if (!sourceNode) {
434
608
  return {
435
609
  ok: false,
436
- error: `Node not found: ${command.sourceNodeId}`,
610
+ error: nodeNotFoundMessage(command.sourceNodeId, workflow.nodes),
437
611
  code: 'NODE_NOT_FOUND'
438
612
  };
439
613
  }
@@ -441,7 +615,7 @@ function executeConnect(command, context) {
441
615
  if (!targetNode) {
442
616
  return {
443
617
  ok: false,
444
- error: `Node not found: ${command.targetNodeId}`,
618
+ error: nodeNotFoundMessage(command.targetNodeId, workflow.nodes),
445
619
  code: 'NODE_NOT_FOUND'
446
620
  };
447
621
  }
@@ -453,7 +627,7 @@ function executeConnect(command, context) {
453
627
  if (!sourcePortInfo) {
454
628
  return {
455
629
  ok: false,
456
- error: `Port '${command.sourcePort}' not found on node ${toShortId(sourceNode.id)}`,
630
+ error: portNotFoundMessage(sourceNode, command.sourcePort, 'output'),
457
631
  code: 'PORT_NOT_FOUND'
458
632
  };
459
633
  }
@@ -461,7 +635,7 @@ function executeConnect(command, context) {
461
635
  if (!targetPortInfo) {
462
636
  return {
463
637
  ok: false,
464
- error: `Port '${command.targetPort}' not found on node ${toShortId(targetNode.id)}`,
638
+ error: portNotFoundMessage(targetNode, command.targetPort, 'input'),
465
639
  code: 'PORT_NOT_FOUND'
466
640
  };
467
641
  }
@@ -536,7 +710,7 @@ function executeDisconnectPorts(command, context) {
536
710
  if (!sourceNode) {
537
711
  return {
538
712
  ok: false,
539
- error: `Node not found: ${command.sourceNodeId}`,
713
+ error: nodeNotFoundMessage(command.sourceNodeId, workflow.nodes),
540
714
  code: 'NODE_NOT_FOUND'
541
715
  };
542
716
  }
@@ -544,7 +718,7 @@ function executeDisconnectPorts(command, context) {
544
718
  if (!targetNode) {
545
719
  return {
546
720
  ok: false,
547
- error: `Node not found: ${command.targetNodeId}`,
721
+ error: nodeNotFoundMessage(command.targetNodeId, workflow.nodes),
548
722
  code: 'NODE_NOT_FOUND'
549
723
  };
550
724
  }
@@ -557,9 +731,13 @@ function executeDisconnectPorts(command, context) {
557
731
  return sourcePort === command.sourcePort && targetPort === command.targetPort;
558
732
  });
559
733
  if (!edge) {
734
+ const outgoing = workflow.edges
735
+ .filter((e) => e.source === sourceNode.id)
736
+ .map((e) => `${toShortId(e.source)}:${extractPortId(e.sourceHandle) ?? '?'} → ${toShortId(e.target)}:${extractPortId(e.targetHandle) ?? '?'}`);
560
737
  return {
561
738
  ok: false,
562
- error: `No edge found from ${toShortId(sourceNode.id)}:${command.sourcePort} to ${toShortId(targetNode.id)}:${command.targetPort}`,
739
+ error: `No edge found from ${toShortId(sourceNode.id)}:${command.sourcePort} to ${toShortId(targetNode.id)}:${command.targetPort}. ` +
740
+ `Edges leaving ${toShortId(sourceNode.id)}: ${listCapped(outgoing)}.`,
563
741
  code: 'EDGE_NOT_FOUND'
564
742
  };
565
743
  }
@@ -578,7 +756,7 @@ function executeDisconnectNode(command, context) {
578
756
  if (!node) {
579
757
  return {
580
758
  ok: false,
581
- error: `Node not found: ${command.nodeId}`,
759
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
582
760
  code: 'NODE_NOT_FOUND'
583
761
  };
584
762
  }
@@ -634,11 +812,7 @@ function executeListEdges(context) {
634
812
  };
635
813
  }
636
814
  function executeListTypes(context) {
637
- const types = context.nodeTypes.map((m) => ({
638
- typeId: toShortTypeId(m.node_type_id),
639
- name: m.name,
640
- category: m.category
641
- }));
815
+ const types = context.nodeTypes.map(typeSummary);
642
816
  const resultData = { types };
643
817
  return {
644
818
  ok: true,
@@ -646,6 +820,51 @@ function executeListTypes(context) {
646
820
  data: resultData
647
821
  };
648
822
  }
823
+ function executeSearchTypes(command, context) {
824
+ const query = command.query.trim().toLowerCase();
825
+ if (!query) {
826
+ return {
827
+ ok: false,
828
+ error: 'search_types needs text to look for. For the whole catalog call list_types.',
829
+ code: 'EMPTY_QUERY'
830
+ };
831
+ }
832
+ const matches = context.nodeTypes.filter((m) => {
833
+ const fields = [
834
+ toShortTypeId(m.node_type_id),
835
+ m.node_type_id,
836
+ m.name,
837
+ m.description ?? '',
838
+ ...(m.tags ?? [])
839
+ ];
840
+ return fields.some((f) => f.toLowerCase().includes(query));
841
+ });
842
+ const types = matches.map(typeSummary);
843
+ const resultData = { query: command.query, types };
844
+ return {
845
+ ok: true,
846
+ message: types.length === 0
847
+ ? `No node type matches "${command.query}" — try list_types for the full catalog`
848
+ : `${types.length} type(s) match "${command.query}": ${listCapped(types.map((t) => t.typeId))}`,
849
+ data: resultData
850
+ };
851
+ }
852
+ function executeDescribeType(command, context) {
853
+ const metadata = context.typeMap.get(command.nodeTypeId);
854
+ if (!metadata) {
855
+ return {
856
+ ok: false,
857
+ error: typeNotFoundMessage(command.nodeTypeId, context),
858
+ code: 'NODE_TYPE_NOT_FOUND'
859
+ };
860
+ }
861
+ const resultData = describeType(metadata);
862
+ return {
863
+ ok: true,
864
+ message: `${resultData.typeId}: ${resultData.inputs.length} input(s), ${resultData.outputs.length} output(s), ${resultData.config.length} config key(s)`,
865
+ data: resultData
866
+ };
867
+ }
649
868
  /** All command help entries */
650
869
  export const COMMAND_HELP = [
651
870
  {
@@ -670,8 +889,8 @@ export const COMMAND_HELP = [
670
889
  },
671
890
  {
672
891
  name: 'get',
673
- syntax: 'get <nodeId>:<key>',
674
- description: 'Get a config value from a node'
892
+ syntax: 'get <nodeId>[:<key>]',
893
+ description: 'Get a config value from a node, or every value plus the schema'
675
894
  },
676
895
  {
677
896
  name: 'connect',
@@ -693,6 +912,16 @@ export const COMMAND_HELP = [
693
912
  syntax: 'list nodes|edges|types',
694
913
  description: 'List workflow nodes, edges, or available types'
695
914
  },
915
+ {
916
+ name: 'describe',
917
+ syntax: 'describe <type>',
918
+ description: 'Show the ports, config schema and defaults of a node type'
919
+ },
920
+ {
921
+ name: 'search',
922
+ syntax: 'search <text>',
923
+ description: 'Find node types by id, name, description or tag'
924
+ },
696
925
  {
697
926
  name: 'info',
698
927
  syntax: 'info <nodeId>',
@@ -835,7 +1064,7 @@ function executeConfigOpen(command, context) {
835
1064
  if (!node) {
836
1065
  return {
837
1066
  ok: false,
838
- error: `Node not found: ${command.nodeId}`,
1067
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
839
1068
  code: 'NODE_NOT_FOUND'
840
1069
  };
841
1070
  }
@@ -861,7 +1090,7 @@ function executeSelectNode(command, context) {
861
1090
  if (!node) {
862
1091
  return {
863
1092
  ok: false,
864
- error: `Node not found: ${command.nodeId}`,
1093
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
865
1094
  code: 'NODE_NOT_FOUND'
866
1095
  };
867
1096
  }
@@ -887,7 +1116,7 @@ function executeSwapNode(command, context) {
887
1116
  if (!node) {
888
1117
  return {
889
1118
  ok: false,
890
- error: `Node not found: ${command.nodeId}`,
1119
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
891
1120
  code: 'NODE_NOT_FOUND'
892
1121
  };
893
1122
  }
@@ -895,7 +1124,7 @@ function executeSwapNode(command, context) {
895
1124
  if (!newMetadata) {
896
1125
  return {
897
1126
  ok: false,
898
- error: `Unknown node type: ${command.newTypeId}`,
1127
+ error: typeNotFoundMessage(command.newTypeId, context),
899
1128
  code: 'NODE_TYPE_NOT_FOUND'
900
1129
  };
901
1130
  }
@@ -956,7 +1185,7 @@ function executeMoveNode(command, context) {
956
1185
  if (!node) {
957
1186
  return {
958
1187
  ok: false,
959
- error: `Node not found: ${command.nodeId}`,
1188
+ error: nodeNotFoundMessage(command.nodeId, workflow.nodes),
960
1189
  code: 'NODE_NOT_FOUND'
961
1190
  };
962
1191
  }
@@ -1131,6 +1360,10 @@ export function executeCommand(command, context) {
1131
1360
  return executeListEdges(context);
1132
1361
  case 'list_types':
1133
1362
  return executeListTypes(context);
1363
+ case 'describe_type':
1364
+ return executeDescribeType(command, context);
1365
+ case 'search_types':
1366
+ return executeSearchTypes(command, context);
1134
1367
  case 'help':
1135
1368
  return executeHelp(command);
1136
1369
  case 'undo':
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * @module commands
8
8
  */
9
- export type { AddNodeCommand, DeleteNodeCommand, RenameNodeCommand, SetConfigCommand, GetConfigCommand, ConnectCommand, DisconnectPortsCommand, DisconnectNodeCommand, ListNodesCommand, ListEdgesCommand, ListTypesCommand, InfoCommand, UndoCommand, RedoCommand, ConfigOpenCommand, SelectNodeCommand, HelpCommand, ClearCommand, SwapNodeCommand, MoveNodeCommand, AutoLayoutCommand, BeautifyLayoutCommand, CanvasFitViewCommand, CanvasZoomInCommand, CanvasZoomOutCommand, CanvasZoomToCommand, CanvasPanToCommand, CanvasResetViewCommand, Command, ParseResult, CommandErrorCode, AddNodeResultData, ListNodesResultData, ListEdgesResultData, ListTypesResultData, InfoResultData, GetConfigResultData, SetConfigResultData, HelpResultData, SwapNodeResultData, CommandResultData, CommandResultOk, CommandResultError, CommandResult, BatchResult, UIAction, CommandDispatch, CommandContext } from './types.js';
9
+ export type { AddNodeCommand, DeleteNodeCommand, RenameNodeCommand, SetConfigCommand, GetConfigCommand, ConnectCommand, DisconnectPortsCommand, DisconnectNodeCommand, ListNodesCommand, ListEdgesCommand, ListTypesCommand, DescribeTypeCommand, SearchTypesCommand, InfoCommand, UndoCommand, RedoCommand, ConfigOpenCommand, SelectNodeCommand, HelpCommand, ClearCommand, SwapNodeCommand, MoveNodeCommand, AutoLayoutCommand, BeautifyLayoutCommand, CanvasFitViewCommand, CanvasZoomInCommand, CanvasZoomOutCommand, CanvasZoomToCommand, CanvasPanToCommand, CanvasResetViewCommand, Command, ParseResult, CommandErrorCode, AddNodeResultData, ListNodesResultData, ListEdgesResultData, ListTypesResultData, SearchTypesResultData, DescribeTypeResultData, TypeSummary, ConfigKeyDescription, PortDescription, InfoResultData, GetConfigResultData, GetConfigKeyResultData, GetConfigAllResultData, SetConfigResultData, HelpResultData, SwapNodeResultData, CommandResultData, CommandResultOk, CommandResultError, CommandResult, BatchResult, UIAction, CommandDispatch, CommandContext } from './types.js';
10
10
  export { buildTypeMap } from './types.js';
11
11
  export { parseCommand } from './parser.js';
12
12
  export { executeCommand, toShortId, toShortTypeId, resolveNode, COMMAND_HELP } from './executor.js';
@@ -105,6 +105,14 @@ const rules = [
105
105
  key: m[2]
106
106
  })
107
107
  },
108
+ // get <nodeId> — every config value plus the schema
109
+ {
110
+ pattern: /^get\s+([^\s:]+)$/i,
111
+ parse: (m) => ({
112
+ type: 'get_config',
113
+ nodeId: m[1]
114
+ })
115
+ },
108
116
  // info <nodeId>
109
117
  {
110
118
  pattern: /^info\s+(\S+)$/i,
@@ -174,6 +182,16 @@ const rules = [
174
182
  pattern: /^list\s+types$/i,
175
183
  parse: () => ({ type: 'list_types' })
176
184
  },
185
+ // describe <type>
186
+ {
187
+ pattern: /^describe\s+(\S+)$/i,
188
+ parse: (m) => ({ type: 'describe_type', nodeTypeId: m[1] })
189
+ },
190
+ // search <text...>
191
+ {
192
+ pattern: /^search\s+(.+)$/i,
193
+ parse: (m) => ({ type: 'search_types', query: m[1].trim() })
194
+ },
177
195
  // undo
178
196
  {
179
197
  pattern: /^undo$/i,
@@ -318,6 +336,8 @@ export function parseCommand(input) {
318
336
  'connect',
319
337
  'disconnect',
320
338
  'list',
339
+ 'describe',
340
+ 'search',
321
341
  'undo',
322
342
  'redo',
323
343
  'help',