@tuongaz/seeflow 0.1.55 → 0.1.57

package/src/operations.ts

@@ -79,8 +79,26 @@ export type ReorderBody = z.infer<typeof ReorderBodySchema>;
 // other key lands inside node.data. Final validity is enforced by re-parsing
 // the whole demo through ResolvedFlowSchema after the merge — this body schema just
 // rejects unknown top-level keys to catch typos.
+const NodeTypeSchema = z.enum([
+  'playNode',
+  'stateNode',
+  'shapeNode',
+  'imageNode',
+  'iconNode',
+  'htmlNode',
+]);
+
 export const NodePatchBodySchema = z
   .object({
+    // When supplied AND different from the node's current type, the merged
+    // node is reclassified in place: data keys not allowed on the new type's
+    // FlowDataSchema are stripped, visuals (which route to style.json) are
+    // preserved, and the post-merge ResolvedFlowSchema reparse enforces the
+    // new type's required fields (e.g. stateNode → playNode without a
+    // playAction in the same body surfaces as `badSchema`). The per-node
+    // folder under `.seeflow/nodes/<id>/` is keyed by id, so retype keeps
+    // scripts, detail.md, and view.html attached.
+    type: NodeTypeSchema.optional(),
     position: PositionBodySchema.optional(),
     name: z.string().optional(),
     borderColor: ColorTokenSchema.optional(),
@@ -164,6 +182,61 @@ const NODE_DATA_PATCH_KEYS = [
 
 const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e) => e.field));
 
+// Semantic (non-visual) data keys allowed by each node type's FlowDataSchema.
+// Visual keys (NODE_STYLE_KEYS in merge.ts) are always preserved on retype —
+// they route to style.json on write. Everything else gets stripped from
+// `data` when a node changes type so the post-merge ResolvedFlowSchema reparse
+// doesn't reject lingering fields from the previous variant. Missing required
+// fields on the new type (e.g. stateNode → playNode without playAction)
+// surface as the normal `badSchema` outcome from the reparse.
+const SEMANTIC_KEYS_BY_TYPE: Record<z.infer<typeof NodeTypeSchema>, ReadonlySet<string>> = {
+  playNode: new Set([
+    'name',
+    'kind',
+    'stateSource',
+    'handlerModule',
+    'icon',
+    'description',
+    'detail',
+    'playAction',
+    'statusAction',
+  ]),
+  stateNode: new Set([
+    'name',
+    'kind',
+    'stateSource',
+    'handlerModule',
+    'icon',
+    'description',
+    'detail',
+    'playAction',
+    'statusAction',
+  ]),
+  shapeNode: new Set(['shape', 'name', 'description', 'detail']),
+  imageNode: new Set(['path', 'alt', 'description', 'detail']),
+  iconNode: new Set(['icon', 'alt', 'name', 'description', 'detail']),
+  htmlNode: new Set(['html', 'name', 'icon', 'description', 'detail']),
+};
+
+// Visual data keys — routed to style.json on write by splitFlow. Kept here
+// (duplicated from merge.ts) so mergeNodeUpdates can preserve them across a
+// type change without taking a runtime dependency on merge.ts.
+const NODE_VISUAL_KEYS = new Set([
+  'width',
+  'height',
+  'borderColor',
+  'backgroundColor',
+  'borderSize',
+  'borderStyle',
+  'fontSize',
+  'textColor',
+  'cornerRadius',
+  'borderWidth',
+  'color',
+  'strokeWidth',
+  'autoSize',
+]);
+
 export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePatchBody): void => {
   if (updates.position !== undefined) {
     node.position = updates.position;
@@ -205,6 +278,27 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
     touchedData = true;
   }
 
+  // Type retype: when the patch supplies a `type` that differs from the
+  // node's current type, reclassify in place. Visual keys are preserved
+  // (they route to style.json on write); any semantic data key not allowed
+  // by the new type's FlowDataSchema is stripped so the post-merge reparse
+  // doesn't reject lingering fields. The per-node folder under
+  // `.seeflow/nodes/<id>/` is keyed by id (unchanged), so scripts and
+  // externalized files stay attached. Missing required fields on the new
+  // type (e.g. stateNode → playNode without a playAction in the same patch)
+  // surface as `badSchema` from the ResolvedFlowSchema reparse.
+  if (updates.type !== undefined && updates.type !== node.type) {
+    node.type = updates.type;
+    const allowedSemantic = SEMANTIC_KEYS_BY_TYPE[updates.type];
+    for (const key of Object.keys(data)) {
+      if (NODE_VISUAL_KEYS.has(key)) continue;
+      if (!allowedSemantic.has(key)) {
+        delete data[key];
+        touchedData = true;
+      }
+    }
+  }
+
   // htmlNode-only invariant enforcement:
   //   autoSize === true ⊻ (width and height set).
   // autoSize: true is the dominant signal — it strips width/height even if
@@ -361,19 +455,29 @@ export type AddNodeOutcome =
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'writeFailed'; message: string };
 
