@tuongaz/seeflow 0.1.57 → 0.1.63

package/examples/ecommerce-platform/{.seeflow/flow.json → flow.json}

@@ -16,7 +16,6 @@
       "type": "playNode",
       "data": {
         "name": "API Gateway",
-        "kind": "gateway",
         "stateSource": {
           "kind": "request"
         },
@@ -25,9 +24,7 @@
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
-          "args": [
-            "run"
-          ],
+          "args": ["run"],
           "scriptPath": "scripts/play.ts"
         }
       }
@@ -37,7 +34,6 @@
       "type": "stateNode",
       "data": {
         "name": "Auth Service",
-        "kind": "service",
         "stateSource": {
           "kind": "request"
         },
@@ -50,7 +46,6 @@
       "type": "stateNode",
       "data": {
         "name": "Product Catalog",
-        "kind": "service",
         "stateSource": {
           "kind": "request"
         },
@@ -63,7 +58,6 @@
       "type": "playNode",
       "data": {
         "name": "Cart Service",
-        "kind": "service",
         "stateSource": {
           "kind": "request"
         },
@@ -72,9 +66,7 @@
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
-          "args": [
-            "run"
-          ],
+          "args": ["run"],
           "scriptPath": "scripts/play.ts"
         }
       }
@@ -84,7 +76,6 @@
       "type": "playNode",
       "data": {
         "name": "Order Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -93,9 +84,7 @@
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
-          "args": [
-            "run"
-          ],
+          "args": ["run"],
           "scriptPath": "scripts/play.ts"
         }
       }
@@ -105,7 +94,6 @@
       "type": "stateNode",
       "data": {
         "name": "Payment Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -118,7 +106,6 @@
       "type": "stateNode",
       "data": {
         "name": "Notification Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -149,7 +136,6 @@
       "id": "conn-4XKU3GcGPF",
       "source": "node-cQOUPXanaX",
       "target": "node-CbwYqb7NfB",
-      "kind": "http",
       "method": "POST",
       "label": "REST API"
     },
@@ -157,7 +143,6 @@
       "id": "conn-OxNUxp7qB3",
       "source": "node-CbwYqb7NfB",
       "target": "node-3zFtHg6ENc",
-      "kind": "http",
       "method": "POST",
       "label": "POST /auth"
     },
@@ -165,7 +150,6 @@
       "id": "conn-7HlJF6KVHx",
       "source": "node-CbwYqb7NfB",
       "target": "node-kwBY8YPmYM",
-      "kind": "http",
       "method": "GET",
       "label": "GET /products"
     },
@@ -173,7 +157,6 @@
       "id": "conn-ORfUTiooia",
       "source": "node-CbwYqb7NfB",
       "target": "node-5F424NWbEu",
-      "kind": "http",
       "method": "POST",
       "label": "POST /cart"
     },
@@ -181,7 +164,6 @@
       "id": "conn-EABXtQv89M",
       "source": "node-5F424NWbEu",
       "target": "node-yKrg9DV5fJ",
-      "kind": "event",
       "eventName": "cart.checkout",
       "label": "cart.checkout"
     },
@@ -189,7 +171,6 @@
       "id": "conn-kjyg3RDDvu",
       "source": "node-yKrg9DV5fJ",
       "target": "node-mPqan8rFYN",
-      "kind": "event",
       "eventName": "order.created",
       "label": "order.created"
     },
@@ -197,7 +178,6 @@
       "id": "conn-wqFq0shXO5",
       "source": "node-mPqan8rFYN",
       "target": "node-fkptXw7uvs",
-      "kind": "event",
       "eventName": "payment.captured",
       "label": "payment.captured"
     },
@@ -205,7 +185,6 @@
       "id": "conn-8ftFXZvD4r",
       "source": "node-yKrg9DV5fJ",
       "target": "node-5SDiw3Wz6s",
-      "kind": "http",
       "method": "POST",
       "label": "read/write"
     },
@@ -213,7 +192,6 @@
       "id": "conn-VTfjsOckF2",
       "source": "node-mPqan8rFYN",
       "target": "node-5SDiw3Wz6s",
-      "kind": "http",
       "method": "POST",
       "label": "read/write"
     }

package/examples/ecommerce-platform/{.seeflow/scripts → scripts}/play.ts

@@ -1,2 +1,2 @@
 // Placeholder — wire up to your running app to make this demo playable.
-console.log("play triggered");
+console.log('play triggered');

package/examples/order-pipeline/{.seeflow/flow.json → flow.json}

