@tuongaz/seeflow 0.1.42 → 0.1.47

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

@@ -12,7 +12,7 @@
           "kind": "request"
         },
         "description": "Creates order, kicks off the pipeline.",
-        "detail": "file://nodes/node-XKIyds0TDg/detail.md",
+        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -33,7 +33,7 @@
           "kind": "event"
         },
         "description": "Reserves stock.",
-        "detail": "file://nodes/node-GXTKUcE3ye/detail.md",
+        "detail": "file://detail.md",
         "icon": "a-arrow-down-icon"
       }
     },
@@ -47,7 +47,7 @@
           "kind": "event"
         },
         "description": "Charges card.",
-        "detail": "file://nodes/node-YOYiHJpY0i/detail.md"
+        "detail": "file://detail.md"
       }
     },
     {
@@ -60,7 +60,7 @@
           "kind": "event"
         },
         "description": "Enqueues shipment.",
-        "detail": "file://nodes/node-zUIH7WFnhK/detail.md"
+        "detail": "file://detail.md"
       }
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.42",
+  "version": "0.1.47",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",
@@ -49,6 +49,7 @@
     "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@tailwindcss/browser": "^4.3.0",
     "@types/bun": "^1.1.14",
     "typescript": "^5.6.3"

package/src/cli-e2e.ts

@@ -63,7 +63,7 @@ interface NodeShape {
   };
 }
 
-interface DemoShape {
+interface FlowBody {
   nodes?: NodeShape[];
 }
 
@@ -71,7 +71,11 @@ interface FlowGetResponse {
   id?: string;
   valid?: boolean;
   error?: string | null;
-  demo?: DemoShape | null;
+  // GET /api/flows/:id returns the resolved flow under the `flow` key (see
+  // FlowGetResponse in operations.ts). Older versions of this file used `demo`,
+  // which left the validator effectively broken (every call returned `ok:false`
+  // with "demo not valid"). Renamed to match the wire format.
+  flow?: FlowBody | null;
 }
 
 interface SseEvent {
@@ -200,21 +204,21 @@ export async function validateEndToEnd(options: ValidateOptions): Promise<Valida
     };
   }
   const demoData = (await demoRes.json()) as FlowGetResponse;
