@tuongaz/seeflow 0.1.26 → 0.1.27

package/src/cli.ts

@@ -15,11 +15,11 @@ import {
   writeConfig,
   writePid,
 } from './runtime.ts';
-import { DemoSchema } from './schema.ts';
+import { ArchitectureSchema, FlowSchema } from './schema.ts';
 import { serve } from './server.ts';
 import { createStatusRunner } from './status-runner.ts';
 
-const DEFAULT_DEMO_PATH = '.seeflow/seeflow.json';
+const DEFAULT_ARCHITECTURE_PATH = '.seeflow/architecture.json';
 const HEALTH_TIMEOUT_MS = 10_000;
 const HEALTH_POLL_INTERVAL_MS = 150;
 
@@ -75,7 +75,7 @@ Options (start):
 Options (register):
   --path <dir>      Path to repo root (default: current directory)
   --flow <file>     Path to flow JSON, relative to repo root
-                    (default: .seeflow/seeflow.json)
+                    (default: .seeflow/architecture.json)
   --no-start        Fail if studio is not already running
 
 Examples:
@@ -140,7 +140,7 @@ async function seedExamples(registry: Registry) {
 
 async function seedExample(registry: Registry, exampleName: string) {
   const destDir = join(seeflowHome(), exampleName);
-  const demoPath = '.seeflow/seeflow.json';
+  const architecturePath = '.seeflow/architecture.json';
 
   // Always sync from source so that schema changes and example updates are
   // reflected on every startup, even when the dest directory already exists.
@@ -148,9 +148,9 @@ async function seedExample(registry: Registry, exampleName: string) {
   if (!existsSync(srcDir)) return;
   cpSync(srcDir, destDir, { recursive: true });
 
-  if (registry.getByRepoPathAndDemoPath(destDir, demoPath)) return;
+  if (registry.getByRepoPathAndArchitecturePath(destDir, architecturePath)) return;
 
-  const flowFile = join(destDir, demoPath);
+  const flowFile = join(destDir, architecturePath);
   if (!existsSync(flowFile)) return;
 
   let demo: unknown;
@@ -160,10 +160,10 @@ async function seedExample(registry: Registry, exampleName: string) {
     return;
   }
 
-  const parsed = DemoSchema.safeParse(demo);
+  const parsed = ArchitectureSchema.safeParse(demo);
   if (!parsed.success) return;
 
-  registry.upsert({ name: parsed.data.name, repoPath: destDir, demoPath });
+  registry.upsert({ name: parsed.data.name, repoPath: destDir, architecturePath });
   console.log(`Seeded example: ${parsed.data.name} → ${destDir}`);
 }
 
@@ -217,7 +217,7 @@ function runStop() {
 
 async function runRegister() {
   const repoPath = resolve(flagValue('path') ?? '.');
-  const demoPathArg = flagValue('flow') ?? DEFAULT_DEMO_PATH;
+  const demoPathArg = flagValue('flow') ?? DEFAULT_ARCHITECTURE_PATH;
   const noStart = hasFlag('no-start');
   const config = readConfig();
   const overrideUrl = process.env.SEEFLOW_STUDIO_URL?.replace(/\/+$/, '');
@@ -226,7 +226,7 @@ async function runRegister() {
   const fullPath = isAbsolute(demoPathArg) ? demoPathArg : join(repoPath, demoPathArg);
   if (!existsSync(fullPath)) {
     console.error(`No demo file at ${fullPath}`);
-    console.error(`Create ${DEFAULT_DEMO_PATH} in your repo, or pass --flow <path>.`);
+    console.error(`Create ${DEFAULT_ARCHITECTURE_PATH} in your repo, or pass --flow <path>.`);
     process.exit(1);
   }
 
@@ -238,7 +238,7 @@ async function runRegister() {
     process.exit(1);
   }
 
-  const parsed = DemoSchema.safeParse(demo);
+  const parsed = ArchitectureSchema.safeParse(demo);
   if (!parsed.success) {
     console.error(`${fullPath} failed schema validation:`);
     for (const issue of parsed.error.issues) {
@@ -251,13 +251,13 @@ async function runRegister() {
 
   let res: Response;
   try {
-    res = await fetch(`${url}/api/demos/register`, {
+    res = await fetch(`${url}/api/flows/register`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({
         name: parsed.data.name,
         repoPath,
-        demoPath: demoPathArg,
+        architecturePath: demoPathArg,
       }),
     });
   } catch (err) {

package/src/demo.ts

@@ -11,7 +11,7 @@ const delay = (): Promise<void> => new Promise((r) => setTimeout(r, 200 + Math.r
 
 function nodeEmit(
   events: EventBus,
-  demoId: string,
+  flowId: string,
   runId: string,
   nodeId: string,
   status: keyof typeof STATUS_TO_EVENT,
@@ -19,17 +19,17 @@ function nodeEmit(
 ) {
   events.broadcast({
     type: STATUS_TO_EVENT[status],
-    demoId,
+    flowId,
     payload: { nodeId, runId, ...payload },
   });
 }
 
-async function runOrderPipeline(events: EventBus, demoId: string, runId: string, orderId: string) {
+async function runOrderPipeline(events: EventBus, flowId: string, runId: string, orderId: string) {
   const emit = (
     nodeId: string,
     status: keyof typeof STATUS_TO_EVENT,
     payload?: Record<string, unknown>,
-  ) => nodeEmit(events, demoId, runId, nodeId, status, payload);
+  ) => nodeEmit(events, flowId, runId, nodeId, status, payload);
 
   emit('post-orders', 'running');
   await delay();
@@ -52,11 +52,11 @@ export function createDemoRouter(events: EventBus): Hono {
   const app = new Hono();
 
   app.post('/orders', async (c) => {
-    const demoId = c.req.header('x-seeflow-demo-id') ?? '';
+    const flowId = c.req.header('x-seeflow-demo-id') ?? '';
     const runId = c.req.header('x-seeflow-run-id') ?? '';
     const orderId = `ord_${Date.now()}`;
 
-    void runOrderPipeline(events, demoId, runId, orderId);
+    void runOrderPipeline(events, flowId, runId, orderId);
 
     return c.json({ orderId });
   });

package/src/diagram.ts

@@ -1,6 +1,6 @@
 import dagre from 'dagre';
 import { z } from 'zod';
-import { DemoSchema } from './schema.ts';
+import { FlowSchema } from './schema.ts';
 
 // Pure-compute helpers backing the three diagram-pipeline endpoints. No file
 // I/O lives here — the skill writes responses to disk on the user's machine.
@@ -137,7 +137,7 @@ export interface AssembleStats {
 
 export interface AssembleResult {
   demo: {
-    version: 1;
+    version: 2;
     name: string;
     nodes: Array<Record<string, unknown>>;
     connectors: Array<Record<string, unknown>>;
@@ -177,7 +177,7 @@ export const assembleDemo = (req: AssembleRequest): AssembleResult => {
 
   return {
     demo: {
-      version: 1,
+      version: 2,
       name: req.wiring.name ?? 'Untitled diagram',
       nodes: positionedNodes,
       connectors,
@@ -364,7 +364,7 @@ export const validateDemo = (req: ValidateRequest): ValidateReport => {
   const issues: ValidateIssue[] = [];
   const warnings: ValidateIssue[] = [];
 
-  const parsed = DemoSchema.safeParse(req.demo);
+  const parsed = FlowSchema.safeParse(req.demo);
   if (!parsed.success) {
     for (const issue of parsed.error.issues) {
       issues.push({

package/src/events.ts

@@ -1,11 +1,11 @@
 /**
- * In-memory pub/sub keyed by demoId. Subscribers receive every event published
+ * In-memory pub/sub keyed by flowId. Subscribers receive every event published
  * for that demo until they unsubscribe; subscribers for other demos are not
  * notified.
  */
 
 export type StudioEventType =
-  | 'demo:reload'
+  | 'flow:reload'
   | 'demo:reset'
   | 'node:running'
   | 'node:done'
@@ -15,7 +15,7 @@ export type StudioEventType =
 
 export interface StudioEvent {
   type: StudioEventType;
-  demoId: string;
+  flowId: string;
   /** Arbitrary JSON-serializable payload. Shape depends on event type. */
   payload: unknown;
   /** Server-side timestamp (ms since epoch). */
@@ -26,33 +26,33 @@ export type Subscriber = (event: StudioEvent) => void;
 
 export interface EventBus {
   /** Subscribe to events for a specific demo. Returns an unsubscribe fn. */
-  subscribe(demoId: string, fn: Subscriber): () => void;
-  /** Broadcast an event to all subscribers of `demoId`. */
+  subscribe(flowId: string, fn: Subscriber): () => void;
+  /** Broadcast an event to all subscribers of `flowId`. */
   broadcast(event: Omit<StudioEvent, 'ts'> & { ts?: number }): void;
   /** Number of active subscribers for a given demo (used in tests). */
-  subscriberCount(demoId: string): number;
+  subscriberCount(flowId: string): number;
 }
 
 export function createEventBus(): EventBus {
   const subs = new Map<string, Set<Subscriber>>();
 
   return {
-    subscribe(demoId, fn) {
-      let set = subs.get(demoId);
+    subscribe(flowId, fn) {
+      let set = subs.get(flowId);
       if (!set) {
         set = new Set();
-        subs.set(demoId, set);
+        subs.set(flowId, set);
       }
       set.add(fn);
       return () => {
-        const current = subs.get(demoId);
+        const current = subs.get(flowId);
         if (!current) return;
         current.delete(fn);
-        if (current.size === 0) subs.delete(demoId);
+        if (current.size === 0) subs.delete(flowId);
       };
     },
     broadcast(event) {
-      const set = subs.get(event.demoId);
+      const set = subs.get(event.flowId);
       if (!set) return;
       const full: StudioEvent = { ...event, ts: event.ts ?? Date.now() };
       for (const fn of set) {
@@ -63,8 +63,8 @@ export function createEventBus(): EventBus {
         }
       }
     },
-    subscriberCount(demoId) {
-      return subs.get(demoId)?.size ?? 0;
+    subscriberCount(flowId) {
+      return subs.get(flowId)?.size ?? 0;
     },
   };
 }

package/src/file-ref.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+
+const FILE_PREFIX = 'file://';
+
+const isCleanRelativePath = (p: string): boolean => {
+  if (p.length === 0) return false;
+  if (p.startsWith('/') || p.startsWith('\\')) return false;
+  if (/^[A-Za-z]:[\\/]/.test(p)) return false;
+  const segments = p.split(/[\\/]/);
+  return !segments.some((seg) => seg === '..');
+};
+
+const invalidMarker = (rawPath: string) => `[seeflow: invalid file:// path '${rawPath}']`;
+const missingMarker = (rawPath: string) => `[seeflow: missing file '${rawPath}']`;
+
+/**
+ * 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.
+ *
+ * Returns the mutated tree plus the sorted, de-duplicated list of relative
+ * paths that resolved cleanly (the watcher tracks these for live reload).
+ */
+export function resolveFileRefs(
+  raw: unknown,
+  seeflowRoot: string,
+): { resolved: unknown; refs: string[] } {
+  const refs = new Set<string>();
+  let seeflowRealRoot: string;
+  try {
+    seeflowRealRoot = existsSync(seeflowRoot) ? realpathSync(seeflowRoot) : seeflowRoot;
+  } catch {
+    seeflowRealRoot = seeflowRoot;
+  }
+
+  const resolveString = (s: string): string => {
+    if (!s.startsWith(FILE_PREFIX)) return s;
+    const relPath = s.slice(FILE_PREFIX.length);
+    if (!isCleanRelativePath(relPath)) return invalidMarker(relPath);
+
+    const abs = join(seeflowRoot, relPath);
+    if (!existsSync(abs)) return missingMarker(relPath);
+
+    // Symlink-escape defense: resolve realpath and confirm it stays inside root.
+    let realAbs: string;
+    try {
+      realAbs = realpathSync(abs);
+    } catch {
+      return missingMarker(relPath);
+    }
+    const rel = relative(seeflowRealRoot, realAbs);
+    if (rel.startsWith('..') || isAbsolute(rel)) return invalidMarker(relPath);
+
+    try {
+      const content = readFileSync(realAbs, 'utf8');
+      refs.add(relPath);
+      return content;
+    } catch {
+      return missingMarker(relPath);
+    }
+  };
+
+  const walk = (node: unknown): unknown => {
+    if (typeof node === 'string') return resolveString(node);
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === 'object') {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+        out[k] = walk(v);
+      }
+      return out;
+    }
+    return node;
+  };
+
+  const resolved = walk(raw);
+  return { resolved, refs: [...refs].sort() };
+}