@tuongaz/seeflow 0.1.64 → 0.1.68

package/src/operations.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSyn
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
 import { writeFileAtomic } from './atomic-write.ts';
+import { inlineComponentSpecs } from './component-spec-resolver.ts';
 import { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
@@ -24,13 +25,14 @@ import {
 import type { Registry } from './registry.ts';
 import {
   ColorTokenSchema,
+  ComponentSpecSchema,
   EdgePinSchema,
   type Flow,
   FlowSchema,
+  NodeTypeSchema,
   PlayActionSchema,
   type ResolvedFlow,
   ResolvedFlowSchema,
-  ShapeKindSchema,
   SourceHandleIdSchema,
   StateSourceSchema,
   StatusActionSchema,
@@ -82,25 +84,16 @@ 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 `nodes/<id>/` is keyed by id, so retype keeps scripts,
-    // detail.md, and view.html attached.
+    // new type's required fields (e.g. type:'image' without a `path` in the
+    // same body surfaces as `badSchema`). The per-node folder under
+    // `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(),
@@ -114,22 +107,22 @@ export const NodePatchBodySchema = z
     cornerRadius: z.number().min(0).optional(),
     width: z.number().positive().optional(),
     height: z.number().positive().optional(),
-    // htmlNode-only: when true, the renderer measures content and React Flow
+    // type:'html'-only: when true, the renderer measures content and React Flow
     // sizes the wrapper around it. mergeNodeUpdates enforces the invariant
     // that autoSize:true never coexists with persisted width/height.
     autoSize: z.boolean().optional(),
-    shape: ShapeKindSchema.optional(),
-    // iconNode-only: stroke color token. Lands at data.color; ResolvedFlowSchema's
-    // post-merge reparse gates that this is only valid on an iconNode.
+    // type:'icon'-only: stroke color token. Lands at data.color; the
+    // post-merge ResolvedFlowSchema reparse gates that this is only valid on
+    // type:'icon'.
     color: ColorTokenSchema.optional(),
-    // iconNode-only: glyph stroke width. Lands at data.strokeWidth; the
+    // type:'icon'-only: glyph stroke width. Lands at data.strokeWidth; the
     // post-merge reparse gates the [0.5, 4] bound and arm validity.
     strokeWidth: z.number().min(0.5).max(4).optional(),
-    // iconNode-only: accessible alt text for the icon. Lands at data.alt.
+    // type:'icon'/type:'image'-only: accessible alt text. Lands at data.alt.
     alt: z.string().optional(),
     // kebab-case Lucide icon name. Lands at data.icon. The post-merge reparse
     // enforces the schema's `.min(1)` non-empty rule for nodes that require
-    // icon (iconNode), and gates which variants allow it. Explicit `null`
+    // icon (type:'icon'), and gates which variants allow it. Explicit `null`
     // clears the field (mergeNodeUpdates strips the key from disk) — mirrors
     // the empty-string clear convention used for description / detail.
     icon: z.string().min(1).nullable().optional(),
@@ -138,17 +131,24 @@ export const NodePatchBodySchema = z
     // serialize signal — `mergeNodeUpdates` strips the key from disk.
     description: z.string().optional(),
     detail: z.string().optional(),
-    // htmlNode-only: inline HTML content. Externalized to
+    // type:'html'-only: inline HTML content. Externalized to
     // `<project>/nodes/<id>/view.html` by patchNodeImpl; the file:// ref on
     // the node persists. Empty string empties the file but keeps the ref.
     html: z.string().optional(),
-    // P5 overlay attach: lets the skill (or any consumer) wire executable
-    // behaviour onto a previously-created node without re-issuing it. Final
-    // validity is enforced by the post-merge ResolvedFlowSchema reparse —
-    // e.g. statusAction is only valid on playNode / stateNode.
+    // Capability attach: lets the skill (or any consumer) wire executable
+    // behaviour onto a previously-created node without re-issuing it. All
+    // capabilities are valid on every node type — presence drives renderer
+    // chrome. Final validity is enforced by the post-merge
+    // ResolvedFlowSchema reparse.
     playAction: PlayActionSchema.optional(),
     statusAction: StatusActionSchema.optional(),
     stateSource: StateSourceSchema.optional(),
+    // type:'component'-only: json-render spec describing the reactive UI.
+    // Externalized to `<project>/nodes/<id>/spec.json` by patchNodeImpl; the
+    // in-memory ResolvedFlow keeps `data.spec` populated for the post-merge
+    // reparse + SSE broadcast, but splitFlow strips it from flow.json so the
+    // sidecar is the source of truth on disk.
+    spec: ComponentSpecSchema.optional(),
   })
   .strict();
 export type NodePatchBody = z.infer<typeof NodePatchBodySchema>;
@@ -170,7 +170,6 @@ const NODE_DATA_PATCH_KEYS = [
   'width',
   'height',
   'autoSize',
-  'shape',
   'color',
   'strokeWidth',
   'alt',
@@ -181,6 +180,7 @@ const NODE_DATA_PATCH_KEYS = [
   'playAction',
   'statusAction',
   'stateSource',
+  'spec',
 ] as const satisfies ReadonlyArray<keyof NodePatchBody>;
 
 const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e) => e.field));
