@cargo-ai/cli 1.0.55 → 1.0.57

package/README.md

@@ -42,7 +42,7 @@ cargo-ai login --token <your-api-token>
 
 `--email` and `--oauth` save the signed-in session — a short-lived access token plus the refresh token that renews it — to `~/.config/cargo-ai/credentials.json` (file mode `0600`). The CLI renews it in the background as it expires, so you stay signed in and no API token is created per machine. `--token` saves the API token you supplied instead. The same file backs `cargo-cdk`, so one login serves both.
 
-`cargo-ai logout` revokes the session at the identity provider, so signing out is final. A token you supplied yourself with `--token` is only forgotten locally, since it may be in use elsewhere; pass `--keep-token` to force that behaviour for a session too.
+`cargo-ai logout` revokes the session at the identity provider, so signing out is final. A token you supplied yourself with `--token` is only forgotten locally, since it may be in use elsewhere; pass `--keep-token` to force that behaviour for a session too. If a credentials file cannot be deleted — a read-only config directory, or one owned by another user — `logout` fails and names the file rather than reporting a sign-out the next command would contradict.
 
 Treat the file as you would a password. A saved session acts as you across **every** workspace you belong to — unlike an API token, which is limited to one workspace and to the permissions it was created with — and it stays valid until you run `cargo-ai logout` or the identity provider expires it. On a shared or long-lived machine (CI, a build box), prefer an API token created under **Settings → API** and passed via `CARGO_API_TOKEN`, which you can scope down and revoke from the dashboard.
 

package/build/commands/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAwBxD,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkGN;AAmFD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,IAAI,EAAE,aAAa,GAClB,cAAc,CAchB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAyBxD,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAyGN;AAiGD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,IAAI,EAAE,aAAa,GAClB,cAAc,CAchB"}

package/build/commands/auth/index.js

@@ -2,7 +2,7 @@ import { revokeSession } from "@cargo-ai/cdk/cli";
 import { Option } from "commander";
 import { AGENT_SKILLS_NEXT_STEP } from "../../agentSkills.js";
 import { getConfig } from "../../config.js";
-import { clearCredentials, getCredentialsPath, loadCredentials, saveCredentials, } from "../../credentials.js";
+import { clearCredentials, CredentialsNotClearedError, getCredentialsPath, loadCredentials, saveCredentials, } from "../../credentials.js";
 import { ExitCodes, failWith, handleApiCall, info, outputJson, success, } from "../runHandler.js";
 import { runEmailLogin } from "./email.js";
 import { selectLoginChannel } from "./loginChannel.js";
@@ -40,8 +40,11 @@ that name when one exists, so this is safe to re-run.
 
 --email and --oauth save the signed-in session to
 ~/.config/cargo-ai/credentials.json and renew it automatically, so you stay
-signed in without a token being created for each machine. Switch workspace at
-any time with CARGO_WORKSPACE_UUID or by signing in again with
+signed in without a token being created for each machine. CARGO_CONFIG_DIR
+(or XDG_CONFIG_HOME) moves that file; where the home directory is not writable
+— agent sandboxes usually run that way — the session is saved under the system
+temp directory instead, which lasts only as long as the sandbox. Switch
+workspace at any time with CARGO_WORKSPACE_UUID or by signing in again with
 --workspace-uuid <uuid>. An API token passed with --token stays pinned to its
 own workspace, so the override does not apply to it.
 
@@ -59,7 +62,11 @@ Environment variables (CARGO_API_TOKEN, CARGO_WORKSPACE_UUID, CARGO_BASE_URL) ta
         .addHelpText("after", `
 A session from "cargo-ai login --email" or "--oauth" is revoked at the identity
 provider, so signing out is final. Tokens you supplied yourself with --token are
-only forgotten locally, since they may be in use elsewhere.`)
+only forgotten locally, since they may be in use elsewhere.
+
+Signing out fails, naming the file, when a credentials file cannot be deleted —
+a read-only config directory, or one owned by another user — because the next
+command would otherwise read it and still be signed in.`)
         .action(async (opts) => {
         await runLogout(opts);
     });
@@ -123,7 +130,20 @@ async function runLogout(opts) {
     const credentials = loadCredentials();
     const plan = planRevocation(credentials, opts);
     const revoked = await applyRevocation(plan, credentials);
-    const removed = clearCredentials();
+    let removed;
+    try {
+        removed = clearCredentials();
+    }
+    catch (error) {
+        if (error instanceof CredentialsNotClearedError) {
+            // Revocation already happened, so say so: re-running logout will not
+            // revoke a second time, and the file is all that is left to deal with.
+            failWith(error.message, {
+                extra: { revoked, credentialsFiles: error.paths },
+            });
+        }
+        throw error;
+    }
     if (removed === true) {
         success(revoked === true ? "Signed out and revoked access." : "Signed out.");
     }

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":"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"}