@tuongaz/seeflow 0.1.47 → 0.1.52

package/src/mcp.ts

@@ -12,26 +12,11 @@ import {
   CreateProjectBodySchema,
   NodePatchBodySchema,
   NodesBulkBodySchema,
-  type OperationsDeps,
+  type Operations,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
-  addConnectorImpl,
-  addConnectorsBulkImpl,
-  addNodeImpl,
-  addNodesBulkImpl,
-  createProjectImpl,
-  deleteConnectorImpl,
-  deleteFlowImpl,
-  deleteNodeImpl,
-  getFlowImpl,
-  listDemosImpl,
-  moveNodeImpl,
-  patchConnectorImpl,
-  patchNodeImpl,
-  registerFlowImpl,
-  reorderNodeImpl,
-  validateImpl,
+  createOperations,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
 import type { FlowWatcher } from './watcher.ts';
@@ -187,13 +172,25 @@ const DeleteConnectorInputSchema = z.object({
   connectorId: z.string().min(1),
 });
 
-const buildTools = (deps: OperationsDeps): McpTool[] => [
+const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_list_flows',
     description: 'List every flow registered with the studio.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler: async () => {
-      const result = listDemosImpl(deps);
+      const result = ops.listFlows();
+      return okResult(result.data);
+    },
+  },
+  {
+    name: 'seeflow_list_flows_summary',
+    description:
+      'List registered flows as { id, name, description } only. Use this for ' +
+      'cheap discovery before drilling into a specific flow with ' +
+      'seeflow_get_flow_graph or seeflow_get_node.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async () => {
+      const result = ops.listFlowsSummary();
       return okResult(result.data);
     },
   },
@@ -217,7 +214,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!body || !('flow' in body)) {
         return errorResult('Body must include `flow`');
       }
-      const result = validateImpl({
+      const result = ops.validate({
         flow: body.flow,
         style: body.style as unknown,
       });
@@ -231,7 +228,28 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
     handler: async (args) => {
       const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
-      const result = await getFlowImpl(deps, v.flowId);
+      const result = await ops.getFlow(v.flowId);
+      switch (result.kind) {
+        case 'ok':
+          return okResult(result.data);
+        case 'notFound':
+          return errorResult('not found');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+      }
+    },
+  },
+  {
+    name: 'seeflow_get_flow_graph',
+    description:
+      "Get a flow's nodes + connectors without inlining per-node file-backed " +
+      'content (`detail`, `html`). Cheap topology read — pair with seeflow_get_node ' +
+      "when you need a specific node's long-form body.",
+    inputSchema: FLOW_ID_INPUT_SCHEMA,
+    handler: async (args) => {
+      const v = requireFlowId(args);
+      if ('error' in v) return errorResult(v.error);
+      const result = await ops.getFlowGraph(v.flowId);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -239,6 +257,56 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
           return errorResult('not found');
         case 'fileNotFound':
           return errorResult(`Flow file not found: ${result.path}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.detail}`);
+        case 'badSchema':
+          return errorResult(
+            `Flow file failed schema validation: ${JSON.stringify(result.issues)}`,
+          );
+      }
+    },
+  },
+  {
+    name: 'seeflow_get_node',
+    description:
+      'Get a single node from a flow with its file-backed content (detail.md, ' +
+      'view.html) inlined. Use after seeflow_get_flow_graph to drill into one node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        flowId: { type: 'string', minLength: 1 },
+        nodeId: { type: 'string', minLength: 1 },
+      },
+      required: ['flowId', 'nodeId'],
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      if (!args || typeof args !== 'object' || Array.isArray(args)) {
+        return errorResult('Invalid arguments: expected an object with flowId + nodeId');
+      }
+      const { flowId, nodeId } = args as { flowId?: unknown; nodeId?: unknown };
+      if (typeof flowId !== 'string' || flowId.length === 0) {
+        return errorResult('Invalid arguments: flowId must be a non-empty string');
+      }
+      if (typeof nodeId !== 'string' || nodeId.length === 0) {
+        return errorResult('Invalid arguments: nodeId must be a non-empty string');
+      }
+      const result = await ops.getNode(flowId, nodeId);
+      switch (result.kind) {
+        case 'ok':
+          return okResult(result.data);
+        case 'notFound':
+          return errorResult('not found');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+        case 'unknownNode':
+          return errorResult(`Unknown nodeId: ${nodeId}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.detail}`);
+        case 'badSchema':
+          return errorResult(
+            `Flow file failed schema validation: ${JSON.stringify(result.issues)}`,
+          );
       }
     },
   },
