@tuongaz/seeflow 0.1.91 → 0.1.93

package/src/cli.ts

@@ -268,11 +268,14 @@ Commands (work without a running studio):
   connectors:patch <connId>  Patch a connector (--project <p> --flow <f>) [--json/--file/--stdin]
   connectors:delete <connId> Delete a connector (--project <p> --flow <f>)
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
-  schema [<category> [<subname>]]
-                       Get the flow.json schema. No arg → category index;
-                       category arg → full JSON Schema(s) for that category;
-                       subname arg → just that named schema (e.g.
-                       'schema node component', 'schema node rectangle')
+  schema [<category> [<subname>]] [--jq <path>]
+                       Get the flow.json schema. Run this before designing /
+                       authoring nodes. No arg → category index with subnames
+                       inlined; category arg → full JSON Schema(s) + jqHints;
+                       subname arg → one variant + jqHints.dataFields listing
+                       every data.<field> available. Pair with --jq to slice
+                       (e.g. 'schema node rectangle --jq
+                       .schemas.rectangle.properties.data.properties.playAction').
   ids <type> <count>   Print <count> short ids of the given <type>, one per
                        line. <type> is 'node' (-> 'node-...') or 'connector'
                        (-> 'conn-...'). <count> is 1..100. Call once per type
@@ -1100,10 +1103,19 @@ async function runSchema() {
   const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
   const subname = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
   const jqFilter = flagValue('jq');
-  const { listSchemaCategories, getSchemaCategory, getCategorySubschema, listCategorySubnames } =
-    await import('./schema-catalog.ts');
+  const {
+    listSchemaCategories,
+    getSchemaCategory,
+    getCategorySubschema,
+    listCategorySubnames,
+    buildJqHints,
+    SCHEMA_INDEX_USAGE,
+  } = await import('./schema-catalog.ts');
   if (!category) {
-    const base = { categories: listSchemaCategories() };
+    const base = {
+      categories: listSchemaCategories(),
+      usage: SCHEMA_INDEX_USAGE,
+    };
     if (jqFilter !== undefined) {
       printOk({ result: applyJqOrDie(base, jqFilter) });
     }
@@ -1141,6 +1153,7 @@ async function runSchema() {
       subname,
       schemas: single.schemas,
       notes: single.notes,
+      jqHints: buildJqHints(category as string, subname),
     };
     if (jqFilter !== undefined) {
       printOk({ name: category, subname, result: applyJqOrDie(base, jqFilter) });
@@ -1154,7 +1167,13 @@ async function runSchema() {
     process.stderr.write(`${JSON.stringify({ error: message, code: 'notFound', available })}\n`);
     process.exit(3);
   }
-  const base = { name: category, schemas: payload.schemas, notes: payload.notes };
+  const base = {
+    name: category,
+    schemas: payload.schemas,
+    notes: payload.notes,
+    subnames: listCategorySubnames(category as string) ?? [],
+    jqHints: buildJqHints(category as string),
+  };
   if (jqFilter !== undefined) {
     printOk({ name: category, result: applyJqOrDie(base, jqFilter) });
   }

package/src/mcp.ts

@@ -30,6 +30,8 @@ import {
 } from './operations.ts';
 import type { Registry } from './registry.ts';
 import {
+  SCHEMA_INDEX_USAGE,
+  buildJqHints,
   getCategorySubschema,
   getSchemaCategory,
   listCategorySubnames,
@@ -329,7 +331,10 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
         if (subname !== undefined && subname !== null && subname !== '') {
           return errorResult('Invalid arguments: `subname` requires `name` to be set');
         }
-        return okResult({ categories: listSchemaCategories() });
+        return okResult({
+          categories: listSchemaCategories(),
+          usage: SCHEMA_INDEX_USAGE,
+        });
       }
       if (typeof name !== 'string') {
         return errorResult('Invalid arguments: `name` must be a string when present');
@@ -345,6 +350,7 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
             subname,
             schemas: single.schemas,
             notes: single.notes,
+            jqHints: buildJqHints(name, subname),
           });
         }
         const availableSubs = listCategorySubnames(name);
@@ -363,7 +369,13 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
           `unknown schema category: ${name} (available: ${schemaCategoryNames().join(', ')})`,
         );
       }
