@assistkick/create 1.19.0 → 1.22.0

package/templates/assistkick-product-system/packages/shared/tools/workflow_builder.ts

@@ -0,0 +1,754 @@
+#!/usr/bin/env node
+
+/**
+ * workflow_builder — Create and edit workflow graphs stored in the database.
+ *
+ * Actions:
+ *   list                          — List all workflows
+ *   get <id>                      — Get a workflow with its graph
+ *   create                        — Create a new workflow
+ *   update <id>                   — Update workflow metadata and/or graph
+ *   delete <id>                   — Delete a workflow
+ *   set-default <id>              — Mark workflow as default for its scope
+ *   add-node <workflow-id>        — Add a node to a workflow graph
+ *   remove-node <workflow-id>     — Remove a node and its edges
+ *   update-node <workflow-id>     — Update a node's data/config
+ *   add-edge <workflow-id>        — Add an edge between two nodes
+ *   remove-edge <workflow-id>     — Remove an edge
+ *   auto-layout <workflow-id>     — Auto-layout the graph nodes
+ *   validate <workflow-id>        — Validate graph structure
+ *   node-types                    — List available node types with config
+ *   list-agents                   — List available agents for runAgent nodes
+ *   list-groups                   — List available reusable groups
+ *   get-group <id>                — Get a group's internal graph
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq, and, isNull, or } from 'drizzle-orm';
+import { workflows, workflowExecutions, workflowGroups, agents } from '../db/schema.js';
+import { getDb } from '../lib/db.js';
+import { randomUUID } from 'node:crypto';
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+const WORKFLOW_NODE_TYPES = [
+  'start', 'transitionCard', 'runAgent', 'checkCardPosition',
+  'checkCycleCount', 'setCardMetadata', 'end', 'group',
+  'rebuildBundle', 'generateTTS', 'renderVideo', 'programmable',
+] as const;
+
+const KANBAN_COLUMNS = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'] as const;
+
+const NODE_DEFAULTS: Record<string, () => Record<string, unknown>> = {
+  start: () => ({}),
+  transitionCard: () => ({ sourceColumn: 'todo', targetColumn: 'in_progress' }),
+  runAgent: () => ({ agentId: '', agentName: '' }),
+  checkCardPosition: () => ({}),
+  checkCycleCount: () => ({ maxCount: 3 }),
+  setCardMetadata: () => ({ key: '', value: '' }),
+  end: () => ({ statusType: 'success' }),
+  group: () => ({ groupId: '', groupName: '', internalNodes: [], internalEdges: [], inputHandles: [], outputHandles: [] }),
+  rebuildBundle: () => ({}),
+  generateTTS: () => ({ scriptPath: '', force: false, voiceId: '' }),
+  renderVideo: () => ({ compositionId: '', resolution: '1920x1080', aspectRatio: '', fileOutputPrefix: '' }),
+  programmable: () => ({
+    label: '', code: 'async function run(context) {\n  return {};\n}',
+    timeout: 30000, memory: 128, maxRequests: 20, maxResponseSize: 5242880,
+  }),
+};
+
+const NODE_DESCRIPTIONS: Record<string, { label: string; description: string; config: string }> = {
+  start: { label: 'Start', description: 'Workflow entry point', config: 'No config needed' },
+  transitionCard: { label: 'Transition Card', description: 'Move kanban card between columns', config: 'sourceColumn, targetColumn (backlog|todo|in_progress|in_review|qa|done)' },
+  runAgent: { label: 'Run Agent', description: 'Execute an AI agent', config: 'agentId, agentName' },
+  checkCardPosition: { label: 'Check Card Position', description: 'Branch by current kanban column', config: 'No config. Outputs: backlog, todo, in_progress, in_review, qa, done' },
+  checkCycleCount: { label: 'Check Cycle Count', description: 'Branch by iteration count', config: 'maxCount (number). Outputs: under_limit, at_limit' },
+  setCardMetadata: { label: 'Set Card Metadata', description: 'Set key/value on kanban card', config: 'key, value' },
+  end: { label: 'End', description: 'Workflow exit point', config: 'statusType (success|blocked|failed)' },
+  group: { label: 'Group', description: 'Reusable nested node group', config: 'groupId, groupName, internalNodes, internalEdges, inputHandles, outputHandles' },
+  rebuildBundle: { label: 'Rebuild Bundle', description: 'Build Remotion webpack bundle', config: 'No config needed' },
+  generateTTS: { label: 'Generate TTS', description: 'Generate text-to-speech audio', config: 'scriptPath, force, voiceId' },
+  renderVideo: { label: 'Render Video', description: 'Render composition to MP4', config: 'compositionId, resolution, aspectRatio, fileOutputPrefix' },
+  programmable: { label: 'Programmable', description: 'Run custom JavaScript code in sandbox', config: 'label, code, timeout, memory, maxRequests, maxResponseSize. Outputs: success, error' },
+};
+
+// ── Auto-layout (port of frontend autoLayout.ts) ──────────────────────────────
+
+const NODE_WIDTH = 200;
+const NODE_HEIGHT = 160;
+const HORIZONTAL_GAP = 60;
+const VERTICAL_GAP = 80;
+
+interface GraphNode {
+  id: string;
+  type: string;
+  position: { x: number; y: number };
+  data: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string | null;
+  targetHandle?: string | null;
+  type?: string;
+  animated?: boolean;
+  data?: Record<string, unknown>;
+}
+
+interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+function autoLayoutNodes(nodes: GraphNode[], edges: GraphEdge[]): GraphNode[] {
+  if (nodes.length === 0) return nodes;
+
+  const children = new Map<string, string[]>();
+  const parentCount = new Map<string, number>();
+  for (const node of nodes) {
+    children.set(node.id, []);
+    parentCount.set(node.id, 0);
+  }
+  for (const edge of edges) {
+    if (children.has(edge.source) && parentCount.has(edge.target)) {
+      children.get(edge.source)!.push(edge.target);
+      parentCount.set(edge.target, (parentCount.get(edge.target) || 0) + 1);
+    }
+  }
+
+  const roots = nodes.filter(n => (parentCount.get(n.id) || 0) === 0);
+  if (roots.length === 0) {
+    const startNodes = nodes.filter(n => n.type === 'start');
+    roots.push(...(startNodes.length > 0 ? startNodes : [nodes[0]]));
+  }
+
+  const depth = new Map<string, number>();
+  const maxDepth = nodes.length;
+  const queue: Array<{ id: string; d: number }> = [];
+  for (const root of roots) {
+    depth.set(root.id, 0);
+    queue.push({ id: root.id, d: 0 });
+  }
+
+  while (queue.length > 0) {
+    const { id, d } = queue.shift()!;
+    for (const childId of children.get(id) || []) {
+      const newDepth = d + 1;
+      if (newDepth > maxDepth) continue;
+      const currentDepth = depth.get(childId);
+      if (currentDepth === undefined || newDepth > currentDepth) {
+        depth.set(childId, newDepth);
+        queue.push({ id: childId, d: newDepth });
+      }
+    }
+  }
+
+  for (const node of nodes) {
+    if (!depth.has(node.id)) depth.set(node.id, 0);
+  }
+
+  const levels = new Map<number, GraphNode[]>();
+  for (const node of nodes) {
+    const d = depth.get(node.id)!;
+    if (!levels.has(d)) levels.set(d, []);
+    levels.get(d)!.push(node);
+  }
+
+  const sortedDepths = [...levels.keys()].sort((a, b) => a - b);
+  const positioned = new Map<string, { x: number; y: number }>();
+
+  for (const d of sortedDepths) {
+    const levelNodes = levels.get(d)!;
+    const rowWidth = levelNodes.length * NODE_WIDTH + (levelNodes.length - 1) * HORIZONTAL_GAP;
+    const startX = -rowWidth / 2;
+    for (let i = 0; i < levelNodes.length; i++) {
+      positioned.set(levelNodes[i].id, {
+        x: startX + i * (NODE_WIDTH + HORIZONTAL_GAP),
+        y: d * (NODE_HEIGHT + VERTICAL_GAP),
+      });
+    }
+  }
+
+  return nodes.map(node => ({
+    ...node,
+    position: positioned.get(node.id) || node.position,
+  }));
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function generateNodeId(): string {
+  return `node_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+}
+
+function generateEdgeId(source: string, target: string, sourceHandle?: string): string {
+  const handleSuffix = sourceHandle ? `_${sourceHandle}` : '';
+  return `edge_${source}_${target}${handleSuffix}`;
+}
+
+function parseGraphData(raw: string): GraphData {
+  try {
+    const data = JSON.parse(raw);
+    return {
+      nodes: Array.isArray(data.nodes) ? data.nodes : [],
+      edges: Array.isArray(data.edges) ? data.edges : [],
+    };
+  } catch {
+    return { nodes: [], edges: [] };
+  }
+}
+
+async function loadWorkflow(db: any, id: string) {
+  const [row] = await db.select().from(workflows).where(eq(workflows.id, id));
+  if (!row) throw new Error(`Workflow not found: ${id}`);
+  return row;
+}
+
+async function saveGraphData(db: any, id: string, graph: GraphData) {
+  const now = new Date().toISOString();
+  await db.update(workflows)
+    .set({ graphData: JSON.stringify(graph), updatedAt: now })
+    .where(eq(workflows.id, id));
+}
+
+function validateNodeType(type: string): void {
+  if (!WORKFLOW_NODE_TYPES.includes(type as any)) {
+    throw new Error(`Invalid node type: ${type}. Valid types: ${WORKFLOW_NODE_TYPES.join(', ')}`);
+  }
+}
+
+function validateGraph(graph: GraphData): string[] {
+  const issues: string[] = [];
+  const nodeIds = new Set(graph.nodes.map(n => n.id));
+
+  // Must have exactly one start node
+  const startNodes = graph.nodes.filter(n => n.type === 'start');
+  if (startNodes.length === 0) issues.push('Missing start node');
+  if (startNodes.length > 1) issues.push(`Multiple start nodes: ${startNodes.map(n => n.id).join(', ')}`);
+
+  // Must have at least one end node
+  const endNodes = graph.nodes.filter(n => n.type === 'end');
+  if (endNodes.length === 0) issues.push('Missing end node');
+
+  // Edges must reference existing nodes
+  for (const edge of graph.edges) {
+    if (!nodeIds.has(edge.source)) issues.push(`Edge ${edge.id}: source "${edge.source}" not found`);
+    if (!nodeIds.has(edge.target)) issues.push(`Edge ${edge.id}: target "${edge.target}" not found`);
+  }
+
+  // Start node should have no incoming edges
+  for (const start of startNodes) {
+    const incoming = graph.edges.filter(e => e.target === start.id);
+    if (incoming.length > 0) issues.push(`Start node "${start.id}" has incoming edges`);
+  }
+
+  // End nodes should have no outgoing edges
+  for (const end of endNodes) {
+    const outgoing = graph.edges.filter(e => e.source === end.id);
+    if (outgoing.length > 0) issues.push(`End node "${end.id}" has outgoing edges`);
+  }
+
+  // Non-start, non-end nodes should have both incoming and outgoing edges
+  for (const node of graph.nodes) {
+    if (node.type === 'start' || node.type === 'end') continue;
+    const incoming = graph.edges.filter(e => e.target === node.id);
+    const outgoing = graph.edges.filter(e => e.source === node.id);
+    if (incoming.length === 0) issues.push(`Node "${node.id}" (${node.type}) has no incoming edges`);
+    if (outgoing.length === 0) issues.push(`Node "${node.id}" (${node.type}) has no outgoing edges`);
+  }
+
+  // Branching nodes must have correct output handles
+  for (const node of graph.nodes) {
+    if (node.type === 'checkCardPosition') {
+      const outgoing = graph.edges.filter(e => e.source === node.id);
+      const handles = new Set(outgoing.map(e => e.sourceHandle).filter(Boolean));
+      for (const h of handles) {
+        if (!KANBAN_COLUMNS.includes(h as any)) {
+          issues.push(`checkCardPosition node "${node.id}": invalid handle "${h}"`);
+        }
+      }
+    }
+    if (node.type === 'checkCycleCount') {
+      const outgoing = graph.edges.filter(e => e.source === node.id);
+      const handles = new Set(outgoing.map(e => e.sourceHandle).filter(Boolean));
+      for (const h of handles) {
+        if (!['under_limit', 'at_limit'].includes(h as string)) {
+          issues.push(`checkCycleCount node "${node.id}": invalid handle "${h}"`);
+        }
+      }
+    }
+    if (node.type === 'programmable') {
+      const outgoing = graph.edges.filter(e => e.source === node.id);
+      const handles = new Set(outgoing.map(e => e.sourceHandle).filter(Boolean));
+      for (const h of handles) {
+        if (!['success', 'error'].includes(h as string)) {
+          issues.push(`programmable node "${node.id}": invalid handle "${h}"`);
+        }
+      }
+    }
+  }
+
+  // runAgent nodes must have agentId set
+  for (const node of graph.nodes) {
+    if (node.type === 'runAgent' && !node.data?.agentId) {
+      issues.push(`runAgent node "${node.id}": missing agentId`);
+    }
+  }
+
+  return issues;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+program
+  .argument('<action>', 'Action to perform')
+  .argument('[target]', 'Workflow ID, group ID, or other target')
+  .option('--project-id <id>', 'Project ID (scope filter)')
+  .option('--name <name>', 'Workflow or group name')
+  .option('--description <desc>', 'Workflow description')
+  .option('--feature-type <type>', 'Feature type filter')
+  .option('--trigger-column <col>', 'Trigger column filter')
+  .option('--graph-data <json>', 'Full graph data as JSON')
+  .option('--node-type <type>', 'Node type for add-node')
+  .option('--node-id <id>', 'Node ID for update-node/remove-node')
+  .option('--node-data <json>', 'Node data/config as JSON')
+  .option('--position <xy>', 'Node position as "x,y"')
+  .option('--source <id>', 'Source node ID for add-edge')
+  .option('--target-node <id>', 'Target node ID for add-edge')
+  .option('--source-handle <handle>', 'Source handle for add-edge')
+  .option('--target-handle <handle>', 'Target handle for add-edge')
+  .option('--edge-label <label>', 'Edge label')
+  .option('--edge-id <id>', 'Edge ID for remove-edge')
+  .parse();
+
+const [action, target] = program.args;
+const opts = program.opts();
+
+(async () => {
+  const db = getDb();
+
+  try {
+    switch (action) {
+
+      // ── List workflows ──────────────────────────────────────────────────────
+      case 'list': {
+        const conditions = [];
+        if (opts.projectId) {
+          conditions.push(or(isNull(workflows.projectId), eq(workflows.projectId, opts.projectId)));
+        }
+        if (opts.featureType) conditions.push(eq(workflows.featureType, opts.featureType));
+        if (opts.triggerColumn) conditions.push(eq(workflows.triggerColumn, opts.triggerColumn));
+
+        const rows = conditions.length > 0
+          ? await db.select({
+              id: workflows.id, name: workflows.name, description: workflows.description,
+              projectId: workflows.projectId, featureType: workflows.featureType,
+              triggerColumn: workflows.triggerColumn, isDefault: workflows.isDefault,
+              createdAt: workflows.createdAt, updatedAt: workflows.updatedAt,
+            }).from(workflows).where(and(...conditions))
+          : await db.select({
+              id: workflows.id, name: workflows.name, description: workflows.description,
+              projectId: workflows.projectId, featureType: workflows.featureType,
+              triggerColumn: workflows.triggerColumn, isDefault: workflows.isDefault,
+              createdAt: workflows.createdAt, updatedAt: workflows.updatedAt,
+            }).from(workflows);
+
+        console.log(chalk.cyan.bold('Workflows:\n'));
+        for (const row of rows) {
+          const def = row.isDefault ? chalk.yellow(' [DEFAULT]') : '';
+          const scope = row.projectId ? chalk.gray(` (project: ${row.projectId})`) : chalk.gray(' (global)');
+          console.log(`  ${chalk.bold(row.name)}${def}${scope}`);
+          console.log(`    ID: ${row.id}`);
+          if (row.description) console.log(`    ${row.description}`);
+          if (row.featureType) console.log(`    Feature type: ${row.featureType}`);
+          if (row.triggerColumn) console.log(`    Trigger column: ${row.triggerColumn}`);
+        }
+        console.log('\n' + JSON.stringify({ workflows: rows }));
+        break;
+      }
+
+      // ── Get workflow ────────────────────────────────────────────────────────
+      case 'get': {
+        if (!target) throw new Error('Usage: workflow_builder get <workflow-id>');
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+
+        console.log(chalk.cyan.bold(`\nWorkflow: ${row.name}\n`));
+        console.log(`  ID: ${row.id}`);
+        if (row.description) console.log(`  Description: ${row.description}`);
+        console.log(`  Nodes: ${graph.nodes.length}`);
+        console.log(`  Edges: ${graph.edges.length}`);
+        if (row.isDefault) console.log(`  ${chalk.yellow('DEFAULT')}`);
+        console.log();
+
+        console.log(chalk.cyan('  Nodes:'));
+        for (const node of graph.nodes) {
+          const data = Object.entries(node.data || {})
+            .filter(([k]) => k !== 'type')
+            .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+            .join(', ');
+          console.log(`    ${chalk.bold(node.id)} [${node.type}]${data ? ` — ${data}` : ''}`);
+        }
+        console.log();
+
+        console.log(chalk.cyan('  Edges:'));
+        for (const edge of graph.edges) {
+          const handle = edge.sourceHandle ? ` (${edge.sourceHandle})` : '';
+          const label = edge.data?.label ? ` "${edge.data.label}"` : '';
+          console.log(`    ${edge.source}${handle} → ${edge.target}${label}`);
+        }
+
+        console.log('\n' + JSON.stringify({
+          id: row.id, name: row.name, description: row.description,
+          projectId: row.projectId, featureType: row.featureType,
+          triggerColumn: row.triggerColumn, isDefault: row.isDefault,
+          graph,
+        }));
+        break;
+      }
+
+      // ── Create workflow ─────────────────────────────────────────────────────
+      case 'create': {
+        if (!opts.name) throw new Error('--name is required for create');
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const graphData = opts.graphData || JSON.stringify({ nodes: [], edges: [] });
+
+        const record = {
+          id, name: opts.name,
+          description: opts.description || null,
+          projectId: opts.projectId || null,
+          featureType: opts.featureType || null,
+          triggerColumn: opts.triggerColumn || null,
+          isDefault: 0,
+          graphData,
+          createdAt: now, updatedAt: now,
+        };
+
+        await db.insert(workflows).values(record);
+        console.log(chalk.green(`Created workflow: ${opts.name} (${id})`));
+        console.log(JSON.stringify({ id, name: opts.name }));
+        break;
+      }
+
+      // ── Update workflow metadata ────────────────────────────────────────────
+      case 'update': {
+        if (!target) throw new Error('Usage: workflow_builder update <workflow-id> [options]');
+        const existing = await loadWorkflow(db, target);
+        const now = new Date().toISOString();
+        const updates: Record<string, any> = { updatedAt: now };
+
+        if (opts.name) updates.name = opts.name;
+        if (opts.description) updates.description = opts.description;
+        if (opts.featureType !== undefined) updates.featureType = opts.featureType || null;
+        if (opts.triggerColumn !== undefined) updates.triggerColumn = opts.triggerColumn || null;
+        if (opts.graphData) updates.graphData = opts.graphData;
+
+        await db.update(workflows).set(updates).where(eq(workflows.id, target));
+        console.log(chalk.green(`Updated workflow: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ id: target, ...updates }));
+        break;
+      }
+
+      // ── Delete workflow ─────────────────────────────────────────────────────
+      case 'delete': {
+        if (!target) throw new Error('Usage: workflow_builder delete <workflow-id>');
+        const existing = await loadWorkflow(db, target);
+
+        const active = await db.select().from(workflowExecutions)
+          .where(and(
+            eq(workflowExecutions.workflowId, target),
+            or(eq(workflowExecutions.status, 'running'), eq(workflowExecutions.status, 'pending')),
+          ));
+        if (active.length > 0) throw new Error('Cannot delete workflow with active executions');
+
+        await db.delete(workflows).where(eq(workflows.id, target));
+        console.log(chalk.green(`Deleted workflow: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ deleted: target }));
+        break;
+      }
+
+      // ── Set default ─────────────────────────────────────────────────────────
+      case 'set-default': {
+        if (!target) throw new Error('Usage: workflow_builder set-default <workflow-id>');
+        const existing = await loadWorkflow(db, target);
+        const now = new Date().toISOString();
+
+        const scopeCondition = existing.projectId
+          ? eq(workflows.projectId, existing.projectId)
+          : isNull(workflows.projectId);
+
+        await db.update(workflows)
+          .set({ isDefault: 0, updatedAt: now })
+          .where(and(scopeCondition, eq(workflows.isDefault, 1)));
+
+        await db.update(workflows)
+          .set({ isDefault: 1, updatedAt: now })
+          .where(eq(workflows.id, target));
+
+        console.log(chalk.green(`Set default: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ id: target, isDefault: 1 }));
+        break;
+      }
+
+      // ── Add node ────────────────────────────────────────────────────────────
+      case 'add-node': {
+        if (!target) throw new Error('Usage: workflow_builder add-node <workflow-id> --node-type <type> [--node-data <json>] [--position <x,y>]');
+        if (!opts.nodeType) throw new Error('--node-type is required');
+        validateNodeType(opts.nodeType);
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+        const nodeId = generateNodeId();
+
+        let position = { x: 0, y: 0 };
+        if (opts.position) {
+          const [x, y] = opts.position.split(',').map(Number);
+          position = { x: x || 0, y: y || 0 };
+        }
+
+        const defaults = NODE_DEFAULTS[opts.nodeType]?.() || {};
+        const customData = opts.nodeData ? JSON.parse(opts.nodeData) : {};
+
+        const newNode: GraphNode = {
+          id: nodeId,
+          type: opts.nodeType,
+          position,
+          data: { ...defaults, ...customData },
+        };
+
+        graph.nodes.push(newNode);
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Added node: ${nodeId} [${opts.nodeType}]`));
+        console.log(JSON.stringify({ nodeId, type: opts.nodeType, data: newNode.data }));
+        break;
+      }
+
+      // ── Remove node ─────────────────────────────────────────────────────────
+      case 'remove-node': {
+        if (!target) throw new Error('Usage: workflow_builder remove-node <workflow-id> --node-id <id>');
+        if (!opts.nodeId) throw new Error('--node-id is required');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+
+        const nodeIdx = graph.nodes.findIndex(n => n.id === opts.nodeId);
+        if (nodeIdx === -1) throw new Error(`Node not found: ${opts.nodeId}`);
+
+        graph.nodes.splice(nodeIdx, 1);
+        graph.edges = graph.edges.filter(e => e.source !== opts.nodeId && e.target !== opts.nodeId);
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Removed node: ${opts.nodeId}`));
+        console.log(JSON.stringify({ removed: opts.nodeId }));
+        break;
+      }
+
+      // ── Update node ─────────────────────────────────────────────────────────
+      case 'update-node': {
+        if (!target) throw new Error('Usage: workflow_builder update-node <workflow-id> --node-id <id> --node-data <json>');
+        if (!opts.nodeId) throw new Error('--node-id is required');
+        if (!opts.nodeData) throw new Error('--node-data is required');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+
+        const node = graph.nodes.find(n => n.id === opts.nodeId);
+        if (!node) throw new Error(`Node not found: ${opts.nodeId}`);
+
+        const updates = JSON.parse(opts.nodeData);
+        node.data = { ...node.data, ...updates };
+
+        if (opts.position) {
+          const [x, y] = opts.position.split(',').map(Number);
+          node.position = { x: x || 0, y: y || 0 };
+        }
+
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Updated node: ${opts.nodeId}`));
+        console.log(JSON.stringify({ nodeId: opts.nodeId, data: node.data }));
+        break;
+      }
+
+      // ── Add edge ────────────────────────────────────────────────────────────
+      case 'add-edge': {
+        if (!target) throw new Error('Usage: workflow_builder add-edge <workflow-id> --source <id> --target-node <id>');
+        if (!opts.source) throw new Error('--source is required');
+        if (!opts.targetNode) throw new Error('--target-node is required');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+        const nodeIds = new Set(graph.nodes.map(n => n.id));
+
+        if (!nodeIds.has(opts.source)) throw new Error(`Source node not found: ${opts.source}`);
+        if (!nodeIds.has(opts.targetNode)) throw new Error(`Target node not found: ${opts.targetNode}`);
+
+        const edgeId = generateEdgeId(opts.source, opts.targetNode, opts.sourceHandle);
+
+        // Check for duplicate
+        const exists = graph.edges.some(e =>
+          e.source === opts.source && e.target === opts.targetNode &&
+          (e.sourceHandle || null) === (opts.sourceHandle || null)
+        );
+        if (exists) throw new Error('Edge already exists between these nodes with this handle');
+
+        const newEdge: GraphEdge = {
+          id: edgeId,
+          source: opts.source,
+          target: opts.targetNode,
+          sourceHandle: opts.sourceHandle || null,
+          targetHandle: opts.targetHandle || null,
+          type: 'smoothstep',
+          animated: true,
+        };
+        if (opts.edgeLabel) {
+          newEdge.data = { label: opts.edgeLabel };
+        }
+
+        graph.edges.push(newEdge);
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Added edge: ${opts.source} → ${opts.targetNode}`));
+        console.log(JSON.stringify({ edgeId, source: opts.source, target: opts.targetNode }));
+        break;
+      }
+
+      // ── Remove edge ─────────────────────────────────────────────────────────
+      case 'remove-edge': {
+        if (!target) throw new Error('Usage: workflow_builder remove-edge <workflow-id> --edge-id <id>');
+        if (!opts.edgeId) throw new Error('--edge-id is required');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+
+        const edgeIdx = graph.edges.findIndex(e => e.id === opts.edgeId);
+        if (edgeIdx === -1) throw new Error(`Edge not found: ${opts.edgeId}`);
+
+        graph.edges.splice(edgeIdx, 1);
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Removed edge: ${opts.edgeId}`));
+        console.log(JSON.stringify({ removed: opts.edgeId }));
+        break;
+      }
+
+      // ── Auto-layout ─────────────────────────────────────────────────────────
+      case 'auto-layout': {
+        if (!target) throw new Error('Usage: workflow_builder auto-layout <workflow-id>');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+
+        graph.nodes = autoLayoutNodes(graph.nodes, graph.edges);
+        await saveGraphData(db, target, graph);
+
+        console.log(chalk.green(`Auto-layout applied to ${graph.nodes.length} nodes`));
+        console.log(JSON.stringify({ nodes: graph.nodes.length, edges: graph.edges.length }));
+        break;
+      }
+
+      // ── Validate ────────────────────────────────────────────────────────────
+      case 'validate': {
+        if (!target) throw new Error('Usage: workflow_builder validate <workflow-id>');
+
+        const row = await loadWorkflow(db, target);
+        const graph = parseGraphData(row.graphData);
+        const issues = validateGraph(graph);
+
+        if (issues.length === 0) {
+          console.log(chalk.green('Workflow graph is valid'));
+        } else {
+          console.log(chalk.yellow(`Found ${issues.length} issue(s):`));
+          for (const issue of issues) {
+            console.log(chalk.yellow(`  - ${issue}`));
+          }
+        }
+        console.log(JSON.stringify({ valid: issues.length === 0, issues }));
+        break;
+      }
+
+      // ── Node types reference ────────────────────────────────────────────────
+      case 'node-types': {
+        console.log(chalk.cyan.bold('Available Node Types:\n'));
+        for (const [type, info] of Object.entries(NODE_DESCRIPTIONS)) {
+          console.log(`  ${chalk.bold(info.label)} (${type})`);
+          console.log(`    ${info.description}`);
+          console.log(`    Config: ${info.config}`);
+          console.log();
+        }
+        console.log(JSON.stringify({ nodeTypes: NODE_DESCRIPTIONS }));
+        break;
+      }
+
+      // ── List agents ─────────────────────────────────────────────────────────
+      case 'list-agents': {
+        const conditions = opts.projectId
+          ? or(isNull(agents.projectId), eq(agents.projectId, opts.projectId))
+          : undefined;
+
+        const rows = conditions
+          ? await db.select({ id: agents.id, name: agents.name, model: agents.model, projectId: agents.projectId })
+              .from(agents).where(conditions)
+          : await db.select({ id: agents.id, name: agents.name, model: agents.model, projectId: agents.projectId })
+              .from(agents);
+
+        console.log(chalk.cyan.bold('Available Agents:\n'));
+        for (const row of rows) {
+          const scope = row.projectId ? chalk.gray(` (project: ${row.projectId})`) : chalk.gray(' (global)');
+          console.log(`  ${chalk.bold(row.name)}${scope}`);
+          console.log(`    ID: ${row.id}  Model: ${row.model}`);
+        }
+        console.log('\n' + JSON.stringify({ agents: rows }));
+        break;
+      }
+
+      // ── List groups ─────────────────────────────────────────────────────────
+      case 'list-groups': {
+        const conditions = opts.projectId
+          ? or(isNull(workflowGroups.projectId), eq(workflowGroups.projectId, opts.projectId))
+          : undefined;
+
+        const rows = conditions
+          ? await db.select().from(workflowGroups).where(conditions)
+          : await db.select().from(workflowGroups);
+
+        console.log(chalk.cyan.bold('Reusable Groups:\n'));
+        for (const row of rows) {
+          const scope = row.projectId ? chalk.gray(` (project: ${row.projectId})`) : chalk.gray(' (global)');
+          const graph = parseGraphData(row.graphData);
+          console.log(`  ${chalk.bold(row.name)}${scope}`);
+          console.log(`    ID: ${row.id}  Nodes: ${graph.nodes.length}  Edges: ${graph.edges.length}`);
+        }
+        console.log('\n' + JSON.stringify({ groups: rows }));
+        break;
+      }
+
+      // ── Get group ───────────────────────────────────────────────────────────
+      case 'get-group': {
+        if (!target) throw new Error('Usage: workflow_builder get-group <group-id>');
+        const [row] = await db.select().from(workflowGroups).where(eq(workflowGroups.id, target));
+        if (!row) throw new Error(`Group not found: ${target}`);
+
+        const graph = parseGraphData(row.graphData);
+        console.log(chalk.cyan.bold(`\nGroup: ${row.name}\n`));
+        console.log(`  ID: ${row.id}`);
+        console.log(`  Nodes: ${graph.nodes.length}`);
+        console.log(`  Edges: ${graph.edges.length}`);
+        console.log('\n' + JSON.stringify({ id: row.id, name: row.name, graph }));
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown action "${action}". Valid actions: list, get, create, update, delete, set-default, add-node, remove-node, update-node, add-edge, remove-edge, auto-layout, validate, node-types, list-agents, list-groups, get-group`);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();