@@ -7,7 +7,6 @@
       "type": "playNode",
       "data": {
         "name": "POST /orders",
-        "kind": "service",
         "stateSource": {
           "kind": "request"
         },
@@ -16,9 +15,7 @@
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
-          "args": [
-            "run"
-          ],
+          "args": ["run"],
           "scriptPath": "scripts/play.ts"
         }
       }
@@ -28,7 +25,6 @@
       "type": "stateNode",
       "data": {
         "name": "Inventory Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -42,7 +38,6 @@
       "type": "stateNode",
       "data": {
         "name": "Payment Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -55,7 +50,6 @@
       "type": "stateNode",
       "data": {
         "name": "Fulfillment Service",
-        "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
@@ -69,7 +63,6 @@
       "id": "conn-jJjuWBfe3a",
       "source": "node-XKIyds0TDg",
       "target": "node-GXTKUcE3ye",
-      "kind": "event",
       "eventName": "order.created",
       "label": "order.created"
     },
@@ -77,7 +70,6 @@
       "id": "conn-8DkPOzrnYo",
       "source": "node-GXTKUcE3ye",
       "target": "node-YOYiHJpY0i",
-      "kind": "event",
       "eventName": "stock.reserved",
       "label": "stock.reserved"
     },
@@ -85,7 +77,6 @@
       "id": "conn-qp90Rd2cgw",
       "source": "node-YOYiHJpY0i",
       "target": "node-zUIH7WFnhK",
-      "kind": "event",
       "eventName": "payment.captured",
       "label": "payment.captured"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.57",
+  "version": "0.1.63",
   "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

@@ -37,8 +37,10 @@ import {
   stopAllPlays as defaultStopAllPlays,
 } from './proxy.ts';
 import type { Registry } from './registry.ts';
+import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
 import { FlowSchema, ResolvedFlowSchema } from './schema.ts';
 import { type Spawner, defaultSpawner } from './shellout.ts';
+import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import type { StatusRunner } from './status-runner.ts';
 import { readMergedFlow } from './watcher.ts';
 import type { FlowWatcher } from './watcher.ts';
@@ -76,14 +78,14 @@ const EMIT_STATUS_TO_EVENT = {
 const FilePathBodySchema = z.object({ path: z.string() });
 
 type ResolvedProjectFile =
-  | { kind: 'ok'; absPath: string; seeflowRoot: string }
+  | { kind: 'ok'; absPath: string; projectRoot: string }
   | { kind: 'unknownProject' }
   | { kind: 'invalidPath'; reason: string }
   | { kind: 'fileMissing'; absPath: string };
 
 // Shared path-safety + filesystem resolution for project-scoped file routes.
 // Performs textual rejection of absolute paths / `..` traversal, then layered
-// realpath verification that the resolved file stays inside `<project>/.seeflow/`
+// realpath verification that the resolved file stays inside the project root
 // (defense against symlink escapes). Returns the realpath of an existing file
 // on success, or `fileMissing` with the would-be absolute path so callers can
 // soft-fail with that path included for clipboard fallback.
@@ -98,15 +100,15 @@ function resolveProjectFile(
   const guard = validateRelativePath(relPath);
   if (guard.kind === 'invalid') return { kind: 'invalidPath', reason: guard.reason };
 
-  const seeflowRoot = join(entry.repoPath, '.seeflow');
+  const projectRoot = entry.repoPath;
   let realRoot: string;
   try {
-    realRoot = realpathSync(seeflowRoot);
+    realRoot = realpathSync(projectRoot);
   } catch {
-    return { kind: 'fileMissing', absPath: resolve(seeflowRoot, relPath) };
+    return { kind: 'fileMissing', absPath: resolve(projectRoot, relPath) };
   }
 
-  const target = resolve(seeflowRoot, relPath);
+  const target = resolve(projectRoot, relPath);
   let realTarget: string;
   try {
     realTarget = realpathSync(target);
@@ -119,7 +121,7 @@ function resolveProjectFile(
     return { kind: 'invalidPath', reason: 'path escapes project root' };
   }
 
-  return { kind: 'ok', absPath: realTarget, seeflowRoot: realRoot };
+  return { kind: 'ok', absPath: realTarget, projectRoot: realRoot };
 }
 
 // Allowed extensions for /nodes/:nodeId/files/upload. Lowercased; matched after dropping the
@@ -174,8 +176,6 @@ export interface ApiOptions {
    *  Tests use this to record call order across runPlay / runReset /
    *  stopAllPlays and to drive each in isolation. */
   proxy?: ProxyFacade;
-  /** Override base directory for new projects. Defaults to ~/.seeflow. Tests inject a tmp dir. */
-  projectBaseDir?: string;
 }
 
 /**
@@ -203,8 +203,7 @@ export function createApi(options: ApiOptions): Hono {
   const platform = options.platform ?? process.platform;
   const processSpawner = options.processSpawner;
   const proxy = options.proxy ?? defaultProxyFacade;
-  const projectBaseDir = options.projectBaseDir;
-  const ops = createOperations({ registry, watcher, projectBaseDir });
+  const ops = createOperations({ registry, watcher });
   const api = new Hono();
 
   api.post('/flows/register', async (c) => {
@@ -230,15 +229,6 @@ export function createApi(options: ApiOptions): Hono {
         return c.json({ error: 'Flow file is not valid JSON', detail: result.detail }, 400);
       case 'badSchema':
         return c.json({ error: 'Flow file failed schema validation', issues: result.issues }, 400);
-      case 'sdkWriteFailed':
-        return c.json(
-          {
-            error: `Failed to write SDK helper: ${result.message}`,
-            id: result.id,
-            slug: result.slug,
-          },
-          500,
-        );
     }
   });
 
@@ -298,8 +288,8 @@ export function createApi(options: ApiOptions): Hono {
   // POST /api/diagram/assemble — Phase 7a. The skill POSTs wiring + layout
   // and gets back the assembled demo (IDs normalized, dupes dropped, dangling
   // connectors removed, positions snapped to a 24px grid). Pure compute; the
-  // skill writes the response to $TARGET/.seeflow/flow.json. No schema
-  // validation here — call /demos/validate for that.
+  // skill writes the response to $TARGET/flow.json. No schema validation
+  // here — call /demos/validate for that.
   api.post('/diagram/assemble', async (c) => {
     let body: unknown;
     try {
@@ -413,17 +403,11 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ error: 'Body must be { flow, options? } or { nodes, edges, options? }' }, 400);
   });
 
-  // POST /api/projects — UI-driven "Create new project" flow (US-020). Two
-  // branches based on whether the target folder already has a SeeFlow
-  // project set up at `<folderPath>/.seeflow/flow.json`:
-  //   1. Existing setup: read + validate the on-disk demo and register it
-  //      as-is (no overwrite, no scaffolding). The user-supplied `name`
-  //      becomes the registry display name; the on-disk demo's `name` is
-  //      preserved on disk.
-  //   2. Fresh scaffold: mkdir -p the folder + .seeflow/, write a default
-  //      scaffold flow.json keyed off `name`, and run the same SDK-emit
-  //      helper write the CLI register flow uses (a no-op for an empty
-  //      scaffold, but kept for parity).
+  // POST /api/projects — UI-driven "Create new project" flow (US-020).
+  // Scaffolds `<path>/flow.json` with the supplied name + optional
+  // description, then registers it. If the target already has a
+  // `flow.json`, returns 409 — callers should use POST /api/flows/register
+  // instead.
   api.post('/projects', async (c) => {
     let body: unknown;
     try {
@@ -441,20 +425,65 @@ export function createApi(options: ApiOptions): Hono {
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
-      case 'badJson':
-        return c.json({ error: `Existing demo file is not valid JSON: ${result.detail}` }, 400);
-      case 'badSchema':
-        return c.json(
-          { error: 'Existing demo file failed schema validation', issues: result.issues },
-          400,
-        );
+      case 'alreadyExists':
+        return c.json({ error: `Project already exists at ${result.path}` }, 409);
       case 'scaffoldFailed':
         return c.json({ error: `Failed to scaffold project: ${result.message}` }, 500);
-      case 'sdkWriteFailed':
-        return c.json({ error: `Failed to write SDK helper: ${result.message}` }, 500);
     }
   });
 
+  // GET /api/schema — index of categories the skill / agents can introspect.
+  // Mirrors `seeflow schema` and the `seeflow_schema` MCP tool. Drill in via
+  // GET /api/schema/:name for the full JSON Schema(s) + invariant notes.
+  api.get('/schema', (c) => c.json({ ok: true as const, categories: listSchemaCategories() }));
+
+  api.get('/schema/:name', (c) => {
+    const name = c.req.param('name');
+    const payload = getSchemaCategory(name);
+    if (!payload) {
+      return c.json(
+        { error: `unknown schema category: ${name}`, available: schemaCategoryNames() },
+        404,
+      );
+    }
+    return c.json({ ok: true as const, name, schemas: payload.schemas, notes: payload.notes });
+  });
+
+  // GET /api/ids/:type/:count — batch-mint canonical short ids. Mirrors
+  // `seeflow ids <type> <count>` and the `seeflow_ids` MCP tool. Pure compute,
+  // no state read, no studio side effects. Same alphabet, length, and
+  // rejection-sampling as every other id producer (operations.ts, canvas,
+  // upload regex), so generated ids match wherever they're inserted.
+  api.get('/ids/:type/:count', (c) => {
+    const type = c.req.param('type');
+    if (!isIdType(type)) {
+      return c.json(
+        {
+          ok: false as const,
+          error: `invalid type: ${type} (expected one of: ${ID_TYPES.join(', ')})`,
+        },
+        400,
+      );
+    }
+    const rawCount = c.req.param('count');
+    const count = Number.parseInt(rawCount, 10);
+    if (
+      !Number.isFinite(count) ||
+      String(count) !== rawCount ||
+      count < 1 ||
+      count > MAX_ID_COUNT
+    ) {
+      return c.json(
+        {
+          ok: false as const,
+          error: `invalid count: ${rawCount} (expected an integer in [1, ${MAX_ID_COUNT}])`,
+        },
+        400,
+      );
+    }
+    return c.json({ ok: true as const, ids: generateIds(type, count) });
+  });
+
   api.get('/flows', (c) => {
     const result = ops.listFlows();
     return c.json(result.data);
@@ -517,9 +546,9 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // GET /api/projects/:id/files/<path> — stream a project-scoped file from
-  // <repoPath>/.seeflow/<path>. Path safety is layered: textual rejection
-  // (absolute / traversal), then realpath check that the resolved file stays
-  // inside the project's .seeflow root (defends against symlink escapes).
+  // <repoPath>/<path>. Path safety is layered: textual rejection (absolute /
+  // traversal), then realpath check that the resolved file stays inside the
+  // project root (defends against symlink escapes).
   api.get('/projects/:id/files/:path{.+}', async (c) => {
     const rawPath = c.req.param('path');
     let relPath: string;
@@ -643,11 +672,11 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // 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.
+  // image upload and persist it under `<project>/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');
@@ -682,7 +711,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'invalid filename or extension' }, 400);
     }
 
-    const nodeDir = join(entry.repoPath, '.seeflow', 'nodes', nodeId);
+    const nodeDir = join(entry.repoPath, 'nodes', nodeId);
     try {
       mkdirSync(nodeDir, { recursive: true });
     } catch (err) {
@@ -899,10 +928,9 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ ok: true, calledResetAction });
   });
 
-  // PATCH a single node's position back into the on-disk flow.json. This is
-  // the second (and only other) place the studio mutates user files — the
-  // first being the SDK helper write in `register`. Atomic write via tempfile
-  // + rename keeps editor diffs clean and avoids corruption mid-write.
+  // PATCH a single node's position back into the on-disk flow.json. Atomic
+  // write via tempfile + rename keeps editor diffs clean and avoids
+  // corruption mid-write.
   api.patch('/flows/:id/nodes/:nodeId/position', async (c) => {
     const id = c.req.param('id');
     const nodeId = c.req.param('nodeId');

package/src/cli-helpers.ts

@@ -62,8 +62,9 @@ export function printError(message: string, opts: CliOutcomeOptions = {}): never
  *  - kind === 'badSchema'|'badJson'                   → exit 2
  *  - kind === 'notFound'|'flowNotFound'|'fileNotFound'|
  *             'unknownNode'|'unknownConnector'        → exit 3
- *  - kind === 'duplicateIdInBatch'|'idAlreadyExists'  → exit 4
- *  - kind === 'writeFailed'|'sdkWriteFailed'|'scaffoldFailed' → exit 5
+ *  - kind === 'duplicateIdInBatch'|'idAlreadyExists'|
+ *             'alreadyExists'                          → exit 4
+ *  - kind === 'writeFailed'|'scaffoldFailed' → exit 5
  *  - anything else                                    → exit 1
  *
  * The error message mirrors the strings used by api.ts so the CLI's
@@ -121,10 +122,10 @@ function describeOutcome(outcome: { kind: string } & Record<string, unknown>): s
             : 'Id already exists';
       return `${prefix}: ${String(outcome.id ?? '')}`;
     }
+    case 'alreadyExists':
+      return `Project already exists at ${String(outcome.path ?? '')}`;
     case 'writeFailed':
       return `Failed to write demo file: ${String(outcome.message ?? '')}`;
-    case 'sdkWriteFailed':
-      return `Failed to write SDK helper: ${String(outcome.message ?? '')}`;
     case 'scaffoldFailed':
       return `Failed to scaffold project: ${String(outcome.message ?? '')}`;
     default:
@@ -142,8 +143,8 @@ export const EXIT_CODE_BY_KIND: Record<string, number> = {
   unknownConnector: 3,
   duplicateIdInBatch: 4,
   idAlreadyExists: 4,
+  alreadyExists: 4,
   writeFailed: 5,
-  sdkWriteFailed: 5,
   scaffoldFailed: 5,
 };