@synergenius/flow-weaver 0.10.8 → 0.10.9

package/dist/cli/flow-weaver.mjs

@@ -47472,26 +47472,44 @@ ${fn.getText()}` : fn.getText();
         ports.execute = { dataType: "STEP", tsType: "boolean", label: "Execute" };
       }
       if (params.length > 1) {
-        const dataParam = params[1];
-        const dataParamType = dataParam.getType();
-        const properties = dataParamType.getProperties();
-        properties.forEach((prop) => {
-          const propName = prop.getName();
-          const propType = prop.getTypeAtLocation(dataParam);
-          const portType = this.inferPortType(propType);
-          const propTypeText = propType.getText();
-          const tsSchema = portType === "OBJECT" ? this.extractTypeSchema(propType) : void 0;
-          const startPortConfig = config2?.startPorts?.[propName];
-          ports[propName] = {
-            dataType: portType,
-            label: startPortConfig?.label || this.capitalize(propName),
-            ...startPortConfig?.metadata && { metadata: startPortConfig.metadata },
-            // Include original TS type for rich type display
-            ...propTypeText && { tsType: propTypeText },
-            // Include schema breakdown for complex types
-            ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
-          };
-        });
+        const dataParams = params.slice(1).filter((p) => p.getName() !== "__abortSignal__");
+        const shouldExpandProperties = dataParams.length === 1 && this.isExpandableObjectType(dataParams[0].getType());
+        if (shouldExpandProperties) {
+          const dataParam = dataParams[0];
+          const dataParamType = dataParam.getType();
+          const properties = dataParamType.getProperties();
+          properties.forEach((prop) => {
+            const propName = prop.getName();
+            const propType = prop.getTypeAtLocation(dataParam);
+            const portType = this.inferPortType(propType);
+            const propTypeText = propType.getText();
+            const tsSchema = portType === "OBJECT" ? this.extractTypeSchema(propType) : void 0;
+            const startPortConfig = config2?.startPorts?.[propName];
+            ports[propName] = {
+              dataType: portType,
+              label: startPortConfig?.label || this.capitalize(propName),
+              ...startPortConfig?.metadata && { metadata: startPortConfig.metadata },
+              ...propTypeText && { tsType: propTypeText },
+              ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
+            };
+          });
+        } else {
+          for (const param of dataParams) {
+            const paramName = param.getName();
+            const paramType = param.getType();
+            const portType = this.inferPortType(paramType);
+            const paramTypeText = paramType.getText(param);
+            const tsSchema = portType === "OBJECT" ? this.extractTypeSchema(paramType) : void 0;
+            const startPortConfig = config2?.startPorts?.[paramName];
+            ports[paramName] = {
+              dataType: portType,
+              label: startPortConfig?.label || this.capitalize(paramName),
+              ...startPortConfig?.metadata && { metadata: startPortConfig.metadata },
+              ...paramTypeText && { tsType: paramTypeText },
+              ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
+            };
+          }
+        }
       }
     } else {
       throw new Error(
@@ -47578,6 +47596,18 @@ ${fn.getText()}` : fn.getText();
     }
     return Object.keys(schema2).length > 0 ? schema2 : void 0;
   }
