@cargo-ai/cli 1.0.55 → 1.0.56

package/build/commands/orchestration/asciiBlocks.d.ts

@@ -0,0 +1,42 @@
+export declare function displayWidth(text: string): number;
+/**
+ * A rectangle of text plus the column its spine sits on. `spine` is where an
+ * incoming `│` attaches at the top and where an outgoing one leaves at the
+ * bottom, so stacking is a matter of lining up that column.
+ */
+export type Block = {
+    lines: string[];
+    width: number;
+    spine: number;
+};
+export declare function padTo(line: string, width: number): string;
+export declare function indent(block: Block, by: number): Block;
+/** Text lines centred on a shared spine. No lines is a legitimate answer — an
+ * unnamed routing node draws as its split and nothing else. */
+export declare function textBlock(texts: string[]): Block;
+/** One row carrying nothing but the spine. */
+export declare function spineBlock(char?: string): Block;
+export declare function emptyBlock(): Block;
+/** Stack blocks vertically, aligning their spines. */
+export declare function vstack(blocks: Block[]): Block;
+/** Place blocks side by side, returning where each one's spine landed. */
+export declare function hstack(blocks: Block[], gap: number): {
+    block: Block;
+    spines: number[];
+};
+/** Extend a column downwards so every column in a split ends level. */
+export declare function padColumn(block: Block, toHeight: number, char: string): Block;
+/**
+ * The glyph where a rail meets the spine. A tee has to point at the rails it
+ * actually carries: drawing `├` while the rail leaves to the left produces a
+ * junction with an arm attached to nothing and a rail attached to nothing.
+ */
+export declare function teeAt(spine: number, others: number[], down: boolean): string;
+/** Draw a horizontal rail across `width`, writing one glyph per marked column. */
+export declare function rail(width: number, marks: {
+    at: number;
+    char: string;
+}[]): string;
+/** Wrap a block in a captioned box, for a sub-flow that runs inside a step. */
+export declare function frame(block: Block, caption: string): Block;
+//# sourceMappingURL=asciiBlocks.d.ts.map

package/build/commands/orchestration/asciiBlocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asciiBlocks.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/asciiBlocks.ts"],"names":[],"mappings":"AAyBA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAMD;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAIF,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAQtD;AAED;+DAC+D;AAC/D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAShD;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,IAAI,SAAM,GAAG,KAAK,CAE5C;AAED,wBAAgB,UAAU,IAAI,KAAK,CAElC;AAED,sDAAsD;AACtD,wBAAgB,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAsB7C;AAED,0EAA0E;AAC1E,wBAAgB,MAAM,CACpB,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA6BpC;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAQ7E;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAO5E;AAED,kFAAkF;AAClF,wBAAgB,IAAI,CAClB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GACpC,MAAM,CAWR;AAED,+EAA+E;AAC/E,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAU1D"}

package/build/commands/orchestration/asciiBlocks.js

@@ -0,0 +1,170 @@
+// Text blocks: the layout algebra the ASCII diagram is assembled from.
+//
+// A Block is a rectangle of text plus the column its spine sits on — the column
+// an incoming `│` attaches to at the top and an outgoing one leaves from at the
+// bottom. Stacking is then a matter of lining that column up, which is what lets
+// the renderer compose a drawing without ever tracking absolute coordinates.
+//
+// Nothing here knows what a workflow is. The invariant every producer maintains
+// is that each line of a Block is exactly `block.width` cells wide, which is why
+// so little of this has to measure anything.
+// ---------------------------------------------------------------------------
+// Character width
+// ---------------------------------------------------------------------------
+// A marker glyph occupies two terminal cells; measuring it as one silently
+// shears every line to its right. `Emoji_Presentation` is the property that
+// means "wide by default" — `Extended_Pictographic` is too broad, matching `◀`,
+// which a terminal draws in a single cell.
+const WIDE = /\p{Emoji_Presentation}/u;
+// Most lines are plain text; the per-character scan is only needed once a line
+// actually carries a marker. One test for the whole string skips it.
+const PLAIN = /^[\x20-\x7E]*$/;
+export function displayWidth(text) {
+    if (PLAIN.test(text))
+        return text.length;
+    let total = 0;
+    for (const char of text)
+        total += WIDE.test(char) ? 2 : 1;
+    return total;
+}
+const blank = (width) => (width > 0 ? " ".repeat(width) : "");
+export function padTo(line, width) {
+    const short = width - displayWidth(line);
+    return short > 0 ? line + " ".repeat(short) : line;
+}
+export function indent(block, by) {
+    if (by <= 0)
+        return block;
+    const prefix = " ".repeat(by);
+    return {
+        lines: block.lines.map((line) => prefix + line),
+        width: block.width + by,
+        spine: block.spine + by,
+    };
+}
+/** Text lines centred on a shared spine. No lines is a legitimate answer — an
+ * unnamed routing node draws as its split and nothing else. */
+export function textBlock(texts) {
+    if (texts.length === 0)
+        return emptyBlock();
+    const measured = texts.map((text) => ({ text, own: displayWidth(text) }));
+    const width = Math.max(...measured.map((entry) => entry.own));
+    const lines = measured.map(({ text, own }) => {
+        const left = Math.floor((width - own) / 2);
+        return " ".repeat(left) + text + blank(width - own - left);
+    });
+    return { lines, width, spine: Math.floor((width - 1) / 2) };
+}
+/** One row carrying nothing but the spine. */
+export function spineBlock(char = "│") {
+    return { lines: [char], width: 1, spine: 0 };
+}
+export function emptyBlock() {
+    return { lines: [], width: 0, spine: 0 };
+}
+/** Stack blocks vertically, aligning their spines. */
+export function vstack(blocks) {
+    const real = blocks.filter((block) => block.lines.length > 0);
+    if (real.length === 0)
+        return emptyBlock();
+    if (real.length === 1) {
+        const only = real[0];
+        if (only === undefined)
+            return emptyBlock();
+        return only;
+    }
+    const spine = Math.max(...real.map((block) => block.spine));
+    const shifted = real.map((block) => indent(block, spine - block.spine));
+    const width = Math.max(...shifted.map((block) => block.width));
+    return {
+        lines: shifted.flatMap((block) => {
+            const short = blank(width - block.width);
+            return short.length === 0
+                ? block.lines
+                : block.lines.map((line) => line + short);
+        }),
+        width,
+        spine,
+    };
+}
+/** Place blocks side by side, returning where each one's spine landed. */
+export function hstack(blocks, gap) {
+    const height = Math.max(...blocks.map((block) => block.lines.length));
+    const spines = [];
+    let offset = 0;
+    const rows = Array.from({ length: height }, () => "");
+    blocks.forEach((block, index) => {
+        if (index > 0)
+            offset += gap;
+        spines.push(offset + block.spine);
+        for (let row = 0; row < height; row += 1) {
+            // Every Block keeps `displayWidth(line) === block.width` on every line, so
+            // the line needs no measuring here — only the canvas does.
+            const canvas = rows[row];
+            const line = block.lines[row];
+            rows[row] =
+                padTo(canvas === undefined ? "" : canvas, offset) +
+                    (line === undefined ? blank(block.width) : line);
+        }
+        offset += block.width;
+    });
+    return {
+        block: {
+            lines: rows.map((row) => padTo(row, offset)),
+            width: offset,
+            spine: 0,
+        },
+        spines,
+    };
+}
+/** Extend a column downwards so every column in a split ends level. */
+export function padColumn(block, toHeight, char) {
+    const missing = toHeight - block.lines.length;
+    if (missing <= 0)
+        return block;
+    const filler = padTo(" ".repeat(block.spine) + char, block.width);
+    return {
+        ...block,
+        lines: [...block.lines, ...Array.from({ length: missing }, () => filler)],
+    };
+}
+/**
+ * The glyph where a rail meets the spine. A tee has to point at the rails it
+ * actually carries: drawing `├` while the rail leaves to the left produces a
+ * junction with an arm attached to nothing and a rail attached to nothing.
+ */
+export function teeAt(spine, others, down) {
+    const left = others.some((at) => at < spine);
+    const right = others.some((at) => at > spine);
+    if (left && right)
+        return "┼";
+    if (left)
+        return "┤";
+    if (right)
+        return "├";
+    return down ? "┬" : "┴";
+}
+/** Draw a horizontal rail across `width`, writing one glyph per marked column. */
+export function rail(width, marks) {
+    const sorted = [...marks].sort((a, b) => a.at - b.at);
+    const first = sorted[0];
+    const last = sorted[sorted.length - 1];
+    if (first === undefined || last === undefined)
+        return " ".repeat(width);
+    const cells = Array.from({ length: width }, (_, column) => column > first.at && column < last.at ? "─" : " ");
+    for (const mark of sorted)
+        cells[mark.at] = mark.char;
+    return cells.join("");
+}
+/** Wrap a block in a captioned box, for a sub-flow that runs inside a step. */
+export function frame(block, caption) {
+    const inner = Math.max(block.width, displayWidth(caption) + 2);
+    const width = inner + 4;
+    const label = ` ${caption} `;
+    const lines = [
+        `┌─${label}${"─".repeat(Math.max(0, width - 3 - displayWidth(label)))}┐`,
+        ...block.lines.map((line) => `│ ${padTo(line, inner)} │`),
+        `└${"─".repeat(width - 2)}┘`,
+    ];
+    return { lines, width, spine: block.spine + 2 };
+}