-// Bulk add: ok payload carries every created node so the caller can read
-// server-assigned ids back. duplicateIdInBatch fires when two items in the
-// same request share an id; idAlreadyExists fires when a request id collides
-// with a node already on disk. Both are pre-write rejections, no rollback
-// needed. writeFailed/badSchema cover the post-mutation failure modes.
-export type AddNodesBulkOutcome =
-  | { kind: 'ok'; data: { nodes: Array<{ id: string; node: Record<string, unknown> }> } }
+// Combined bulk add: ok payload carries every created node + connector so the
+// caller can read server-assigned ids back. nodes/connectors arrays in the
+// payload are empty when the input section was absent. duplicateIdInBatch
+// fires when two items in the same collection of one request share an id;
+// idAlreadyExists fires when a request id collides with an existing entry on
+// disk; both are pre-write rejections (with a `collection` discriminator so
+// callers know which array tripped). The whole batch is wrapped in one
+// mutateMergedFlowAndBroadcast — a post-mutation ResolvedFlowSchema failure
+// (e.g. dangling connector source/target) rolls back both arrays together.
+export type FlowBulkOutcome =
+  | {
+      kind: 'ok';
+      data: {
+        nodes: Array<{ id: string; node: Record<string, unknown> }>;
+        connectors: Array<{ id: string }>;
+      };
+    }
   | { kind: 'flowNotFound' }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; message: string }
   | { kind: 'badSchema'; issues: ZodIssue[] }
-  | { kind: 'duplicateIdInBatch'; id: string }
-  | { kind: 'idAlreadyExists'; id: string }
+  | { kind: 'duplicateIdInBatch'; collection: 'nodes' | 'connectors'; id: string }
+  | { kind: 'idAlreadyExists'; collection: 'nodes' | 'connectors'; id: string }
   | { kind: 'writeFailed'; message: string };
 
 export type DeleteNodeOutcome =
@@ -491,20 +595,32 @@ export const mergeConnectorUpdates = (
   }
 };
 
-// Bulk-add envelopes. Body shape gated here; per-item shape is implicit and
-// enforced by ResolvedFlowSchema after the whole batch is merged in — same
-// pattern the singular add endpoints already rely on. The 100-item cap keeps
-// one SSE broadcast payload reasonable; the LLM caller is meant to chunk if
-// it ever needs more.
+// Combined bulk-add envelope. Body shape gated here; per-item shape is
+// implicit and enforced by ResolvedFlowSchema after the whole batch is merged
+// in — same pattern the singular add endpoints already rely on. The 100-item
+// per-kind cap keeps one SSE broadcast payload reasonable; the LLM caller is
+// meant to chunk if it ever needs more. Both arrays are optional; the refine
+// requires at least one non-empty so an empty {} can't no-op a write.
+//
+// The shape is exported as a bare ZodObject (FlowBulkBodyShape) so MCP/CLI
+// surfaces can `.extend({ flowId })` and re-apply the refine — extend()
+// doesn't survive ZodEffects (a refined schema), and we want the JSON Schema
+// to stay a clean `{ type: 'object', properties: ... }` for agent
+// introspection instead of an `allOf` intersection.
 const BULK_MAX_ITEMS = 100;
