@tuongaz/seeflow 0.1.57 → 0.1.61

package/src/cli.ts

@@ -157,6 +157,8 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runConnectorsDelete();
 } else if (sub === 'validate') {
   await runValidate();
+} else if (sub === 'schema') {
+  await runSchema();
 } else if (sub === 'e2e') {
   await runE2e();
 } else {
@@ -196,6 +198,8 @@ Commands (work without a running studio):
   connectors:patch <id> <connId>  Patch a connector (--json/--file/--stdin)
   connectors:delete <id> <connId> Delete a connector
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
+  schema [<category>]  Get the flow.json schema. No arg → category index;
+                       category arg → full JSON Schema(s) for that category
 
 Commands (require a running studio):
   flows:play <id> <n>  Trigger a play on node <n>
@@ -251,6 +255,7 @@ async function runHelp() {
 }
 
 async function runStart() {
+  mkdirSync(seeflowHome(), { recursive: true });
   const config = readConfig();
   const portArg = flagValue('port');
   // --port wins; otherwise always fall back to the schema default (not the
@@ -800,6 +805,22 @@ async function runValidate() {
   printOk(body);
 }
 
+async function runSchema() {
+  const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+  const { listSchemaCategories, getSchemaCategory } = await import('./schema-catalog.ts');
+  if (!category) {
+    printOk({ categories: listSchemaCategories() });
+  }
+  const payload = getSchemaCategory(category as string);
+  if (!payload) {
+    const available = listSchemaCategories().map((c) => c.name);
+    const message = `unknown schema category: ${category}`;
+    process.stderr.write(`${JSON.stringify({ error: message, code: 'notFound', available })}\n`);
+    process.exit(3);
+  }
+  printOk({ name: category, schemas: payload.schemas, notes: payload.notes });
+}
+
 async function runE2e() {
   const flowId = requireArg(1, '<flowId>');
   const skipNodesRaw = flagValue('skip-nodes');

package/src/mcp.ts

@@ -20,6 +20,7 @@ import {
   flowBulkNonEmpty,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
+import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
 import type { FlowWatcher } from './watcher.ts';
 
 export interface CreateMcpServerOptions {
@@ -193,6 +194,43 @@ const buildTools = (ops: Operations): McpTool[] => [
       return okResult(result.data);
     },
   },
+  {
+    name: 'seeflow_schema',
+    description:
+      'Get the SeeFlow flow.json schema. Call with no args for a category index; ' +
+      "call with `name` for one category's full JSON Schemas. Use this to learn " +
+      'what a node, connector, action, or flow envelope looks like before authoring ' +
+      'writes. Categories: `flow`, `node`, `connector`, `action`, `style`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Optional category name. Omit for the index.',
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const name =
+        args && typeof args === 'object' && !Array.isArray(args)
+          ? (args as { name?: unknown }).name
+          : undefined;
+      if (name === undefined || name === null || name === '') {
+        return okResult({ categories: listSchemaCategories() });
+      }
+      if (typeof name !== 'string') {
+        return errorResult('Invalid arguments: `name` must be a string when present');
+      }
+      const payload = getSchemaCategory(name);
+      if (!payload) {
+        return errorResult(
+          `unknown schema category: ${name} (available: ${schemaCategoryNames().join(', ')})`,
+        );
+      }
+      return okResult({ name, schemas: payload.schemas, notes: payload.notes });
+    },
+  },
   {
     name: 'validate_seeflow',
     description:

package/src/schema-catalog.ts

@@ -0,0 +1,120 @@
+// Single source of truth for runtime schema introspection. The CLI
+// (`seeflow schema`), the MCP tool (`seeflow_schema`), and the REST routes
+// (`GET /api/schema[/:name]`) all delegate here so the agent-facing surface
+// stays in lockstep with the on-disk Zod schemas in schema.ts. Built once at
+// module load — each call returns a fresh shallow copy so callers can't
+// mutate the cached payload.
+
+import type { ZodTypeAny } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  FlowDefaultConnectorSchema,
+  FlowEnvelopeSchema,
+  FlowEventConnectorSchema,
+  FlowHtmlNodeSchema,
+  FlowHttpConnectorSchema,
+  FlowIconNodeSchema,
+  FlowImageNodeSchema,
+  FlowPlayNodeSchema,
+  FlowQueueConnectorSchema,
+  FlowShapeNodeSchema,
+  FlowStateNodeSchema,
+  PlayActionSchema,
+  ResetActionSchema,
+  StatusActionSchema,
+  StatusReportSchema,
+  StyleSchema,
+} from './schema.ts';
+
+export interface SchemaCategory {
+  name: string;
+  description: string;
+}
+
+export interface SchemaPayload {
+  schemas: Record<string, unknown>;
+  notes: 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[] = [
+  { name: 'flow', description: 'Top-level flow.json envelope.' },
+  {
+    name: 'node',
+    description:
+      'All six node variants (playNode, stateNode, shapeNode, imageNode, iconNode, htmlNode).',
+  },
+  {
+    name: 'connector',
+    description: 'All four connector kinds (http, event, queue, default).',
+  },
+  {
+    name: 'action',
+    description: 'playAction, statusAction, resetAction, statusReport.',
+  },
+  { name: 'style', description: 'style.json (studio-owned).' },
+];
+
+const PAYLOADS: Record<string, SchemaPayload> = {
+  flow: {
+    schemas: { flow: toJsonSchema(FlowEnvelopeSchema) },
+    notes: ['connectors[].source and connectors[].target must reference an existing nodes[].id.'],
+  },
+  node: {
+    schemas: {
+      playNode: toJsonSchema(FlowPlayNodeSchema),
+      stateNode: toJsonSchema(FlowStateNodeSchema),
+      shapeNode: toJsonSchema(FlowShapeNodeSchema),
+      imageNode: toJsonSchema(FlowImageNodeSchema),
+      iconNode: toJsonSchema(FlowIconNodeSchema),
+      htmlNode: toJsonSchema(FlowHtmlNodeSchema),
+    },
+    notes: [
+      "imageNode.data.path must start with 'nodes/<id>/'.",
+      "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+    ],
+  },
+  connector: {
+    schemas: {
+      http: toJsonSchema(FlowHttpConnectorSchema),
+      event: toJsonSchema(FlowEventConnectorSchema),
+      queue: toJsonSchema(FlowQueueConnectorSchema),
+      default: toJsonSchema(FlowDefaultConnectorSchema),
+    },
+    notes: [],
+  },
+  action: {
+    schemas: {
+      playAction: toJsonSchema(PlayActionSchema),
+      statusAction: toJsonSchema(StatusActionSchema),
+      resetAction: toJsonSchema(ResetActionSchema),
+      statusReport: toJsonSchema(StatusReportSchema),
+    },
+    notes: [
+      "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+    ],
+  },
+  style: {
+    schemas: { style: toJsonSchema(StyleSchema) },
+    notes: [],
+  },
+};
+
+export function listSchemaCategories(): SchemaCategory[] {
+  return CATEGORIES.map((c) => ({ ...c }));
+}
+
+export function getSchemaCategory(name: string): SchemaPayload | null {
+  const payload = PAYLOADS[name];
+  if (!payload) return null;
+  return { schemas: { ...payload.schemas }, notes: [...payload.notes] };
+}
+
+export function schemaCategoryNames(): string[] {
+  return CATEGORIES.map((c) => c.name);
+}

package/src/schema.ts

@@ -84,7 +84,7 @@ export const PlayActionSchema = ScriptActionSchema;
 // invoked from the /reset endpoint. The studio kills every live play and
 // status script for the demo before running this script, so the running app
 // sees a clean baseline when wiping its state.
-const ResetActionSchema = ScriptActionSchema;
+export const ResetActionSchema = ScriptActionSchema;
 
 // Long-running status script. Same spawn shape as ScriptAction (interpreter +
 // args + scriptPath) but no stdin payload and a much longer max lifetime since
@@ -524,49 +524,61 @@ const FlowNodeBaseShape = {
   id: z.string().min(1),
 };
 
+export const FlowPlayNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('playNode'),
+    data: FlowPlayNodeDataSchema,
+  })
+  .strict();
+
+export const FlowStateNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('stateNode'),
+    data: FlowStateNodeDataSchema,
+  })
+  .strict();
+
+export const FlowShapeNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('shapeNode'),
+    data: FlowShapeNodeDataSchema,
+  })
+  .strict();
+
+export const FlowImageNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('imageNode'),
+    data: FlowImageNodeDataSchema,
+  })
+  .strict();
+
+export const FlowIconNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('iconNode'),
+    data: FlowIconNodeDataSchema,
+  })
+  .strict();
+
+export const FlowHtmlNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('htmlNode'),
+    data: FlowHtmlNodeDataSchema,
+  })
+  .strict();
+
 const FlowNodeSchema = z.discriminatedUnion('type', [
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('playNode'),
-      data: FlowPlayNodeDataSchema,
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('stateNode'),
-      data: FlowStateNodeDataSchema,
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('shapeNode'),
-      data: FlowShapeNodeDataSchema,
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('imageNode'),
-      data: FlowImageNodeDataSchema,
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('iconNode'),
-      data: FlowIconNodeDataSchema,
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowNodeBaseShape,
-      type: z.literal('htmlNode'),
-      data: FlowHtmlNodeDataSchema,
-    })
-    .strict(),
+  FlowPlayNodeSchema,
+  FlowStateNodeSchema,
+  FlowShapeNodeSchema,
+  FlowImageNodeSchema,
+  FlowIconNodeSchema,
+  FlowHtmlNodeSchema,
 ]);
 
 const FlowConnectorBaseShape = {
@@ -576,35 +588,43 @@ const FlowConnectorBaseShape = {
   label: z.string().optional(),
 };
 
+export const FlowHttpConnectorSchema = z
+  .object({
+    ...FlowConnectorBaseShape,
+    kind: z.literal('http'),
+    method: HttpMethodSchema.optional(),
+    url: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const FlowEventConnectorSchema = z
+  .object({
+    ...FlowConnectorBaseShape,
+    kind: z.literal('event'),
+    eventName: z.string().min(1),
+  })
+  .strict();
+
+export const FlowQueueConnectorSchema = z
+  .object({
+    ...FlowConnectorBaseShape,
+    kind: z.literal('queue'),
+    queueName: z.string().min(1),
+  })
+  .strict();
+
+export const FlowDefaultConnectorSchema = z
+  .object({
+    ...FlowConnectorBaseShape,
+    kind: z.literal('default'),
+  })
+  .strict();
+
 const FlowConnectorSchema = z.discriminatedUnion('kind', [
-  z
-    .object({
-      ...FlowConnectorBaseShape,
-      kind: z.literal('http'),
-      method: HttpMethodSchema.optional(),
-      url: z.string().min(1).optional(),
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowConnectorBaseShape,
-      kind: z.literal('event'),
-      eventName: z.string().min(1),
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowConnectorBaseShape,
-      kind: z.literal('queue'),
-      queueName: z.string().min(1),
-    })
-    .strict(),
-  z
-    .object({
-      ...FlowConnectorBaseShape,
-      kind: z.literal('default'),
-    })
-    .strict(),
+  FlowHttpConnectorSchema,
+  FlowEventConnectorSchema,
+  FlowQueueConnectorSchema,
+  FlowDefaultConnectorSchema,
 ]);
 
 export const FlowSchema = z
@@ -641,6 +661,23 @@ export type Flow = z.infer<typeof FlowSchema>;
 export type FlowNode = z.infer<typeof FlowNodeSchema>;
 export type FlowConnector = z.infer<typeof FlowConnectorSchema>;
 
+// Envelope-only flow shape for the `seeflow schema flow` surface. The full
+// FlowSchema validates the whole graph; this companion schema describes the
+// top-level shape without inlining every node + connector variant, so the
+// runtime-introspectable JSON Schema stays compact. Authors drill into
+// `seeflow schema node` / `seeflow schema connector` for the per-variant
+// shapes. Not used for validation — only the catalog reads it.
+export const FlowEnvelopeSchema = z
+  .object({
+    version: z.literal(2),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    resetAction: ResetActionSchema.optional(),
+    nodes: z.array(z.unknown().describe('See `seeflow schema node`')),
+    connectors: z.array(z.unknown().describe('See `seeflow schema connector`')),
+  })
+  .strict();
+
 // =============================================================================
 // Style schema — keyed map of presentation overrides, side-table by id.
 // What lives on disk in <project>/.seeflow/style.json (optional file).

package/src/server.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { Hono } from 'hono';
@@ -7,6 +7,7 @@ import { type ProxyFacade, createApi } from './api.ts';
 import { createDemoRouter } from './demo.ts';
 import { type EventBus, createEventBus } from './events.ts';
 import { createMcpServer } from './mcp.ts';
+import { seeflowHome } from './paths.ts';
 import { type ProcessSpawner, defaultProcessSpawner } from './process-spawner.ts';
 import { type RegistryWatcher, createRegistryWatcher } from './registry-watcher.ts';
 import { type Registry, createRegistry } from './registry.ts';
@@ -208,6 +209,7 @@ export interface ServeOptions extends CreateAppOptions {
 export function serve(options: ServeOptions = {}) {
   const port = options.port ?? 4321;
   const hostname = options.hostname ?? '0.0.0.0';
+  mkdirSync(seeflowHome(), { recursive: true });
   const app = createApp(options);
   return Bun.serve({ port, hostname, fetch: app.fetch });
 }