@@ -190,35 +190,67 @@ const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e
 // 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)
+// fields on the new type (e.g. retype to type:'image' without a `path`)
 // surface as the normal `badSchema` outcome from the reparse.
+const GEOMETRIC_SEMANTIC_KEYS: ReadonlySet<string> = new Set([
+  'name',
+  'description',
+  'detail',
+  'icon',
+  'stateSource',
+  'handlerModule',
+  'playAction',
+  'statusAction',
+]);
+
 const SEMANTIC_KEYS_BY_TYPE: Record<z.infer<typeof NodeTypeSchema>, ReadonlySet<string>> = {
-  playNode: new Set([
+  rectangle: GEOMETRIC_SEMANTIC_KEYS,
+  ellipse: GEOMETRIC_SEMANTIC_KEYS,
+  sticky: GEOMETRIC_SEMANTIC_KEYS,
+  text: GEOMETRIC_SEMANTIC_KEYS,
+  database: GEOMETRIC_SEMANTIC_KEYS,
+  server: GEOMETRIC_SEMANTIC_KEYS,
+  user: GEOMETRIC_SEMANTIC_KEYS,
+  queue: GEOMETRIC_SEMANTIC_KEYS,
+  cloud: GEOMETRIC_SEMANTIC_KEYS,
+  image: new Set([
     'name',
-    'kind',
-    'stateSource',
-    'handlerModule',
-    'icon',
     'description',
     'detail',
+    'icon',
+    'stateSource',
+    'handlerModule',
     'playAction',
     'statusAction',
+    'path',
+    'alt',
   ]),
-  stateNode: new Set([
+  html: new Set([
     'name',
-    'kind',
+    'description',
+    'detail',
+    'icon',
     'stateSource',
     'handlerModule',
-    'icon',
+    'playAction',
+    'statusAction',
+    'html',
+  ]),
+  icon: new Set([
+    'name',
     'description',
     'detail',
+    'icon',
+    'stateSource',
+    'handlerModule',
     'playAction',
     'statusAction',
+    'alt',
   ]),
-  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']),
+  // Component nodes externalize `spec` to <project>/nodes/<id>/spec.json; the
+  // semantic-key set covers only the universal capability fields so retype
+  // never drags `spec` through `data`. (US-007 wires the sidecar writer.)
+  component: GEOMETRIC_SEMANTIC_KEYS,
 };
 
 // Visual data keys — routed to style.json on write by splitFlow. Kept here
@@ -288,7 +320,7 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
   // doesn't reject lingering fields. The per-node folder under
   // `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
+  // retype to type:'image' without a `path` in the same patch) surface as
   // `badSchema` from the ResolvedFlowSchema reparse.
   if (updates.type !== undefined && updates.type !== node.type) {
     node.type = updates.type;
@@ -302,12 +334,13 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
     }
   }
 
-  // htmlNode-only invariant enforcement:
+  // type:'html' + type:'component' invariant enforcement:
   //   autoSize === true ⊻ (width and height set).
   // autoSize: true is the dominant signal — it strips width/height even if
   // the same patch tried to write them. Writing width/height implicitly
-  // flips autoSize to false.
-  if (node.type === 'htmlNode') {
+  // flips autoSize to false. Both node types default to autoSize:true in the
+  // renderer and share the same shrink-wrap-to-content mechanism.
+  if (node.type === 'html' || node.type === 'component') {
     // The autoSize invariant requires `width`/`height` to be ABSENT from the
     // serialized JSON when autoSize is true — not present with value
     // `undefined` (which would serialize as a stray `"width": null` or get
@@ -389,7 +422,7 @@ export type GetFlowOutcome =
   | { kind: 'fileNotFound'; path: string };
 
 // Lightweight graph projection — flow + nodes + connectors with file-backed
-// fields (`detail` on every node, `html` on htmlNode) stripped so the
+// fields (`detail` on every node, `html` on type:'html') stripped so the
 // caller can navigate the topology without paying for inlined bodies.
 export interface FlowGraphResponse {
   id: string;
@@ -738,7 +771,16 @@ export async function mutateMergedFlow<E extends { kind: string }>(
   const styleParse = StyleSchema.safeParse(read.rawStyle);
   if (!styleParse.success) return { kind: 'badSchema', issues: styleParse.error.issues };
 
-  const merged = mergeFlowAndStyle(flowParse.data, styleParse.data) as unknown as {
+  // Inline component spec sidecars (<project>/nodes/<id>/spec.json) before the
+  // mutator runs so the post-mutation ResolvedFlowSchema parse sees `data.spec`
+  // on every existing component node. splitFlow strips `spec` back out before
+  // we write flow.json, keeping the sidecar as the on-disk source of truth.
+  const projectRoot = dirname(flowPath);
+  const { flow: inlinedFlow } = inlineComponentSpecs(
+    mergeFlowAndStyle(flowParse.data, styleParse.data),
+    projectRoot,
+  );
+  const merged = inlinedFlow as unknown as {
     version: number;
     name: string;
     resetAction?: unknown;
@@ -1141,6 +1183,9 @@ export async function createProjectImpl(
   try {
     mkdirSync(folderPath, { recursive: true });
     writeFileSync(demoFullPath, `${JSON.stringify(scaffold, null, 2)}\n`);
+    const tmpDir = join(folderPath, '.tmp');
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, '.gitignore'), '*\n!.gitignore\n');
   } catch (err) {
     return { kind: 'scaffoldFailed', message: err instanceof Error ? err.message : String(err) };
   }
@@ -1378,7 +1423,7 @@ export async function addFlowBulkImpl(
 // schema violation surfaces honestly instead of being silently papered over.
 // After the flow.json write, `removeNodeDir` cascades the node's whole
 // `<project>/nodes/<id>/` folder — covering detail.md, view.html, and any
-// imageNode upload that lived there.
+// type:'image' upload that lived there.
 export async function deleteNodeImpl(
   deps: OperationsDeps,
   flowId: string,
@@ -1510,6 +1555,22 @@ export async function patchNodeImpl(
       }
       node.data = data;
     }
+    // Component spec sidecar — write the pretty-printed JSON to
+    // `<project>/nodes/<id>/spec.json` so the on-disk source of truth stays
+    // in sync. mergeNodeUpdates already put data.spec on the merged tree for
+    // the post-mutation ResolvedFlowSchema parse; splitFlow strips it from
+    // flow.json so we don't double-store the spec.
+    if (node.type === 'component' && updates.spec !== undefined) {
+      const specAbs = nodeFileAbsPath(entry.repoPath, nodeId, 'spec.json');
+      try {
+        writeNodeFile(specAbs, `${JSON.stringify(updates.spec, null, 2)}\n`);
+      } catch (err) {
+        return {
+          kind: 'writeFailed',
+          message: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
     return { kind: 'ok' };
   });
 }
@@ -1765,11 +1826,7 @@ export async function applyLayoutImpl(
 
   const flow = flowParse.data;
   const result = await computeLayout(
-    flow.nodes.map((n) => ({
-      id: n.id,
-      type: n.type,
-      data: n.type === 'shapeNode' ? { shape: (n.data as { shape?: string }).shape } : undefined,
-    })),
+    flow.nodes.map((n) => ({ id: n.id, type: n.type })),
     flow.connectors.map((c) => ({ id: c.id, source: c.source, target: c.target })),
     options,
   );

package/src/runtime.ts

@@ -76,3 +76,40 @@ export function isPidAlive(pid: number): boolean {
     return false;
   }
 }
+
+// `0.0.0.0` / `::` are wildcard bind addresses, not connectable destinations —
+// probe loopback when the caller passes one. IPv6 unspecified `::` maps to
+// `::1`; everything else is treated as IPv4 wildcard → `127.0.0.1`.
+function probeHost(host: string): string {
+  if (host === '::' || host === '[::]') return '::1';
+  if (host === '0.0.0.0' || host === '') return '127.0.0.1';
+  return host;
+}
+
+/**
+ * Detects whether a TCP listener is responding on host:port. Uses a short
+ * connect probe (300 ms default) so we catch actively-listening servers
+ * without padding fast paths. Returns false on any connect error or timeout.
+ */
+export async function portInUse(host: string, port: number, timeoutMs = 300): Promise<boolean> {
+  const hostname = probeHost(host);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const socket = await Promise.race([
+      Bun.connect({
+        hostname,
+        port,
+        socket: { data() {}, open() {}, close() {}, error() {} },
+      }),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+      }),
+    ]);
+    socket.end();
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/schema-catalog.ts

@@ -8,14 +8,20 @@
 import type { ZodTypeAny } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
+  FlowCloudNodeSchema,
   FlowConnectorSchema,
+  FlowDatabaseNodeSchema,
+  FlowEllipseNodeSchema,
   FlowEnvelopeSchema,
   FlowHtmlNodeSchema,
   FlowIconNodeSchema,
   FlowImageNodeSchema,
-  FlowPlayNodeSchema,
-  FlowShapeNodeSchema,
-  FlowStateNodeSchema,
+  FlowQueueNodeSchema,
+  FlowRectangleNodeSchema,
+  FlowServerNodeSchema,
+  FlowStickyNodeSchema,
+  FlowTextNodeSchema,
+  FlowUserNodeSchema,
   PlayActionSchema,
   ResetActionSchema,
   StatusActionSchema,
@@ -44,7 +50,7 @@ const CATEGORIES: SchemaCategory[] = [
   {
     name: 'node',
     description:
-      'All six node variants (playNode, stateNode, shapeNode, imageNode, iconNode, htmlNode).',
+      'All 12 flat node variants (rectangle, ellipse, sticky, text, database, server, user, queue, cloud, image, html, icon). Visual kind is the type; capabilities (playAction / statusAction / stateSource) are independent optional fields on every variant.',
   },
   {
     name: 'connector',
@@ -64,15 +70,21 @@ const PAYLOADS: Record<string, SchemaPayload> = {
   },
   node: {
     schemas: {
-      playNode: toJsonSchema(FlowPlayNodeSchema),
-      stateNode: toJsonSchema(FlowStateNodeSchema),
-      shapeNode: toJsonSchema(FlowShapeNodeSchema),
-      imageNode: toJsonSchema(FlowImageNodeSchema),
-      iconNode: toJsonSchema(FlowIconNodeSchema),
-      htmlNode: toJsonSchema(FlowHtmlNodeSchema),
+      rectangle: toJsonSchema(FlowRectangleNodeSchema),
+      ellipse: toJsonSchema(FlowEllipseNodeSchema),
+      sticky: toJsonSchema(FlowStickyNodeSchema),
+      text: toJsonSchema(FlowTextNodeSchema),
+      database: toJsonSchema(FlowDatabaseNodeSchema),
+      server: toJsonSchema(FlowServerNodeSchema),
+      user: toJsonSchema(FlowUserNodeSchema),
+      queue: toJsonSchema(FlowQueueNodeSchema),
+      cloud: toJsonSchema(FlowCloudNodeSchema),
+      image: toJsonSchema(FlowImageNodeSchema),
+      html: toJsonSchema(FlowHtmlNodeSchema),
+      icon: toJsonSchema(FlowIconNodeSchema),
     },
     notes: [
-      "imageNode.data.path must start with 'nodes/<id>/'.",
+      "type:'image' data.path must start with 'nodes/<id>/'.",
       "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
     ],
   },