@tuongaz/seeflow 0.1.55 → 0.1.57

package/src/api.ts

@@ -15,10 +15,9 @@ import type { EventBus } from './events.ts';
 import { type LayoutOptions, computeLayout } from './layout.ts';
 import {
   ConnectorPatchBodySchema,
-  ConnectorsBulkBodySchema,
   CreateProjectBodySchema,
+  FlowBulkBodySchema,
   NodePatchBodySchema,
-  NodesBulkBodySchema,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
@@ -1053,11 +1052,14 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
-  // Bulk-create up to 100 nodes in one transactional write. Either the whole
-  // batch lands and a single flow:reload broadcast fires, or nothing lands.
-  // Intended for skill/LLM seeding where N singular calls would burn tokens
-  // and round-trip latency. Per-item shape mirrors the singular endpoint.
-  api.post('/flows/:id/nodes/bulk', async (c) => {
+  // Bulk-create up to 100 nodes + 100 connectors in one transactional write.
+  // Either the whole batch lands (single flow:reload broadcast) or nothing
+  // does — a post-mutation ResolvedFlowSchema reject (e.g. dangling connector
+  // source/target) rolls back both arrays together. Connectors may reference
+  // nodes added in the same call; the parse sees the merged graph as a whole.
+  // Intended for skill/LLM seeding where multiple singular calls would burn
+  // tokens and round-trip latency.
+  api.post('/flows/:id/bulk', async (c) => {
     const id = c.req.param('id');
 
     let body: unknown;
@@ -1066,15 +1068,19 @@ export function createApi(options: ApiOptions): Hono {
     } catch {
       return c.json({ error: 'Body must be valid JSON' }, 400);
     }
-    const parsed = NodesBulkBodySchema.safeParse(body);
+    const parsed = FlowBulkBodySchema.safeParse(body);
     if (!parsed.success) {
-      return c.json({ error: 'Invalid bulk nodes body', issues: parsed.error.issues }, 400);
+      return c.json({ error: 'Invalid bulk body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await ops.addNodesBulk(id, parsed.data);
+    const result = await ops.addBulk(id, parsed.data);
     switch (result.kind) {
       case 'ok':
-        return c.json({ ok: true, nodes: result.data.nodes });
+        return c.json({
+          ok: true,
+          nodes: result.data.nodes,
+          connectors: result.data.connectors,
+        });
       case 'flowNotFound':
         return c.json({ error: 'unknown demo' }, 404);
       case 'fileNotFound':
@@ -1084,9 +1090,14 @@ export function createApi(options: ApiOptions): Hono {
       case 'badSchema':
         return c.json({ error: 'Flow failed schema validation', issues: result.issues }, 400);
       case 'duplicateIdInBatch':
-        return c.json({ error: `Duplicate id in batch: ${result.id}` }, 400);
+        return c.json({ error: `Duplicate ${result.collection} id in batch: ${result.id}` }, 400);
       case 'idAlreadyExists':
-        return c.json({ error: `Node id already exists: ${result.id}` }, 400);
+        return c.json(
+          {
+            error: `${result.collection === 'nodes' ? 'Node' : 'Connector'} id already exists: ${result.id}`,
+          },
+          400,
+        );
       case 'writeFailed':
         return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
     }
@@ -1195,44 +1206,6 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
-  // Bulk-create up to 100 connectors in one transactional write. Mirrors the
-  // /nodes/bulk shape. Dangling source/target on any item rolls back the whole
-  // batch via the post-mutation ResolvedFlowSchema parse.
-  api.post('/flows/:id/connectors/bulk', async (c) => {
-    const id = c.req.param('id');
-
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: 'Body must be valid JSON' }, 400);
-    }
-    const parsed = ConnectorsBulkBodySchema.safeParse(body);
-    if (!parsed.success) {
-      return c.json({ error: 'Invalid bulk connectors body', issues: parsed.error.issues }, 400);
-    }
-
-    const result = await ops.addConnectorsBulk(id, parsed.data);
-    switch (result.kind) {
-      case 'ok':
-        return c.json({ ok: true, connectors: result.data.connectors });
-      case 'flowNotFound':
-        return c.json({ error: 'unknown demo' }, 404);
-      case 'fileNotFound':
-        return c.json({ error: `Flow file not found: ${result.path}` }, 404);
-      case 'badJson':
-        return c.json({ error: `Flow file is not valid JSON: ${result.message}` }, 400);
-      case 'badSchema':
-        return c.json({ error: 'Flow failed schema validation', issues: result.issues }, 400);
-      case 'duplicateIdInBatch':
-        return c.json({ error: `Duplicate id in batch: ${result.id}` }, 400);
-      case 'idAlreadyExists':
-        return c.json({ error: `Connector id already exists: ${result.id}` }, 400);
-      case 'writeFailed':
-        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
-    }
-  });
-
   // DELETE a connector. Just removes the entry from demo.connectors — node
   // deletion is what cascades, not connector deletion.
   api.delete('/flows/:id/connectors/:connId', async (c) => {

package/src/cli-helpers.ts

@@ -101,10 +101,26 @@ function describeOutcome(outcome: { kind: string } & Record<string, unknown>): s
       return `Flow file is not valid JSON: ${String(outcome.detail ?? outcome.message ?? '')}`;
     case 'badSchema':
       return `Flow failed schema validation: ${JSON.stringify(outcome.issues ?? [])}`;
-    case 'duplicateIdInBatch':
-      return `Duplicate id in batch: ${String(outcome.id ?? '')}`;
-    case 'idAlreadyExists':
-      return `Id already exists: ${String(outcome.id ?? '')}`;
+    case 'duplicateIdInBatch': {
+      // `collection` is present on the FlowBulk outcome ('nodes' | 'connectors')
+      // and absent on legacy singular outcomes — keep both shapes working.
+      const collection = outcome.collection;
+      const prefix =
+        collection === 'nodes' || collection === 'connectors'
+          ? `Duplicate ${collection} id in batch`
+          : 'Duplicate id in batch';
+      return `${prefix}: ${String(outcome.id ?? '')}`;
+    }
+    case 'idAlreadyExists': {
+      const collection = outcome.collection;
+      const prefix =
+        collection === 'nodes'
+          ? 'Node id already exists'
+          : collection === 'connectors'
+            ? 'Connector id already exists'
+            : 'Id already exists';
+      return `${prefix}: ${String(outcome.id ?? '')}`;
+    }
     case 'writeFailed':
       return `Failed to write demo file: ${String(outcome.message ?? '')}`;
     case 'sdkWriteFailed':

package/src/cli-manifest.ts

@@ -6,10 +6,9 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { EXIT_CODE_BY_KIND, exitCodeForKind } from './cli-helpers.ts';
 import {
   ConnectorPatchBodySchema,
-  ConnectorsBulkBodySchema,
   CreateProjectBodySchema,
+  FlowBulkBodySchema,
   NodePatchBodySchema,
-  NodesBulkBodySchema,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
@@ -252,6 +251,40 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     requiresStudio: false,
     examples: ['seeflow flows:layout abc12345'],
   },
+  {
+    name: 'flow:add-bulk',
+    synopsis: 'seeflow flow:add-bulk <flowId> [--json | --file | --stdin]',
+    description:
+      'Add up to 100 nodes + 100 connectors atomically. Body shape: ' +
+      '`{ nodes?: Node[], connectors?: Connector[] }` (at least one non-empty). ' +
+      'Connectors may reference nodes added in the same batch; the whole flow ' +
+      'is re-validated post-merge so a dangling source/target — or any per-item ' +
+      'schema failure — rolls back both arrays together and emits no broadcast.',
+    category: 'flows',
+    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
+    flags: BODY_FLAGS,
+    body: { schemaRef: 'FlowBulkBody' },
+    outputs: {
+      okExample: {
+        nodes: [{ id: 'node-a', node: { id: 'node-a' } }],
+        connectors: [{ id: 'conn-a' }],
+      },
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'badJson',
+        'badSchema',
+        'duplicateIdInBatch',
+        'idAlreadyExists',
+        'writeFailed',
+      ],
+    },
+    requiresStudio: false,
+    examples: [
+      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"shapeNode","data":{"shape":"rectangle"}}],"connectors":[]}\'',
+      'seeflow flow:add-bulk abc12345 --file batch.json',
+    ],
+  },
   {
     name: 'flows:play',
     synopsis: 'seeflow flows:play <flowId> <nodeId>',
@@ -317,25 +350,6 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow nodes:add abc12345 --json \'{"type":"shapeNode","data":{"shape":"rectangle"}}\'',
     ],
   },
-  {
-    name: 'nodes:add-bulk',
-    synopsis: 'seeflow nodes:add-bulk <flowId> [--json | --file | --stdin]',
-    description:
-      'Add up to 100 nodes in one transactional write. Body shape: ' +
-      '`{ nodes: Node[] }`. Any duplicate id rolls back the whole batch.',
-    category: 'nodes',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
-    body: { schemaRef: 'NodesBulkBody' },
-    outputs: {
-      okExample: { ids: ['a', 'b'] },
-      errorKinds: ['flowNotFound', 'fileNotFound', 'badSchema', 'duplicateIdInBatch'],
-    },
-    requiresStudio: false,
-    examples: [
-      'seeflow nodes:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"shapeNode","data":{"shape":"rectangle"}}]}\'',
-    ],
-  },
   {
     name: 'nodes:get',
     synopsis: 'seeflow nodes:get <flowId> <nodeId>',
@@ -451,18 +465,6 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow connectors:add abc12345 --json \'{"source":{"nodeId":"a"},"target":{"nodeId":"b"}}\'',
     ],
   },
-  {
-    name: 'connectors:add-bulk',
-    synopsis: 'seeflow connectors:add-bulk <flowId> [--json | --file | --stdin]',
-    description: 'Add up to 100 connectors transactionally. Body: `{ connectors: Connector[] }`.',
-    category: 'connectors',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
-    body: { schemaRef: 'ConnectorsBulkBody' },
-    outputs: { errorKinds: ['flowNotFound', 'badSchema', 'duplicateIdInBatch'] },
-    requiresStudio: false,
-    examples: ['seeflow connectors:add-bulk abc12345 --file connectors.json'],
-  },
   {
     name: 'connectors:patch',
     synopsis: 'seeflow connectors:patch <flowId> <connectorId> [--json | --file | --stdin]',
@@ -542,10 +544,8 @@ function resolveSchemaRef(ref: string): unknown {
       return zodToJsonSchema(NodePatchBodySchema, { $refStrategy: 'none' });
     case 'ConnectorPatchBody':
       return zodToJsonSchema(ConnectorPatchBodySchema, { $refStrategy: 'none' });
-    case 'NodesBulkBody':
-      return zodToJsonSchema(NodesBulkBodySchema, { $refStrategy: 'none' });
-    case 'ConnectorsBulkBody':
-      return zodToJsonSchema(ConnectorsBulkBodySchema, { $refStrategy: 'none' });
+    case 'FlowBulkBody':
+      return zodToJsonSchema(FlowBulkBodySchema, { $refStrategy: 'none' });
     case 'CreateProjectBody':
       return zodToJsonSchema(CreateProjectBodySchema, { $refStrategy: 'none' });
     case 'RegisterBody':

package/src/cli.ts

@@ -8,9 +8,8 @@ import { createEventBus } from './events.ts';
 import type { LayoutOptions } from './layout.ts';
 import {
   ConnectorPatchBodySchema,
-  ConnectorsBulkBodySchema,
+  FlowBulkBodySchema,
   NodePatchBodySchema,
-  NodesBulkBodySchema,
   ReorderBodySchema,
 } from './operations.ts';
 import { seeflowHome } from './paths.ts';
@@ -134,12 +133,12 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runFlowsDelete();
 } else if (sub === 'flows:layout') {
   await runFlowsLayout();
+} else if (sub === 'flow:add-bulk') {
+  await runFlowAddBulk();
 } else if (sub === 'flows:play') {
   await runFlowsPlay();
 } else if (sub === 'nodes:add') {
   await runNodesAdd();
-} else if (sub === 'nodes:add-bulk') {
-  await runNodesAddBulk();
 } else if (sub === 'nodes:get') {
   await runNodesGet();
 } else if (sub === 'nodes:patch') {
@@ -152,8 +151,6 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runNodesDelete();
 } else if (sub === 'connectors:add') {
   await runConnectorsAdd();
-} else if (sub === 'connectors:add-bulk') {
-  await runConnectorsAddBulk();
 } else if (sub === 'connectors:patch') {
   await runConnectorsPatch();
 } else if (sub === 'connectors:delete') {
@@ -188,15 +185,14 @@ Commands (work without a running studio):
   flows:graph <id>     List nodes + connectors without inlined file content
   flows:delete <id>    Unregister a flow
   flows:layout <id>    Apply ELK layout, writing style.json (--json/--file/--stdin optional)
+  flow:add-bulk <id>   Add many nodes + connectors atomically (--json/--file/--stdin; body { nodes?, connectors? })
   nodes:add <id>       Add a node (--json/--file/--stdin)
-  nodes:add-bulk <id>  Add many nodes (--json/--file/--stdin)
   nodes:get <id> <n>   Get a node with detail / html content inlined
   nodes:patch <id> <n> Patch a node (--json/--file/--stdin)
   nodes:move <id> <n>  Move a node (--x N --y N)
   nodes:reorder <id> <n> Reorder a node (--op forward|backward|toFront|toBack|toIndex [--index N])
   nodes:delete <id> <n> Delete a node
   connectors:add <id>  Add a connector (--json/--file/--stdin)
-  connectors:add-bulk <id>  Add many connectors (--json/--file/--stdin)
   connectors:patch <id> <connId>  Patch a connector (--json/--file/--stdin)
   connectors:delete <id> <connId> Delete a connector
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
@@ -661,15 +657,15 @@ async function runNodesAdd() {
   printOutcome(result);
 }
 
-async function runNodesAddBulk() {
+async function runFlowAddBulk() {
   const flowId = requireArg(1, '<flowId>');
   const body = await bodyFromFlags();
-  const parsed = NodesBulkBodySchema.safeParse(body);
+  const parsed = FlowBulkBodySchema.safeParse(body);
   if (!parsed.success) {
-    printError(`Invalid nodes:add-bulk body: ${JSON.stringify(parsed.error.issues)}`);
+    printError(`Invalid flow:add-bulk body: ${JSON.stringify(parsed.error.issues)}`);
   }
   const ops = createCliOperations();
-  const result = await ops.addNodesBulk(flowId, parsed.data);
+  const result = await ops.addBulk(flowId, parsed.data);
   printOutcome(result);
 }
 
@@ -755,18 +751,6 @@ async function runConnectorsAdd() {
   printOutcome(result);
 }
 
-async function runConnectorsAddBulk() {
-  const flowId = requireArg(1, '<flowId>');
-  const body = await bodyFromFlags();
-  const parsed = ConnectorsBulkBodySchema.safeParse(body);
-  if (!parsed.success) {
-    printError(`Invalid connectors:add-bulk body: ${JSON.stringify(parsed.error.issues)}`);
-  }
-  const ops = createCliOperations();
-  const result = await ops.addConnectorsBulk(flowId, parsed.data);
-  printOutcome(result);
-}
-
 async function runConnectorsPatch() {
   const flowId = requireArg(1, '<flowId>');
   const connId = requireArg(2, '<connectorId>');

package/src/mcp.ts

@@ -8,15 +8,16 @@ import { type ZodTypeAny, z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
   ConnectorPatchBodySchema,
-  ConnectorsBulkBodySchema,
   CreateProjectBodySchema,
+  FLOW_BULK_NON_EMPTY_MESSAGE,
+  FlowBulkBodyShape,
   NodePatchBodySchema,
-  NodesBulkBodySchema,
   type Operations,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
   createOperations,
+  flowBulkNonEmpty,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
 import type { FlowWatcher } from './watcher.ts';
@@ -103,13 +104,16 @@ const AddNodeInputSchema = z.object({
   node: z.record(z.unknown()),
 });
 
-// add_nodes input: { flowId, nodes: [...] }. Same loose per-item shape as
-// add_node — ResolvedFlowSchema runs once over the whole batch server-side
-// after the merge. Min/max bounds come from NodesBulkBodySchema so the
-// 100-item cap shows up in the JSON Schema the agent introspects.
-const AddNodesInputSchema = NodesBulkBodySchema.extend({
+// add_bulk input: { flowId, nodes?: [...], connectors?: [...] }. Same loose
+// per-item shape as add_node / add_connector — ResolvedFlowSchema runs once
+// over the whole merged graph server-side after the batch lands. The
+// 100-per-kind cap and "at least one non-empty" invariant come from
+// FlowBulkBodyShape + flowBulkNonEmpty (the unrefined object + reusable
+// predicate exported by operations.ts) so the JSON Schema the agent
+// introspects stays a clean object — not an intersection.
+const AddBulkInputSchema = FlowBulkBodyShape.extend({
   flowId: z.string().min(1),
-});
+}).refine(flowBulkNonEmpty, { message: FLOW_BULK_NON_EMPTY_MESSAGE });
 
 const DeleteNodeInputSchema = FlowNodeIdBaseSchema;
 
@@ -153,11 +157,6 @@ const AddConnectorInputSchema = z.object({
   connector: z.record(z.unknown()),
 });
 
-// add_connectors input: { flowId, connectors: [...] }. Mirrors add_nodes.
-const AddConnectorsInputSchema = ConnectorsBulkBodySchema.extend({
-  flowId: z.string().min(1),
-});
-
 // patch_connector input: { flowId, connectorId } merged with the strict
 // ConnectorPatchBodySchema. .extend() preserves strict mode so unknown
 // top-level keys trip the Zod parse before any IO — matching the REST
@@ -407,20 +406,24 @@ const buildTools = (ops: Operations): McpTool[] => [
     },
   },
   {
-    name: 'seeflow_add_nodes',
+    name: 'seeflow_add_bulk',
     description:
-      'Append 1–100 nodes to a flow in a single transactional write. Either every node lands or nothing does — if any item fails schema validation the whole batch is rejected. Use this instead of multiple seeflow_add_node calls when seeding a flow; it avoids per-item round-trips. Same per-item shape and externalization rules as seeflow_add_node.',
-    inputSchema: inputSchemaFromZod(AddNodesInputSchema),
+      'Append 1–100 nodes and 1–100 connectors to a flow in a SINGLE transactional write. Either every item lands or nothing does — a dangling connector source/target, a duplicate id, or any per-item schema failure rolls back BOTH arrays together (no flow:reload broadcast emitted). Connectors may reference nodes added in the same call. Body: { flowId, nodes?, connectors? } with at least one non-empty. Use this — not multiple seeflow_add_node / seeflow_add_connector round-trips — when seeding a flow. Same per-item shape and externalization rules as the singular tools.',
+    inputSchema: inputSchemaFromZod(AddBulkInputSchema),
     handler: async (args) => {
-      const parsed = AddNodesInputSchema.safeParse(args);
+      const parsed = AddBulkInputSchema.safeParse(args);
       if (!parsed.success) {
-        return errorResult(`Invalid add_nodes arguments: ${JSON.stringify(parsed.error.issues)}`);
+        return errorResult(`Invalid add_bulk arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, nodes } = parsed.data;
-      const result = await ops.addNodesBulk(flowId, { nodes });
+      const { flowId, nodes, connectors } = parsed.data;
+      const result = await ops.addBulk(flowId, { nodes, connectors });
       switch (result.kind) {
         case 'ok':
-          return okResult({ ok: true, nodes: result.data.nodes });
+          return okResult({
+            ok: true,
+            nodes: result.data.nodes,
+            connectors: result.data.connectors,
+          });
         case 'flowNotFound':
           return errorResult('unknown demo');
         case 'fileNotFound':
@@ -430,9 +433,11 @@ const buildTools = (ops: Operations): McpTool[] => [
         case 'badSchema':
           return errorResult(`Flow failed schema validation: ${JSON.stringify(result.issues)}`);
         case 'duplicateIdInBatch':
-          return errorResult(`Duplicate id in batch: ${result.id}`);
+          return errorResult(`Duplicate ${result.collection} id in batch: ${result.id}`);
         case 'idAlreadyExists':
-          return errorResult(`Node id already exists: ${result.id}`);
+          return errorResult(
+            `${result.collection === 'nodes' ? 'Node' : 'Connector'} id already exists: ${result.id}`,
+          );
         case 'writeFailed':
           return errorResult(`Failed to write demo file: ${result.message}`);
       }
@@ -592,40 +597,6 @@ const buildTools = (ops: Operations): McpTool[] => [
       }
     },
   },
-  {
-    name: 'seeflow_add_connectors',
-    description:
-      'Append 1–100 connectors to a flow in a single transactional write. Either every connector lands or nothing does — a dangling source/target on any item rolls back the whole batch. Use after seeflow_add_nodes when seeding a flow.',
-    inputSchema: inputSchemaFromZod(AddConnectorsInputSchema),
-    handler: async (args) => {
-      const parsed = AddConnectorsInputSchema.safeParse(args);
-      if (!parsed.success) {
-        return errorResult(
-          `Invalid add_connectors arguments: ${JSON.stringify(parsed.error.issues)}`,
-        );
-      }
-      const { flowId, connectors } = parsed.data;
-      const result = await ops.addConnectorsBulk(flowId, { connectors });
-      switch (result.kind) {
-        case 'ok':
-          return okResult({ ok: true, connectors: result.data.connectors });
-        case 'flowNotFound':
-          return errorResult('unknown demo');
-        case 'fileNotFound':
-          return errorResult(`Flow file not found: ${result.path}`);
-        case 'badJson':
-          return errorResult(`Flow file is not valid JSON: ${result.message}`);
-        case 'badSchema':
-          return errorResult(`Flow failed schema validation: ${JSON.stringify(result.issues)}`);
-        case 'duplicateIdInBatch':
-          return errorResult(`Duplicate id in batch: ${result.id}`);
-        case 'idAlreadyExists':
-          return errorResult(`Connector id already exists: ${result.id}`);
-        case 'writeFailed':
-          return errorResult(`Failed to write demo file: ${result.message}`);
-      }
-    },
-  },
   {
     name: 'seeflow_patch_connector',
     description: