@tuongaz/seeflow 0.1.83 → 0.1.85

package/src/cli-manifest.ts

@@ -133,9 +133,10 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     name: 'register',
     synopsis: 'seeflow register [--path <dir>] [--flow <file>]',
     description:
-      'Register a demo repo with the studio. Reads <repoPath>/<flow> (defaulting ' +
-      'to ./flow.json), validates the schema, and writes an entry to ' +
-      '~/.seeflow/registry.json. Alias of flows:register.',
+      'Register a demo repo with the studio. Manifest-aware: when <repoPath>/seeflow.json ' +
+      'exists, scans every declared flow under flows/<id>/flow.json and upserts one entry ' +
+      'per flow. Otherwise reads <repoPath>/<flow> (defaulting to ./flow.json) as a ' +
+      'single-flow project. Writes to ~/.seeflow/registry.json. Alias of flows:register.',
     category: 'flows',
     args: [],
     flags: [
@@ -143,20 +144,25 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: flow.json)',
+        description:
+          'Path to flow.json relative to repo root (default: flow.json). Ignored when seeflow.json exists.',
       },
     ],
     outputs: {
       okExample: { id: 'abc12345', slug: 'checkout' },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'manifestInvalid'],
     },
     requiresStudio: false,
-    examples: ['seeflow register', 'seeflow register --path ./my-app'],
+    examples: [
+      'seeflow register',
+      'seeflow register --path ./my-app',
+      'seeflow register --path ./checkout  # manifest-aware re-scan',
+    ],
   },
   {
     name: 'flows:register',
     synopsis: 'seeflow flows:register [--path <dir>] [--flow <file>]',
-    description: 'Register a demo repo. Identical behaviour to `register`.',
+    description: 'Register a demo repo. Identical behaviour to `register` (manifest-aware).',
     category: 'flows',
     args: [],
     flags: [
@@ -164,27 +170,40 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: flow.json)',
+        description:
+          'Path to flow.json relative to repo root (default: flow.json). Ignored when seeflow.json exists.',
       },
     ],
     body: { schemaRef: 'RegisterBody' },
     outputs: {
       okExample: { id: 'abc12345', slug: 'checkout' },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'manifestInvalid'],
     },
     requiresStudio: false,
     examples: ['seeflow flows:register --path ./my-app'],
   },
   {
     name: 'flows:list',
-    synopsis: 'seeflow flows:list',
-    description: 'List every registered flow with id, slug, name, repoPath, and valid flag.',
+    synopsis: 'seeflow flows:list [--project <p>]',
+    description:
+      'List every registered flow with id, slug, name, repoPath, and valid flag. With ' +
+      '--project <p>, filters to one project and returns { projectSlug, flows: [{ flowSlug, ' +
+      'name, icon?, isDefault, valid }] }.',
     category: 'flows',
     args: [],
-    flags: [],
-    outputs: { okExample: { flows: [{ id: 'abc12345', slug: 'checkout', name: 'Checkout' }] } },
+    flags: [
+      {
+        name: 'project',
+        valuePlaceholder: '<p>',
+        description: 'Project slug — filters output to flows under this project',
+      },
+    ],
+    outputs: {
+      okExample: { flows: [{ id: 'abc12345', slug: 'checkout', name: 'Checkout' }] },
+      errorKinds: ['projectNotFound'],
+    },
     requiresStudio: false,
-    examples: ['seeflow flows:list'],
+    examples: ['seeflow flows:list', 'seeflow flows:list --project order-pipeline'],
   },
   {
     name: 'flows:summary',
@@ -488,6 +507,33 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow projects:create --path ./checkout --name "Checkout" --description "Cart + payments flow"',
     ],
   },
+  {
+    name: 'projects:list',
+    synopsis: 'seeflow projects:list',
+    description:
+      'List every registered project: groups the registry by projectSlug and reads each ' +
+      'seeflow.json for the human-readable name + defaultFlow. Falls back to the ' +
+      "projectSlug and the registry's isDefault entry when a manifest is missing or " +
+      'malformed, so a partially-broken project still surfaces.',
+    category: 'project',
+    args: [],
+    flags: [],
+    outputs: {
+      okExample: {
+        projects: [
+          {
+            projectSlug: 'checkout',
+            name: 'Checkout',
+            defaultFlow: 'main',
+            flowCount: 2,
+            repoPath: '/abs/path/to/.seeflow/checkout',
+          },
+        ],
+      },
+    },
+    requiresStudio: false,
+    examples: ['seeflow projects:list'],
+  },
   // ---- nodes -------------------------------------------------------------
   {
     name: 'nodes:add',
@@ -860,7 +906,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
           'Optional named schema within the category — e.g. for `node`: ' +
           'rectangle, ellipse, sticky, text, database, server, user, queue, ' +
           'cloud, image, html, icon, component. For `action`: playAction, ' +
-          'statusAction, resetAction, statusReport, componentAction. For ' +
+          'statusAction, statusReport, componentAction. For ' +
           '`componentSpec`: componentSpec, componentSpecElement.',
       },
     ],

package/src/cli-ops.ts