-      return okResult({ name, schemas: payload.schemas, notes: payload.notes });
+      return okResult({
+        name,
+        schemas: payload.schemas,
+        notes: payload.notes,
+        subnames: listCategorySubnames(name) ?? [],
+        jqHints: buildJqHints(name),
+      });
     },
   },
   {

package/src/merge.ts

@@ -64,7 +64,6 @@ const NODE_STYLE_KEYS = new Set([
   'borderSize',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',

package/src/node-files.ts

@@ -8,16 +8,54 @@ import { writeFileAtomic } from './atomic-write.ts';
 // `flows/<flow-id>/nodes/<id>/`; for legacy single-flow fixtures with
 // `flowPath: 'flow.json'` it collapses to the project root. `nodeTypes` (when
 // present) scopes the spec entry to specific node types; absent means
-// "applies to every node type". Adding a future text field is one line.
+// "applies to every node type".
+//
+// Two flavors of externalization:
+// - `kind: 'ref'` (default) — write the file, replace `data[field]` with
+//   `file://<fileName>`. The ref survives splitFlow (the field is in
+//   NODE_DATA_FLOW_KEYS in merge.ts). Used by string fields like `detail`
+//   and `html`.
+// - `kind: 'sidecar'` — write the file, leave `data[field]` untouched on
+//   the in-memory node so the post-mutation parse still sees the original
+//   value. splitFlow drops the field from flow.json on write; the resolver
+//   inlines it from disk on read. Used by JSON fields like component `spec`.
+//
+// `serialize` turns the in-memory value into file contents. Returning `null`
+// skips the write entirely — used by `spec` to no-op when the caller didn't
+// supply one, instead of writing an empty file that would fail JSON parse
+// on the next read.
 export interface ExternalizedFieldSpec {
   field: string;
   fileName: string;
   nodeTypes?: readonly string[];
+  kind?: 'ref' | 'sidecar';
+  serialize?: (value: unknown) => string | null;
 }
 
+// Default serializer: strings pass through; non-strings coerce to empty.
+// Keeps the historical detail/html behavior — an absent detail still writes
+// an empty detail.md so the file:// ref points somewhere.
+export const defaultExternalizedSerializer = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+// JSON serializer for sidecar fields: pretty-print plain objects with a
+// trailing newline. Returns null for anything else so the loop can skip the
+// write rather than emit an invalid sidecar.
+const jsonExternalizedSerializer = (value: unknown): string | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? `${JSON.stringify(value, null, 2)}\n`
+    : null;
+
 export const EXTERNALIZED_NODE_FIELDS: readonly ExternalizedFieldSpec[] = [
   { field: 'detail', fileName: 'detail.md' },
   { field: 'html', fileName: 'view.html', nodeTypes: ['html'] },
+  {
+    field: 'spec',
+    fileName: 'spec.json',
+    nodeTypes: ['component'],
+    kind: 'sidecar',
+    serialize: jsonExternalizedSerializer,
+  },
 ];
 
 export const externalizedFieldsForNodeType = (

package/src/operations.ts

@@ -16,6 +16,7 @@ import { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
   EXTERNALIZED_NODE_FIELDS,
+  defaultExternalizedSerializer,
   externalizedFieldsForNodeType,
   nodeFileAbsPath,
   nodeFileRef,
@@ -100,7 +101,6 @@ export const NodePatchBodySchema = z
     borderWidth: z.number().min(0).max(8).optional(),
     borderStyle: z.enum(['solid', 'dashed', 'dotted']).optional(),
     fontSize: z.number().positive().optional(),
-    textColor: ColorTokenSchema.optional(),
     textAlign: z.enum(['left', 'center', 'right']).optional(),
     cornerRadius: z.number().min(0).optional(),
     shadow: z.number().int().min(0).max(5).optional(),
@@ -164,7 +164,6 @@ const NODE_DATA_PATCH_KEYS = [
   'borderWidth',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',
@@ -267,7 +266,6 @@ const NODE_VISUAL_KEYS = new Set([
   'borderSize',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',
@@ -1347,12 +1345,16 @@ export async function addNodeImpl(
       ? { ...(newNode.data as Record<string, unknown>) }
       : {};
     const flowDir = dirname(entry.flowPath);
-    for (const { field, fileName } of externalizedFieldsForNodeType(newNode.type)) {
-      const incoming = data[field];
-      const content = typeof incoming === 'string' ? incoming : '';
-      data[field] = nodeFileRef(newId, fileName);
+    for (const spec of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[spec.field];
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out (e.g. spec absent)
+      if ((spec.kind ?? 'ref') === 'ref') {
+        data[spec.field] = nodeFileRef(newId, spec.fileName);
+      }
       externalized.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, spec.fileName),
         content,
       });
     }
@@ -1431,12 +1433,16 @@ export async function addFlowBulkImpl(
     const data: Record<string, unknown> = dataIsRecord
       ? { ...(newNode.data as Record<string, unknown>) }
       : {};
-    for (const { field, fileName } of externalizedFieldsForNodeType(newNode.type)) {
-      const incoming = data[field];
-      const content = typeof incoming === 'string' ? incoming : '';
-      data[field] = nodeFileRef(newId, fileName);
+    for (const spec of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[spec.field];
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out (e.g. spec absent)
+      if ((spec.kind ?? 'ref') === 'ref') {
+        data[spec.field] = nodeFileRef(newId, spec.fileName);
+      }
       externalized.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, spec.fileName),
         content,
       });
     }
@@ -1637,15 +1643,20 @@ export async function patchNodeImpl(
       ref: string;
       field: string;
       content: string;
+      kind: 'ref' | 'sidecar';
     }> = [];
-    for (const { field, fileName } of externalizedFieldsForNodeType(node.type)) {
-      const incoming = (updates as Record<string, unknown>)[field];
+    for (const spec of externalizedFieldsForNodeType(node.type)) {
+      const incoming = (updates as Record<string, unknown>)[spec.field];
       if (incoming === undefined) continue;
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out
       externalizedWrites.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, nodeId, fileName),
-        ref: nodeFileRef(nodeId, fileName),
-        field,
-        content: typeof incoming === 'string' ? incoming : '',
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, nodeId, spec.fileName),
+        ref: nodeFileRef(nodeId, spec.fileName),
+        field: spec.field,
+        content,
+        kind: spec.kind ?? 'ref',
       });
     }
     mergeNodeUpdates(node, updates);
@@ -1664,26 +1675,14 @@ export async function patchNodeImpl(
             message: err instanceof Error ? err.message : String(err),
           };
         }
-        data[w.field] = w.ref;
+        // 'ref' fields swap data[field] for a file:// pointer; 'sidecar'
+        // fields (e.g. component spec) leave the in-memory value alone so the
+        // post-mutation parse still sees it — splitFlow drops it from flow.json
+        // on write and the resolver inlines it back from disk on read.
+        if (w.kind === 'ref') data[w.field] = w.ref;
       }
       node.data = data;
     }
