@synergenius/flow-weaver 0.10.7 → 0.10.9

package/dist/cli/index.js

@@ -102,7 +102,7 @@ program
 program
     .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('-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')
@@ -124,7 +124,7 @@ program
     .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('-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 {

package/dist/diagram/ascii-renderer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ASCII-based renderers for workflow diagrams.
+ *
+ * Three formats:
+ * - renderASCII: port-level detail with box-drawing, connections drawn between ports
+ * - renderASCIICompact: single-row compact node boxes
+ * - renderText: structured text listing (most LLM-parseable)
+ */
+import type { DiagramGraph } from './types.js';
+export declare function renderASCII(graph: DiagramGraph): string;
+export declare function renderASCIICompact(graph: DiagramGraph): string;
+export declare function renderText(graph: DiagramGraph): string;
+//# sourceMappingURL=ascii-renderer.d.ts.map

package/dist/diagram/ascii-renderer.js

@@ -0,0 +1,528 @@
+/**
+ * ASCII-based renderers for workflow diagrams.
+ *
+ * Three formats:
+ * - renderASCII: port-level detail with box-drawing, connections drawn between ports
+ * - renderASCIICompact: single-row compact node boxes
+ * - renderText: structured text listing (most LLM-parseable)
+ */
+// ── Helpers ──────────────────────────────────────────────────────────────────
+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 = 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';
+}
+// ── Corner characters ────────────────────────────────────────────────────────
+/**
+ * Pick the right corner box-drawing character.
+ * hDir: which side of the corner the horizontal segment extends to.
+ * vDir: which side of the corner the vertical segment extends to.
+ */
+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'; // ┼ fallback
+}
+// ── 2D character grid ────────────────────────────────────────────────────────
+const H_CHARS = new Set('\u2500\u2550'); // ─ ═
+const V_CHARS = new Set('\u2502\u2551'); // │ ║
+class CharGrid {
+    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 !== ' ') {
+            // Handle crossings: horizontal meets vertical
+            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;
+            }
+            // Same direction: keep existing (shared path)
+            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 = 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');
+}
+export function renderASCII(graph) {
+    const layers = groupByLayer(graph.nodes);
+    if (layers.length === 0)
+        return `${graph.workflowName}\n(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;
+    // Column x-offsets
+    const colX = [];
+    let cx = 1;
+    for (let c = 0; c < layerBoxes.length; c++) {
+        colX.push(cx);
+        cx += colWidths[c] + wireGap;
+    }
+    const gridWidth = cx + 1;
+    // Count spanning connections to reserve highway margin rows
+    const nodeColMap = 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 !== undefined && tc !== undefined && Math.abs(tc - fc) > 1)
+            spanCount++;
+    }
+    const highwayMargin = spanCount > 0 ? spanCount + 1 : 0;
+    // Position boxes, shifted down to leave room for above-highways
+    const nodeGapY = 2;
+    const boxPositions = 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);
+    // Title (centered, above the highway margin)
+    const titleX = Math.max(0, Math.floor((gridWidth - graph.workflowName.length) / 2));
+    grid.writeStr(titleX, 1, graph.workflowName);
+    // Draw boxes
+    for (const pos of boxPositions.values()) {
+        drawBox(grid, pos.box, pos.bx, pos.by, connected);
+    }
+    // Draw connections
+    drawConnections(grid, graph.connections, boxPositions, boxStartY, maxGridHeight);
+    // Scope sub-diagrams
+    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');
+}
+// ── Connection drawing ───────────────────────────────────────────────────────
+function drawConnections(grid, connections, positions, boxAreaTop, _gridHeight) {
+    // Compute global box y-bounds
+    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);
+    }
+    // Sort: adjacent connections first, then spanning. Within each group, sort by source y.
+    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 = 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 === undefined || toRowOff === undefined)
+            continue;
+        const y1 = fromPos.by + fromRowOff;
+        const y2 = toPos.by + toRowOff;
+        const x1 = fromPos.bx + fromPos.box.boxWidth; // first cell after source box right border
+        const x2 = toPos.bx - 1; // cell for arrowhead (just before target box left border)
+        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 {
+            // Spanning: route via highway lane above or below all boxes
+            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);
+        }
+    }
+}
+/** Route a connection between adjacent columns (1 gap to cross). */
+function drawAdjacentRoute(grid, x1, y1, x2, y2, hCh, vCh, isStep, usedTracks, fromPos, toPos) {
+    if (y1 === y2) {
+        // Straight horizontal
+        for (let x = x1; x < x2; x++)
+            grid.set(x, y1, hCh);
+        grid.set(x2, y1, '\u25B6');
+        return;
+    }
+    // L-route: horizontal -> corner -> vertical -> corner -> horizontal
+    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);
+    // Source horizontal
+    for (let x = x1; x < midX; x++)
+        grid.set(x, y1, hCh);
+    // Corner at source end
+    grid.set(midX, y1, cornerChar(isStep, 'left', y2 > y1 ? 'down' : 'up'));
+    // Vertical
+    drawVerticalSegment(grid, midX, y1, y2, vCh);
+    // Corner at target end
+    grid.set(midX, y2, cornerChar(isStep, 'right', y2 > y1 ? 'up' : 'down'));
+    // Target horizontal
+    for (let x = midX + 1; x < x2; x++)
+        grid.set(x, y2, hCh);
+    grid.set(x2, y2, '\u25B6');
+}
+/**
+ * Route a connection spanning multiple columns via a highway lane.
+ * Shape: horizontal out -> vertical to highway -> horizontal at highway -> vertical to target -> horizontal in
+ */
+function drawSpanningRoute(grid, x1, y1, x2, y2, highwayY, hCh, vCh, isStep, usedTracks, fromPos, toPos) {
+    // Find vertical track positions in the source gap and target gap
+    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; // source to highway direction
+    const goingUp = y2 < highwayY; // highway to target direction
+    // 1. Horizontal from source to srcMidX
+    for (let x = x1; x < srcMidX; x++)
+        grid.set(x, y1, hCh);
+    // 2. Corner: horizontal ends, vertical begins toward highway
+    grid.set(srcMidX, y1, cornerChar(isStep, 'left', goingDown ? 'down' : 'up'));
+    // 3. Vertical from y1 toward highwayY
+    drawVerticalSegment(grid, srcMidX, y1, highwayY, vCh);
+    // 4. Corner: vertical ends, horizontal begins at highway level
+    grid.set(srcMidX, highwayY, cornerChar(isStep, 'right', goingDown ? 'up' : 'down'));
+    // 5. Horizontal at highwayY from srcMidX to tgtMidX
+    for (let x = srcMidX + 1; x < tgtMidX; x++)
+        grid.set(x, highwayY, hCh);
+    // 6. Corner: horizontal ends, vertical begins toward target
+    grid.set(tgtMidX, highwayY, cornerChar(isStep, 'left', goingUp ? 'up' : 'down'));
+    // 7. Vertical from highwayY toward y2
+    drawVerticalSegment(grid, tgtMidX, highwayY, y2, vCh);
+    // 8. Corner: vertical ends, horizontal begins to target
+    grid.set(tgtMidX, y2, cornerChar(isStep, 'right', goingUp ? 'down' : 'up'));
+    // 9. Horizontal from tgtMidX to target
+    for (let x = tgtMidX + 1; x < x2; x++)
+        grid.set(x, y2, hCh);
+    // 10. Arrowhead
+    grid.set(x2, y2, '\u25B6');
+}
+/** Draw a vertical segment between two y values (exclusive of endpoints). */
+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, 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);
+}
+// ── renderASCIICompact ───────────────────────────────────────────────────────
+export function renderASCIICompact(graph) {
+    const layers = groupByLayer(graph.nodes);
+    if (layers.length === 0)
+        return `${graph.workflowName}\n(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');
+}
+// ── renderText ───────────────────────────────────────────────────────────────
+export 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 type = conn.isStepConnection ? 'STEP' : '';
+            lines.push(`  ${from}  ${arrow} ${to}${type ? '  ' + type : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=ascii-renderer.js.map

package/dist/diagram/index.d.ts

@@ -1,6 +1,7 @@
 import type { TWorkflowAST } from '../ast/types.js';
 import type { DiagramOptions } from './types.js';
 export type { DiagramOptions } from './types.js';
+export { renderASCII, renderASCIICompact, renderText } from './ascii-renderer.js';
 /**
  * Render a workflow AST to an SVG string.
  */
@@ -25,4 +26,7 @@ export declare function sourceToHTML(code: string, options?: DiagramOptions): st
  * Parse a workflow file and render the first (or named) workflow to interactive HTML.
  */
 export declare function fileToHTML(filePath: string, options?: DiagramOptions): string;
+export declare function workflowToASCII(ast: TWorkflowAST, options?: DiagramOptions): string;
+export declare function sourceToASCII(code: string, options?: DiagramOptions): string;
+export declare function fileToASCII(filePath: string, options?: DiagramOptions): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/diagram/index.js

@@ -2,6 +2,8 @@ import { parser } from '../parser.js';
 import { buildDiagramGraph } from './geometry.js';
 import { renderSVG } from './renderer.js';
 import { wrapSVGInHTML } from './html-viewer.js';
+import { renderASCII, renderASCIICompact, renderText } from './ascii-renderer.js';
+export { renderASCII, renderASCIICompact, renderText } from './ascii-renderer.js';
 /**
  * Render a workflow AST to an SVG string.
  */
@@ -97,4 +99,28 @@ function pickWorkflow(workflows, options) {
 function pickAndRender(workflows, options) {
     return workflowToSVG(pickWorkflow(workflows, options), options);
 }
+// ── ASCII / Text convenience functions ───────────────────────────────────────
+function renderByFormat(graph, format) {
+    switch (format) {
+        case 'ascii': return renderASCII(graph);
+        case 'ascii-compact': return renderASCIICompact(graph);
+        case 'text': return renderText(graph);
+    }
+}
+export function workflowToASCII(ast, options = {}) {
+    const graph = buildDiagramGraph(ast, options);
+    return renderByFormat(graph, options.format ?? 'ascii');
+}
+export 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');
+}
+export 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');
+}
 //# sourceMappingURL=index.js.map

package/dist/diagram/types.d.ts

@@ -5,7 +5,7 @@ export interface DiagramOptions {
     padding?: number;
     showPortLabels?: boolean;
     workflowName?: string;
-    format?: 'svg' | 'html';
+    format?: 'svg' | 'html' | 'ascii' | 'ascii-compact' | 'text';
 }
 export interface DiagramPort {
     name: string;

package/dist/mcp/index.d.ts

@@ -8,5 +8,6 @@ export { registerQueryTools } from './tools-query.js';
 export { registerTemplateTools } from './tools-template.js';
 export { registerPatternTools } from './tools-pattern.js';
 export { registerResources } from './resources.js';
+export { registerPrompts } from './prompts.js';
 export { startMcpServer, mcpServerCommand } from './server.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.js

@@ -7,5 +7,6 @@ export { registerQueryTools } from './tools-query.js';
 export { registerTemplateTools } from './tools-template.js';
 export { registerPatternTools } from './tools-pattern.js';
 export { registerResources } from './resources.js';
+export { registerPrompts } from './prompts.js';
 export { startMcpServer, mcpServerCommand } from './server.js';
 //# sourceMappingURL=index.js.map

package/dist/mcp/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(mcp: McpServer): void;
+//# sourceMappingURL=prompts.d.ts.map