+  /**
+   * Check if a type should be expanded into individual ports via getProperties().
+   * Returns true for object literals and interfaces, false for primitives, arrays,
+   * and built-in types whose properties are prototype methods (string, number, etc.).
+   */
+  isExpandableObjectType(tsType) {
+    const typeText = tsType.getText();
+    const primitiveTypes2 = /* @__PURE__ */ new Set(["string", "number", "boolean", "any", "unknown", "never", "object", "Object"]);
+    if (primitiveTypes2.has(typeText)) return false;
+    if (typeText.endsWith("[]") || typeText.startsWith("Array<")) return false;
+    return tsType.isObject() && tsType.getProperties().length > 0;
+  }
   inferPortType(tsType) {
     const typeText = tsType.getText();
     return inferDataTypeFromTS(typeText);
@@ -59279,331 +59309,6 @@ async function createNodeCommand(name, file, options = {}) {
 import * as fs11 from "fs";
 import * as path11 from "path";
 init_validator();
-function buildNodeInfo(instance, nodeType) {
-  return {
-    id: instance.id,
-    type: instance.nodeType,
-    inputs: nodeType ? Object.keys(nodeType.inputs) : [],
-    outputs: nodeType ? Object.keys(nodeType.outputs) : []
-  };
-}
-function buildAdjacency(ast) {
-  const fromStart = [];
-  const toExit = /* @__PURE__ */ new Set();
-  const edges = /* @__PURE__ */ new Map();
-  ast.connections.forEach((conn) => {
-    if (conn.from.node === "Start") {
-      if (!fromStart.includes(conn.to.node)) {
-        fromStart.push(conn.to.node);
-      }
-    } else if (conn.to.node === "Exit") {
-      toExit.add(conn.from.node);
-    } else {
-      const targets = edges.get(conn.from.node) || [];
-      if (!targets.includes(conn.to.node)) {
-        targets.push(conn.to.node);
-      }
-      edges.set(conn.from.node, targets);
-    }
-  });
-  return { fromStart, toExit, edges };
-}
-function enumeratePaths(ast) {
-  const { fromStart, toExit, edges } = buildAdjacency(ast);
-  const paths = [];
-  function dfs(current2, path42, visited) {
-    if (toExit.has(current2)) {
-      paths.push([...path42, "Exit"]);
-    }
-    const targets = edges.get(current2) || [];
-    for (const next of targets) {
-      if (!visited.has(next)) {
-        visited.add(next);
-        path42.push(next);
-        dfs(next, path42, visited);
-        path42.pop();
-        visited.delete(next);
-      }
-    }
-  }
-  fromStart.forEach((startNode) => {
-    const visited = /* @__PURE__ */ new Set([startNode]);
-    dfs(startNode, ["Start", startNode], visited);
-  });
-  return paths;
-}
-function buildGraph(ast) {
-  const { fromStart, toExit, edges } = buildAdjacency(ast);
-  const lines = [];
-  function dfs(current2, path42, visited) {
-    if (toExit.has(current2)) {
-      lines.push([...path42, "Exit"].join(" -> "));
-    }
-    const targets = edges.get(current2) || [];
-    for (const next of targets) {
-      if (!visited.has(next)) {
-        visited.add(next);
-        path42.push(next);
-        dfs(next, path42, visited);
-        path42.pop();
-        visited.delete(next);
-      }
-    }
-    if (targets.length === 0 && !toExit.has(current2)) {
-      lines.push(path42.join(" -> "));
-    }
-  }
-  fromStart.forEach((startNode) => {
-    const visited = /* @__PURE__ */ new Set([startNode]);
-    dfs(startNode, ["Start", startNode], visited);
-  });
-  return lines.join("\n");
-}
-function formatPaths(ast) {
-  const paths = enumeratePaths(ast);
-  if (paths.length === 0) return "(no complete Start-to-Exit paths found)";
-  return paths.map((p) => p.join(" -> ")).join("\n");
-}
-function generateMermaid(ast) {
-  const lines = ["graph LR"];
-  ast.instances.forEach((instance) => {
-    lines.push(`  ${instance.id}[${instance.id}: ${instance.nodeType}]`);
-  });
-  const seenEdges = /* @__PURE__ */ new Set();
-  ast.connections.forEach((conn) => {
-    const edgeKey = `${conn.from.node}->${conn.to.node}`;
-    if (!seenEdges.has(edgeKey)) {
-      seenEdges.add(edgeKey);
-      const from = conn.from.node === "Start" ? "Start((Start))" : conn.from.node;
-      const to = conn.to.node === "Exit" ? "Exit((Exit))" : conn.to.node;
-      lines.push(`  ${from} --> ${to}`);
-    }
-  });
-  return lines.join("\n");
-}
-function describeWorkflow(ast, options = {}) {
-  const { node: focusNodeId } = options;
-  const validation = validator.validate(ast);
-  const validationOutput = {
-    valid: validation.valid,
-    errors: validation.errors.map((e) => e.message),
-    warnings: validation.warnings.map((w) => w.message)
-  };
-  const nodeTypeMap = /* @__PURE__ */ new Map();
-  ast.nodeTypes.forEach((nt) => nodeTypeMap.set(nt.functionName, nt));
-  if (focusNodeId) {
-    const nodeInstance = getNode(ast, focusNodeId);
-    if (!nodeInstance) {
-      throw new Error(`Node not found: ${focusNodeId}`);
-    }
-    const nodeType = nodeTypeMap.get(nodeInstance.nodeType);
-    const incoming = getIncomingConnections(ast, focusNodeId).map((c) => ({
-      from: `${c.from.node}.${c.from.port}`,
-      to: `${c.to.node}.${c.to.port}`
-    }));
-    const outgoing = getOutgoingConnections(ast, focusNodeId).map((c) => ({
-      from: `${c.from.node}.${c.from.port}`,
-      to: `${c.to.node}.${c.to.port}`
-    }));
-    return {
-      focusNode: focusNodeId,
-      node: buildNodeInfo(nodeInstance, nodeType),
-      incoming,
-      outgoing,
-      validation: validationOutput
-    };
-  }
-  const nodes = ast.instances.map((instance) => {
-    const nodeType = nodeTypeMap.get(instance.nodeType);
-    return buildNodeInfo(instance, nodeType);
-  });
-  const connections = ast.connections.map((c) => ({
-    from: `${c.from.node}.${c.from.port}`,
-    to: `${c.to.node}.${c.to.port}`
-  }));
-  return {
-    name: ast.functionName,
-    description: ast.description || null,
-    nodes,
-    connections,
-    graph: buildGraph(ast),
-    validation: validationOutput
-  };
-}
-function formatTextOutput(ast, output) {
-  if ("focusNode" in output) {
-    const focused = output;
-    const lines2 = [];
-    lines2.push(`Node: ${focused.node.id} [${focused.node.type}]`);
-    lines2.push(`  Inputs:  ${focused.node.inputs.join(", ") || "(none)"}`);
-    lines2.push(`  Outputs: ${focused.node.outputs.join(", ") || "(none)"}`);
-    if (focused.incoming.length > 0) {
-      lines2.push("");
-      lines2.push("Incoming:");
-      focused.incoming.forEach((c) => lines2.push(`  ${c.from} -> ${c.to}`));
-    }
-    if (focused.outgoing.length > 0) {
-      lines2.push("");
-      lines2.push("Outgoing:");
-      focused.outgoing.forEach((c) => lines2.push(`  ${c.from} -> ${c.to}`));
-    }
-    return lines2.join("\n");
-  }
-  const desc = output;
-  const lines = [];
-  lines.push(`Workflow: ${desc.name}`);
-  if (desc.description) {
-    lines.push(`  ${desc.description}`);
-  }
-  const nodeTypeMap = /* @__PURE__ */ new Map();
-  ast.nodeTypes.forEach((nt) => nodeTypeMap.set(nt.functionName, nt));
-  lines.push("");
-  lines.push(`Nodes (${desc.nodes.length}):`);
-  const maxIdLen = Math.max(...desc.nodes.map((n) => n.id.length), 2);
-  const maxTypeLen = Math.max(...desc.nodes.map((n) => n.type.length), 2);
-  desc.nodes.forEach((node) => {
-    const id = node.id.padEnd(maxIdLen);
-    const type2 = `[${node.type}]`.padEnd(maxTypeLen + 2);
-    const nodeType = nodeTypeMap.get(node.type);
-    const isExpression = nodeType?.expression === true;
-    const scopeNames = nodeType?.scopes ?? (nodeType?.scope ? [nodeType.scope] : []);
-    const filterPorts = (ports, direction) => {
-      if (!isExpression || !nodeType) return ports;
-      return ports.filter((portName) => {
-        if (portName === "execute" || portName === "onSuccess" || portName === "onFailure") {
-          return false;
-        }
-        const portDef = direction === "input" ? nodeType.inputs[portName] : nodeType.outputs[portName];
-        return !(portDef?.isControlFlow || portDef?.dataType === "STEP");
-      });
-    };
-    if (scopeNames.length > 0 && nodeType) {
-      const regularInputs = [];
-      const regularOutputs = [];
-      const scopedPorts = {};
-      scopeNames.forEach((s) => {
-        scopedPorts[s] = { sends: [], receives: [], children: [] };
-      });
-      Object.entries(nodeType.inputs).forEach(([name, port]) => {
-        if (port.scope && scopedPorts[port.scope]) {
-          scopedPorts[port.scope].receives.push(name + (port.isControlFlow ? " (STEP)" : ""));
-        } else {
-          regularInputs.push(name);
-        }
-      });
-      Object.entries(nodeType.outputs).forEach(([name, port]) => {
-        if (port.scope && scopedPorts[port.scope]) {
-          scopedPorts[port.scope].sends.push(name + (port.isControlFlow ? " (STEP)" : ""));
-        } else {
-          regularOutputs.push(name);
-        }
-      });
-      if (ast.scopes) {
-        for (const [scopeKey, childIds] of Object.entries(ast.scopes)) {
-          const dotIdx = scopeKey.indexOf(".");
-          const scopeName = dotIdx >= 0 ? scopeKey.substring(dotIdx + 1) : scopeKey;
-          if (scopedPorts[scopeName]) {
-            scopedPorts[scopeName].children.push(...childIds);
-          }
-        }
-      }
-      const ins = regularInputs.length > 0 ? `IN: ${regularInputs.join(", ")}` : "";
-      const outs = regularOutputs.length > 0 ? `OUT: ${regularOutputs.join(", ")}` : "";
-      const ports = [ins, outs].filter(Boolean).join("  ");
-      lines.push(`  ${id}  ${type2}  ${ports}`);
-      for (const [scopeName, info] of Object.entries(scopedPorts)) {
-        lines.push(`    Scope "${scopeName}":`);
-        if (info.sends.length > 0) {
-          lines.push(`      Sends to children: ${info.sends.join(", ")}`);
-        }
-        if (info.receives.length > 0) {
-          lines.push(`      Receives from children: ${info.receives.join(", ")}`);
-        }
-        if (info.children.length > 0) {
-          lines.push(`      Children: ${info.children.join(", ")}`);
-        }
-      }
-    } else {
-      const filteredInputs = filterPorts(node.inputs, "input");
-      const filteredOutputs = filterPorts(node.outputs, "output");
-      const ins = filteredInputs.length > 0 ? `IN: ${filteredInputs.join(", ")}` : "";
-      const outs = filteredOutputs.length > 0 ? `OUT: ${filteredOutputs.join(", ")}` : "";
-      const ports = [ins, outs].filter(Boolean).join("  ");
-      lines.push(`  ${id}  ${type2}  ${ports}`);
-    }
-  });
-  if (desc.graph) {
-    lines.push("");
-    const paths = enumeratePaths(ast);
-    if (paths.length > 1) {
-      lines.push(`Paths (${paths.length}):`);
-      paths.forEach((p, i) => {
-        lines.push(`  Path ${i + 1}: ${p.join(" -> ")}`);
-      });
-    } else {
-      lines.push("Flow:");
-      desc.graph.split("\n").forEach((flowLine) => {
-        lines.push(`  ${flowLine}`);
-      });
-    }
-  }
-  lines.push("");
-  lines.push(
-    `Validation: ${desc.validation.errors.length} errors, ${desc.validation.warnings.length} warnings`
-  );
-  return lines.join("\n");
-}
-function formatDescribeOutput(ast, output, format) {
-  switch (format) {
-    case "text":
-      return formatTextOutput(ast, output);
-    case "mermaid":
-      return generateMermaid(ast);
-    case "paths":
-      return formatPaths(ast);
-    case "json":
-    default:
-      return JSON.stringify(output, null, 2);
-  }
-}
-async function describeCommand(input, options = {}) {
-  const { format = "json", node: focusNodeId, workflowName, compile = false } = options;
-  const filePath = path11.resolve(input);
-  if (!fs11.existsSync(filePath)) {
-    logger.error(`File not found: ${filePath}`);
-    process.exit(1);
-  }
-  try {
-    const parseResult = await parseWorkflow(filePath, { workflowName });
-    if (parseResult.errors.length > 0) {
-      logger.error(`Parse errors:`);
-      parseResult.errors.forEach((err) => logger.error(`  ${err}`));
-      process.exit(1);
-    }
-    const ast = parseResult.ast;
-    if (compile) {
-      const sourceCode = fs11.readFileSync(filePath, "utf8");
-      const generated = generateInPlace(sourceCode, ast, { production: false });
-      if (generated.hasChanges) {
-        fs11.writeFileSync(filePath, generated.code, "utf8");
-        logger.info(`Updated runtime markers in ${path11.basename(filePath)}`);
-      }
-    }
-    const output = describeWorkflow(ast, { node: focusNodeId });
-    console.log(formatDescribeOutput(ast, output, format));
-  } catch (error2) {
-    if (error2 instanceof Error && error2.message.startsWith("Node not found:")) {
-      logger.error(error2.message);
-      process.exit(1);
-    }
-    logger.error(`Failed to describe workflow: ${getErrorMessage(error2)}`);
-    process.exit(1);
-  }
-}
-
-// src/cli/commands/diagram.ts
-import * as fs12 from "fs";
-import * as path12 from "path";
 
 // src/diagram/geometry.ts
 init_constants();
@@ -61257,6 +60962,772 @@ function maxPortLabelExtent(ports) {
   return max;
 }
 
+// src/diagram/ascii-renderer.ts
+function groupByLayer(nodes) {
+  if (nodes.length === 0) return [];
+  const sorted = [...nodes].sort((a, b) => a.x - b.x);
+  const layers = [];
+  let currentX = sorted[0].x;
+  let currentLayer = [];
+  for (const node of sorted) {
+    if (Math.abs(node.x - currentX) > 10) {
+      layers.push(currentLayer);
+      currentLayer = [];
+      currentX = node.x;
+    }
+    currentLayer.push(node);
+  }
+  if (currentLayer.length > 0) layers.push(currentLayer);
+  return layers;
+}
+function buildConnectedPorts(connections) {
+  const s = /* @__PURE__ */ new Set();
+  for (const c of connections) {
+    s.add(`${c.fromNode}.${c.fromPort}`);
+    s.add(`${c.toNode}.${c.toPort}`);
+  }
+  return s;
+}
+function portSymbol(nodeId, port, connected) {
+  return connected.has(`${nodeId}.${port.name}`) ? "\u25CF" : "\u25CB";
+}
+function cornerChar(isStep, hDir, vDir) {
+  if (hDir === "right" && vDir === "down") return isStep ? "\u2554" : "\u250C";
+  if (hDir === "left" && vDir === "down") return isStep ? "\u2557" : "\u2510";
+  if (hDir === "right" && vDir === "up") return isStep ? "\u255A" : "\u2514";
+  if (hDir === "left" && vDir === "up") return isStep ? "\u255D" : "\u2518";
+  return "\u253C";
+}
+var H_CHARS = new Set("\u2500\u2550");
+var V_CHARS = new Set("\u2502\u2551");
+var CharGrid = class {
+  cells;
+  width;
+  height;
+  constructor(w, h) {
+    this.width = w;
+    this.height = h;
+    this.cells = new Array(w * h).fill(" ");
+  }
+  set(x, y, ch) {
+    if (x < 0 || x >= this.width || y < 0 || y >= this.height) return;
+    const existing = this.cells[y * this.width + x];
+    if (existing !== " ") {
+      if (H_CHARS.has(ch) && V_CHARS.has(existing) || V_CHARS.has(ch) && H_CHARS.has(existing)) {
+        this.cells[y * this.width + x] = "\u253C";
+        return;
+      }
+      if (H_CHARS.has(ch) && H_CHARS.has(existing) || V_CHARS.has(ch) && V_CHARS.has(existing)) {
+        return;
+      }
+    }
+    this.cells[y * this.width + x] = ch;
+  }
+  get(x, y) {
+    if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
+      return this.cells[y * this.width + x];
+    }
+    return " ";
+  }
+  /** Force-write, ignoring collision logic (for boxes and text). */
+  forceSet(x, y, ch) {
+    if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
+      this.cells[y * this.width + x] = ch;
+    }
+  }
+  writeStr(x, y, s) {
+    for (let i = 0; i < s.length; i++) {
+      this.forceSet(x + i, y, s[i]);
+    }
+  }
+  toLines() {
+    const lines = [];
+    for (let y = 0; y < this.height; y++) {
+      let line = "";
+      for (let x = 0; x < this.width; x++) {
+        line += this.cells[y * this.width + x];
+      }
+      lines.push(line.trimEnd());
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    return lines;
+  }
+};
+function mergePortRows(inputs, outputs) {
+  const rows = [];
+  const maxLen = Math.max(inputs.length, outputs.length);
+  for (let i = 0; i < maxLen; i++) {
+    rows.push({
+      input: i < inputs.length ? inputs[i] : null,
+      output: i < outputs.length ? outputs[i] : null
+    });
+  }
+  return rows;
+}
+function measureBox(node) {
+  const portRows = mergePortRows(node.inputs, node.outputs);
+  const maxInputPortLen = node.inputs.length > 0 ? Math.max(...node.inputs.map((p) => p.name.length)) : 0;
+  const maxOutputPortLen = node.outputs.length > 0 ? Math.max(...node.outputs.map((p) => p.name.length)) : 0;
+  const portsContentWidth = (maxInputPortLen > 0 ? maxInputPortLen + 2 : 0) + 2 + (maxOutputPortLen > 0 ? maxOutputPortLen + 2 : 0);
+  const innerWidth = Math.max(node.label.length + 2, portsContentWidth, 10);
+  const boxWidth = innerWidth + 2;
+  const headerRows = 3;
+  const portRowCount = Math.max(portRows.length, 1);
+  const boxHeight = headerRows + portRowCount + 1;
+  const portRowOffsets = /* @__PURE__ */ new Map();
+  for (let i = 0; i < portRows.length; i++) {
+    if (portRows[i].input) portRowOffsets.set(portRows[i].input.name, headerRows + i);
+    if (portRows[i].output) portRowOffsets.set(portRows[i].output.name, headerRows + i);
+  }
+  return { node, innerWidth, boxWidth, portRows, boxHeight, portRowOffsets };
+}
+function drawBox(grid, box, bx, by, connected) {
+  const { innerWidth, portRows, node } = box;
+  grid.forceSet(bx, by, "\u250C");
+  for (let i = 0; i < innerWidth; i++) grid.forceSet(bx + 1 + i, by, "\u2500");
+  grid.forceSet(bx + innerWidth + 1, by, "\u2510");
+  const labelPad = innerWidth - node.label.length;
+  const padL = Math.floor(labelPad / 2);
+  grid.forceSet(bx, by + 1, "\u2502");
+  grid.writeStr(bx + 1 + padL, by + 1, node.label);
+  grid.forceSet(bx + innerWidth + 1, by + 1, "\u2502");
+  grid.forceSet(bx, by + 2, "\u251C");
+  for (let i = 0; i < innerWidth; i++) grid.forceSet(bx + 1 + i, by + 2, "\u2500");
+  grid.forceSet(bx + innerWidth + 1, by + 2, "\u2524");
+  for (let i = 0; i < Math.max(portRows.length, 1); i++) {
+    const ry = by + 3 + i;
+    grid.forceSet(bx, ry, "\u2502");
+    grid.forceSet(bx + innerWidth + 1, ry, "\u2502");
+    if (i < portRows.length) {
+      const row = portRows[i];
+      if (row.input) {
+        grid.writeStr(bx + 1, ry, `${portSymbol(node.id, row.input, connected)} ${row.input.name}`);
+      }
+      if (row.output) {
+        const txt = `${row.output.name} ${portSymbol(node.id, row.output, connected)}`;
+        grid.writeStr(bx + innerWidth + 1 - txt.length, ry, txt);
+      }
+    }
+  }
+  const bottomY = by + box.boxHeight - 1;
+  grid.forceSet(bx, bottomY, "\u2514");
+  for (let i = 0; i < innerWidth; i++) grid.forceSet(bx + 1 + i, bottomY, "\u2500");
+  grid.forceSet(bx + innerWidth + 1, bottomY, "\u2518");
+}
+function renderASCII(graph) {
+  const layers = groupByLayer(graph.nodes);
+  if (layers.length === 0) return `${graph.workflowName}
+(empty workflow)`;
+  const layerBoxes = layers.map((layer) => layer.map(measureBox));
+  const colWidths = layerBoxes.map((boxes) => Math.max(...boxes.map((b) => b.boxWidth)));
+  const wireGap = 14;
+  const colX = [];
+  let cx = 1;
+  for (let c = 0; c < layerBoxes.length; c++) {
+    colX.push(cx);
+    cx += colWidths[c] + wireGap;
+  }
+  const gridWidth = cx + 1;
+  const nodeColMap = /* @__PURE__ */ new Map();
+  for (let c = 0; c < layerBoxes.length; c++) {
+    for (const box of layerBoxes[c]) nodeColMap.set(box.node.id, c);
+  }
+  let spanCount = 0;
+  for (const conn of graph.connections) {
+    const fc = nodeColMap.get(conn.fromNode);
+    const tc = nodeColMap.get(conn.toNode);
+    if (fc !== void 0 && tc !== void 0 && Math.abs(tc - fc) > 1) spanCount++;
+  }
+  const highwayMargin = spanCount > 0 ? spanCount + 1 : 0;
+  const nodeGapY = 2;
+  const boxPositions = /* @__PURE__ */ new Map();
+  const boxStartY = 3 + highwayMargin;
+  let maxGridHeight = 0;
+  for (let c = 0; c < layerBoxes.length; c++) {
+    let y = boxStartY;
+    for (const box of layerBoxes[c]) {
+      boxPositions.set(box.node.id, { col: c, bx: colX[c], by: y, box });
+      y += box.boxHeight + nodeGapY;
+    }
+    if (y > maxGridHeight) maxGridHeight = y;
+  }
+  maxGridHeight += highwayMargin + 3;
+  const connected = buildConnectedPorts(graph.connections);
+  const grid = new CharGrid(gridWidth, maxGridHeight);
+  const titleX = Math.max(0, Math.floor((gridWidth - graph.workflowName.length) / 2));
+  grid.writeStr(titleX, 1, graph.workflowName);
+  for (const pos of boxPositions.values()) {
+    drawBox(grid, pos.box, pos.bx, pos.by, connected);
+  }
+  drawConnections(grid, graph.connections, boxPositions, boxStartY, maxGridHeight);
+  const scopeLines = [];
+  for (const node of graph.nodes) {
+    if (node.scopeChildren && node.scopeChildren.length > 0) {
+      scopeLines.push("");
+      scopeLines.push(` Scope [${node.label}]:`);
+      if (node.scopeConnections) {
+        for (const sc of node.scopeConnections) {
+          const arrow = sc.isStepConnection ? "\u2550\u2550\u25B6" : "\u2500\u2500\u25B6";
+          scopeLines.push(`   ${sc.fromNode}.${sc.fromPort} ${arrow} ${sc.toNode}.${sc.toPort}${sc.isStepConnection ? "  STEP" : ""}`);
+        }
+      }
+    }
+  }
+  const lines = grid.toLines();
+  lines.push(...scopeLines);
+  lines.push("");
+  lines.push(" \u25CF connected  \u25CB not connected  \u2550\u2550\u25B6 STEP  \u2500\u2500\u25B6 DATA");
+  return lines.join("\n");
+}
+function drawConnections(grid, connections, positions, boxAreaTop, _gridHeight) {
+  let globalMinY = Infinity;
+  let globalMaxY = 0;
+  for (const pos of positions.values()) {
+    globalMinY = Math.min(globalMinY, pos.by);
+    globalMaxY = Math.max(globalMaxY, pos.by + pos.box.boxHeight);
+  }
+  const sorted = [...connections].sort((a, b) => {
+    const fa = positions.get(a.fromNode);
+    const ta = positions.get(a.toNode);
+    const fb = positions.get(b.fromNode);
+    const tb = positions.get(b.toNode);
+    if (!fa || !ta || !fb || !tb) return 0;
+    const spanA = Math.abs(ta.col - fa.col);
+    const spanB = Math.abs(tb.col - fb.col);
+    if (spanA !== spanB) return spanA - spanB;
+    const ya = fa.by + (fa.box.portRowOffsets.get(a.fromPort) ?? 0);
+    const yb = fb.by + (fb.box.portRowOffsets.get(b.fromPort) ?? 0);
+    return ya - yb;
+  });
+  const usedTracks = /* @__PURE__ */ new Map();
+  let nextAboveHighway = globalMinY - 2;
+  let nextBelowHighway = globalMaxY + 1;
+  for (const conn of sorted) {
+    const fromPos = positions.get(conn.fromNode);
+    const toPos = positions.get(conn.toNode);
+    if (!fromPos || !toPos) continue;
+    const fromRowOff = fromPos.box.portRowOffsets.get(conn.fromPort);
+    const toRowOff = toPos.box.portRowOffsets.get(conn.toPort);
+    if (fromRowOff === void 0 || toRowOff === void 0) continue;
+    const y1 = fromPos.by + fromRowOff;
+    const y2 = toPos.by + toRowOff;
+    const x1 = fromPos.bx + fromPos.box.boxWidth;
+    const x2 = toPos.bx - 1;
+    const isStep = conn.isStepConnection;
+    const hCh = isStep ? "\u2550" : "\u2500";
+    const vCh = isStep ? "\u2551" : "\u2502";
+    const isAdjacent = toPos.col === fromPos.col + 1;
+    if (isAdjacent) {
+      drawAdjacentRoute(grid, x1, y1, x2, y2, hCh, vCh, isStep, usedTracks, fromPos, toPos);
+    } else {
+      const avgY = (y1 + y2) / 2;
+      const midBoxY = (globalMinY + globalMaxY) / 2;
+      let highwayY;
+      if (avgY <= midBoxY) {
+        highwayY = nextAboveHighway;
+        nextAboveHighway--;
+      } else {
+        highwayY = nextBelowHighway;
+        nextBelowHighway++;
+      }
+      drawSpanningRoute(grid, x1, y1, x2, y2, highwayY, hCh, vCh, isStep, usedTracks, fromPos, toPos);
+    }
+  }
+}
+function drawAdjacentRoute(grid, x1, y1, x2, y2, hCh, vCh, isStep, usedTracks, fromPos, toPos) {
+  if (y1 === y2) {
+    for (let x = x1; x < x2; x++) grid.set(x, y1, hCh);
+    grid.set(x2, y1, "\u25B6");
+    return;
+  }
+  const gapStart = fromPos.bx + fromPos.box.boxWidth + 1;
+  const gapEnd = toPos.bx - 2;
+  const midX = findTrack(usedTracks, gapStart, gapEnd, y1, y2);
+  markTrack(usedTracks, midX, y1, y2);
+  for (let x = x1; x < midX; x++) grid.set(x, y1, hCh);
+  grid.set(midX, y1, cornerChar(isStep, "left", y2 > y1 ? "down" : "up"));
+  drawVerticalSegment(grid, midX, y1, y2, vCh);
+  grid.set(midX, y2, cornerChar(isStep, "right", y2 > y1 ? "up" : "down"));
+  for (let x = midX + 1; x < x2; x++) grid.set(x, y2, hCh);
+  grid.set(x2, y2, "\u25B6");
+}
+function drawSpanningRoute(grid, x1, y1, x2, y2, highwayY, hCh, vCh, isStep, usedTracks, fromPos, toPos) {
+  const srcGapStart = fromPos.bx + fromPos.box.boxWidth + 1;
+  const srcGapEnd = srcGapStart + 10;
+  const srcMidX = findTrack(usedTracks, srcGapStart, srcGapEnd, y1, highwayY);
+  markTrack(usedTracks, srcMidX, y1, highwayY);
+  const tgtGapEnd = toPos.bx - 2;
+  const tgtGapStart = tgtGapEnd - 10;
+  const tgtMidX = findTrack(usedTracks, tgtGapStart, tgtGapEnd, highwayY, y2);
+  markTrack(usedTracks, tgtMidX, highwayY, y2);
+  const goingDown = highwayY > y1;
+  const goingUp = y2 < highwayY;
+  for (let x = x1; x < srcMidX; x++) grid.set(x, y1, hCh);
+  grid.set(srcMidX, y1, cornerChar(isStep, "left", goingDown ? "down" : "up"));
+  drawVerticalSegment(grid, srcMidX, y1, highwayY, vCh);
+  grid.set(srcMidX, highwayY, cornerChar(isStep, "right", goingDown ? "up" : "down"));
+  for (let x = srcMidX + 1; x < tgtMidX; x++) grid.set(x, highwayY, hCh);
+  grid.set(tgtMidX, highwayY, cornerChar(isStep, "left", goingUp ? "up" : "down"));
+  drawVerticalSegment(grid, tgtMidX, highwayY, y2, vCh);
+  grid.set(tgtMidX, y2, cornerChar(isStep, "right", goingUp ? "down" : "up"));
+  for (let x = tgtMidX + 1; x < x2; x++) grid.set(x, y2, hCh);
+  grid.set(x2, y2, "\u25B6");
+}
+function drawVerticalSegment(grid, x, y1, y2, vCh) {
+  const minY = Math.min(y1, y2);
+  const maxY = Math.max(y1, y2);
+  for (let y = minY + 1; y < maxY; y++) {
+    grid.set(x, y, vCh);
+  }
+}
+function findTrack(usedTracks, gapStart, gapEnd, y1, y2) {
+  const minY = Math.min(y1, y2);
+  const maxY = Math.max(y1, y2);
+  const actualStart = Math.min(gapStart, gapEnd);
+  const actualEnd = Math.max(gapStart, gapEnd);
+  const mid = Math.floor((actualStart + actualEnd) / 2);
+  for (let offset = 0; offset <= actualEnd - actualStart; offset++) {
+    for (const candidate of [mid + offset, mid - offset]) {
+      if (candidate < actualStart || candidate > actualEnd) continue;
+      const existing = usedTracks.get(candidate);
+      if (!existing) return candidate;
+      let conflict = false;
+      for (let y = minY; y <= maxY; y++) {
+        if (existing.has(y)) {
+          conflict = true;
+          break;
+        }
+      }
+      if (!conflict) return candidate;
+    }
+  }
+  return mid;
+}
+function markTrack(usedTracks, x, y1, y2) {
+  if (!usedTracks.has(x)) usedTracks.set(x, /* @__PURE__ */ new Set());
+  const s = usedTracks.get(x);
+  const minY = Math.min(y1, y2);
+  const maxY = Math.max(y1, y2);
+  for (let y = minY; y <= maxY; y++) s.add(y);
+}
+function renderASCIICompact(graph) {
+  const layers = groupByLayer(graph.nodes);
+  if (layers.length === 0) return `${graph.workflowName}
+(empty workflow)`;
+  const outputLines = [];
+  outputLines.push(graph.workflowName);
+  outputLines.push("");
+  const mainChain = [];
+  const parallelNodes = [];
+  for (const layer of layers) {
+    mainChain.push(layer[0]);
+    for (let i = 1; i < layer.length; i++) parallelNodes.push(layer[i]);
+  }
+  const topParts = [];
+  const midParts = [];
+  const botParts = [];
+  for (let i = 0; i < mainChain.length; i++) {
+    const node = mainChain[i];
+    const innerWidth = Math.max(node.label.length + 2, 5);
+    const padLeft = Math.floor((innerWidth - node.label.length) / 2);
+    const padRight = innerWidth - node.label.length - padLeft;
+    topParts.push("\u250C" + "\u2500".repeat(innerWidth) + "\u2510");
+    midParts.push("\u2502" + " ".repeat(padLeft) + node.label + " ".repeat(padRight) + "\u2502");
+    botParts.push("\u2514" + "\u2500".repeat(innerWidth) + "\u2518");
+    if (i < mainChain.length - 1) {
+      topParts.push("    ");
+      midParts.push("\u2501\u2501\u2501\u25B6");
+      botParts.push("    ");
+    }
+  }
+  outputLines.push(" " + topParts.join(""));
+  outputLines.push(" " + midParts.join(""));
+  outputLines.push(" " + botParts.join(""));
+  if (parallelNodes.length > 0) {
+    outputLines.push("");
+    outputLines.push(" Parallel: " + parallelNodes.map((n) => n.label).join(", "));
+  }
+  for (const node of graph.nodes) {
+    if (node.scopeChildren && node.scopeChildren.length > 0) {
+      outputLines.push("");
+      outputLines.push(` Scope [${node.label}]: ` + node.scopeChildren.map((c) => c.label).join(" \u2501\u25B6 "));
+    }
+  }
+  return outputLines.join("\n");
+}
+function renderText(graph) {
+  const lines = [];
+  const connected = buildConnectedPorts(graph.connections);
+  lines.push(graph.workflowName);
+  lines.push("\u2550".repeat(graph.workflowName.length));
+  lines.push("");
+  lines.push("Nodes:");
+  const maxLabelLen = Math.max(...graph.nodes.map((n) => n.label.length), 5);
+  for (const node of graph.nodes) {
+    const label = node.label.padEnd(maxLabelLen);
+    const inputPorts = node.inputs.map((p) => `${p.name}${portSymbol(node.id, p, connected)}`);
+    const outputPorts = node.outputs.map((p) => `${p.name}${portSymbol(node.id, p, connected)}`);
+    const inputStr = inputPorts.length > 0 ? `[${inputPorts.join(", ")}]` : "";
+    const outputStr = outputPorts.length > 0 ? `[${outputPorts.join(", ")}]` : "";
+    if (inputStr && outputStr) {
+      lines.push(`  ${label}  ${inputStr} \u2192 ${outputStr}`);
+    } else if (outputStr) {
+      lines.push(`  ${label}  ${outputStr}`);
+    } else if (inputStr) {
+      lines.push(`  ${label}  ${inputStr}`);
+    } else {
+      lines.push(`  ${label}`);
+    }
+    if (node.scopeChildren && node.scopeChildren.length > 0) {
+      lines.push(`  ${" ".repeat(maxLabelLen)}    scope: ${node.scopeChildren.map((c) => c.label).join(", ")}`);
+    }
+  }
+  if (graph.connections.length > 0) {
+    lines.push("");
+    lines.push("Connections:");
+    const maxFromLen = Math.max(...graph.connections.map((c) => `${c.fromNode}.${c.fromPort}`.length));
+    for (const conn of graph.connections) {
+      const from = `${conn.fromNode}.${conn.fromPort}`.padEnd(maxFromLen);
+      const arrow = conn.isStepConnection ? "\u2501\u2501\u25B6" : "\u2500\u2500\u25B6";
+      const to = `${conn.toNode}.${conn.toPort}`;
+      const type2 = conn.isStepConnection ? "STEP" : "";
+      lines.push(`  ${from}  ${arrow} ${to}${type2 ? "  " + type2 : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/cli/commands/describe.ts
+function buildNodeInfo(instance, nodeType) {
+  return {
+    id: instance.id,
+    type: instance.nodeType,
+    inputs: nodeType ? Object.keys(nodeType.inputs) : [],
+    outputs: nodeType ? Object.keys(nodeType.outputs) : []
+  };
+}
+function buildAdjacency(ast) {
+  const fromStart = [];
+  const toExit = /* @__PURE__ */ new Set();
+  const edges = /* @__PURE__ */ new Map();
+  ast.connections.forEach((conn) => {
+    if (conn.from.node === "Start") {
+      if (!fromStart.includes(conn.to.node)) {
+        fromStart.push(conn.to.node);
+      }
+    } else if (conn.to.node === "Exit") {
+      toExit.add(conn.from.node);
+    } else {
+      const targets = edges.get(conn.from.node) || [];
+      if (!targets.includes(conn.to.node)) {
+        targets.push(conn.to.node);
+      }
+      edges.set(conn.from.node, targets);
+    }
+  });
+  return { fromStart, toExit, edges };
+}
+function enumeratePaths(ast) {
+  const { fromStart, toExit, edges } = buildAdjacency(ast);
+  const paths = [];
+  function dfs(current2, path42, visited) {
+    if (toExit.has(current2)) {
+      paths.push([...path42, "Exit"]);
+    }
+    const targets = edges.get(current2) || [];
+    for (const next of targets) {
+      if (!visited.has(next)) {
+        visited.add(next);
+        path42.push(next);
+        dfs(next, path42, visited);
+        path42.pop();
+        visited.delete(next);
+      }
+    }
+  }
+  fromStart.forEach((startNode) => {
+    const visited = /* @__PURE__ */ new Set([startNode]);
+    dfs(startNode, ["Start", startNode], visited);
+  });
+  return paths;
+}
+function buildGraph(ast) {
+  const { fromStart, toExit, edges } = buildAdjacency(ast);
+  const lines = [];
+  function dfs(current2, path42, visited) {
+    if (toExit.has(current2)) {
+      lines.push([...path42, "Exit"].join(" -> "));
+    }
+    const targets = edges.get(current2) || [];
+    for (const next of targets) {
+      if (!visited.has(next)) {
+        visited.add(next);
+        path42.push(next);
+        dfs(next, path42, visited);
+        path42.pop();
+        visited.delete(next);
+      }
+    }
+    if (targets.length === 0 && !toExit.has(current2)) {
+      lines.push(path42.join(" -> "));
+    }
+  }
+  fromStart.forEach((startNode) => {
+    const visited = /* @__PURE__ */ new Set([startNode]);
+    dfs(startNode, ["Start", startNode], visited);
+  });
+  return lines.join("\n");
+}
+function formatPaths(ast) {
+  const paths = enumeratePaths(ast);
+  if (paths.length === 0) return "(no complete Start-to-Exit paths found)";
+  return paths.map((p) => p.join(" -> ")).join("\n");
+}
+function generateMermaid(ast) {
+  const lines = ["graph LR"];
+  ast.instances.forEach((instance) => {
+    lines.push(`  ${instance.id}[${instance.id}: ${instance.nodeType}]`);
+  });
+  const seenEdges = /* @__PURE__ */ new Set();
+  ast.connections.forEach((conn) => {
+    const edgeKey = `${conn.from.node}->${conn.to.node}`;
+    if (!seenEdges.has(edgeKey)) {
+      seenEdges.add(edgeKey);
+      const from = conn.from.node === "Start" ? "Start((Start))" : conn.from.node;
+      const to = conn.to.node === "Exit" ? "Exit((Exit))" : conn.to.node;
+      lines.push(`  ${from} --> ${to}`);
+    }
+  });
+  return lines.join("\n");
+}
+function describeWorkflow(ast, options = {}) {
+  const { node: focusNodeId } = options;
+  const validation = validator.validate(ast);
+  const validationOutput = {
+    valid: validation.valid,
+    errors: validation.errors.map((e) => e.message),
+    warnings: validation.warnings.map((w) => w.message)
+  };
+  const nodeTypeMap = /* @__PURE__ */ new Map();
+  ast.nodeTypes.forEach((nt) => nodeTypeMap.set(nt.functionName, nt));
+  if (focusNodeId) {
+    const nodeInstance = getNode(ast, focusNodeId);
+    if (!nodeInstance) {
+      throw new Error(`Node not found: ${focusNodeId}`);
+    }
+    const nodeType = nodeTypeMap.get(nodeInstance.nodeType);
+    const incoming = getIncomingConnections(ast, focusNodeId).map((c) => ({
+      from: `${c.from.node}.${c.from.port}`,
+      to: `${c.to.node}.${c.to.port}`
+    }));
+    const outgoing = getOutgoingConnections(ast, focusNodeId).map((c) => ({
+      from: `${c.from.node}.${c.from.port}`,
+      to: `${c.to.node}.${c.to.port}`
+    }));
+    return {
+      focusNode: focusNodeId,
+      node: buildNodeInfo(nodeInstance, nodeType),
+      incoming,
+      outgoing,
+      validation: validationOutput
+    };
+  }
+  const nodes = ast.instances.map((instance) => {
+    const nodeType = nodeTypeMap.get(instance.nodeType);
+    return buildNodeInfo(instance, nodeType);
+  });
+  const connections = ast.connections.map((c) => ({
+    from: `${c.from.node}.${c.from.port}`,
+    to: `${c.to.node}.${c.to.port}`
+  }));
+  return {
+    name: ast.functionName,
+    description: ast.description || null,
+    nodes,
+    connections,
+    graph: buildGraph(ast),
+    validation: validationOutput
+  };
+}
+function formatTextOutput(ast, output) {
+  if ("focusNode" in output) {
+    const focused = output;
+    const lines2 = [];
+    lines2.push(`Node: ${focused.node.id} [${focused.node.type}]`);
+    lines2.push(`  Inputs:  ${focused.node.inputs.join(", ") || "(none)"}`);
+    lines2.push(`  Outputs: ${focused.node.outputs.join(", ") || "(none)"}`);
+    if (focused.incoming.length > 0) {
+      lines2.push("");
+      lines2.push("Incoming:");
+      focused.incoming.forEach((c) => lines2.push(`  ${c.from} -> ${c.to}`));
+    }
+    if (focused.outgoing.length > 0) {
+      lines2.push("");
+      lines2.push("Outgoing:");
+      focused.outgoing.forEach((c) => lines2.push(`  ${c.from} -> ${c.to}`));
+    }
+    return lines2.join("\n");
+  }
+  const desc = output;
+  const lines = [];
+  lines.push(`Workflow: ${desc.name}`);
+  if (desc.description) {
+    lines.push(`  ${desc.description}`);
+  }
+  const nodeTypeMap = /* @__PURE__ */ new Map();
+  ast.nodeTypes.forEach((nt) => nodeTypeMap.set(nt.functionName, nt));
+  lines.push("");
+  lines.push(`Nodes (${desc.nodes.length}):`);
+  const maxIdLen = Math.max(...desc.nodes.map((n) => n.id.length), 2);
+  const maxTypeLen = Math.max(...desc.nodes.map((n) => n.type.length), 2);
+  desc.nodes.forEach((node) => {
+    const id = node.id.padEnd(maxIdLen);
+    const type2 = `[${node.type}]`.padEnd(maxTypeLen + 2);
+    const nodeType = nodeTypeMap.get(node.type);
+    const isExpression = nodeType?.expression === true;
+    const scopeNames = nodeType?.scopes ?? (nodeType?.scope ? [nodeType.scope] : []);
+    const filterPorts = (ports, direction) => {
+      if (!isExpression || !nodeType) return ports;
+      return ports.filter((portName) => {
+        if (portName === "execute" || portName === "onSuccess" || portName === "onFailure") {
+          return false;
+        }
+        const portDef = direction === "input" ? nodeType.inputs[portName] : nodeType.outputs[portName];
+        return !(portDef?.isControlFlow || portDef?.dataType === "STEP");
+      });
+    };
+    if (scopeNames.length > 0 && nodeType) {
+      const regularInputs = [];
+      const regularOutputs = [];
+      const scopedPorts = {};
+      scopeNames.forEach((s) => {
+        scopedPorts[s] = { sends: [], receives: [], children: [] };
+      });
+      Object.entries(nodeType.inputs).forEach(([name, port]) => {
+        if (port.scope && scopedPorts[port.scope]) {
+          scopedPorts[port.scope].receives.push(name + (port.isControlFlow ? " (STEP)" : ""));
+        } else {
+          regularInputs.push(name);
+        }
+      });
+      Object.entries(nodeType.outputs).forEach(([name, port]) => {
+        if (port.scope && scopedPorts[port.scope]) {
+          scopedPorts[port.scope].sends.push(name + (port.isControlFlow ? " (STEP)" : ""));
+        } else {
+          regularOutputs.push(name);
+        }
+      });
+      if (ast.scopes) {
+        for (const [scopeKey, childIds] of Object.entries(ast.scopes)) {
+          const dotIdx = scopeKey.indexOf(".");
+          const scopeName = dotIdx >= 0 ? scopeKey.substring(dotIdx + 1) : scopeKey;
+          if (scopedPorts[scopeName]) {
+            scopedPorts[scopeName].children.push(...childIds);
+          }
+        }
+      }
+      const ins = regularInputs.length > 0 ? `IN: ${regularInputs.join(", ")}` : "";
+      const outs = regularOutputs.length > 0 ? `OUT: ${regularOutputs.join(", ")}` : "";
+      const ports = [ins, outs].filter(Boolean).join("  ");
+      lines.push(`  ${id}  ${type2}  ${ports}`);
+      for (const [scopeName, info] of Object.entries(scopedPorts)) {
+        lines.push(`    Scope "${scopeName}":`);
+        if (info.sends.length > 0) {
+          lines.push(`      Sends to children: ${info.sends.join(", ")}`);
+        }
+        if (info.receives.length > 0) {
+          lines.push(`      Receives from children: ${info.receives.join(", ")}`);
+        }
+        if (info.children.length > 0) {
+          lines.push(`      Children: ${info.children.join(", ")}`);
+        }
+      }
+    } else {
+      const filteredInputs = filterPorts(node.inputs, "input");
+      const filteredOutputs = filterPorts(node.outputs, "output");
+      const ins = filteredInputs.length > 0 ? `IN: ${filteredInputs.join(", ")}` : "";
+      const outs = filteredOutputs.length > 0 ? `OUT: ${filteredOutputs.join(", ")}` : "";
+      const ports = [ins, outs].filter(Boolean).join("  ");
+      lines.push(`  ${id}  ${type2}  ${ports}`);
+    }
+  });
+  if (desc.graph) {
+    lines.push("");
+    const paths = enumeratePaths(ast);
+    if (paths.length > 1) {
+      lines.push(`Paths (${paths.length}):`);
+      paths.forEach((p, i) => {
+        lines.push(`  Path ${i + 1}: ${p.join(" -> ")}`);
+      });
+    } else {
+      lines.push("Flow:");
+      desc.graph.split("\n").forEach((flowLine) => {
+        lines.push(`  ${flowLine}`);
+      });
+    }
+  }
+  lines.push("");
+  lines.push(
+    `Validation: ${desc.validation.errors.length} errors, ${desc.validation.warnings.length} warnings`
+  );
+  return lines.join("\n");
+}
+function formatDescribeOutput(ast, output, format) {
+  switch (format) {
+    case "text":
+      return formatTextOutput(ast, output);
+    case "mermaid":
+      return generateMermaid(ast);
+    case "paths":
+      return formatPaths(ast);
+    case "ascii":
+      return renderASCII(buildDiagramGraph(ast));
+    case "ascii-compact":
+      return renderASCIICompact(buildDiagramGraph(ast));
+    case "json":
+    default:
+      return JSON.stringify(output, null, 2);
+  }
+}
+async function describeCommand(input, options = {}) {
+  const { format = "json", node: focusNodeId, workflowName, compile = false } = options;
+  const filePath = path11.resolve(input);
+  if (!fs11.existsSync(filePath)) {
+    logger.error(`File not found: ${filePath}`);
+    process.exit(1);
+  }
+  try {
+    const parseResult = await parseWorkflow(filePath, { workflowName });
+    if (parseResult.errors.length > 0) {
+      logger.error(`Parse errors:`);
+      parseResult.errors.forEach((err) => logger.error(`  ${err}`));
+      process.exit(1);
+    }
+    const ast = parseResult.ast;
+    if (compile) {
+      const sourceCode = fs11.readFileSync(filePath, "utf8");
+      const generated = generateInPlace(sourceCode, ast, { production: false });
+      if (generated.hasChanges) {
+        fs11.writeFileSync(filePath, generated.code, "utf8");
+        logger.info(`Updated runtime markers in ${path11.basename(filePath)}`);
+      }
+    }
+    const output = describeWorkflow(ast, { node: focusNodeId });
+    console.log(formatDescribeOutput(ast, output, format));
+  } catch (error2) {
+    if (error2 instanceof Error && error2.message.startsWith("Node not found:")) {
+      logger.error(error2.message);
+      process.exit(1);
+    }
+    logger.error(`Failed to describe workflow: ${getErrorMessage(error2)}`);
+    process.exit(1);
+  }
+}
+
+// src/cli/commands/diagram.ts
+import * as fs12 from "fs";
+import * as path12 from "path";
+
 // src/diagram/renderer.ts
 init_theme();
 function escapeXml(str2) {
@@ -62555,10 +63026,20 @@ function workflowToSVG(ast, options = {}) {
   const graph = buildDiagramGraph(ast, options);
   return renderSVG(graph, options);
 }
+function sourceToSVG(code, options = {}) {
+  const result = parser.parseFromString(code);
+  return pickAndRender(result.workflows, options);
+}
 function fileToSVG(filePath, options = {}) {
   const result = parser.parse(filePath);
   return pickAndRender(result.workflows, options);
 }
+function sourceToHTML(code, options = {}) {
+  const result = parser.parseFromString(code);
+  const ast = pickWorkflow(result.workflows, options);
+  const svg = workflowToSVG(ast, options);
+  return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme, nodeSources: buildNodeSourceMap(ast) });
+}
 function fileToHTML(filePath, options = {}) {
   const result = parser.parse(filePath);
   const ast = pickWorkflow(result.workflows, options);
@@ -62612,8 +63093,31 @@ function pickWorkflow(workflows, options) {
 function pickAndRender(workflows, options) {
   return workflowToSVG(pickWorkflow(workflows, options), options);
 }
+function renderByFormat(graph, format) {
+  switch (format) {
+    case "ascii":
+      return renderASCII(graph);
+    case "ascii-compact":
+      return renderASCIICompact(graph);
+    case "text":
+      return renderText(graph);
+  }
+}
+function sourceToASCII(code, options = {}) {
+  const result = parser.parseFromString(code);
+  const ast = pickWorkflow(result.workflows, options);
+  const graph = buildDiagramGraph(ast, options);
+  return renderByFormat(graph, options.format ?? "ascii");
+}
+function fileToASCII(filePath, options = {}) {
+  const result = parser.parse(filePath);
+  const ast = pickWorkflow(result.workflows, options);
+  const graph = buildDiagramGraph(ast, options);
+  return renderByFormat(graph, options.format ?? "ascii");
+}
 
 // src/cli/commands/diagram.ts
+var ASCII_FORMATS = /* @__PURE__ */ new Set(["ascii", "ascii-compact", "text"]);
 async function diagramCommand(input, options = {}) {
   const { output, format = "svg", ...diagramOptions } = options;
   const filePath = path12.resolve(input);
@@ -62622,8 +63126,14 @@ async function diagramCommand(input, options = {}) {
     process.exit(1);
   }
   try {
-    const isHtml = format === "html";
-    const result = isHtml ? fileToHTML(filePath, diagramOptions) : fileToSVG(filePath, diagramOptions);
+    let result;
+    if (ASCII_FORMATS.has(format)) {
+      result = fileToASCII(filePath, { ...diagramOptions, format });
+    } else if (format === "html") {
+      result = fileToHTML(filePath, diagramOptions);
+    } else {
+      result = fileToSVG(filePath, diagramOptions);
+    }
     if (output) {
       const outputPath = path12.resolve(output);
       fs12.writeFileSync(outputPath, result, "utf-8");
@@ -86027,7 +86537,7 @@ function registerQueryTools(mcp) {
     "Describe a workflow in LLM-friendly format (nodes, connections, graph, validation).",
     {
       filePath: external_exports.string().describe("Path to the workflow .ts file"),
-      format: external_exports.enum(["json", "text", "mermaid", "paths"]).optional().describe("Output format (default: json)"),
+      format: external_exports.enum(["json", "text", "mermaid", "paths", "ascii", "ascii-compact"]).optional().describe("Output format (default: json). ascii/ascii-compact produce terminal-readable diagrams."),
       node: external_exports.string().optional().describe("Focus on a specific node ID"),
       workflowName: external_exports.string().optional().describe("Specific workflow if file has multiple")
     },
@@ -93200,31 +93710,54 @@ function resolvePackageName(spec) {
 // src/mcp/tools-diagram.ts
 import * as fs26 from "fs";
 import * as path29 from "path";
+var ASCII_FORMATS2 = /* @__PURE__ */ new Set(["ascii", "ascii-compact", "text"]);
 function registerDiagramTools(mcp) {
   mcp.tool(
     "fw_diagram",
-    "Generate an SVG diagram of a workflow. Returns SVG string or writes to a file.",
+    "Generate a diagram of a workflow. Formats: svg/html produce visual markup, ascii/ascii-compact/text produce plain text readable in terminal. Provide either filePath (workflow .ts file) or source (inline code).",
     {
-      filePath: external_exports.string().describe("Path to the workflow .ts file"),
-      outputPath: external_exports.string().optional().describe("Output file path for the SVG. If omitted, returns SVG as text."),
+      filePath: external_exports.string().optional().describe("Path to the workflow .ts file (required if source is not provided)"),
+      source: external_exports.string().optional().describe("Inline workflow source code (required if filePath is not provided)"),
+      outputPath: external_exports.string().optional().describe("Output file path. If omitted, returns content as text."),
       workflowName: external_exports.string().optional().describe("Specific workflow name if file has multiple"),
       theme: external_exports.enum(["dark", "light"]).optional().describe("Color theme (default: dark)"),
       showPortLabels: external_exports.boolean().optional().describe("Show port labels on diagram (default: true)"),
-      format: external_exports.enum(["svg", "html"]).optional().describe("Output format: svg (default) or html (interactive viewer)")
+      format: external_exports.enum(["svg", "html", "ascii", "ascii-compact", "text"]).optional().describe("Output format: svg (default), html (interactive viewer), ascii (port-level detail), ascii-compact (compact boxes), text (structured list)")
     },
     async (args) => {
       try {
-        const resolvedPath = path29.resolve(args.filePath);
-        if (!fs26.existsSync(resolvedPath)) {
-          return makeErrorResult("FILE_NOT_FOUND", `File not found: ${resolvedPath}`);
+        if (!args.filePath && !args.source) {
+          return makeErrorResult("MISSING_PARAM", "Provide either filePath or source parameter");
         }
+        const format = args.format ?? "svg";
         const diagramOptions = {
           workflowName: args.workflowName,
           theme: args.theme,
-          showPortLabels: args.showPortLabels
+          showPortLabels: args.showPortLabels,
+          format
         };
-        const isHtml = args.format === "html";
-        const result = isHtml ? fileToHTML(resolvedPath, diagramOptions) : fileToSVG(resolvedPath, diagramOptions);
+        let result;
+        if (args.source) {
+          if (ASCII_FORMATS2.has(format)) {
+            result = sourceToASCII(args.source, diagramOptions);
+          } else if (format === "html") {
+            result = sourceToHTML(args.source, diagramOptions);
+          } else {
+            result = sourceToSVG(args.source, diagramOptions);
+          }
+        } else {
+          const resolvedPath = path29.resolve(args.filePath);
+          if (!fs26.existsSync(resolvedPath)) {
+            return makeErrorResult("FILE_NOT_FOUND", `File not found: ${resolvedPath}`);
+          }
+          if (ASCII_FORMATS2.has(format)) {
+            result = fileToASCII(resolvedPath, diagramOptions);
+          } else if (format === "html") {
+            result = fileToHTML(resolvedPath, diagramOptions);
+          } else {
+            result = fileToSVG(resolvedPath, diagramOptions);
+          }
+        }
         if (args.outputPath) {
           const outputResolved = path29.resolve(args.outputPath);
           fs26.writeFileSync(outputResolved, result, "utf-8");
@@ -93821,6 +94354,75 @@ function registerResources(mcp, connection, buffer) {
   );
 }
 
+// src/mcp/prompts.ts
+var NOCODE_SYSTEM_PROMPT = `You are a workflow developer powered by Flow Weaver. You write real, production-quality TypeScript behind the scenes, but you present everything to the user as plain-language step descriptions, connections, and diagrams. The user never needs to see code unless they ask for it.
+
+## How you work
+
+When the user describes a workflow:
+
+1. Break their description into discrete steps (nodes), each with typed inputs and outputs.
+2. Call fw_create_model to generate the workflow skeleton with declare stubs.
+3. Call fw_implement_node for each step, writing real TypeScript function bodies that do what the user described. Write actual working code, not placeholder comments.
+4. Call fw_validate to check the result. If there are errors you can fix (missing connections, type mismatches), fix them silently with fw_modify. Only tell the user about problems you genuinely cannot resolve.
+5. Show the result as:
+   - A numbered list of steps with one-sentence descriptions
+   - An ASCII diagram (call fw_diagram with format "ascii-compact")
+   Never show TypeScript code in this summary.
+
+When the user asks to modify an existing workflow:
+- Use fw_modify or fw_modify_batch for structural changes (add/remove nodes, connections).
+- Use fw_implement_node to update a step's logic.
+- Re-validate after every change.
+
+## When to show code
+
+Only reveal TypeScript when the user explicitly asks: "show me the code", "let me see the implementation", "what does step X look like", etc. When showing code, use fw_describe with format "text" or read the file directly.
+
+## Tool usage patterns
+
+- fw_create_model: Create new workflows from a structured description (steps, inputs/outputs, flow path).
+- fw_implement_node: Replace a declare stub with a real function body.
+- fw_modify / fw_modify_batch: Add/remove nodes and connections, rename nodes, reposition.
+- fw_validate: Always run after changes. Fix what you can, report what you cannot.
+- fw_describe: Inspect workflow structure. Use format "text" for human-readable, "json" for programmatic.
+- fw_diagram: Generate visual representation. Prefer format "ascii-compact" for chat.
+- fw_workflow_status: Check which steps are implemented vs still stubs.
+- fw_scaffold / fw_list_templates: Bootstrap from templates when the user's request matches a known pattern.
+- fw_docs: Look up Flow Weaver features (scoped ports, branching, iteration, agents) when you need specifics.
+- fw_find_workflows: Locate existing workflow files in a directory.
+- fw_compile: Generate executable JavaScript from the workflow source.
+
+## Interaction style
+
+- Ask 1-2 clarifying questions when the request is vague, not a long interrogation list.
+- Default to sensible choices for things the user did not specify (file names, port types, node names).
+- After creating or modifying a workflow, always show the step summary and ASCII diagram.
+- Use fw_docs to look up advanced features before guessing at syntax.
+
+## File conventions
+
+- Workflow files use .ts extension.
+- Default location is the current working directory.
+- Node names use camelCase (e.g., validateEmail, sendNotification).
+- Workflow names use PascalCase (e.g., EmailValidation, OrderProcessing).`;
+function registerPrompts(mcp) {
+  mcp.registerPrompt("flow-weaver-nocode", {
+    title: "Flow Weaver No-Code Mode",
+    description: "Describe workflows in plain language. The agent writes real TypeScript behind the scenes and presents results as step summaries and diagrams. Code is available on request."
+  }, () => ({
+    messages: [
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: NOCODE_SYSTEM_PROMPT
+        }
+      }
+    ]
+  }));
+}
+
 // src/mcp/server.ts
 function parseEventFilterFromEnv() {
   const filter3 = {};
@@ -93870,6 +94472,7 @@ async function startMcpServer(options) {
   registerDocsTools(mcp);
   registerModelTools(mcp);
   registerResources(mcp, connection, buffer);
+  registerPrompts(mcp);
   if (!options._testDeps && options.stdio) {
     const transport = new StdioServerTransport();
     await mcp.connect(transport);
@@ -97168,7 +97771,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.8" : "0.0.0-dev";
+var version2 = true ? "0.10.9" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({
@@ -97196,7 +97799,7 @@ program2.command("strip <input>").description("Remove generated code from compil
     process.exit(1);
   }
 });
-program2.command("describe <input>").description("Output workflow structure in LLM-friendly formats (JSON, text, mermaid)").option("-f, --format <format>", "Output format: json (default), text, mermaid", "json").option("-n, --node <id>", "Focus on a specific node").option("--compile", "Also update runtime markers in the source file").option("-w, --workflow-name <name>", "Specific workflow name to describe").action(async (input, options) => {
+program2.command("describe <input>").description("Output workflow structure in LLM-friendly formats (JSON, text, mermaid)").option("-f, --format <format>", "Output format: json (default), text, mermaid, paths, ascii, ascii-compact", "json").option("-n, --node <id>", "Focus on a specific node").option("--compile", "Also update runtime markers in the source file").option("-w, --workflow-name <name>", "Specific workflow name to describe").action(async (input, options) => {
   try {
     await describeCommand(input, options);
   } catch (error2) {
@@ -97204,7 +97807,7 @@ program2.command("describe <input>").description("Output workflow structure in L
     process.exit(1);
   }
 });
-program2.command("diagram <input>").description("Generate SVG or interactive HTML diagram of a workflow").option("-t, --theme <theme>", "Color theme: dark (default), light", "dark").option("-w, --width <pixels>", "SVG width in pixels").option("-p, --padding <pixels>", "Canvas padding in pixels").option("--no-port-labels", "Hide data type labels on ports").option("--workflow-name <name>", "Specific workflow to render").option("-f, --format <format>", "Output format: svg (default), html (interactive viewer)", "svg").option("-o, --output <file>", "Write output to file instead of stdout").action(async (input, options) => {
+program2.command("diagram <input>").description("Generate SVG or interactive HTML diagram of a workflow").option("-t, --theme <theme>", "Color theme: dark (default), light", "dark").option("-w, --width <pixels>", "SVG width in pixels").option("-p, --padding <pixels>", "Canvas padding in pixels").option("--no-port-labels", "Hide data type labels on ports").option("--workflow-name <name>", "Specific workflow to render").option("-f, --format <format>", "Output format: svg (default), html, ascii, ascii-compact, text", "svg").option("-o, --output <file>", "Write output to file instead of stdout").action(async (input, options) => {
   try {
     if (options.width) options.width = Number(options.width);
     if (options.padding) options.padding = Number(options.padding);