@@ -10,8 +10,8 @@ import {
 /**
  * Build a single Operations handle for in-process CLI use.
  *
- * The CLI has no watcher and no statusRunner — play/reset are server-only
- * features that still go via HTTP. When a CLI mutates a flow file, the
+ * The CLI has no watcher and no statusRunner — play is server-only
+ * and still goes via HTTP. When a CLI mutates a flow file, the
  * running studio's flow watcher picks up the disk write externally and
  * broadcasts flow:reload to connected SPA clients.
  *

package/src/cli.ts

@@ -178,6 +178,8 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runRegister();
 } else if (sub === 'projects:create') {
   await runProjectsCreate();
+} else if (sub === 'projects:list') {
+  await runProjectsList();
 } else if (sub === 'flows:list') {
   await runFlowsList();
 } else if (sub === 'flows:summary') {
@@ -243,10 +245,11 @@ Usage:
 Commands (work without a running studio):
   start                Start the SeeFlow Studio server (default port 4321) — default when no command is given
   stop                 Stop a background studio instance
-  register             Register a demo repo, writing to ~/.seeflow/registry.json (alias of flows:register)
-  flows:register       Register a demo repo
+  register             Register a demo repo. Manifest-aware: when <repoPath>/seeflow.json exists, re-scans every declared flow; otherwise reads <repoPath>/<flow> (defaults to flow.json) as a single-flow project (alias of flows:register)
+  flows:register       Register a demo repo (manifest-aware — same behaviour as register)
   projects:create      Scaffold a new project (writes <path>/seeflow.json + <path>/flows/main/flow.json) — (--path <dir> --name <name> [--description <text>])
-  flows:list           List registered flows
+  projects:list        List every registered project with projectSlug, name, defaultFlow, flowCount
+  flows:list           List registered flows. With --project <p>, filters to one project (returns flowSlug, name, icon?, isDefault per flow)
   flows:summary        List registered flows (id + name + description only)
   flows:get            Get flow details (--project <p> --flow <f>)
   flows:graph          List nodes + connectors without inlined file content (--project <p> --flow <f>)
@@ -594,12 +597,24 @@ function isEsrch(err: unknown): boolean {
 
 async function runRegister() {
   const repoPath = resolve(flagValue('path') ?? '.');
-  const demoPathArg = flagValue('flow') ?? DEFAULT_FLOW_PATH;
 
+  // Manifest-aware path: if <repoPath>/seeflow.json is on disk, scan and
+  // upsert every declared flow in one shot.
+  if (existsSync(join(repoPath, 'seeflow.json'))) {
+    await runRegisterManifest(repoPath);
+    return;
+  }
+
+  // Legacy single-flow path: pre-manifest projects (and skill tests that
+  // exercise registerFlow directly) still pass a bare flow.json at the
+  // root. Read it, schema-validate, upsert one entry.
+  const demoPathArg = flagValue('flow') ?? DEFAULT_FLOW_PATH;
   const fullPath = isAbsolute(demoPathArg) ? demoPathArg : join(repoPath, demoPathArg);
   if (!existsSync(fullPath)) {
     console.error(`No demo file at ${fullPath}`);
-    console.error(`Create ${DEFAULT_FLOW_PATH} in your repo, or pass --flow <path>.`);
+    console.error(
+      `Create ${DEFAULT_FLOW_PATH} in your repo, or pass --flow <path>. For manifest-driven projects, place a seeflow.json at the repo root.`,
+    );
     process.exit(1);
   }
 
@@ -643,6 +658,48 @@ async function runRegister() {
   }
 }
 
+async function runRegisterManifest(repoPath: string) {
+  const outcome = registerProject({ repoPath });
+  if (outcome.kind !== 'ok') {
+    switch (outcome.kind) {
+      case 'manifest-invalid':
+        console.error(`${join(repoPath, 'seeflow.json')} is invalid: ${outcome.message}`);
+        process.exit(2);
+        break;
+      case 'manifest-missing':
+        // Defensive — runRegister gated on existsSync, so this should not fire.
+        console.error(`No seeflow.json at ${repoPath}`);
+        process.exit(3);
+        break;
+      case 'legacy-root-flow':
+        console.error(
+          `${repoPath} has a legacy root flow.json but no seeflow.json. Migrate it into the new flows/<id>/ layout before re-registering.`,
+        );
+        process.exit(3);
+        break;
+      case 'flow-json-missing':
+        console.error(
+          `Manifest declares flow "${outcome.flowId}" but ${outcome.flowPath} is missing.`,
+        );
+        process.exit(3);
+        break;
+    }
+    process.exit(1);
+  }
+
+  const pid = readPid();
+  const live = pid !== undefined && isPidAlive(pid);
+  const overrideUrl = process.env.SEEFLOW_STUDIO_URL?.replace(/\/+$/, '');
+  const baseUrl = live ? (overrideUrl ?? studioUrl(readConfig())) : null;
+
+  for (const entry of outcome.entries) {
+    const tail = baseUrl
+      ? ` → ${baseUrl}/projects/${outcome.projectSlug}/flows/${entry.flowSlug}`
+      : ` (slug: ${entry.slug})`;
+    console.log(`Registered "${entry.name}"${tail}`);
+  }
+}
+
 async function ensureStudioRunning(url: string, port: number, noStart: boolean) {
   if (await healthOk(url)) return;
 
@@ -709,10 +766,23 @@ async function runProjectsCreate() {
 
 async function runFlowsList() {
   const ops = createCliOperations();
+  const project = flagValue('project');
+  if (project) {
+    const result = ops.listFlowsByProject(project);
+    if (result.kind !== 'ok') printOutcome(result);
+    printOk({ projectSlug: result.data.projectSlug, flows: result.data.flows });
+    return;
+  }
   const result = ops.listFlows();
   printOk({ flows: result.data });
 }
 
+function runProjectsList() {
+  const ops = createCliOperations();
+  const result = ops.listProjects();
+  printOk({ projects: result.data });
+}
+
 async function runFlowsSummary() {
   const ops = createCliOperations();
   const result = ops.listFlowsSummary();

package/src/events.ts

@@ -6,7 +6,6 @@
 
 export type StudioEventType =
   | 'flow:reload'
-  | 'demo:reset'
   | 'node:running'
   | 'node:done'
   | 'node:error'

package/src/mcp.ts

@@ -295,7 +295,7 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
       'spec, or flow envelope looks like before authoring writes. Categories: ' +
       '`flow`, `node` (13 flat variants — rectangle/ellipse/sticky/text/' +
       'database/server/user/queue/cloud/image/html/icon/component), ' +
-      '`connector`, `action` (playAction/statusAction/resetAction/statusReport/' +
+      '`connector`, `action` (playAction/statusAction/statusReport/' +
       "componentAction), `componentSpec` (sidecar shape for type:'component' " +
       'nodes), `style`.',
     inputSchema: {
@@ -311,7 +311,7 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
             'Optional named schema within the category (requires `name`). For ' +
             "name='node': rectangle, ellipse, sticky, text, database, server, " +
             'user, queue, cloud, image, html, icon, component. For ' +
-            "name='action': playAction, statusAction, resetAction, statusReport, " +
+            "name='action': playAction, statusAction, statusReport, " +
             "componentAction. For name='componentSpec': componentSpec, " +
             'componentSpecElement.',
         },

package/src/merge.ts

@@ -32,7 +32,6 @@ export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
     version: flow.version,
     name: flow.name,
     ...(flow.description !== undefined ? { description: flow.description } : {}),
-    ...(flow.resetAction ? { resetAction: flow.resetAction } : {}),
     nodes: mergedNodes,
     connectors: mergedConnectors,
   } as ResolvedFlow;
@@ -114,7 +113,6 @@ export function splitFlow(resolved: {
   version: number;
   name: string;
   description?: string;
-  resetAction?: unknown;
   nodes: Array<Record<string, unknown>>;
   connectors: Array<Record<string, unknown>>;
 }): { flow: Record<string, unknown>; style: Record<string, unknown> } {
@@ -187,7 +185,6 @@ export function splitFlow(resolved: {
     connectors: flowConnectors,
   };
   if (resolved.description !== undefined) flow.description = resolved.description;
-  if (resolved.resetAction !== undefined) flow.resetAction = resolved.resetAction;
 
   const style: Record<string, unknown> = {};
   if (Object.keys(styleNodes).length > 0) style.nodes = styleNodes;

package/src/operations.ts

@@ -22,8 +22,8 @@ import {
   removeNodeDir,
   writeNodeFile,
 } from './node-files.ts';
-import { scanProject } from './project-scanner.ts';
-import { type Registry, slugify } from './registry.ts';
+import { readProjectManifest, scanProject } from './project-scanner.ts';
+import { type FlowEntry, type Registry, slugify } from './registry.ts';
 import {
   ColorTokenSchema,
   ComponentSpecSchema,
@@ -404,6 +404,31 @@ export interface CreateProjectSuccess {
 
 export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
 
+export interface ProjectListItem {
+  projectSlug: string;
+  name: string;
+  description?: string;
+  defaultFlow: string;
+  flowCount: number;
+  repoPath: string;
+}
+
+export type ListProjectsOutcome = { kind: 'ok'; data: ProjectListItem[] };
+
+export interface ProjectFlowListItem {
+  id: string;
+  slug: string;
+  flowSlug: string;
+  name: string;
+  icon?: string;
+  isDefault: boolean;
+  valid: boolean;
+}
+
+export type ListFlowsByProjectOutcome =
+  | { kind: 'ok'; data: { projectSlug: string; flows: ProjectFlowListItem[] } }
+  | { kind: 'projectNotFound'; projectSlug: string };
+
 // Minimal projection for agent/CLI discovery — `description` and `name` come
 // from the live watcher snapshot when available so author edits to flow.json
 // surface immediately; fall back to the registry value at startup before
@@ -737,7 +762,6 @@ function readRawFlowAndStyle(flowPath: string): ReadRawResult {
 type MutateMergedFlowMutator<E> = (flow: {
   version: number;
   name: string;
-  resetAction?: unknown;
   nodes: Array<Record<string, unknown>>;
   connectors: Array<Record<string, unknown>>;
 }) => { kind: 'ok' } | E;
@@ -783,7 +807,6 @@ export async function mutateMergedFlow<E extends { kind: string }>(
   const merged = inlinedFlow as unknown as {
     version: number;
     name: string;
-    resetAction?: unknown;
     nodes: Array<Record<string, unknown>>;
     connectors: Array<Record<string, unknown>>;
   };
@@ -951,6 +974,52 @@ export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   return { kind: 'ok', data };
 }
 
+export function listProjectsImpl(deps: OperationsDeps): ListProjectsOutcome {
+  const grouped = new Map<string, FlowEntry[]>();
+  for (const entry of deps.registry.list()) {
+    const existing = grouped.get(entry.projectSlug);
+    if (existing) existing.push(entry);
+    else grouped.set(entry.projectSlug, [entry]);
+  }
+  const data: ProjectListItem[] = [];
+  for (const [projectSlug, entries] of grouped) {
+    const head = entries[0];
+    if (!head) continue;
+    const manifest = readProjectManifest(head.repoPath);
+    const defaultEntry = entries.find((e) => e.isDefault) ?? head;
+    data.push({
+      projectSlug,
+      name: manifest?.name ?? projectSlug,
+      ...(manifest?.description !== undefined ? { description: manifest.description } : {}),
+      defaultFlow: manifest?.defaultFlow ?? defaultEntry.flowSlug,
+      flowCount: entries.length,
+      repoPath: head.repoPath,
+    });
+  }
+  return { kind: 'ok', data };
+}
+
+export function listFlowsByProjectImpl(
+  deps: OperationsDeps,
+  projectSlug: string,
+): ListFlowsByProjectOutcome {
+  const entries = deps.registry.list().filter((e) => e.projectSlug === projectSlug);
+  if (entries.length === 0) return { kind: 'projectNotFound', projectSlug };
+  const flows: ProjectFlowListItem[] = entries.map((e) => {
+    const fileExists = existsSync(resolveFilePath(e.repoPath, e.flowPath));
+    return {
+      id: e.id,
+      slug: e.slug,
+      flowSlug: e.flowSlug,
+      name: e.name,
+      ...(e.icon !== undefined ? { icon: e.icon } : {}),
+      isDefault: e.isDefault,
+      valid: e.valid && fileExists,
+    };
+  });
+  return { kind: 'ok', data: { projectSlug, flows } };
+}
+
 export function listFlowsSummaryImpl(deps: OperationsDeps): ListFlowsSummaryOutcome {
   const { registry, watcher } = deps;
   const data = registry.list().map((e) => {
@@ -1899,6 +1968,8 @@ export async function applyLayoutImpl(
 export interface Operations {
   listFlows(): ReturnType<typeof listDemosImpl>;
   listFlowsSummary(): ReturnType<typeof listFlowsSummaryImpl>;
+  listProjects(): ReturnType<typeof listProjectsImpl>;
+  listFlowsByProject(projectSlug: string): ReturnType<typeof listFlowsByProjectImpl>;
   getFlow(id: string): ReturnType<typeof getFlowImpl>;
   getFlowGraph(id: string): ReturnType<typeof getFlowGraphImpl>;
   getNode(flowId: string, nodeId: string): ReturnType<typeof getNodeImpl>;
@@ -1946,6 +2017,8 @@ export function createOperations(deps: OperationsDeps): Operations {
   return {
     listFlows: () => listDemosImpl(deps),
     listFlowsSummary: () => listFlowsSummaryImpl(deps),
+    listProjects: () => listProjectsImpl(deps),
+    listFlowsByProject: (projectSlug) => listFlowsByProjectImpl(deps, projectSlug),
     getFlow: (id) => getFlowImpl(deps, id),
     getFlowGraph: (id) => getFlowGraphImpl(deps, id),
     getNode: (flowId, nodeId) => getNodeImpl(deps, flowId, nodeId),

package/src/project-scanner.ts

@@ -47,6 +47,24 @@ export type ScanResult =
 const MANIFEST_FILENAME = 'seeflow.json';
 const LEGACY_FLOW_FILENAME = 'flow.json';
 
+/**
+ * Best-effort manifest read for listing routes / CLI listing verbs.
+ * Returns `null` when the manifest is missing or malformed — callers fall
+ * back to derived defaults (projectSlug, isDefault entry) so one broken
+ * project does not collapse the whole listing.
+ */
+export function readProjectManifest(repoPath: string): SeeflowManifest | null {
+  const manifestPath = join(repoPath, MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const parsed = SeeflowManifestSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
 export function scanProject(repoPath: string): ScanResult {
   const manifestPath = join(repoPath, MANIFEST_FILENAME);
   if (!existsSync(manifestPath)) {