@@ -251,7 +319,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid register body: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const result = await registerFlowImpl(deps, parsed.data);
+      const result = await ops.registerFlow(parsed.data);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -275,7 +343,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
     handler: async (args) => {
       const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
-      const result = deleteFlowImpl(deps, v.flowId);
+      const result = ops.deleteFlow(v.flowId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -293,7 +361,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid create project body: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const result = await createProjectImpl(deps, parsed.data);
+      const result = await ops.createProject(parsed.data);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -321,7 +389,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid add_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, node } = parsed.data;
-      const result = await addNodeImpl(deps, flowId, node);
+      const result = await ops.addNode(flowId, node);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id, node: result.data.node });
@@ -349,7 +417,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid add_nodes arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodes } = parsed.data;
-      const result = await addNodesBulkImpl(deps, flowId, { nodes });
+      const result = await ops.addNodesBulk(flowId, { nodes });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, nodes: result.data.nodes });
@@ -380,7 +448,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid delete_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId } = parsed.data;
-      const result = await deleteNodeImpl(deps, flowId, nodeId);
+      const result = await ops.deleteNode(flowId, nodeId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -409,7 +477,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid move_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId, x, y } = parsed.data;
-      const result = await moveNodeImpl(deps, flowId, nodeId, { x, y });
+      const result = await ops.moveNode(flowId, nodeId, { x, y });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, position: result.data.position });
@@ -439,7 +507,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid patch_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId, ...updates } = parsed.data;
-      const result = await patchNodeImpl(deps, flowId, nodeId, updates);
+      const result = await ops.patchNode(flowId, nodeId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -475,7 +543,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       // reorderNodeImpl receives the same discriminated union the REST route
       // does — keeps a single source of truth for op semantics.
       const reorderBody = ReorderBodySchema.parse(body);
-      const result = await reorderNodeImpl(deps, flowId, nodeId, reorderBody);
+      const result = await ops.reorderNode(flowId, nodeId, reorderBody);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -507,7 +575,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connector } = parsed.data;
-      const result = await addConnectorImpl(deps, flowId, connector);
+      const result = await ops.addConnector(flowId, connector);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id });
@@ -537,7 +605,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectors } = parsed.data;
-      const result = await addConnectorsBulkImpl(deps, flowId, { connectors });
+      const result = await ops.addConnectorsBulk(flowId, { connectors });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, connectors: result.data.connectors });
@@ -571,7 +639,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectorId, ...updates } = parsed.data;
-      const result = await patchConnectorImpl(deps, flowId, connectorId, updates);
+      const result = await ops.patchConnector(flowId, connectorId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -602,7 +670,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectorId } = parsed.data;
-      const result = await deleteConnectorImpl(deps, flowId, connectorId);
+      const result = await ops.deleteConnector(flowId, connectorId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -630,11 +698,12 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
  * mcp-shim.ts) — every request builds its own server in stateless mode.
  */
 export function createMcpServer(options: CreateMcpServerOptions): Server {
-  const tools = buildTools({
+  const ops = createOperations({
     registry: options.registry,
     watcher: options.watcher,
     projectBaseDir: options.projectBaseDir,
   });
+  const tools = buildTools(ops);
 
   const server = new Server({ name: 'seeflow', version: '0.1.0' }, { capabilities: { tools: {} } });
 

package/src/merge.ts

@@ -31,6 +31,7 @@ export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
   return {
     version: flow.version,
     name: flow.name,
+    ...(flow.description !== undefined ? { description: flow.description } : {}),
     ...(flow.resetAction ? { resetAction: flow.resetAction } : {}),
     nodes: mergedNodes,
     connectors: mergedConnectors,
@@ -111,6 +112,7 @@ const CONNECTOR_STYLE_KEYS = new Set([
 export function splitFlow(resolved: {
   version: number;
   name: string;
+  description?: string;
   resetAction?: unknown;
   nodes: Array<Record<string, unknown>>;
   connectors: Array<Record<string, unknown>>;
@@ -179,6 +181,7 @@ export function splitFlow(resolved: {
     nodes: flowNodes,
     connectors: flowConnectors,
   };
+  if (resolved.description !== undefined) flow.description = resolved.description;
   if (resolved.resetAction !== undefined) flow.resetAction = resolved.resetAction;
 
   const style: Record<string, unknown> = {};

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 { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
   EXTERNALIZED_NODE_FIELDS,
@@ -281,11 +282,58 @@ export interface CreateProjectSuccess {
 
 export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
 
+// 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
+// any reparse has happened.
+export interface FlowSummary {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export type ListFlowsSummaryOutcome = { kind: 'ok'; data: FlowSummary[] };
+
 export type GetFlowOutcome =
   | { kind: 'ok'; data: FlowGetResponse }
   | { kind: 'notFound' }
   | { kind: 'fileNotFound'; path: string };
 
+// Lightweight graph projection — flow + nodes + connectors with file-backed
+// fields (`detail` on every node, `html` on htmlNode) stripped so the
+// caller can navigate the topology without paying for inlined bodies.
+export interface FlowGraphResponse {
+  id: string;
+  slug: string;
+  name: string;
+  description?: string;
+  nodes: Array<Record<string, unknown>>;
+  connectors: Array<Record<string, unknown>>;
+}
+
+export type GetFlowGraphOutcome =
+  | { kind: 'ok'; data: FlowGraphResponse }
+  | { kind: 'notFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] };
+
+// Single node, content resolved. The node shape mirrors the on-disk Flow
+// node shape (no position / style) with `file://` refs already inlined.
+export interface GetNodeResponse {
+  id: string;
+  flowId: string;
+  node: Record<string, unknown>;
+}
+
+export type GetNodeOutcome =
+  | { kind: 'ok'; data: GetNodeResponse }
+  | { kind: 'notFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] }
+  | { kind: 'unknownNode' };
+
 export type RegisterFlowOutcome =
   | { kind: 'ok'; data: RegisterFlowSuccess }
   | { kind: 'fileNotFound'; path: string }
@@ -776,6 +824,22 @@ export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   return { kind: 'ok', data };
 }
 
+export function listFlowsSummaryImpl(deps: OperationsDeps): ListFlowsSummaryOutcome {
+  const { registry, watcher } = deps;
+  const data = registry.list().map((e) => {
+    const snap = watcher?.snapshot(e.id) ?? null;
+    const liveFlow = snap?.valid ? snap.flow : null;
+    const item: FlowSummary = {
+      id: e.id,
+      name: liveFlow?.name ?? e.name,
+    };
+    const description = liveFlow?.description ?? e.description;
+    if (description !== undefined) item.description = description;
+    return item;
+  });
+  return { kind: 'ok', data };
+}
+
 export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise<GetFlowOutcome> {
   const { registry, watcher } = deps;
   const entry = registry.getById(flowId);
@@ -813,6 +877,101 @@ export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise
   };
 }
 
+// Strip the only file-backed fields that ride on `node.data` today.
+// Keep narrow on purpose — if file-ref.ts ever grows another resolved field,
+// this list must grow with it (covered by the operations.test.ts coverage).
+const FILE_BACKED_NODE_DATA_FIELDS = ['detail', 'html'] as const;
+
+function stripFileBackedFields(node: Record<string, unknown>): Record<string, unknown> {
+  const data = node.data;
+  if (!data || typeof data !== 'object') return node;
+  const stripped: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+    if ((FILE_BACKED_NODE_DATA_FIELDS as readonly string[]).includes(k)) continue;
+    stripped[k] = v;
+  }
+  return { ...node, data: stripped };
+}
+
+export async function getFlowGraphImpl(
+  deps: OperationsDeps,
+  flowId: string,
+): Promise<GetFlowGraphOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'notFound' };
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(fullPath, 'utf8'));
+  } catch (err) {
+    return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  // Parse the on-disk Flow shape directly (no resolveFileRefs, no style.json
+  // merge) so we never read the per-node detail/html files from disk.
+  const parsed = FlowSchema.safeParse(raw);
+  if (!parsed.success) return { kind: 'badSchema', issues: parsed.error.issues };
+
+  const data: FlowGraphResponse = {
+    id: entry.id,
+    slug: entry.slug,
+    name: parsed.data.name,
+    nodes: parsed.data.nodes.map((n) => stripFileBackedFields(n as Record<string, unknown>)),
+    connectors: parsed.data.connectors as Array<Record<string, unknown>>,
+  };
+  if (parsed.data.description !== undefined) data.description = parsed.data.description;
+  return { kind: 'ok', data };
+}
+
+export async function getNodeImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  nodeId: string,
+): Promise<GetNodeOutcome> {
+  const { registry, watcher } = deps;
+  const entry = registry.getById(flowId);
+  if (!entry) return { kind: 'notFound' };
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+
+  // Prefer a live snapshot (already has file:// refs resolved) so we don't
+  // re-walk the filesystem on every call. Fall back to readMergedFlow for
+  // callers without a watcher (CLI, MCP-only setups).
+  const snap = watcher?.snapshot(flowId) ?? watcher?.reparse(flowId) ?? null;
+  let flow: ResolvedFlow | null = snap?.valid ? snap.flow : null;
+
+  if (!flow) {
+    if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+    const result = readMergedFlow(fullPath);
+    if (!result.valid || !result.flow) {
+      if (result.error?.startsWith('Invalid JSON')) {
+        return { kind: 'badJson', detail: result.error };
+      }
+      // Schema failed — re-parse to surface ZodIssues.
+      try {
+        const raw = JSON.parse(readFileSync(fullPath, 'utf8'));
+        const parsed = FlowSchema.safeParse(raw);
+        if (!parsed.success) return { kind: 'badSchema', issues: parsed.error.issues };
+      } catch (err) {
+        return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+      }
+      return { kind: 'badJson', detail: result.error ?? 'unknown error' };
+    }
+    flow = result.flow;
+  }
+
+  const node = flow.nodes.find((n) => n.id === nodeId);
+  if (!node) return { kind: 'unknownNode' };
+
+  return {
+    kind: 'ok',
+    data: { id: nodeId, flowId, node: node as unknown as Record<string, unknown> },
+  };
+}
+
 export async function registerFlowImpl(
   deps: OperationsDeps,
   body: RegisterBody,
@@ -845,6 +1004,7 @@ export async function registerFlowImpl(
   const lastModified = statSync(fullPath).mtimeMs;
   const entry = registry.upsert({
     name: body.name ?? merged.flow.name,
+    description: merged.flow.description,
     repoPath,
     flowPath,
     valid: true,
@@ -1522,3 +1682,163 @@ export function validateImpl(body: ValidateBody): ValidateOutcome {
 
   return issues.length === 0 ? { ok: true } : { ok: false, issues };
 }
+
+// ---------------------------------------------------------------------------
+// applyLayoutImpl — ELK layout for a registered flow. Reads flow.json from
+// the registry-resolved path, validates it, computes layout, writes
+// style.json atomically, and (if a watcher is present) calls notifyWritten so
+// the studio's flow watcher seeds its snapshot and broadcasts flow:reload
+// without echoing the style.json fs event.
+// ---------------------------------------------------------------------------
+
+export type ApplyLayoutOutcome =
+  | { kind: 'ok' }
+  | { kind: 'flowNotFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ValidationIssue[] }
+  | { kind: 'writeFailed'; message: string };
+
+export async function applyLayoutImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  options: LayoutOptions | undefined,
+): Promise<ApplyLayoutOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
+
+  const flowAbs = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(flowAbs)) return { kind: 'fileNotFound', path: flowAbs };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(flowAbs, 'utf8'));
+  } catch (err) {
+    return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  const flowParse = FlowSchema.safeParse(raw);
+  if (!flowParse.success) {
+    return {
+      kind: 'badSchema',
+      issues: flowParse.error.issues.map((i) => ({
+        scope: 'flow',
+        path: [...i.path],
+        message: i.message,
+        code: i.code,
+      })),
+    };
+  }
+
+  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.connectors.map((c) => ({ id: c.id, source: c.source, target: c.target })),
+    options,
+  );
+
+  const styleAbs = join(dirname(flowAbs), 'style.json');
+  const styleContent = `${JSON.stringify(result, null, 2)}\n`;
+  try {
+    writeFileAtomic(styleAbs, styleContent);
+  } catch (err) {
+    return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+  }
+
+  // Inform the watcher so it broadcasts flow:reload with the new payload and
+  // suppresses the upcoming fs-watcher echo for this style.json write.
+  const snap = deps.watcher?.reparse(flowId);
+  if (deps.watcher && snap) {
+    const flowContent = readFileSync(flowAbs, 'utf8');
+    deps.watcher.notifyWritten(flowId, snap, flowContent, styleContent);
+  }
+
+  return { kind: 'ok' };
+}
+
+// ---------------------------------------------------------------------------
+// createOperations — thin handle that exposes every *Impl as a bound method.
+// Consumers (api.ts, mcp.ts, cli.ts) construct one of these at startup so they
+// don't re-thread `deps` through every call site. No behaviour change — every
+// method delegates to the existing *Impl function.
+// ---------------------------------------------------------------------------
+
+export interface Operations {
+  listFlows(): ReturnType<typeof listDemosImpl>;
+  listFlowsSummary(): ReturnType<typeof listFlowsSummaryImpl>;
+  getFlow(id: string): ReturnType<typeof getFlowImpl>;
+  getFlowGraph(id: string): ReturnType<typeof getFlowGraphImpl>;
+  getNode(flowId: string, nodeId: string): ReturnType<typeof getNodeImpl>;
+  addNode(flowId: string, body: Record<string, unknown>): ReturnType<typeof addNodeImpl>;
+  addNodesBulk(
+    flowId: string,
+    body: Parameters<typeof addNodesBulkImpl>[2],
+  ): ReturnType<typeof addNodesBulkImpl>;
+  patchNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof patchNodeImpl>[3],
+  ): ReturnType<typeof patchNodeImpl>;
+  moveNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof moveNodeImpl>[3],
+  ): ReturnType<typeof moveNodeImpl>;
+  reorderNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof reorderNodeImpl>[3],
+  ): ReturnType<typeof reorderNodeImpl>;
+  deleteNode(flowId: string, nodeId: string): ReturnType<typeof deleteNodeImpl>;
+  addConnector(flowId: string, body: Record<string, unknown>): ReturnType<typeof addConnectorImpl>;
+  addConnectorsBulk(
+    flowId: string,
+    body: Parameters<typeof addConnectorsBulkImpl>[2],
+  ): ReturnType<typeof addConnectorsBulkImpl>;
+  patchConnector(
+    flowId: string,
+    connectorId: string,
+    body: Parameters<typeof patchConnectorImpl>[3],
+  ): ReturnType<typeof patchConnectorImpl>;
+  deleteConnector(flowId: string, connectorId: string): ReturnType<typeof deleteConnectorImpl>;
+  registerFlow(body: Parameters<typeof registerFlowImpl>[1]): ReturnType<typeof registerFlowImpl>;
+  createProject(
+    body: Parameters<typeof createProjectImpl>[1],
+  ): ReturnType<typeof createProjectImpl>;
+  deleteFlow(id: string): ReturnType<typeof deleteFlowImpl>;
+  validate(body: ValidateBody): ReturnType<typeof validateImpl>;
+  applyLayout(
+    flowId: string,
+    options: LayoutOptions | undefined,
+  ): ReturnType<typeof applyLayoutImpl>;
+}
+
+export function createOperations(deps: OperationsDeps): Operations {
+  return {
+    listFlows: () => listDemosImpl(deps),
+    listFlowsSummary: () => listFlowsSummaryImpl(deps),
+    getFlow: (id) => getFlowImpl(deps, id),
+    getFlowGraph: (id) => getFlowGraphImpl(deps, id),
+    getNode: (flowId, nodeId) => getNodeImpl(deps, flowId, nodeId),
+    addNode: (flowId, body) => addNodeImpl(deps, flowId, body),
+    addNodesBulk: (flowId, body) => addNodesBulkImpl(deps, flowId, body),
+    patchNode: (flowId, nodeId, body) => patchNodeImpl(deps, flowId, nodeId, body),
+    moveNode: (flowId, nodeId, body) => moveNodeImpl(deps, flowId, nodeId, body),
+    reorderNode: (flowId, nodeId, body) => reorderNodeImpl(deps, flowId, nodeId, body),
+    deleteNode: (flowId, nodeId) => deleteNodeImpl(deps, flowId, nodeId),
+    addConnector: (flowId, body) => addConnectorImpl(deps, flowId, body),
+    addConnectorsBulk: (flowId, body) => addConnectorsBulkImpl(deps, flowId, body),
+    patchConnector: (flowId, connectorId, body) =>
+      patchConnectorImpl(deps, flowId, connectorId, body),
+    deleteConnector: (flowId, connectorId) => deleteConnectorImpl(deps, flowId, connectorId),
+    registerFlow: (body) => registerFlowImpl(deps, body),
+    createProject: (body) => createProjectImpl(deps, body),
+    deleteFlow: (id) => deleteFlowImpl(deps, id),
+    validate: (body) => validateImpl(body),
+    applyLayout: (flowId, options) => applyLayoutImpl(deps, flowId, options),
+  };
+}