-    // Component spec sidecar — write the pretty-printed JSON to
-    // `<repoPath>/<flowDir>/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, flowDir, 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' };
   });
 }

package/src/schema-catalog.ts

@@ -37,6 +37,9 @@ import {
 export interface SchemaCategory {
   name: string;
   description: string;
+  // Every drill target valid for `seeflow schema <name> <subname>`. Lets the
+  // agent pick a variant without a second round-trip to listCategorySubnames.
+  subnames: string[];
 }
 
 export interface SchemaPayload {
@@ -44,13 +47,40 @@ export interface SchemaPayload {
   notes: string[];
 }
 
+// Hint payload attached to every schema response so the agent can drill in
+// further without round-tripping. `examples` are ready-to-paste jq paths;
+// `dataFields` lists the node-variant `data.<field>` keys (single-variant
+// lookups only — undefined for non-node categories or category-level
+// responses).
+export interface JqHints {
+  dataFields?: string[];
+  examples: string[];
+  tip?: string;
+}
+
 // Draft-07 pin matches the widest tool support; the same target string is
 // used by the MCP `tools/list` JSON Schemas (default in zod-to-json-schema)
 // so consumers see one consistent dialect across the whole surface.
 const toJsonSchema = (schema: ZodTypeAny): unknown =>
   zodToJsonSchema(schema, { $refStrategy: 'none', target: 'jsonSchema7' });
 
-const CATEGORIES: SchemaCategory[] = [
+// Recipe block returned on the schema index (CLI / REST / MCP) so the agent
+// sees the drill + filter pattern in the response itself, not just in
+// `seeflow help schema`.
+export const SCHEMA_INDEX_USAGE = {
+  drill: 'seeflow schema <category> [<subname>]',
+  filter: 'seeflow schema <category> [<subname>] --jq <jq-path>',
+  examples: [
+    'seeflow schema node',
+    'seeflow schema node rectangle',
+    'seeflow schema node rectangle --jq .schemas.rectangle.properties.data.properties.playAction',
+    'seeflow schema action playAction',
+  ],
+} as const;
+
+// Description metadata. `subnames` are filled in by listSchemaCategories()
+// at call time from PAYLOADS, so the two stay in lockstep automatically.
+const CATEGORY_META: Array<Omit<SchemaCategory, 'subnames'>> = [
   { name: 'flow', description: 'Top-level flow.json envelope.' },
   {
     name: 'node',
@@ -141,7 +171,10 @@ const PAYLOADS: Record<string, SchemaPayload> = {
 };
 
 export function listSchemaCategories(): SchemaCategory[] {
-  return CATEGORIES.map((c) => ({ ...c }));
+  return CATEGORY_META.map((c) => ({
+    ...c,
+    subnames: Object.keys(PAYLOADS[c.name]?.schemas ?? {}),
+  }));
 }
 
 export function getSchemaCategory(name: string): SchemaPayload | null {
@@ -151,7 +184,7 @@ export function getSchemaCategory(name: string): SchemaPayload | null {
 }
 
 export function schemaCategoryNames(): string[] {
-  return CATEGORIES.map((c) => c.name);
+  return CATEGORY_META.map((c) => c.name);
 }
 
 // Drill into one named schema inside a category — e.g. ('node', 'rectangle')
@@ -176,3 +209,76 @@ export function listCategorySubnames(category: string): string[] | null {
   if (!payload) return null;
   return Object.keys(payload.schemas);
 }
+
+// Top-level keys under `data.properties` for a single node variant — i.e.
+// the per-shape data fields an author actually sets on a flow.json node
+// (`name`, `icon`, `playAction`, etc.). Returns null when the variant has
+// no `data.properties` wrapper (action / connector / style / componentSpec
+// schemas, plus anything malformed). Pure helper consumed by buildJqHints
+// to surface concrete drill-down paths.
+export function getDataFieldNames(category: string, subname: string): string[] | null {
+  const sub = PAYLOADS[category]?.schemas[subname] as
+    | { properties?: { data?: { properties?: Record<string, unknown> } } }
+    | undefined;
+  const dataProps = sub?.properties?.data?.properties;
+  if (!dataProps) return null;
+  return Object.keys(dataProps);
+}
+
+// Build ready-to-paste jq path examples for a schema response. When `subname`
+// is provided, the examples drill into that single variant — including one
+// path per `data.<field>` so the agent can `--jq` straight to (say)
+// `.schemas.rectangle.properties.data.properties.playAction` without first
+// reading the whole envelope. When `subname` is omitted, the hints cover the
+// whole category (iteration, one sample variant, notes). `dataFields` only
+// surfaces on single-variant lookups for shapes that actually carry a
+// `data.properties` wrapper.
+export function buildJqHints(category: string, subname?: string): JqHints | null {
+  const payload = PAYLOADS[category];
+  if (!payload) return null;
+  if (subname) {
+    if (payload.schemas[subname] === undefined) return null;
+    const dataFields = getDataFieldNames(category, subname);
+    const examples = [
+      `.schemas.${subname}`,
+      `.schemas.${subname}.required`,
+      ...(dataFields && dataFields.length > 0
+        ? [
+            `.schemas.${subname}.properties.data.properties`,
+            ...dataFields
+              .slice(0, 6)
+              .map((f) => `.schemas.${subname}.properties.data.properties.${f}`),
+          ]
+        : [`.schemas.${subname}.properties`]),
+      '.notes',
+      '.notes[]',
+    ];
+    const hint = dataFields
+      ? `dataFields lists every \`data.<field>\` available on this variant — point \`--jq\` at any of them with \`.schemas.${subname}.properties.data.properties.<field>\`.`
+      : `Use \`--jq\` to pluck a single property — e.g. \`.schemas.${subname}.required\`.`;
+    return {
+      ...(dataFields ? { dataFields } : {}),
+      examples,
+      tip: hint,
+    };
+  }
+  const subs = Object.keys(payload.schemas);
+  const sample = subs[0];
+  if (!sample) return { examples: ['.schemas', '.notes', '.notes[]'] };
+  const examples = [
+    '.schemas',
+    `.schemas.${sample}`,
+    `.schemas.${sample}.required`,
+    `.schemas.${sample}.properties.data.properties`,
+    '.schemas[]',
+    '.notes',
+    '.notes[]',
+  ];
+  return {
+    examples,
+    tip:
+      subs.length > 1
+        ? `Pass \`seeflow schema ${category} <subname>\` (one of: ${subs.join(', ')}) to drop the other ${subs.length - 1} variant(s) from the payload before \`--jq\`-ing.`
+        : `Single-variant category — \`--jq\` paths drill straight into \`.schemas.${sample}\`.`,
+  };
+}

package/src/schema.ts

@@ -14,25 +14,26 @@ const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 // them to actual CSS values (theme-aware, light + dark).
 export const ColorTokenSchema = z.enum([
   // `'none'` renders transparent border / fill on nodes (no stroke, no fill).
-  // Hidden from the text-color and connector-color pickers — invisible text
-  // and edges aren't useful, and `'default'` already covers "inherit".
+  // Hidden from the connector-color picker — invisible edges aren't useful,
+  // and `'default'` already covers "inherit".
   'none',
   'default',
   'white',
   'slate',
   'gray',
   'red',
-  'rose',
   'orange',
   'amber',
+  'yellow',
   'lime',
   'green',
   'teal',
   'cyan',
+  'sky',
   'blue',
   'indigo',
   'violet',
-  'purple',
+  'fuchsia',
   'pink',
 ]);
 
@@ -47,7 +48,6 @@ const NodeVisualBaseShape = {
   borderSize: z.number().min(0).optional(),
   borderStyle: z.enum(['solid', 'dashed', 'dotted']).optional(),
   fontSize: z.number().positive().optional(),
-  textColor: ColorTokenSchema.optional(),
   // Horizontal alignment for the node's text content. Defaults to 'center'
   // at render time when omitted; explicit picks from the toolbar's Align
   // toggle persist here.
@@ -711,7 +711,6 @@ const NodeStyleSchema = z
     borderSize: z.number().min(0).optional(),
     borderStyle: z.enum(['solid', 'dashed', 'dotted']).optional(),
     fontSize: z.number().positive().optional(),
-    textColor: ColorTokenSchema.optional(),
     textAlign: z.enum(['left', 'center', 'right']).optional(),
     cornerRadius: z.number().min(0).optional(),
     shadow: z.number().int().min(0).max(5).optional(),

package/dist/web/assets/channel-CilAQwI4.js

@@ -1 +0,0 @@
-import{U as a,C as n}from"./mermaid.core-CRo4rzDL.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/web/assets/classDiagram-4FO5ZUOK-fiT0MjXY.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-2Se8RGwW.js";import{a as i}from"./mermaid.core-CRo4rzDL.js";import"./index-DFpY3RpV.js";import"./chunk-FMBD7UC4-BJX_21R2.js";import"./chunk-ND2GUHAM-DFBKXknR.js";import"./chunk-55IACEB6-DlboNFJr.js";import"./chunk-2J33WTMH-9vQ1xqy3.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/web/assets/classDiagram-v2-Q7XG4LA2-fiT0MjXY.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-2Se8RGwW.js";import{a as i}from"./mermaid.core-CRo4rzDL.js";import"./index-DFpY3RpV.js";import"./chunk-FMBD7UC4-BJX_21R2.js";import"./chunk-ND2GUHAM-DFBKXknR.js";import"./chunk-55IACEB6-DlboNFJr.js";import"./chunk-2J33WTMH-9vQ1xqy3.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};