package/build/commands/orchestration/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/node.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAexC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAoK7E"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/node.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAgBxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAoK7E"}

package/build/commands/orchestration/node.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { ExitCodes, failWith, handleApiCall, outputJson, parseJson, } from "../runHandler.js";
 import { extractNodes, renderNodeDiagram, toMermaidBlock, } from "./nodeDiagram.js";
+import { renderNodeAscii } from "./nodeDiagramAscii.js";
 export function registerNodeCommands(parent, getApi) {
     const node = parent
         .command("node")
@@ -105,7 +106,7 @@ Examples:
 function registerDiagramCommand(node, getApi) {
     node
         .command("diagram")
-        .description("Draw a node graph as a Mermaid flowchart (free, runs nothing, no credits)")
+        .description("Draw a node graph — ASCII for a terminal, Mermaid to paste elsewhere (free, runs nothing, no credits)")
         .option("--nodes <json>", "Node definitions (JSON array, or '-' to read from stdin)")
         .option("--file <path>", "Read a JSON payload or node array from a file")
         .option("--workflow-uuid <uuid>", "Diagram a workflow's deployed release (add --draft for its draft)")
@@ -113,37 +114,74 @@ function registerDiagramCommand(node, getApi) {
         .option("--release-uuid <uuid>", "Diagram a specific release")
         .option("--run-uuid <uuid>", "Diagram the graph a run executed (follows the run's release when it has one)")
         .option("--title <text>", "Title rendered above the diagram")
-        .option("--direction <TD|LR>", "Flow direction (default: TD)", "TD")
+        .option("--format <ascii|mermaid>", "ascii = readable in a terminal · mermaid = paste into a PR, docs or a page (default: mermaid)", "mermaid")
+        .option("--direction <TD|LR>", "Mermaid flow direction, ignored by --format ascii (default: TD)", "TD")
         .option("--paid <slugs>", "Comma-separated node slugs/uuids that bill credits — marked 💳")
-        .option("--highlight <slugs>", "Comma-separated node slugs/uuids to mark red, e.g. a failing node")
-        .option("--raw", "Print the fenced Mermaid block instead of JSON")
+        .option("--highlight <slugs>", "Comma-separated node slugs/uuids to mark (red in Mermaid, ← in ASCII)")
+        .option("--raw", "Print the diagram itself instead of JSON")
         .addHelpText("after", `
 Free, runs nothing: turns a node graph into a picture so a reviewer can see the
 routing, the fallback paths and which steps bill before approving or deploying
 it. Pass exactly one source.
 
-Returns {"diagram":"flowchart TD…","format":"mermaid","warnings":[…]}, or the
-fenced block itself with --raw. 'warnings' reports structural problems worth
-saying out loud — nodes unreachable from start, dangling childrenUuids.
+Which format:
+  --format ascii     SHOWING a graph to someone at a terminal. Renders as a
+                     centred flow with named steps and labelled branches, so it
+                     is readable as-is. Use this whenever you are about to
+                     explain what a workflow, tool or play does.
+  --format ascii resolves step names from the integration catalog, so a step
+  reads 'Apollo.io / Enrich person'. --nodes and --file skip that lookup and
+  keep the slugs, so they work with no credential at all.
+
+  --format mermaid   PASTING the graph somewhere that renders it — a PR body, a
+                     markdown doc, a published page. In a terminal it is source
+                     code, not a picture. This is the default, for
+                     compatibility.
+
+Returns {"diagram":"…","format":"ascii"|"mermaid","warnings":[…]}, or the
+diagram itself with --raw (fenced for mermaid, plain text for ascii).
+'warnings' reports structural problems worth saying out loud — nodes
+unreachable from start, dangling childrenUuids.
 
 A run created by 'action execute' carries its own graph; a run of a deployed
 tool or play carries only a releaseUuid, and --run-uuid follows it either way.
 
 Examples:
-  $ cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw
-  $ cargo-ai orchestration node diagram --workflow-uuid <uuid> --draft --paid enrich,verify
-  $ cargo-ai orchestration node diagram --run-uuid <uuid> --highlight branch_1 --raw
-  $ cargo-ai orchestration release get-deployed --workflow-uuid <uuid> | cargo-ai orchestration node diagram --nodes -`)
+  $ cargo-ai orchestration node diagram --workflow-uuid <uuid> --format ascii --raw
+  $ cargo-ai orchestration node diagram --workflow-uuid <uuid> --draft --paid enrich,verify --format ascii --raw
+  $ cargo-ai orchestration node diagram --run-uuid <uuid> --highlight branch_1 --format ascii --raw
+  $ cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw   # mermaid, for a PR
+  $ cargo-ai orchestration release get-deployed --workflow-uuid <uuid> | cargo-ai orchestration node diagram --nodes - --format ascii --raw`)
         .action(async (opts) => {
+        const format = (opts.format === undefined ? "mermaid" : opts.format).toLowerCase();
+        if (format !== "ascii" && format !== "mermaid") {
+            failWith(`--format must be 'ascii' or 'mermaid', got '${format}'`, {
+                code: ExitCodes.InvalidUsage,
+            });
+        }
         const nodes = await resolveNodes(getApi, opts);
-        const result = renderNodeDiagram(nodes, {
-            title: opts.title,
-            direction: (opts.direction ?? "TD").toUpperCase(),
-            paid: splitList(opts.paid),
-            highlight: splitList(opts.highlight),
-        });
+        const result = format === "ascii"
+            ? renderNodeAscii(nodes, {
+                title: opts.title,
+                paid: splitList(opts.paid),
+                highlight: splitList(opts.highlight),
+                // `--nodes` / `--file` are the offline sources: resolving them
+                // touched no API, and reaching for one now to prettify a label
+                // would make an offline command demand a login.
+                names: opts.nodes === undefined && opts.file === undefined
+                    ? await catalogNames(getApi, nodes)
+                    : undefined,
+            })
+            : renderNodeDiagram(nodes, {
+                title: opts.title,
+                direction: (opts.direction === undefined
+                    ? "TD"
+                    : opts.direction).toUpperCase(),
+                paid: splitList(opts.paid),
+                highlight: splitList(opts.highlight),
+            });
         if (opts.raw === true) {
-            console.log(toMermaidBlock(result.diagram));
+            console.log(format === "ascii" ? result.diagram : toMermaidBlock(result.diagram));
             for (const warning of result.warnings)
                 console.error(`⚠ ${warning}`);
             return;
@@ -151,6 +189,81 @@ Examples:
         outputJson(result);
     });
 }
+/**
+ * Display names for the steps a graph actually uses, so it reads
+ * `Apollo.io` / `Enrich person` rather than `apolloio` / `enrichPerson`.
+ *
+ * Both halves come from the platform's own catalogs — the integration catalog
+ * for connector steps, the native-integration catalog for built-in ones — so a
+ * step is never labelled with a name this CLI invented. Renaming an action on
+ * the platform reaches the drawing without a code change.
+ *
+ * Best-effort, and only for graphs that came from the API in the first place.
+ * `--nodes` and `--file` skip it entirely: those resolve without a credential,
+ * and `getApi()` exits the process when there is none, so asking for names
+ * there would turn an offline command into one that demands a login. A catalog
+ * that is reachable but fails — a token without the scope, a network blip —
+ * falls back to slugs rather than losing the drawing.
+ */
+async function catalogNames(getApi, nodes) {
+    const used = new Set();
+    let hasNative = false;
+    // Group bodies live in `config._nodes` and are drawn too, so their steps need
+    // names as much as the outer ones — otherwise a loop shows wire slugs beside
+    // an outer graph showing product names.
+    const collect = (list) => {
+        for (const node of list) {
+            if (node.kind === "connector" &&
+                typeof node.integrationSlug === "string") {
+                used.add(node.integrationSlug);
+            }
+            if (node.kind === "native")
+                hasNative = true;
+            const config = node.config;
+            if (config !== null && config !== undefined) {
+                const nested = config["_nodes"];
+                if (Array.isArray(nested))
+                    collect(nested);
+            }
+        }
+    };
+    collect(nodes);
+    if (used.size === 0 && !hasNative)
+        return undefined;
+    try {
+        const api = getApi();
+        const [integrations, native] = await Promise.all([
+            used.size === 0
+                ? undefined
+                : api.connection.integration
+                    .list({ slugs: [...used] })
+                    .catch(() => undefined),
+            hasNative
+                ? api.connection.nativeIntegration.get().catch(() => undefined)
+                : undefined,
+        ]);
+        const byIntegration = {};
+        const byAction = {};
+        const listed = integrations === undefined ? [] : integrations.integrations;
+        for (const integration of listed) {
+            const actions = integration.actions === undefined ? {} : integration.actions;
+            byIntegration[integration.slug] = integration.name;
+            byAction[integration.slug] = Object.fromEntries(Object.entries(actions).map(([slug, action]) => [slug, action.name]));
+        }
+        const nativeActions = native === undefined ? {} : native.nativeIntegration.actions;
+        return {
+            integrations: byIntegration,
+            actions: byAction,
+            native: Object.fromEntries(Object.entries(nativeActions).map(([slug, action]) => [
+                slug,
+                action.name,
+            ])),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 function splitList(value) {
     if (value === undefined)
         return [];

package/build/commands/orchestration/nodeDiagram.d.ts

@@ -30,8 +30,50 @@ export type DiagramResult = {
     /** Structural problems worth saying out loud rather than drawing over. */
     warnings: string[];
 };
+/** Actions that route rather than do work. Shared, so adding one to the
+ * platform does not have to be mirrored in each renderer. */
+export declare const ROUTING_ACTIONS: Set<string>;
+export declare function isStart(node: DiagramNode | undefined): boolean;
+export declare function isEnd(node: DiagramNode | undefined): boolean;
+export declare function indexByUuid(nodes: DiagramNode[]): Map<string, DiagramNode>;
+/** Where the graph begins — the `start` node, or the first node if it has none. */
+export declare function findStart(nodes: DiagramNode[]): DiagramNode | undefined;
+/**
+ * Whether a user-supplied `--paid` / `--highlight` token names this node.
+ * Slugs repeat within a release, so a slug token marks every node carrying it;
+ * pass a uuid to mark exactly one.
+ */
+export declare function matchesNode(node: DiagramNode, needles: string[]): boolean;
+/**
+ * A node's outgoing edges, in `childrenUuids` order, labelled by what the
+ * routing node means. Shared because this encodes routing *semantics* — index
+ * order, and the rule that a fallback pointing at the node's own next step is
+ * the same arrow rather than a second one. Two copies would let the two formats
+ * draw different graphs from one release.
+ */
+/**
+ * A fallback pointing at the node's own next step: a failure here does not stop
+ * the run. It is not a second arrow — it is the same one — so it shows as a mark
+ * on the step rather than an edge. Silently dropping it makes a step that
+ * survives a provider outage look like one that dies on it, which is the exact
+ * misread this command exists to prevent.
+ */
+export declare function continuesOnFailure(node: DiagramNode): boolean;
+export declare function outgoingEdges(node: DiagramNode, byUuid: Map<string, DiagramNode>): {
+    to: string;
+    label?: string;
+    dashed?: boolean;
+}[];
+/** Structural problems worth saying out loud rather than drawing over. */
+export declare function graphWarnings(nodes: DiagramNode[], byUuid: Map<string, DiagramNode>, reached: Set<string>): string[];
 /** What the node is, in words a user recognises. */
 export declare function labelFor(node: DiagramNode): string;
+/**
+ * `childrenUuids` order carries the routing semantics — index 0 of a `branch`
+ * is the matched path, index 1 the unmatched one. Getting this backwards
+ * inverts the diagram's meaning, so it is table-driven, never inferred.
+ */
+export declare function edgeLabels(node: DiagramNode, count: number): (string | undefined)[];
 export declare function renderNodeDiagram(nodes: DiagramNode[], options?: DiagramOptions): DiagramResult;
 /** Node-shaped means: a uuid plus the fields a graph is walked by. */
 export declare function isNodeArray(value: unknown): value is DiagramNode[];

package/build/commands/orchestration/nodeDiagram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeDiagram.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/nodeDiagram.ts"],"names":[],"mappings":"AAgBA;;2CAE2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAsHF,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CASlD;AAyND,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAkCf;AAMD,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,EAAE,CAYlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,EAAE,GAAG,SAAS,CAexE;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"nodeDiagram.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/nodeDiagram.ts"],"names":[],"mappings":"AAgBA;;2CAE2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;6DAC6D;AAC7D,eAAO,MAAM,eAAe,aAO1B,CAAC;AAOH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAG9D;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAG5D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAM1E;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CAGvE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAGzE;AAED;;;;;;GAMG;AACH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAI7D;AAQD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAC/B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,CAmBpD;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAAE,EACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAChC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GACnB,MAAM,EAAE,CAyBV;AA4GD,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CASlD;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,GACZ,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAyBxB;AAoKD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAkCf;AAMD,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,EAAE,CAYlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,EAAE,GAAG,SAAS,CAexE;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/build/commands/orchestration/nodeDiagram.js

@@ -13,24 +13,117 @@
 //   * `childrenUuids` order carries the routing semantics (index 0 of a
 //     `branch` is the matched path), so edge labels are table-driven rather
 //     than inferred from node names.
-const ROUTING_ACTIONS = [
+/** Actions that route rather than do work. Shared, so adding one to the
+ * platform does not have to be mirrored in each renderer. */
+export const ROUTING_ACTIONS = new Set([
     "branch",
     "filter",
     "switch",
     "split",
     "balance",
     "humanReview",
-];
+]);
 const CODE_ACTIONS = ["python", "script"];
 // ---------------------------------------------------------------------------
+// Graph basics, shared by every renderer
+// ---------------------------------------------------------------------------
+export function isStart(node) {
+    if (node === undefined)
+        return false;
+    return node.kind === "native" && node.actionSlug === "start";
+}
+export function isEnd(node) {
+    if (node === undefined)
+        return false;
+    return node.kind === "native" && node.actionSlug === "end";
+}
+export function indexByUuid(nodes) {
+    const byUuid = new Map();
+    for (const node of nodes) {
+        if (typeof node.uuid === "string")
+            byUuid.set(node.uuid, node);
+    }
+    return byUuid;
+}
+/** Where the graph begins — the `start` node, or the first node if it has none. */
+export function findStart(nodes) {
+    const start = nodes.find(isStart);
+    return start === undefined ? nodes[0] : start;
+}
+/**
+ * Whether a user-supplied `--paid` / `--highlight` token names this node.
+ * Slugs repeat within a release, so a slug token marks every node carrying it;
+ * pass a uuid to mark exactly one.
+ */
+export function matchesNode(node, needles) {
+    const slug = node.slug === null ? undefined : node.slug;
+    return needles.some((needle) => needle === node.uuid || needle === slug);
+}
+/**
+ * A node's outgoing edges, in `childrenUuids` order, labelled by what the
+ * routing node means. Shared because this encodes routing *semantics* — index
+ * order, and the rule that a fallback pointing at the node's own next step is
+ * the same arrow rather than a second one. Two copies would let the two formats
+ * draw different graphs from one release.
+ */
+/**
+ * A fallback pointing at the node's own next step: a failure here does not stop
+ * the run. It is not a second arrow — it is the same one — so it shows as a mark
+ * on the step rather than an edge. Silently dropping it makes a step that
+ * survives a provider outage look like one that dies on it, which is the exact
+ * misread this command exists to prevent.
+ */
+export function continuesOnFailure(node) {
+    const fallback = node.fallbackChildUuid;
+    if (typeof fallback !== "string")
+        return false;
+    return childrenOf(node).includes(fallback);
+}
+/** A node's child slots, in order, including the empty ones. */
+function childrenOf(node) {
+    const children = node.childrenUuids;
+    return children === null || children === undefined ? [] : children;
+}
+export function outgoingEdges(node, byUuid) {
+    const children = childrenOf(node);
+    const labels = edgeLabels(node, children.length);
+    const edges = [];
+    children.forEach((child, index) => {
+        if (typeof child === "string" && byUuid.has(child)) {
+            edges.push({ to: child, label: labels[index] });
+        }
+    });
+    const fallback = node.fallbackChildUuid;
+    if (typeof fallback === "string" &&
+        byUuid.has(fallback) &&
+        !children.includes(fallback)) {
+        edges.push({ to: fallback, label: "on failure", dashed: true });
+    }
+    return edges;
+}
+/** Structural problems worth saying out loud rather than drawing over. */
+export function graphWarnings(nodes, byUuid, reached) {
+    const warnings = [];
+    const name = (node) => node.slug === null || node.slug === undefined ? node.uuid : node.slug;
+    const orphans = nodes.filter((node) => typeof node.uuid === "string" && !reached.has(node.uuid));
+    if (orphans.length > 0) {
+        warnings.push(`unreachable from start: ${orphans.map(name).join(", ")} — these nodes never run`);
+    }
+    const dangling = nodes.filter((node) => childrenOf(node).some((child) => child === null || byUuid.has(child) === false));
+    if (dangling.length > 0) {
+        warnings.push(`dangling childrenUuids (null or unknown) on: ${dangling.map(name).join(", ")} — the graph stops there`);
+    }
+    return warnings;
+}
+// ---------------------------------------------------------------------------
 // Shapes and labels
 // ---------------------------------------------------------------------------
 function shapeFor(node) {
     const action = node.actionSlug ?? "";
     if (node.kind === "native") {
-        if (action === "start" || action === "end")
+        if (isStart(node) || isEnd(node))
             return ["([", "])"];
-        if (ROUTING_ACTIONS.includes(action))
+        if (ROUTING_ACTIONS.has(action))
             return ["{", "}"];
         if (CODE_ACTIONS.includes(action))
             return ["[/", "/]"];
@@ -146,7 +239,7 @@ export function labelFor(node) {
  * is the matched path, index 1 the unmatched one. Getting this backwards
  * inverts the diagram's meaning, so it is table-driven, never inferred.
  */
-function edgeLabels(node, count) {
+export function edgeLabels(node, count) {
     const action = node.kind === "native" ? (node.actionSlug ?? "") : "";
     if (action === "branch")
         return ["yes", "no"];
@@ -179,9 +272,6 @@ function edgeLabels(node, count) {
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
-function matches(node, needles) {
-    return needles.some((needle) => needle === node.uuid || needle === (node.slug ?? undefined));
-}
 function subNodes(node) {
     const nested = node.config?.["_nodes"];
     return Array.isArray(nested) && nested.length > 0
@@ -192,11 +282,7 @@ function renderNodes(nodes, context) {
     const warnings = [];
     const highlighted = [];
     const direction = context.direction;
-    const byUuid = new Map();
-    for (const node of nodes) {
-        if (typeof node.uuid === "string")
-            byUuid.set(node.uuid, node);
-    }
+    const byUuid = indexByUuid(nodes);
     // Ids come from a breadth-first walk from `start`, so the diagram reads in
     // execution order and is stable across runs. Slugs are never used as ids:
     // they repeat within a single release.
@@ -204,7 +290,7 @@ function renderNodes(nodes, context) {
     const ids = new Map();
     const seen = new Set();
     const queue = [];
-    const start = nodes.find((node) => node.kind === "native" && node.actionSlug === "start") ?? nodes[0];
+    const start = findStart(nodes);
     if (start !== undefined)
         queue.push(start.uuid);
     while (queue.length > 0) {
@@ -236,28 +322,29 @@ function renderNodes(nodes, context) {
     if (orphans.length > 0) {
         warnings.push(`unreachable from start: ${orphans.map((node) => node.slug ?? node.uuid).join(", ")} — these nodes never run`);
     }
+    // Edges come from the shared walk, so both formats encode routing the same
+    // way — index order, and the rule that a fallback pointing at a node's own
+    // next step is a ↷ mark rather than a second arrow. Only the id mapping is
+    // Mermaid's own.
     const edges = [];
     const dangling = new Set();
     for (const { id, node } of order) {
-        const children = node.childrenUuids ?? [];
-        const labels = edgeLabels(node, children.length);
-        children.forEach((child, index) => {
-            const target = child !== null && child !== undefined ? ids.get(child) : undefined;
-            if (target === undefined) {
-                dangling.add(node.slug ?? id);
-                return;
-            }
-            edges.push({ from: id, to: target, label: labels[index] });
-        });
-        // A fallback pointing at the node's own next step means "a failure here
-        // does not stop the run" — the same arrow, not a second one. Drawing it
-        // twice clutters the graph, so it becomes a ↷ marker on the label instead.
-        const fallbackUuid = node.fallbackChildUuid;
-        if (fallbackUuid !== null && fallbackUuid !== undefined) {
-            const target = ids.get(fallbackUuid);
-            if (target !== undefined && !children.includes(fallbackUuid)) {
-                edges.push({ from: id, to: target, label: "on failure", dashed: true });
-            }
+        for (const edge of outgoingEdges(node, byUuid)) {
+            const target = ids.get(edge.to);
+            if (target === undefined)
+                continue;
+            edges.push({
+                from: id,
+                to: target,
+                label: edge.label,
+                dashed: edge.dashed,
+            });
+        }
+        // `outgoingEdges` drops unusable slots by design; the diagram still has to
+        // report them, and it reports the node rather than the slot.
+        const hasUnusableSlot = childrenOf(node).some((child) => child === null || byUuid.has(child) === false);
+        if (hasUnusableSlot) {
+            dangling.add(node.slug === null || node.slug === undefined ? id : node.slug);
         }
     }
     if (dangling.size > 0) {
@@ -266,14 +353,10 @@ function renderNodes(nodes, context) {
     const lines = [];
     for (const { id, node } of order) {
         const [open, close] = shapeFor(node);
-        const paid = matches(node, context.paid) ? "💳 " : "";
-        if (matches(node, context.highlight))
+        const paid = matchesNode(node, context.paid) ? "💳 " : "";
+        if (matchesNode(node, context.highlight))
             highlighted.push(id);
-        const children = node.childrenUuids ?? [];
-        const continuesOnFailure = node.fallbackChildUuid !== null &&
-            node.fallbackChildUuid !== undefined &&
-            children.includes(node.fallbackChildUuid);
-        lines.push(`    ${id}${open}"${paid}${labelFor(node)}${continuesOnFailure ? " ↷" : ""}"${close}`);
+        lines.push(`    ${id}${open}"${paid}${labelFor(node)}${continuesOnFailure(node) ? " ↷" : ""}"${close}`);
         // A group's steps are drawn inside a sub-graph, under an id namespace of
         // their own — `--paid` and `--highlight` apply just as they do out here,
         // since a billing step buried in a loop is exactly the one worth seeing.

package/build/commands/orchestration/nodeDiagramAscii.d.ts

@@ -0,0 +1,32 @@
+import { displayWidth } from "./asciiBlocks.js";
+import { type DiagramNode } from "./nodeDiagram.js";
+/**
+ * Display names from the integration catalog. A graph stores wire slugs
+ * (`apolloio`, `enrichPerson`); the reader knows the product by its name.
+ * Optional throughout, so a graph diagrammed offline still renders.
+ */
+export type NameBook = {
+    /** integration slug → product name, e.g. `apolloio` → `Apollo.io`. */
+    integrations?: Record<string, string>;
+    /** integration slug → action slug → action name. */
+    actions?: Record<string, Record<string, string>>;
+    /** native action slug → action name, e.g. `script` → `JavaScript`. */
+    native?: Record<string, string>;
+};
+export type AsciiOptions = {
+    title?: string;
+    /** Catalog names, so steps read as products rather than as slugs. */
+    names?: NameBook;
+    /** Node slugs or uuids that bill credits — marked with 💳. */
+    paid?: string[];
+    /** Node slugs or uuids to mark, e.g. the failing node in a trace. */
+    highlight?: string[];
+};
+export { displayWidth };
+export type AsciiResult = {
+    diagram: string;
+    format: "ascii";
+    warnings: string[];
+};
+export declare function renderNodeAscii(nodes: DiagramNode[], options?: AsciiOptions): AsciiResult;
+//# sourceMappingURL=nodeDiagramAscii.d.ts.map

package/build/commands/orchestration/nodeDiagramAscii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeDiagramAscii.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/nodeDiagramAscii.ts"],"names":[],"mappings":"AA4BA,OAAO,EAEL,YAAY,EAWb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEL,KAAK,WAAW,EAQjB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAkkBF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAiDb"}

package/build/commands/orchestration/nodeDiagramAscii.js

@@ -0,0 +1,528 @@
+// Render a workflow node graph as a centred ASCII flow, for terminals.
+//
+// Mermaid is the right answer when the output lands somewhere that renders it —
+// a PR, the docs, a published page. It is the wrong answer in a terminal, where
+// it is just source code the reader has to compile in their head. This module
+// draws the same graph as text a person can read where they are standing.
+//
+// Why not shell out to one of the mermaid-to-ASCII renderers: they re-parse the
+// diagram and auto-route edges on a character grid, which collides as soon as a
+// graph has crossings. Measured on the 29-node `Find email` waterfall, they
+// produce rails drawn straight through node boxes, doubled edge labels
+// (`├─noo►`), and junction characters overwriting label text (`Email┴valid?`) —
+// a picture that reads as edges the workflow does not have. We never have to
+// infer layout, because we hold the graph: this renderer lays a spine down the
+// centre and hangs rails off it, so an edge it draws is an edge that exists.
+//
+// The shape it draws, and why:
+//
+//   * A **spine** runs down the centre. One child continues it; the others peel
+//     off as rails.
+//   * A branch whose paths reconverge is a **detour**: the rail leaves at `├──┐`
+//     and rejoins at `├──┘`, and the spine keeps its identity across the split.
+//   * A branch whose paths never reconverge is a **fork**: `┌──┴──┐`, columns
+//     side by side, no spine survives.
+//
+// Which child holds the spine is the whole readability question, and it is not
+// the same answer in both cases — see `chooseSpine`.
+import { displayWidth, emptyBlock, frame, hstack, indent, padColumn, rail, spineBlock, teeAt, textBlock, vstack, } from "./asciiBlocks.js";
+import { continuesOnFailure, findStart, graphWarnings, indexByUuid, isEnd, matchesNode, outgoingEdges, ROUTING_ACTIONS, } from "./nodeDiagram.js";
+export { displayWidth };
+/**
+ * Where the incoming line meets the split. A detour lands on the column that
+ * keeps the spine; a fork lands between the columns, snapped onto one when it
+ * falls beside it — `┴` and `┬` in adjacent cells read as a smudge rather than
+ * a junction.
+ */
+function columnAnchor(spines, spineIndex, midpoint) {
+    if (spineIndex !== undefined) {
+        const at = spines[spineIndex];
+        return at === undefined ? 0 : at;
+    }
+    const nearest = spines.find((at) => Math.abs(at - midpoint) <= 1);
+    return nearest === undefined ? midpoint : nearest;
+}
+/** Whether a split column is still carrying the flow. */
+function isColumnOpen(columns, index) {
+    if (index === undefined)
+        return false;
+    const column = columns[index];
+    return column === undefined ? false : column.open;
+}
+/** A node's outgoing edges, or none when it has no entry in the graph. */
+function edgesFrom(graph, uuid) {
+    const edges = graph.out.get(uuid);
+    return edges === undefined ? [] : edges;
+}
+/** What to call a node when nothing better is available. */
+function fallbackLabel(node) {
+    return node.slug === null || node.slug === undefined ? node.uuid : node.slug;
+}
+function buildGraph(nodes) {
+    const byUuid = indexByUuid(nodes);
+    const out = new Map();
+    for (const node of nodes)
+        out.set(node.uuid, outgoingEdges(node, byUuid));
+    return { byUuid, out, reach: new Map() };
+}
+/** Everything reachable from `uuid`, itself excluded. Cycle-safe, memoised. */
+function reachable(graph, uuid) {
+    const cached = graph.reach.get(uuid);
+    if (cached !== undefined)
+        return cached;
+    const seen = new Set();
+    const stack = edgesFrom(graph, uuid).map((edge) => edge.to);
+    while (stack.length > 0) {
+        const next = stack.pop();
+        if (next === undefined || seen.has(next))
+            continue;
+        seen.add(next);
+        for (const edge of edgesFrom(graph, next))
+            stack.push(edge.to);
+    }
+    // A descendant pointing back adds the node to its own set. `chooseSpine`
+    // weighs arms by these sizes, so one extra entry is enough to hand the spine
+    // to an arm that should have stayed half of a fork.
+    seen.delete(uuid);
+    graph.reach.set(uuid, seen);
+    return seen;
+}
+/**
+ * Where a branch's paths come back together: the first node reachable from
+ * every child, in one child's own reach order so the choice is deterministic.
+ *
+ * A merge on an `end` node does not count. Every path in a workflow ends there,
+ * so treating it as a reconvergence would wrap the entire graph in one split
+ * and nest every later branch inside it.
+ */
+function mergePoint(graph, children) {
+    const [first, ...rest] = children;
+    if (first === undefined || rest.length === 0)
+        return undefined;
+    // `reachable` hands back its memoised set, so the child itself is compared
+    // separately rather than added to it. Adding would poison the cache, and
+    // `chooseSpine` weighs branches by exactly those set sizes — an entry that
+    // grew by one flips the `best >= second * 2 + 1` test and picks the wrong
+    // arm to carry the spine.
+    const others = rest.map((child) => ({
+        child,
+        reaches: reachable(graph, child),
+    }));
+    const candidates = [first, ...reachable(graph, first)];
+    for (const candidate of candidates) {
+        if (isEnd(graph.byUuid.get(candidate)))
+            continue;
+        if (others.every(({ child, reaches }) => child === candidate || reaches.has(candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Which child keeps the spine — the one judgement call in the layout, and the
+ * answer differs by branch kind:
+ *
+ *   * **Detour** (the paths reconverge): the spine is the *straight-through*
+ *     path, so source order wins and child 0 keeps it. A "not found → look it
+ *     up another way → carry on" branch then reads as a short excursion off a
+ *     continuous main line, which is what it is.
+ *
+ *   * **Fork** (they never reconverge): source order is meaningless, because
+ *     the two sides are not a main line and an excursion. The path with more
+ *     work left in it is the main line. In a provider waterfall the "yes" exit
+ *     is two nodes and the "no" carries the remaining twenty, so weighting by
+ *     what is left keeps the waterfall vertical instead of stair-stepping it
+ *     sideways once per stage.
+ *
+ * The fork rule only applies when one side is decisively bigger. Two ends of
+ * comparable weight are a genuine fork and get drawn symmetrically.
+ */
+function chooseSpine(graph, edges, merged) {
+    if (merged)
+        return 0;
+    const weights = edges.map((edge) => reachable(graph, edge.to).size + 1);
+    let best = 0;
+    let second = 0;
+    let bestIndex = 0;
+    weights.forEach((weight, index) => {
+        if (weight > best) {
+            second = best;
+            best = weight;
+            bestIndex = index;
+        }
+        else if (weight > second) {
+            second = weight;
+        }
+    });
+    return best >= second * SPINE_DOMINANCE + 1 ? bestIndex : undefined;
+}
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+/** Past this the drawing wraps in an ordinary terminal and stops being one. */
+const TERMINAL_WIDTH = 100;
+/**
+ * How much bigger one arm of a non-reconverging branch must be before it is
+ * treated as the main line rather than one of two equal ends.
+ */
+const SPINE_DOMINANCE = 2;
+const GAP = 5;
+/**
+ * `enrichPerson` → `Enrich person`. Only ever a fallback: the catalog's own name
+ * is better, and this is what a graph rendered without one falls back to.
+ * Splitting on case is safe for the slugs the platform mints; it deliberately
+ * does not touch integration slugs, where guessing turns `apolloio` into
+ * something that is neither the slug nor the product.
+ */
+function prettyAction(slug) {
+    const words = slug
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+    const first = words[0];
+    return first === undefined ? slug : first.toUpperCase() + words.slice(1);
+}
+function marks(node, context) {
+    let suffix = "";
+    if (continuesOnFailure(node))
+        suffix += " ↷";
+    if (matchesNode(node, context.paid))
+        suffix += " 💳";
+    if (matchesNode(node, context.highlight))
+        suffix += " ←";
+    return suffix;
+}
+/**
+ * The two label lines: what system the step runs on, then what it does. That
+ * ordering is deliberate — scanning a flow, the reader wants the provider first
+ * ("Apollo", "Slack") and the specifics second.
+ */
+function nodeLines(node, context) {
+    const suffix = marks(node, context);
+    const action = node.actionSlug === null || node.actionSlug === undefined
+        ? ""
+        : node.actionSlug;
+    if (node.kind === "native" && (action === "start" || action === "end")) {
+        return [`${fallbackLabel(node)}${suffix}`];
+    }
+    const name = node.name === null || node.name === undefined
+        ? undefined
+        : node.name.trim();
+    const book = context.names;
+    // The action's own name, as the platform publishes it. Falling back to the
+    // slug split into words keeps an offline drawing readable without this file
+    // inventing a name that disagrees with the product.
+    const published = book === undefined || book.native === undefined
+        ? undefined
+        : book.native[action];
+    const nativeName = published === undefined ? prettyAction(action) : published;
+    // A routing step's second line would read "Branch" under every one of them,
+    // so it gets one line. The labelled rails leaving it already say it routes.
+    if (node.kind === "native" && ROUTING_ACTIONS.has(action)) {
+        const headline = name !== undefined && name.length > 0 ? name : nativeName;
+        return [`${headline}${suffix}`];
+    }
+    if (node.kind === "connector") {
+        const slug = node.integrationSlug === null || node.integrationSlug === undefined
+            ? "connector"
+            : node.integrationSlug;
+        const named = book === undefined || book.integrations === undefined
+            ? undefined
+            : book.integrations[slug];
+        const provider = named === undefined ? slug : named;
+        const perAction = book === undefined || book.actions === undefined
+            ? undefined
+            : book.actions[slug];
+        const actionName = perAction === undefined ? undefined : perAction[action];
+        const what = name !== undefined && name.length > 0
+            ? name
+            : actionName === undefined
+                ? prettyAction(action)
+                : actionName;
+        return provider === what
+            ? [`${provider}${suffix}`]
+            : [`${provider}${suffix}`, what];
+    }
+    const provider = node.kind === "tool"
+        ? "Tool"
+        : node.kind === "agent"
+            ? "Agent"
+            : nativeName;
+    const headline = name !== undefined && name.length > 0 ? name : node.slug;
+    if (headline === undefined ||
+        headline === null ||
+        headline === provider ||
+        headline === action) {
+        return [`${provider}${suffix}`];
+    }
+    return [`${provider}${suffix}`, headline];
+}
+function referenceBlock(node, context) {
+    // The step's most specific line — for a two-line step that is what it does,
+    // not the product it runs on, since the product repeats across steps.
+    const lines = nodeLines(node, context);
+    const specific = lines[lines.length - 1];
+    const label = specific ?? fallbackLabel(node);
+    return textBlock([`↑ ${label}`]);
+}
+/**
+ * A group's own graph, drawn inside a box rather than left to the reader's
+ * imagination. The steps live in `config._nodes` and form a complete graph of
+ * their own — start node included — so the same walk draws them one level down.
+ * Marks and names carry in; `drawn` does not, because an inner step repeating an
+ * outer slug is a different step.
+ */
+function subGraph(node, context) {
+    const config = node.config;
+    const nested = config === null || config === undefined ? undefined : config["_nodes"];
+    // No `_nodes` key at all means the graph came from a source that does not
+    // carry loop bodies; an empty one means the loop was left empty, which is a
+    // defect the drawing should not hide behind a tidy box.
+    if (!Array.isArray(nested))
+        return undefined;
+    const label = fallbackLabel(node);
+    if (nested.length === 0) {
+        context.notes.push(`${label}: the loop has no steps`);
+        return undefined;
+    }
+    const nodes = nested;
+    const start = findStart(nodes);
+    if (start === undefined)
+        return undefined;
+    const graph = buildGraph(nodes);
+    const inner = { ...context, graph, drawn: new Set() };
+    const { block } = layout(start.uuid, new Set(), inner);
+    for (const warning of graphWarnings(nodes, graph.byUuid, inner.drawn)) {
+        context.notes.push(`${label}: ${warning}`);
+    }
+    return frame(block, "per item");
+}
+/**
+ * Draw the flow rooted at `uuid`, stopping when it reaches anything in `stop`.
+ * The returned block's spine is live at the bottom only when `open` is true —
+ * a caller merging rails back together needs to know whether there is anything
+ * left to merge.
+ */
+function layout(uuid, stop, context) {
+    if (stop.has(uuid))
+        return { block: emptyBlock(), open: true };
+    const node = context.graph.byUuid.get(uuid);
+    if (node === undefined)
+        return { block: emptyBlock(), open: false };
+    // An `end` is allowed to appear more than once: five paths finishing at `end`
+    // read better as five `end`s than as five pointers to one. Every other node
+    // is referenced on a second arrival, leaf or not — drawing a named step like
+    // "Send to #best-leads" twice reads as two separate sends.
+    const edges = edgesFrom(context.graph, uuid);
+    if (context.drawn.has(uuid) && !isEnd(node)) {
+        return { block: referenceBlock(node, context), open: false };
+    }
+    context.drawn.add(uuid);
+    const nested = subGraph(node, context);
+    const head = nested === undefined
+        ? textBlock(nodeLines(node, context))
+        : vstack([textBlock(nodeLines(node, context)), spineBlock(), nested]);
+    if (edges.length === 0)
+        return { block: head, open: false };
+    if (edges.length === 1) {
+        const edge = edges[0];
+        if (edge === undefined)
+            return { block: head, open: false };
+        const tail = layout(edge.to, stop, context);
+        // A lone edge usually has no label and draws as a bare `│`. When it does
+        // carry one — a branch whose other arm is dangling, or a step whose only
+        // outgoing edge is its fallback — the label goes above the stem, the way
+        // every multi-edge column draws it, so it reads as an edge label rather
+        // than as the name of the step below it.
+        const stem = spineBlock(edge.dashed === true ? "┆" : "│");
+        const connector = edge.label === undefined ? stem : vstack([textBlock([edge.label]), stem]);
+        if (tail.block.lines.length === 0) {
+            return { block: vstack([head, connector]), open: true };
+        }
+        return {
+            block: vstack([head, connector, tail.block]),
+            open: tail.open,
+        };
+    }
+    return branch(head, edges, stop, context);
+}
+function branch(head, edges, stop, context) {
+    // An elided routing node contributes no rows, and the step above it already
+    // drew the `│` leading in — adding another leaves a two-row gap above every
+    // split in a graph whose branches are unnamed.
+    const lead = head.lines.length === 0 ? emptyBlock() : spineBlock();
+    const merge = mergePoint(context.graph, edges.map((edge) => edge.to));
+    const spineIndex = chooseSpine(context.graph, edges, merge !== undefined);
+    const innerStop = new Set(stop);
+    if (merge !== undefined)
+        innerStop.add(merge);
+    // Columns are label-over-body so `hstack` sizes each one around whichever is
+    // wider, and an edge label can never collide with the node beneath it.
+    const columns = edges.map((edge) => {
+        const drawn = layout(edge.to, innerStop, context);
+        const char = edge.dashed === true ? "┆" : "│";
+        return {
+            block: vstack([
+                textBlock([edge.label === undefined ? char : edge.label]),
+                spineBlock(char),
+                drawn.block,
+            ]),
+            open: drawn.open,
+            char,
+        };
+    });
+    const height = Math.max(...columns.map((column) => column.block.lines.length));
+    const padded = columns.map((column) => padColumn(column.block, 
+    // A column still carrying the flow is drawn to the bottom of the split,
+    // so its spine is unbroken all the way to whatever joins it below. One
+    // that has ended stops where it ended — the difference is how the reader
+    // tells a path that continues from a path that terminates.
+    column.open ? height : column.block.lines.length, column.char));
+    // The spine column is drawn leftmost, whichever child holds it, so rails
+    // always peel off to the right. Ordering columns by edge index instead pushes
+    // the spine one indent further right at every nesting level — five stages of
+    // a waterfall then stair-step across 80 columns rather than staying in one
+    // vertical line. Labels ride their own rail, so nothing is mislabelled by the
+    // reordering; only the left-to-right order of the arms changes.
+    const order = spineIndex === undefined
+        ? padded.map((_, index) => index)
+        : [
+            spineIndex,
+            ...padded
+                .map((_, index) => index)
+                .filter((index) => index !== spineIndex),
+        ];
+    const laid = hstack(order.map((index) => {
+        const column = padded[index];
+        return column === undefined ? emptyBlock() : column;
+    }), GAP);
+    const body = laid.block;
+    const width = body.width;
+    const spines = new Array(padded.length).fill(0);
+    order.forEach((original, position) => {
+        const at = laid.spines[position];
+        spines[original] = at === undefined ? 0 : at;
+    });
+    const isDetour = spineIndex !== undefined;
+    const first = spines[0];
+    const last = spines[spines.length - 1];
+    const midpoint = Math.round(((first === undefined ? 0 : first) + (last === undefined ? 0 : last)) / 2);
+    // Snap the incoming line onto a column when it lands beside one: `┴` and `┬`
+    // printed in adjacent cells read as a smudge, not a junction.
+    const anchor = columnAnchor(spines, spineIndex, midpoint);
+    const others = spines.filter((_, index) => index !== spineIndex);
+    // A detour keeps its spine and hangs the rails off it; a fork has no spine to
+    // keep, so the incoming line lands between the columns instead.
+    const splitRail = isDetour
+        ? rail(width, spines.map((at, index) => ({
+            at,
+            char: index === spineIndex
+                ? teeAt(anchor, others, true)
+                : at > anchor
+                    ? "┐"
+                    : "┌",
+        })))
+        : rail(width, [
+            ...spines.map((at, index) => ({
+                at,
+                char: at === anchor
+                    ? "┼"
+                    : index === 0
+                        ? "┌"
+                        : index === spines.length - 1
+                            ? "┐"
+                            : "┬",
+            })),
+            ...(spines.includes(anchor) ? [] : [{ at: anchor, char: "┴" }]),
+        ]);
+    const top = vstack([head, lead]);
+    const aligned = indent({ lines: [splitRail, ...body.lines], width, spine: anchor }, Math.max(0, top.spine - anchor));
+    const whole = vstack([top, aligned]);
+    const mergeAt = aligned.spine;
+    // Every column still carrying the flow is joined back to one spine, whether
+    // this branch owns the merge point or an ancestor does. A column left hanging
+    // reads as a path that stops, which is a different claim about the workflow.
+    const shift = aligned.width - width;
+    const arms = spines
+        .map((at, index) => ({
+        at: at + shift,
+        open: isColumnOpen(columns, index),
+    }))
+        .filter(({ at, open }) => open && at !== mergeAt)
+        .map(({ at }) => at);
+    const joined = arms.length === 0
+        ? []
+        : [
+            {
+                lines: [
+                    rail(aligned.width, [
+                        { at: mergeAt, char: teeAt(mergeAt, arms, false) },
+                        ...arms.map((at) => ({
+                            at,
+                            char: at > mergeAt ? "┘" : "└",
+                        })),
+                    ]),
+                ],
+                width: aligned.width,
+                spine: mergeAt,
+            },
+        ];
+    if (merge === undefined) {
+        // For a detour, the spine column's status determines the flow. For a fork,
+        // any open column means the flow continues — including the column at the
+        // anchor, which `arms` filters out because it needs no rail to reach it.
+        const spineOpen = isDetour
+            ? isColumnOpen(columns, spineIndex)
+            : columns.some((column) => column.open);
+        return { block: vstack([whole, ...joined]), open: spineOpen };
+    }
+    const after = layout(merge, stop, context);
+    return {
+        block: vstack([whole, ...joined, spineBlock(), after.block]),
+        open: after.open,
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export function renderNodeAscii(nodes, options = {}) {
+    const graph = buildGraph(nodes);
+    const warnings = [];
+    const start = findStart(nodes);
+    if (start === undefined) {
+        return { diagram: "", format: "ascii", warnings: ["no nodes to draw"] };
+    }
+    const context = {
+        graph,
+        names: options.names,
+        paid: options.paid === undefined ? [] : options.paid,
+        highlight: options.highlight === undefined ? [] : options.highlight,
+        drawn: new Set(),
+        notes: warnings,
+    };
+    const { block } = layout(start.uuid, new Set(), context);
+    warnings.push(...graphWarnings(nodes, graph.byUuid, context.drawn));
+    // Rails stack rightward, so a graph that branches at every step of a long
+    // chain gets wide no matter how the columns are packed — each rail has to
+    // clear the one belonging to the step below it. Say so rather than letting it
+    // wrap in the reader's terminal and look like a rendering bug.
+    const widest = Math.max(0, ...block.lines.map((line) => displayWidth(line)));
+    if (widest > TERMINAL_WIDTH) {
+        warnings.push(`the drawing is ${String(widest)} columns wide and will wrap in most terminals — try --format mermaid, or diagram a sub-graph`);
+    }
+    const body = block.lines.map((line) => line.replace(/\s+$/, "")).join("\n");
+    const title = options.title === undefined ? undefined : options.title.trim();
+    if (title === undefined || title.length === 0) {
+        return { diagram: body, format: "ascii", warnings };
+    }
+    // Centre the title on the spine, not on the drawing's bounding box — the
+    // spine is what the eye follows down, and a wide rail off to one side would
+    // otherwise drag the title away from it.
+    const left = Math.max(0, block.spine - Math.floor(displayWidth(title) / 2));
+    return {
+        diagram: `${" ".repeat(left)}${title}\n\n${body}`,
+        format: "ascii",
+        warnings,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.55",
+  "version": "1.0.56",
   "private": false,
   "license": "UNLICENSED",
   "homepage": "https://getcargo.ai",