@tuongaz/seeflow 0.1.40 → 0.1.42

package/examples/ecommerce-platform/.seeflow/flow.json

@@ -3,7 +3,7 @@
   "name": "E-Commerce Platform",
   "nodes": [
     {
-      "id": "client",
+      "id": "node-cQOUPXanaX",
       "type": "shapeNode",
       "data": {
         "shape": "user",
@@ -12,7 +12,7 @@
       }
     },
     {
-      "id": "api-gateway",
+      "id": "node-CbwYqb7NfB",
       "type": "playNode",
       "data": {
         "name": "API Gateway",
@@ -21,7 +21,7 @@
           "kind": "request"
         },
         "description": "Auth, rate-limiting, routing.",
-        "detail": "file://details/api-gateway.md",
+        "detail": "file://nodes/node-CbwYqb7NfB/detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -33,7 +33,7 @@
       }
     },
     {
-      "id": "auth-service",
+      "id": "node-3zFtHg6ENc",
       "type": "stateNode",
       "data": {
         "name": "Auth Service",
@@ -42,11 +42,11 @@
           "kind": "request"
         },
         "description": "JWT issuance + OAuth2 / OIDC.",
-        "detail": "file://details/auth-service.md"
+        "detail": "file://nodes/node-3zFtHg6ENc/detail.md"
       }
     },
     {
-      "id": "product-service",
+      "id": "node-kwBY8YPmYM",
       "type": "stateNode",
       "data": {
         "name": "Product Catalog",
@@ -55,11 +55,11 @@
           "kind": "request"
         },
         "description": "SKUs, variants, pricing, full-text search.",
-        "detail": "file://details/product-service.md"
+        "detail": "file://nodes/node-kwBY8YPmYM/detail.md"
       }
     },
     {
-      "id": "cart-service",
+      "id": "node-5F424NWbEu",
       "type": "playNode",
       "data": {
         "name": "Cart Service",
@@ -68,7 +68,7 @@
           "kind": "request"
         },
         "description": "Add/remove items, apply coupons, checkout.",
-        "detail": "file://details/cart-service.md",
+        "detail": "file://nodes/node-5F424NWbEu/detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -80,7 +80,7 @@
       }
     },
     {
-      "id": "order-service",
+      "id": "node-yKrg9DV5fJ",
       "type": "playNode",
       "data": {
         "name": "Order Service",
@@ -88,8 +88,8 @@
         "stateSource": {
           "kind": "event"
         },
-        "description": "pending \u2192 confirmed \u2192 shipped \u2192 delivered.",
-        "detail": "file://details/order-service.md",
+        "description": "pending → confirmed → shipped → delivered.",
+        "detail": "file://nodes/node-yKrg9DV5fJ/detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -101,7 +101,7 @@
       }
     },
     {
-      "id": "payment-service",
+      "id": "node-mPqan8rFYN",
       "type": "stateNode",
       "data": {
         "name": "Payment Service",
@@ -110,11 +110,11 @@
           "kind": "event"
         },
         "description": "Stripe + PayPal gateway integration.",
-        "detail": "file://details/payment-service.md"
+        "detail": "file://nodes/node-mPqan8rFYN/detail.md"
       }
     },
     {
-      "id": "notification-service",
+      "id": "node-fkptXw7uvs",
       "type": "stateNode",
       "data": {
         "name": "Notification Service",
@@ -123,96 +123,96 @@
           "kind": "event"
         },
         "description": "Email + SMS + push via AWS SES / SNS.",
-        "detail": "file://details/notification-service.md"
+        "detail": "file://nodes/node-fkptXw7uvs/detail.md"
       }
     },
     {
-      "id": "postgresql",
+      "id": "node-5SDiw3Wz6s",
       "type": "shapeNode",
       "data": {
         "shape": "database",
         "name": "PostgreSQL",
-        "description": "Orders, users, products \u2014 primary OLTP store"
+        "description": "Orders, users, products — primary OLTP store"
       }
     },
     {
-      "id": "platform-health",
+      "id": "node-XwygzfKPZ5",
       "type": "htmlNode",
       "data": {
         "name": "Platform Health",
-        "htmlPath": "scripts/platform-health.html"
+        "html": "file://nodes/node-XwygzfKPZ5/view.html"
       }
     }
   ],
   "connectors": [
     {
-      "id": "c-client-api",
-      "source": "client",
-      "target": "api-gateway",
+      "id": "conn-4XKU3GcGPF",
+      "source": "node-cQOUPXanaX",
+      "target": "node-CbwYqb7NfB",
       "kind": "http",
       "method": "POST",
       "label": "REST API"
     },
     {
-      "id": "c-api-auth",
-      "source": "api-gateway",
-      "target": "auth-service",
+      "id": "conn-OxNUxp7qB3",
+      "source": "node-CbwYqb7NfB",
+      "target": "node-3zFtHg6ENc",
       "kind": "http",
       "method": "POST",
       "label": "POST /auth"
     },
     {
-      "id": "c-api-product",
-      "source": "api-gateway",
-      "target": "product-service",
+      "id": "conn-7HlJF6KVHx",
+      "source": "node-CbwYqb7NfB",
+      "target": "node-kwBY8YPmYM",
       "kind": "http",
       "method": "GET",
       "label": "GET /products"
     },
     {
-      "id": "c-api-cart",
-      "source": "api-gateway",
-      "target": "cart-service",
+      "id": "conn-ORfUTiooia",
+      "source": "node-CbwYqb7NfB",
+      "target": "node-5F424NWbEu",
       "kind": "http",
       "method": "POST",
       "label": "POST /cart"
     },
     {
-      "id": "c-cart-order",
-      "source": "cart-service",
-      "target": "order-service",
+      "id": "conn-EABXtQv89M",
+      "source": "node-5F424NWbEu",
+      "target": "node-yKrg9DV5fJ",
       "kind": "event",
       "eventName": "cart.checkout",
       "label": "cart.checkout"
     },
     {
-      "id": "c-order-payment",
-      "source": "order-service",
-      "target": "payment-service",
+      "id": "conn-kjyg3RDDvu",
+      "source": "node-yKrg9DV5fJ",
+      "target": "node-mPqan8rFYN",
       "kind": "event",
       "eventName": "order.created",
       "label": "order.created"
     },
     {
-      "id": "c-payment-notify",
-      "source": "payment-service",
-      "target": "notification-service",
+      "id": "conn-wqFq0shXO5",
+      "source": "node-mPqan8rFYN",
+      "target": "node-fkptXw7uvs",
       "kind": "event",
       "eventName": "payment.captured",
       "label": "payment.captured"
     },
     {
-      "id": "c-order-pg",
-      "source": "order-service",
-      "target": "postgresql",
+      "id": "conn-8ftFXZvD4r",
+      "source": "node-yKrg9DV5fJ",
+      "target": "node-5SDiw3Wz6s",
       "kind": "http",
       "method": "POST",
       "label": "read/write"
     },
     {
-      "id": "c-payment-pg",
-      "source": "payment-service",
-      "target": "postgresql",
+      "id": "conn-VTfjsOckF2",
+      "source": "node-mPqan8rFYN",
+      "target": "node-5SDiw3Wz6s",
       "kind": "http",
       "method": "POST",
       "label": "read/write"

package/examples/ecommerce-platform/.seeflow/style.json

@@ -1,6 +1,6 @@
 {
   "nodes": {
-    "client": {
+    "node-cQOUPXanaX": {
       "position": {
         "x": 80,
         "y": 215.5
@@ -9,7 +9,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "api-gateway": {
+    "node-CbwYqb7NfB": {
       "position": {
         "x": 320,
         "y": 227
@@ -18,7 +18,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "auth-service": {
+    "node-3zFtHg6ENc": {
       "position": {
         "x": 660,
         "y": 50
@@ -27,7 +27,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "product-service": {
+    "node-kwBY8YPmYM": {
       "position": {
         "x": 660,
         "y": 218
@@ -36,7 +36,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "cart-service": {
+    "node-5F424NWbEu": {
       "position": {
         "x": 660,
         "y": 413
@@ -45,7 +45,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "order-service": {
+    "node-yKrg9DV5fJ": {
       "position": {
         "x": 1000,
         "y": 413
@@ -54,7 +54,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "payment-service": {
+    "node-mPqan8rFYN": {
       "position": {
         "x": 1340,
         "y": 349
@@ -63,7 +63,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "notification-service": {
+    "node-fkptXw7uvs": {
       "position": {
         "x": 1680,
         "y": 339
@@ -72,7 +72,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "postgresql": {
+    "node-5SDiw3Wz6s": {
       "position": {
         "x": 1720,
         "y": 507
@@ -81,7 +81,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "platform-health": {
+    "node-XwygzfKPZ5": {
       "position": {
         "x": 1340,
         "y": 50

package/examples/order-pipeline/.seeflow/flow.json

@@ -3,7 +3,7 @@
   "name": "Order Pipeline",
   "nodes": [
     {
-      "id": "post-orders",
+      "id": "node-XKIyds0TDg",
       "type": "playNode",
       "data": {
         "name": "POST /orders",
@@ -12,7 +12,7 @@
           "kind": "request"
         },
         "description": "Creates order, kicks off the pipeline.",
-        "detail": "file://details/post-orders.md",
+        "detail": "file://nodes/node-XKIyds0TDg/detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -24,7 +24,7 @@
       }
     },
     {
-      "id": "inventory-service",
+      "id": "node-GXTKUcE3ye",
       "type": "stateNode",
       "data": {
         "name": "Inventory Service",
@@ -33,12 +33,12 @@
           "kind": "event"
         },
         "description": "Reserves stock.",
-        "detail": "file://details/inventory-service.md",
+        "detail": "file://nodes/node-GXTKUcE3ye/detail.md",
         "icon": "a-arrow-down-icon"
       }
     },
     {
-      "id": "payment-service",
+      "id": "node-YOYiHJpY0i",
       "type": "stateNode",
       "data": {
         "name": "Payment Service",
@@ -47,11 +47,11 @@
           "kind": "event"
         },
         "description": "Charges card.",
-        "detail": "file://details/payment-service.md"
+        "detail": "file://nodes/node-YOYiHJpY0i/detail.md"
       }
     },
     {
-      "id": "fulfillment-service",
+      "id": "node-zUIH7WFnhK",
       "type": "stateNode",
       "data": {
         "name": "Fulfillment Service",
@@ -60,31 +60,31 @@
           "kind": "event"
         },
         "description": "Enqueues shipment.",
-        "detail": "file://details/fulfillment-service.md"
+        "detail": "file://nodes/node-zUIH7WFnhK/detail.md"
       }
     }
   ],
   "connectors": [
     {
-      "id": "c1",
-      "source": "post-orders",
-      "target": "inventory-service",
+      "id": "conn-jJjuWBfe3a",
+      "source": "node-XKIyds0TDg",
+      "target": "node-GXTKUcE3ye",
       "kind": "event",
       "eventName": "order.created",
       "label": "order.created"
     },
     {
-      "id": "c2",
-      "source": "inventory-service",
-      "target": "payment-service",
+      "id": "conn-8DkPOzrnYo",
+      "source": "node-GXTKUcE3ye",
+      "target": "node-YOYiHJpY0i",
       "kind": "event",
       "eventName": "stock.reserved",
       "label": "stock.reserved"
     },
     {
-      "id": "c3",
-      "source": "payment-service",
-      "target": "fulfillment-service",
+      "id": "conn-qp90Rd2cgw",
+      "source": "node-YOYiHJpY0i",
+      "target": "node-zUIH7WFnhK",
       "kind": "event",
       "eventName": "payment.captured",
       "label": "payment.captured"

package/examples/order-pipeline/.seeflow/style.json

@@ -1,6 +1,6 @@
 {
   "nodes": {
-    "post-orders": {
+    "node-XKIyds0TDg": {
       "position": {
         "x": -181.96549037838943,
         "y": 138.95644990042385
@@ -9,7 +9,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "inventory-service": {
+    "node-GXTKUcE3ye": {
       "position": {
         "x": 66.21484197841792,
         "y": -126.31035925520507
@@ -20,7 +20,7 @@
       "borderColor": "green",
       "borderSize": 1
     },
-    "payment-service": {
+    "node-YOYiHJpY0i": {
       "position": {
         "x": 469.1422114437386,
         "y": 206.48855752663212
@@ -29,7 +29,7 @@
       "fontSize": 15,
       "borderColor": "green"
     },
-    "fulfillment-service": {
+    "node-zUIH7WFnhK": {
       "position": {
         "x": 747.51321046746,
         "y": -37.78865629343234

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",

package/src/api.ts

@@ -15,14 +15,18 @@ import type { EventBus } from './events.ts';
 import { type LayoutOptions, computeLayout } from './layout.ts';
 import {
   ConnectorPatchBodySchema,
+  ConnectorsBulkBodySchema,
   CreateProjectBodySchema,
   NodePatchBodySchema,
+  NodesBulkBodySchema,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
   type ValidateBody,
   addConnectorImpl,
+  addConnectorsBulkImpl,
   addNodeImpl,
+  addNodesBulkImpl,
   createProjectImpl,
   deleteConnectorImpl,
   deleteFlowImpl,
@@ -134,7 +138,7 @@ function resolveProjectFile(
   return { kind: 'ok', absPath: realTarget, seeflowRoot: realRoot };
 }
 
-// Allowed extensions for /files/upload. Lowercased; matched after dropping the
+// Allowed extensions for /nodes/:nodeId/files/upload. Lowercased; matched after dropping the
 // leading `.`. Stored as a Set so future expansion (PDF, video) is one-edit.
 const UPLOAD_ALLOWED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
 const UPLOAD_MAX_BYTES = 5 * 1024 * 1024;
@@ -609,17 +613,23 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ ok: true, absPath: resolved.absPath });
   });
 
-  // POST /api/projects/:id/files/upload — accept a multipart image upload and
-  // persist it under `<project>/.seeflow/assets/`. The frontend (US-008 OS
-  // drop) sends `file` (Blob) and optionally `filename` (the original OS name)
-  // in a multipart form; we sanitize the filename to a lowercased slug,
-  // dedupe with `-2`, `-3` suffixes inside the assets dir, and return the
-  // demo-relative path. Allowlist + 5 MB cap guard against arbitrary uploads.
-  api.post('/projects/:id/files/upload', async (c) => {
+  // POST /api/projects/:id/nodes/:nodeId/files/upload — accept a multipart
+  // image upload and persist it under `<project>/.seeflow/nodes/<nodeId>/`.
+  // Multipart shape: `file` (Blob) and optional `filename` (the original OS
+  // name). Allowlist + 5 MB cap guard against arbitrary uploads; the
+  // destination folder is scoped to the node, so delete_node's removeNodeDir
+  // cascade cleans up the asset along with the node row.
+  api.post('/projects/:id/nodes/:nodeId/files/upload', async (c) => {
     const projectId = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
     const entry = registry.getById(projectId);
     if (!entry) return c.json({ error: 'unknown project' }, 404);
 
+    // node id shape: `node-<10 base62 chars>` (matches shortId() output).
+    if (!/^node-[A-Za-z0-9]{10}$/.test(nodeId)) {
+      return c.json({ error: 'invalid nodeId' }, 400);
+    }
+
     let form: FormData;
     try {
       form = await c.req.formData();
@@ -643,20 +653,20 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'invalid filename or extension' }, 400);
     }
 
-    const assetsDir = join(entry.repoPath, '.seeflow', 'assets');
+    const nodeDir = join(entry.repoPath, '.seeflow', 'nodes', nodeId);
     try {
-      mkdirSync(assetsDir, { recursive: true });
+      mkdirSync(nodeDir, { recursive: true });
     } catch (err) {
       return c.json(
         {
-          error: `Failed to create assets dir: ${err instanceof Error ? err.message : String(err)}`,
+          error: `Failed to create node dir: ${err instanceof Error ? err.message : String(err)}`,
         },
         500,
       );
     }
 
-    const finalName = pickUploadFilename(assetsDir, sanitized.base, sanitized.ext);
-    const absPath = join(assetsDir, finalName);
+    const finalName = pickUploadFilename(nodeDir, sanitized.base, sanitized.ext);
+    const absPath = join(nodeDir, finalName);
     try {
       await Bun.write(absPath, fileField);
     } catch (err) {
@@ -666,7 +676,7 @@ export function createApi(options: ApiOptions): Hono {
       );
     }
 
-    return c.json({ path: `assets/${finalName}` });
+    return c.json({ path: `nodes/${nodeId}/${finalName}` });
   });
 
   api.delete('/flows/:id', (c) => {
@@ -1058,6 +1068,45 @@ 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) => {
+    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 = NodesBulkBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid bulk nodes body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await addNodesBulkImpl({ registry, watcher }, id, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true, nodes: result.data.nodes });
+      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: `Node id already exists: ${result.id}` }, 400);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
   // DELETE a node and cascade-remove every connector with source === nodeId or
   // target === nodeId in the same atomic write. Final-ResolvedFlowSchema validation
   // is still run after the mutation — connector cascade closure means it
@@ -1165,6 +1214,44 @@ 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 addConnectorsBulkImpl({ registry, watcher }, 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/atomic-write.ts

@@ -0,0 +1,16 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+
+export const writeFileAtomic = (filePath: string, content: string): void => {
+  const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  try {
+    writeFileSync(tempPath, content);
+    renameSync(tempPath, filePath);
+  } catch (err) {
+    try {
+      if (existsSync(tempPath)) unlinkSync(tempPath);
+    } catch {
+      // best-effort cleanup
+    }
+    throw err;
+  }
+};