-  if (!demoData.valid || !demoData.demo) {
+  if (!demoData.valid || !demoData.flow) {
     return {
       ok: false,
       plays,
       statuses,
       skipped: [
         {
-          nodeId: '<demo>',
-          reason: `demo not valid: ${demoData.error ?? '<no error>'}`,
+          nodeId: '<flow>',
+          reason: `flow not valid: ${demoData.error ?? '<no error>'}`,
         },
       ],
     };
   }
 
-  const nodes = demoData.demo.nodes ?? [];
+  const nodes = demoData.flow.nodes ?? [];
 
   const skipSet = new Set(options.skipNodes ?? []);
   const playTargets: string[] = [];

package/src/file-ref.ts

@@ -14,13 +14,18 @@ const isCleanRelativePath = (p: string): boolean => {
 const invalidMarker = (rawPath: string) => `[seeflow: invalid file:// path '${rawPath}']`;
 const missingMarker = (rawPath: string) => `[seeflow: missing file '${rawPath}']`;
 
+const looksLikeFlowNode = (obj: Record<string, unknown>): obj is { id: string; data: object } =>
+  typeof obj.id === 'string' && obj.data !== null && typeof obj.data === 'object';
+
 /**
  * Resolve every `file://<relative-path>` string in `raw` by reading the file
- * under `<seeflowRoot>` and substituting its UTF-8 content. Missing or invalid
- * paths are replaced with placeholder markers so schema parse still succeeds.
+ * under `<seeflowRoot>/nodes/<nodeId>/` (node-relative) and substituting its
+ * UTF-8 content. Strings outside any enclosing flow node are treated as
+ * invalid — every supported file:// ref currently lives inside `node.data`.
  *
- * Returns the mutated tree plus the sorted, de-duplicated list of relative
- * paths that resolved cleanly (the watcher tracks these for live reload).
+ * Returns the mutated tree plus the sorted, de-duplicated list of seeflow-root-relative
+ * paths that resolved cleanly (the watcher tracks these for live reload, so the
+ * external contract uses `nodes/<id>/<file>` even though the source string is short).
  */
 export function resolveFileRefs(
   raw: unknown,
@@ -34,46 +39,52 @@ export function resolveFileRefs(
     seeflowRealRoot = seeflowRoot;
   }
 
-  const resolveString = (s: string): string => {
+  const resolveString = (s: string, nodeId: string | null): string => {
     if (!s.startsWith(FILE_PREFIX)) return s;
     const relPath = s.slice(FILE_PREFIX.length);
     if (!isCleanRelativePath(relPath)) return invalidMarker(relPath);
+    if (nodeId === null) return invalidMarker(relPath);
 
-    const abs = join(seeflowRoot, relPath);
-    if (!existsSync(abs)) return missingMarker(relPath);
+    const seeflowRelPath = `nodes/${nodeId}/${relPath}`;
+    const abs = join(seeflowRoot, seeflowRelPath);
+    if (!existsSync(abs)) return missingMarker(seeflowRelPath);
 
     // Symlink-escape defense: resolve realpath and confirm it stays inside root.
     let realAbs: string;
     try {
       realAbs = realpathSync(abs);
     } catch {
-      return missingMarker(relPath);
+      return missingMarker(seeflowRelPath);
     }
     const rel = relative(seeflowRealRoot, realAbs);
     if (rel.startsWith('..') || isAbsolute(rel)) return invalidMarker(relPath);
 
     try {
       const content = readFileSync(realAbs, 'utf8');
-      refs.add(relPath);
+      refs.add(seeflowRelPath);
       return content;
     } catch {
-      return missingMarker(relPath);
+      return missingMarker(seeflowRelPath);
     }
   };
 
-  const walk = (node: unknown): unknown => {
-    if (typeof node === 'string') return resolveString(node);
-    if (Array.isArray(node)) return node.map(walk);
+  const walk = (node: unknown, nodeId: string | null): unknown => {
+    if (typeof node === 'string') return resolveString(node, nodeId);
+    if (Array.isArray(node)) return node.map((v) => walk(v, nodeId));
     if (node && typeof node === 'object') {
+      const obj = node as Record<string, unknown>;
+      // Entering a flow node carves out a new resolution context for its subtree:
+      // any file:// inside `data` now resolves relative to nodes/<id>/.
+      const childNodeId = looksLikeFlowNode(obj) ? obj.id : nodeId;
       const out: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
-        out[k] = walk(v);
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = walk(v, childNodeId);
       }
       return out;
     }
     return node;
   };
 
-  const resolved = walk(raw);
+  const resolved = walk(raw, null);
   return { resolved, refs: [...refs].sort() };
 }

package/src/node-files.ts

@@ -29,8 +29,11 @@ export type ExternalizedFieldName = (typeof EXTERNALIZED_NODE_FIELDS)[number]['f
 export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
   `nodes/${nodeId}/${fileName}`;
 
-export const nodeFileRef = (nodeId: string, fileName: string): string =>
-  `file://${nodeFileRelPath(nodeId, fileName)}`;
+// Node-relative ref: the resolver knows the enclosing node id from the flow.json
+// shape (nodes[i].id), so the on-disk string only needs the filename. Kept as a
+// 2-arg helper so call sites don't change shape and the spec stays explicit
+// that the file lives under the given node.
+export const nodeFileRef = (_nodeId: string, fileName: string): string => `file://${fileName}`;
 
 export const nodeFileAbsPath = (repoPath: string, nodeId: string, fileName: string): string =>
   join(repoPath, '.seeflow', nodeFileRelPath(nodeId, fileName));

package/src/operations.ts

@@ -658,13 +658,27 @@ export async function mutateMergedFlow<E extends { kind: string }>(
     return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  const snap: FlowSnapshot = {
-    flow: finalParse.data as ResolvedFlow,
-    valid: true,
-    error: null,
-    filePath: flowPath,
-    parsedAt: Date.now(),
-  };
+  // Re-read through readMergedFlow so the snapshot we hand to notifyWritten
+  // carries file://-resolved content (detail.md, view.html, …). The in-memory
+  // `merged` tree above still holds raw `file://<name>` strings — broadcasting
+  // it would clobber the watcher's resolved seed and ship unresolved refs to
+  // every SSE subscriber until the next reparse.
+  const reread = readMergedFlow(flowPath);
+  const snap: FlowSnapshot = reread.valid
+    ? {
+        flow: reread.flow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      }
+    : {
+        flow: finalParse.data as ResolvedFlow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      };
   return { kind: 'ok', snap, flowContent, styleContent };
 }