-export const NodesBulkBodySchema = z.object({
-  nodes: z.array(z.record(z.unknown())).min(1).max(BULK_MAX_ITEMS),
+export const FLOW_BULK_NON_EMPTY_MESSAGE = 'Body must include at least one node or connector';
+export const flowBulkNonEmpty = (b: {
+  nodes?: unknown[];
+  connectors?: unknown[];
+}): boolean => (b.nodes?.length ?? 0) + (b.connectors?.length ?? 0) > 0;
+export const FlowBulkBodyShape = z.object({
+  nodes: z.array(z.record(z.unknown())).max(BULK_MAX_ITEMS).optional(),
+  connectors: z.array(z.record(z.unknown())).max(BULK_MAX_ITEMS).optional(),
 });
-export type NodesBulkBody = z.infer<typeof NodesBulkBodySchema>;
-export const ConnectorsBulkBodySchema = z.object({
-  connectors: z.array(z.record(z.unknown())).min(1).max(BULK_MAX_ITEMS),
+export const FlowBulkBodySchema = FlowBulkBodyShape.refine(flowBulkNonEmpty, {
+  message: FLOW_BULK_NON_EMPTY_MESSAGE,
 });
-export type ConnectorsBulkBody = z.infer<typeof ConnectorsBulkBodySchema>;
+export type FlowBulkBody = z.infer<typeof FlowBulkBodySchema>;
 
 export type AddConnectorOutcome =
   | { kind: 'ok'; data: { id: string } }
@@ -514,16 +630,6 @@ export type AddConnectorOutcome =
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'writeFailed'; message: string };
 
-export type AddConnectorsBulkOutcome =
-  | { kind: 'ok'; data: { connectors: Array<{ id: string }> } }
-  | { kind: 'flowNotFound' }
-  | { kind: 'fileNotFound'; path: string }
-  | { kind: 'badJson'; message: string }
-  | { kind: 'badSchema'; issues: ZodIssue[] }
-  | { kind: 'duplicateIdInBatch'; id: string }
-  | { kind: 'idAlreadyExists'; id: string }
-  | { kind: 'writeFailed'; message: string };
-
 export type PatchConnectorOutcome =
   | { kind: 'ok' }
   | { kind: 'flowNotFound' }
@@ -842,7 +948,7 @@ export function listFlowsSummaryImpl(deps: OperationsDeps): ListFlowsSummaryOutc
 
 export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise<GetFlowOutcome> {
   const { registry, watcher } = deps;
-  const entry = registry.getById(flowId);
+  const entry = registry.resolve(flowId);
   if (!entry) return { kind: 'notFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -897,7 +1003,7 @@ export async function getFlowGraphImpl(
   deps: OperationsDeps,
   flowId: string,
 ): Promise<GetFlowGraphOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'notFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -932,7 +1038,7 @@ export async function getNodeImpl(
   nodeId: string,
 ): Promise<GetNodeOutcome> {
   const { registry, watcher } = deps;
-  const entry = registry.getById(flowId);
+  const entry = registry.resolve(flowId);
   if (!entry) return { kind: 'notFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1033,7 +1139,7 @@ export async function registerFlowImpl(
 
 export function deleteFlowImpl(deps: OperationsDeps, idOrSlug: string): DeleteFlowOutcome {
   const { registry, watcher } = deps;
-  const entry = registry.getById(idOrSlug) ?? registry.getBySlug(idOrSlug);
+  const entry = registry.resolve(idOrSlug);
   if (!entry) return { kind: 'notFound' };
   watcher?.unwatch(entry.id);
   registry.remove(entry.id);
@@ -1112,7 +1218,7 @@ export async function addNodeImpl(
   flowId: string,
   nodeBody: Record<string, unknown>,
 ): Promise<AddNodeOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const newNode = { ...nodeBody };
@@ -1173,39 +1279,44 @@ export async function addNodeImpl(
   return result;
 }
 
-// Bulk add — N nodes in one read-validate-write-broadcast cycle. Transactional:
-// any single item failing the post-mutation ResolvedFlowSchema parse rolls
-// back the whole batch (nothing on flow.json, no per-node folders created).
-// Per-node externalization runs per item exactly like the singular path; the
-// queued file writes all happen inside the mutator so a writeFailed on item
-// K leaves items 0..K-1 with stranded folders — same shape as the singular
-// path's writeFailed, but amplified by N. Caller is expected to retry.
-export async function addNodesBulkImpl(
+// Bulk add — N nodes + M connectors in one read-validate-write-broadcast
+// cycle. Transactional: any single item failing the post-mutation
+// ResolvedFlowSchema parse rolls back the whole batch (nothing on flow.json,
+// no per-node folders surviving). Connectors that reference nodes added in
+// the same call validate correctly because the parse sees the merged graph
+// as a whole; a dangling source/target rolls back BOTH arrays. Per-node
+// externalization is queued in Phase A and flushed inside the mutator so a
+// writeFailed on node K leaves nodes 0..K-1 with stranded folders — same
+// shape as the singular path's writeFailed, but amplified by N. Caller is
+// expected to retry.
+export async function addFlowBulkImpl(
   deps: OperationsDeps,
   flowId: string,
-  body: NodesBulkBody,
-): Promise<AddNodesBulkOutcome> {
-  const entry = deps.registry.getById(flowId);
+  body: FlowBulkBody,
+): Promise<FlowBulkOutcome> {
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
-  // Pre-allocate ids + capture externalization writes per item. Doing this
-  // outside the mutator means the duplicateIdInBatch check runs before any
-  // disk IO; the collide-with-existing check happens inside the mutator where
-  // it can see the freshly-read flow.nodes.
-  const prepared: Array<{
+  // Phase A — prepare ids + externalization, per-collection duplicate check.
+  // No IO yet; duplicates inside a single collection trip here, before any
+  // disk write. Cross-collection id reuse is intentionally allowed (a node
+  // and a connector may share an id today).
+  const preparedNodes: Array<{
     id: string;
     node: Record<string, unknown>;
     externalized: Array<{ absPath: string; content: string }>;
   }> = [];
-  const idsInBatch = new Set<string>();
-  for (const item of body.nodes) {
+  const nodeIdsInBatch = new Set<string>();
+  for (const item of body.nodes ?? []) {
     const newNode = { ...item };
     if (typeof newNode.id !== 'string' || newNode.id.length === 0) {
       newNode.id = `node-${shortId()}`;
     }
     const newId = newNode.id as string;
-    if (idsInBatch.has(newId)) return { kind: 'duplicateIdInBatch', id: newId };
-    idsInBatch.add(newId);
+    if (nodeIdsInBatch.has(newId)) {
+      return { kind: 'duplicateIdInBatch', collection: 'nodes', id: newId };
+    }
+    nodeIdsInBatch.add(newId);
     if (!newNode.position || typeof newNode.position !== 'object') {
       newNode.position = { x: 0, y: 0 };
     }
@@ -1225,32 +1336,70 @@ export async function addNodesBulkImpl(
       });
     }
     newNode.data = data;
-    prepared.push({ id: newId, node: newNode, externalized });
+    preparedNodes.push({ id: newId, node: newNode, externalized });
+  }
+
+  const preparedConns: Array<{ id: string; conn: Record<string, unknown> }> = [];
+  const connIdsInBatch = new Set<string>();
+  for (const item of body.connectors ?? []) {
+    const newConn = { ...item };
+    if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
+      newConn.id = `conn-${shortId()}`;
+    }
+    if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
+      newConn.kind = 'default';
+    }
+    const newId = newConn.id as string;
+    if (connIdsInBatch.has(newId)) {
+      return { kind: 'duplicateIdInBatch', collection: 'connectors', id: newId };
+    }
+    connIdsInBatch.add(newId);
+    preparedConns.push({ id: newId, conn: newConn });
   }
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  const result = await mutateMergedFlowAndBroadcast<
-    { kind: 'idAlreadyExists'; id: string } | { kind: 'writeFailed'; message: string }
-  >(deps, flowId, fullPath, (flow) => {
-    const existing = new Set(
+  // Phase B — single transactional mutate. Push nodes first so connectors
+  // added in the same batch can reference them, then queue externalized file
+  // writes. mutateMergedFlowAndBroadcast runs one post-mutation
+  // ResolvedFlowSchema parse over the merged graph and emits one flow:reload
+  // broadcast.
+  type MutErr =
+    | { kind: 'idAlreadyExists'; collection: 'nodes' | 'connectors'; id: string }
+    | { kind: 'writeFailed'; message: string };
+  const result = await mutateMergedFlowAndBroadcast<MutErr>(deps, flowId, fullPath, (flow) => {
+    const existingNodeIds = new Set(
       flow.nodes
         .map((n) => (typeof n.id === 'string' ? n.id : null))
         .filter((id): id is string => id !== null),
     );
-    for (const p of prepared) {
-      if (existing.has(p.id)) return { kind: 'idAlreadyExists', id: p.id };
+    for (const p of preparedNodes) {
+      if (existingNodeIds.has(p.id)) {
+        return { kind: 'idAlreadyExists', collection: 'nodes', id: p.id };
+      }
     }
-    for (const p of prepared) {
-      flow.nodes.push(p.node);
+    const existingConnIds = new Set(
+      flow.connectors
+        .map((c) => (typeof c.id === 'string' ? c.id : null))
+        .filter((id): id is string => id !== null),
+    );
+    for (const p of preparedConns) {
+      if (existingConnIds.has(p.id)) {
+        return { kind: 'idAlreadyExists', collection: 'connectors', id: p.id };
+      }
     }
-    for (const p of prepared) {
+    for (const p of preparedNodes) flow.nodes.push(p.node);
+    for (const p of preparedConns) flow.connectors.push(p.conn);
+    for (const p of preparedNodes) {
       for (const ext of p.externalized) {
         try {
           writeNodeFile(ext.absPath, ext.content);
         } catch (err) {
-          return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+          return {
+            kind: 'writeFailed',
+            message: err instanceof Error ? err.message : String(err),
+          };
         }
       }
     }
@@ -1260,17 +1409,20 @@ export async function addNodesBulkImpl(
   if (result.kind === 'ok') {
     return {
       kind: 'ok',
-      data: { nodes: prepared.map((p) => ({ id: p.id, node: p.node })) },
+      data: {
+        nodes: preparedNodes.map((p) => ({ id: p.id, node: p.node })),
+        connectors: preparedConns.map((p) => ({ id: p.id })),
+      },
     };
   }
 
   // Non-ok branch: the post-mutation ResolvedFlowSchema parse (or a later
   // writeFailed) ran AFTER the mutator already wrote per-node folders. The
   // collide-with-existing check ran first inside the mutator, so any folder
-  // at `nodes/<prepared.id>/` was created by this call — safe to cascade.
-  // The idAlreadyExists branch returns before any writeNodeFile, so we still
-  // try to remove (it's a no-op when the folder doesn't exist).
-  for (const p of prepared) {
+  // at `nodes/<p.id>/` was created by this call — safe to cascade. The
+  // idAlreadyExists branch returns before any writeNodeFile, so the rmdir is
+  // a no-op there.
+  for (const p of preparedNodes) {
     removeNodeDir(entry.repoPath, p.id);
   }
   return result;
@@ -1287,7 +1439,7 @@ export async function deleteNodeImpl(
   flowId: string,
   nodeId: string,
 ): Promise<DeleteNodeOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1330,7 +1482,7 @@ export async function moveNodeImpl(
   nodeId: string,
   position: PositionBody,
 ): Promise<MoveNodeOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1366,7 +1518,7 @@ export async function patchNodeImpl(
   nodeId: string,
   updates: NodePatchBody,
 ): Promise<PatchNodeOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1426,7 +1578,7 @@ export async function reorderNodeImpl(
   nodeId: string,
   body: ReorderBody,
 ): Promise<ReorderNodeOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1458,7 +1610,7 @@ export async function addConnectorImpl(
   flowId: string,
   connBody: Record<string, unknown>,
 ): Promise<AddConnectorOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const newConn = { ...connBody };
@@ -1482,64 +1634,6 @@ export async function addConnectorImpl(
   return result;
 }
 
-// Bulk add — N connectors in one read-validate-write-broadcast cycle. Same
-// transactional shape as addNodesBulkImpl: any single connector failing the
-// post-mutation ResolvedFlowSchema parse (dangling source/target, missing
-// kind-specific field) rolls back the whole batch. No per-item externalization
-// to manage — connectors don't own per-node folders.
-export async function addConnectorsBulkImpl(
-  deps: OperationsDeps,
-  flowId: string,
-  body: ConnectorsBulkBody,
-): Promise<AddConnectorsBulkOutcome> {
-  const entry = deps.registry.getById(flowId);
-  if (!entry) return { kind: 'flowNotFound' };
-
-  const prepared: Array<{ id: string; conn: Record<string, unknown> }> = [];
-  const idsInBatch = new Set<string>();
-  for (const item of body.connectors) {
-    const newConn = { ...item };
-    if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
-      newConn.id = `conn-${shortId()}`;
-    }
-    if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
-      newConn.kind = 'default';
-    }
-    const newId = newConn.id as string;
-    if (idsInBatch.has(newId)) return { kind: 'duplicateIdInBatch', id: newId };
-    idsInBatch.add(newId);
-    prepared.push({ id: newId, conn: newConn });
-  }
-
-  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
-  if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
-
-  const result = await mutateMergedFlowAndBroadcast<{ kind: 'idAlreadyExists'; id: string }>(
-    deps,
-    flowId,
-    fullPath,
-    (flow) => {
-      const existing = new Set(
-        flow.connectors
-          .map((c) => (typeof c.id === 'string' ? c.id : null))
-          .filter((id): id is string => id !== null),
-      );
-      for (const p of prepared) {
-        if (existing.has(p.id)) return { kind: 'idAlreadyExists', id: p.id };
-      }
-      for (const p of prepared) {
-        flow.connectors.push(p.conn);
-      }
-      return { kind: 'ok' };
-    },
-  );
-
-  if (result.kind === 'ok') {
-    return { kind: 'ok', data: { connectors: prepared.map((p) => ({ id: p.id })) } };
-  }
-  return result;
-}
-
 // Apply a partial PATCH body to a single connector. Mutation runs against
 // the raw parsed JSON (so unknown forward-compat fields survive a round-trip).
 // When `kind` changes, the previous kind's payload fields are dropped first
@@ -1555,7 +1649,7 @@ export async function patchConnectorImpl(
   connectorId: string,
   updates: ConnectorPatchBody,
 ): Promise<PatchConnectorOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1582,7 +1676,7 @@ export async function deleteConnectorImpl(
   flowId: string,
   connectorId: string,
 ): Promise<DeleteConnectorOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1704,7 +1798,7 @@ export async function applyLayoutImpl(
   flowId: string,
   options: LayoutOptions | undefined,
 ): Promise<ApplyLayoutOutcome> {
-  const entry = deps.registry.getById(flowId);
+  const entry = deps.registry.resolve(flowId);
   if (!entry) return { kind: 'flowNotFound' };
 
   const flowAbs = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1774,10 +1868,6 @@ export interface Operations {
   getFlowGraph(id: string): ReturnType<typeof getFlowGraphImpl>;
   getNode(flowId: string, nodeId: string): ReturnType<typeof getNodeImpl>;
   addNode(flowId: string, body: Record<string, unknown>): ReturnType<typeof addNodeImpl>;
-  addNodesBulk(
-    flowId: string,
-    body: Parameters<typeof addNodesBulkImpl>[2],
-  ): ReturnType<typeof addNodesBulkImpl>;
   patchNode(
     flowId: string,
     nodeId: string,
@@ -1795,16 +1885,16 @@ export interface Operations {
   ): ReturnType<typeof reorderNodeImpl>;
   deleteNode(flowId: string, nodeId: string): ReturnType<typeof deleteNodeImpl>;
   addConnector(flowId: string, body: Record<string, unknown>): ReturnType<typeof addConnectorImpl>;
-  addConnectorsBulk(
-    flowId: string,
-    body: Parameters<typeof addConnectorsBulkImpl>[2],
-  ): ReturnType<typeof addConnectorsBulkImpl>;
   patchConnector(
     flowId: string,
     connectorId: string,
     body: Parameters<typeof patchConnectorImpl>[3],
   ): ReturnType<typeof patchConnectorImpl>;
   deleteConnector(flowId: string, connectorId: string): ReturnType<typeof deleteConnectorImpl>;
+  addBulk(
+    flowId: string,
+    body: Parameters<typeof addFlowBulkImpl>[2],
+  ): ReturnType<typeof addFlowBulkImpl>;
   registerFlow(body: Parameters<typeof registerFlowImpl>[1]): ReturnType<typeof registerFlowImpl>;
   createProject(
     body: Parameters<typeof createProjectImpl>[1],
@@ -1825,16 +1915,15 @@ export function createOperations(deps: OperationsDeps): Operations {
     getFlowGraph: (id) => getFlowGraphImpl(deps, id),
     getNode: (flowId, nodeId) => getNodeImpl(deps, flowId, nodeId),
     addNode: (flowId, body) => addNodeImpl(deps, flowId, body),
-    addNodesBulk: (flowId, body) => addNodesBulkImpl(deps, flowId, body),
     patchNode: (flowId, nodeId, body) => patchNodeImpl(deps, flowId, nodeId, body),
     moveNode: (flowId, nodeId, body) => moveNodeImpl(deps, flowId, nodeId, body),
     reorderNode: (flowId, nodeId, body) => reorderNodeImpl(deps, flowId, nodeId, body),
     deleteNode: (flowId, nodeId) => deleteNodeImpl(deps, flowId, nodeId),
     addConnector: (flowId, body) => addConnectorImpl(deps, flowId, body),
-    addConnectorsBulk: (flowId, body) => addConnectorsBulkImpl(deps, flowId, body),
     patchConnector: (flowId, connectorId, body) =>
       patchConnectorImpl(deps, flowId, connectorId, body),
     deleteConnector: (flowId, connectorId) => deleteConnectorImpl(deps, flowId, connectorId),
+    addBulk: (flowId, body) => addFlowBulkImpl(deps, flowId, body),
     registerFlow: (body) => registerFlowImpl(deps, body),
     createProject: (body) => createProjectImpl(deps, body),
     deleteFlow: (id) => deleteFlowImpl(deps, id),

package/src/registry.ts

@@ -31,6 +31,9 @@ export interface Registry {
   list(): FlowEntry[];
   getById(id: string): FlowEntry | undefined;
   getBySlug(slug: string): FlowEntry | undefined;
+  /** Resolve by id, falling back to slug. The canonical lookup for CLI/API
+   *  paths that document `<flowId>` as "Flow id or slug". */
+  resolve(idOrSlug: string): FlowEntry | undefined;
   getByRepoPath(repoPath: string): FlowEntry | undefined;
   getByRepoPathAndFlowPath(repoPath: string, flowPath: string): FlowEntry | undefined;
   upsert(input: RegisterInput): FlowEntry;
@@ -182,6 +185,12 @@ export function createRegistry(options: { path?: string } = {}): Registry {
       refreshIfStale();
       return [...entries.values()].find((e) => e.slug === slug);
     },
+    resolve: (idOrSlug) => {
+      refreshIfStale();
+      const byId = entries.get(idOrSlug);
+      if (byId) return byId;
+      return [...entries.values()].find((e) => e.slug === idOrSlug);
+    },
     getByRepoPath: (repoPath) => {
       refreshIfStale();
       return findByRepoPath(repoPath);