@cargo-ai/cli 1.0.53 → 1.0.54

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":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CA8J7E"}
+{"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"}

package/build/commands/orchestration/node.js

@@ -1,21 +1,28 @@
-import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
+import { readFileSync } from "node:fs";
+import { ExitCodes, failWith, handleApiCall, outputJson, parseJson, } from "../runHandler.js";
+import { extractNodes, renderNodeDiagram, toMermaidBlock, } from "./nodeDiagram.js";
 export function registerNodeCommands(parent, getApi) {
     const node = parent
         .command("node")
-        .description("Debug a workflow one node at a time: compute a node's config, validate node definitions, execute a single node")
+        .description("Work with a workflow's node graph: draw it, validate it, compute a node's config, execute a single node")
         .addHelpText("after", `
-Use these commands to debug one node of an existing workflow release. To just
+Use these commands to inspect or debug the node graph of a workflow. To just
 run a tool or connector action, no workflow needed, use instead:
   $ cargo-ai orchestration action execute --action '<json>' --data '<json>'
 
-'compute' and 'validate' are free and run nothing. 'execute' is not a dry run:
-it performs the node's real action and consumes credits.
+'diagram', 'compute' and 'validate' are free and run nothing. 'execute' is not
+a dry run: it performs the node's real action and consumes credits.
+
+Before deploying a graph:
+  $ cargo-ai orchestration node validate --nodes '<json>'
+  $ cargo-ai orchestration node diagram --nodes '<json>' --raw
 
 Debugging loop:
   $ cargo-ai orchestration span list --run-uuid <uuid> --execution-started-after <iso-date>
-  $ cargo-ai orchestration release get-deployed --workflow-uuid <uuid>
+  $ cargo-ai orchestration node diagram --run-uuid <uuid> --highlight <slug> --raw
   $ cargo-ai orchestration node compute --node '<json>' --context '<json>'
   $ cargo-ai orchestration node execute --workflow-uuid <uuid> --release-uuid <uuid> --node '<json>' --computed-config '<json>' --context '<json>'`);
+    registerDiagramCommand(node, getApi);
     node
         .command("compute")
         .description("Compute a node's configuration from its definition and context")
@@ -95,3 +102,135 @@ Examples:
         outputJson(result);
     });
 }
+function registerDiagramCommand(node, getApi) {
+    node
+        .command("diagram")
+        .description("Draw a node graph as a Mermaid flowchart (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)")
+        .option("--draft", "With --workflow-uuid, use the draft release")
+        .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("--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")
+        .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.
+
+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 -`)
+        .action(async (opts) => {
+        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),
+        });
+        if (opts.raw === true) {
+            console.log(toMermaidBlock(result.diagram));
+            for (const warning of result.warnings)
+                console.error(`⚠ ${warning}`);
+            return;
+        }
+        outputJson(result);
+    });
+}
+function splitList(value) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+async function resolveNodes(getApi, opts) {
+    const sources = [
+        opts.nodes !== undefined ? "--nodes" : undefined,
+        opts.file !== undefined ? "--file" : undefined,
+        opts.workflowUuid !== undefined ? "--workflow-uuid" : undefined,
+        opts.releaseUuid !== undefined ? "--release-uuid" : undefined,
+        opts.runUuid !== undefined ? "--run-uuid" : undefined,
+    ].filter((source) => source !== undefined);
+    if (sources.length === 0) {
+        failWith("pass one of --nodes, --file, --workflow-uuid, --release-uuid or --run-uuid", { code: ExitCodes.InvalidUsage });
+    }
+    if (sources.length > 1) {
+        failWith(`${sources.join(" and ")} are mutually exclusive`, {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+    if (opts.nodes !== undefined) {
+        const raw = opts.nodes === "-" ? await readStdin() : opts.nodes;
+        return fromPayload(parseJson(raw, "--nodes"), "--nodes");
+    }
+    if (opts.file !== undefined) {
+        return fromPayload(parseJson(readFileSync(opts.file, "utf8"), "--file"), "--file");
+    }
+    const api = getApi();
+    if (opts.workflowUuid !== undefined) {
+        const workflowUuid = opts.workflowUuid;
+        const result = await handleApiCall(() => opts.draft === true
+            ? api.orchestration.draftRelease.get({ workflowUuid })
+            : api.orchestration.release.getDeployed({ workflowUuid }));
+        return fromPayload(result, "--workflow-uuid");
+    }
+    if (opts.releaseUuid !== undefined) {
+        const releaseUuid = opts.releaseUuid;
+        const result = await handleApiCall(() => api.orchestration.release.get(releaseUuid));
+        return fromPayload(result, "--release-uuid");
+    }
+    // A run either carries its own graph (`action execute`, `run create --nodes`)
+    // or points at the release that holds one — never both. Follow whichever it
+    // has, so the caller does not have to know which kind of run they were given.
+    const runUuid = opts.runUuid;
+    if (runUuid === undefined) {
+        failWith("no graph source resolved", { code: ExitCodes.InvalidUsage });
+    }
+    const run = await handleApiCall(() => api.orchestration.run.get(runUuid));
+    const inline = extractNodes(run);
+    if (inline !== undefined)
+        return inline;
+    const releaseUuid = run.run
+        ?.releaseUuid;
+    if (releaseUuid === null || releaseUuid === undefined) {
+        failWith(`run ${runUuid} carries neither a node graph nor a release`, {
+            code: ExitCodes.NotFound,
+        });
+    }
+    const release = await handleApiCall(() => api.orchestration.release.get(releaseUuid));
+    return fromPayload(release, "--run-uuid");
+}
+function fromPayload(payload, source) {
+    const nodes = extractNodes(payload);
+    if (nodes === undefined) {
+        failWith(`no node graph found in the payload passed to ${source} — expected a node array, or the output of 'release get', 'release get-draft', 'template get' or 'run get'`, { code: ExitCodes.InvalidUsage });
+    }
+    return nodes;
+}
+async function readStdin() {
+    if (process.stdin.isTTY === true) {
+        failWith("--nodes - expects JSON on stdin", {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}

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

@@ -0,0 +1,45 @@
+/** Structural shape of a node — deliberately loose, so this module stays
+ * decoupled from the generated API types and can also render a hand-written
+ * graph that has not been deployed yet. */
+export type DiagramNode = {
+    uuid: string;
+    slug?: string | null;
+    name?: string | null;
+    kind?: string | null;
+    actionSlug?: string | null;
+    integrationSlug?: string | null;
+    toolUuid?: string | null;
+    agentUuid?: string | null;
+    /** Template slug for tool/agent nodes sourced from a template graph. */
+    templateSlug?: string | null;
+    childrenUuids?: (string | null)[] | null;
+    fallbackChildUuid?: string | null;
+    config?: Record<string, unknown> | null;
+};
+export type DiagramOptions = {
+    title?: string;
+    direction?: string;
+    /** Node slugs or uuids that bill credits — rendered with a 💳. */
+    paid?: string[];
+    /** Node slugs or uuids to mark red, e.g. the failing node in a trace. */
+    highlight?: string[];
+};
+export type DiagramResult = {
+    diagram: string;
+    format: "mermaid";
+    /** Structural problems worth saying out loud rather than drawing over. */
+    warnings: string[];
+};
+/** What the node is, in words a user recognises. */
+export declare function labelFor(node: DiagramNode): string;
+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[];
+/**
+ * Pull the graph out of a CLI payload: `release get`, `release get-draft`,
+ * `template get`, an ad-hoc `run get`, or a bare node array.
+ */
+export declare function extractNodes(payload: unknown): DiagramNode[] | undefined;
+/** The fenced block, ready to paste into a message, a PR, or the docs. */
+export declare function toMermaidBlock(diagram: string): string;
+//# sourceMappingURL=nodeDiagram.d.ts.map

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

@@ -0,0 +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"}

package/build/commands/orchestration/nodeDiagram.js

@@ -0,0 +1,373 @@
+// Render a workflow node graph as a Mermaid flowchart.
+//
+// A node graph carries routing, fallback paths and paid steps; prose flattens
+// all three, so "what does this play do?" is best answered with a picture. Every
+// surface the CLI prints into — coding agents, GitHub, the docs — renders
+// Mermaid, and this is a pure local transform: no API call, no credits.
+//
+// Two properties of real releases drive the implementation:
+//
+//   * `slug` is NOT unique within a release. A shipped waterfall carries six
+//     nodes slugged `variables`. Everything here keys on `uuid`; slugs are used
+//     for labels and for matching user-supplied --paid / --highlight only.
+//   * `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 = [
+    "branch",
+    "filter",
+    "switch",
+    "split",
+    "balance",
+    "humanReview",
+];
+const CODE_ACTIONS = ["python", "script"];
+// ---------------------------------------------------------------------------
+// Shapes and labels
+// ---------------------------------------------------------------------------
+function shapeFor(node) {
+    const action = node.actionSlug ?? "";
+    if (node.kind === "native") {
+        if (action === "start" || action === "end")
+            return ["([", "])"];
+        if (ROUTING_ACTIONS.includes(action))
+            return ["{", "}"];
+        if (CODE_ACTIONS.includes(action))
+            return ["[/", "/]"];
+        if (action === "agent")
+            return ["{{", "}}"];
+        if (action === "group")
+            return ["[", "]"];
+        return ["(", ")"];
+    }
+    if (node.kind === "tool")
+        return ["[[", "]]"];
+    if (node.kind === "agent")
+        return ["{{", "}}"];
+    return ["[", "]"]; // connector, and anything unrecognised
+}
+// Labels are emitted quoted, so brackets and parens inside them are safe; a raw
+// quote, angle bracket, pipe or newline is not — those end the label early or
+// inject markup into Mermaid's HTML labels. Pipe also breaks edge labels
+// (|…|), so it must be escaped everywhere.
+function escapeLabel(text) {
+    return text
+        .replace(/\s+/g, " ")
+        .replace(/"/g, "#quot;")
+        .replace(/</g, "#lt;")
+        .replace(/>/g, "#gt;")
+        .replace(/\|/g, "#124;")
+        .trim();
+}
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+function configString(node, key) {
+    const value = node.config?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+// A constant config number, however the graph happens to spell it: `30`, the
+// string `"30"`, or a `{{ 30 }}` template body. Anchored, so a real expression
+// (`{{ nodes.start.pct }}`) has no match and stays unlabelled rather than
+// showing a number the run will not use.
+const CONSTANT_NUMBER = /^\s*(?:\{\{\s*([+-]?\d+(?:\.\d+)?)\s*\}\}|([+-]?\d+(?:\.\d+)?))\s*$/;
+/**
+ * A numeric config value. Only the canvas writes these as raw JSON numbers: a
+ * stored release and an SDK-compiled graph both wrap them in the wire's
+ * expression object — `{ kind: "templateExpression", expression: "{{ 30 }}" }`
+ * — which the engine resolves before the action sees it. Reading only raw
+ * numbers loses the value on every graph that was not hand-written.
+ */
+function configNumber(node, key) {
+    const value = node.config?.[key];
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    let source;
+    if (typeof value === "string") {
+        source = value;
+    }
+    else if (value !== null && typeof value === "object") {
+        const expression = value.expression;
+        if (typeof expression === "string")
+            source = expression;
+    }
+    if (source === undefined)
+        return undefined;
+    const match = CONSTANT_NUMBER.exec(source);
+    if (match === null)
+        return undefined;
+    const digits = match[1] !== undefined ? match[1] : match[2];
+    if (digits === undefined)
+        return undefined;
+    const parsed = Number(digits);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** The second label line: what the node actually calls. */
+function detailFor(node) {
+    if (node.kind === "connector") {
+        return `${node.integrationSlug ?? "?"}.${node.actionSlug ?? "?"}`;
+    }
+    if (node.kind === "tool") {
+        const uuid = node.toolUuid ?? configString(node, "toolUuid");
+        const slug = node.templateSlug ?? configString(node, "templateSlug");
+        return `tool ${uuid !== undefined && uuid !== null ? uuid.slice(0, 8) : (slug ?? "?")}`;
+    }
+    if (node.kind === "agent") {
+        const uuid = node.agentUuid ?? configString(node, "agentUuid");
+        const slug = node.templateSlug ?? configString(node, "templateSlug");
+        return `agent ${uuid !== undefined && uuid !== null ? uuid.slice(0, 8) : (slug ?? "?")}`;
+    }
+    if (node.kind === "native") {
+        const action = node.actionSlug ?? "";
+        if (action === "start" || action === "end")
+            return undefined;
+        if (action === "delay") {
+            const minutes = configNumber(node, "minutes");
+            return minutes !== undefined ? `delay ${String(minutes)}m` : "delay";
+        }
+        return action.length > 0 ? action : undefined;
+    }
+    return node.kind ?? undefined;
+}
+/** What the node is, in words a user recognises. */
+export function labelFor(node) {
+    const headline = node.name !== null && node.name !== undefined && node.name.trim().length > 0
+        ? node.name.trim()
+        : (node.slug ?? node.kind ?? "node");
+    const lines = [truncate(headline)];
+    const detail = detailFor(node);
+    if (detail !== undefined && detail !== lines[0])
+        lines.push(truncate(detail));
+    return lines.map(escapeLabel).join("<br/>");
+}
+/**
+ * `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.
+ */
+function edgeLabels(node, count) {
+    const action = node.kind === "native" ? (node.actionSlug ?? "") : "";
+    if (action === "branch")
+        return ["yes", "no"];
+    if (action === "humanReview")
+        return ["approve", "decline"];
+    if (action === "filter")
+        return ["if true"];
+    if (action === "split") {
+        const pct = configNumber(node, "percentage");
+        if (pct === undefined)
+            return ["A", "B"];
+        return [`A ${String(pct)}%`, `B ${String(100 - pct)}%`];
+    }
+    if (action === "switch" || action === "balance") {
+        const rawRoutes = node.config?.["routes"];
+        const routes = Array.isArray(rawRoutes) ? rawRoutes : [];
+        return Array.from({ length: count }, (_, index) => {
+            // A switch often has one more child than routes — the default/else path.
+            if (index >= routes.length)
+                return "default";
+            const route = routes[index];
+            const name = route !== null && typeof route === "object" && "name" in route
+                ? route.name
+                : undefined;
+            return typeof name === "string" ? name : `route ${String(index + 1)}`;
+        });
+    }
+    return Array.from({ length: count }, () => undefined);
+}
+// ---------------------------------------------------------------------------
+// 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
+        ? nested
+        : undefined;
+}
+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);
+    }
+    // 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.
+    const order = [];
+    const ids = new Map();
+    const seen = new Set();
+    const queue = [];
+    const start = nodes.find((node) => node.kind === "native" && node.actionSlug === "start") ?? nodes[0];
+    if (start !== undefined)
+        queue.push(start.uuid);
+    while (queue.length > 0) {
+        const uuid = queue.shift();
+        if (uuid === undefined || seen.has(uuid))
+            continue;
+        const node = byUuid.get(uuid);
+        if (node === undefined)
+            continue;
+        seen.add(uuid);
+        const id = `${context.idPrefix}n${String(order.length)}`;
+        ids.set(uuid, id);
+        order.push({ id, node });
+        for (const child of node.childrenUuids ?? []) {
+            if (child !== null && child !== undefined)
+                queue.push(child);
+        }
+        if (node.fallbackChildUuid !== null &&
+            node.fallbackChildUuid !== undefined) {
+            queue.push(node.fallbackChildUuid);
+        }
+    }
+    const orphans = nodes.filter((node) => typeof node.uuid === "string" && !seen.has(node.uuid));
+    for (const node of orphans) {
+        const id = `${context.idPrefix}n${String(order.length)}`;
+        ids.set(node.uuid, id);
+        order.push({ id, node });
+    }
+    if (orphans.length > 0) {
+        warnings.push(`unreachable from start: ${orphans.map((node) => node.slug ?? node.uuid).join(", ")} — these nodes never run`);
+    }
+    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 });
+            }
+        }
+    }
+    if (dangling.size > 0) {
+        warnings.push(`dangling childrenUuids (null or unknown) on: ${[...dangling].join(", ")} — the graph stops there`);
+    }
+    const lines = [];
+    for (const { id, node } of order) {
+        const [open, close] = shapeFor(node);
+        const paid = matches(node, context.paid) ? "💳 " : "";
+        if (matches(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}`);
+        // 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.
+        const nested = subNodes(node);
+        if (nested !== undefined) {
+            const inner = renderNodes(nested, { ...context, idPrefix: `${id}s` });
+            warnings.push(...inner.warnings.map((w) => `${node.slug ?? id}: ${w}`));
+            highlighted.push(...inner.highlighted);
+            lines.push(`    subgraph ${id}_sub["per item"]`);
+            lines.push(`    direction ${direction}`);
+            lines.push(...inner.lines.map((line) => `    ${line}`));
+            lines.push("    end");
+            lines.push(`    ${id} --> ${id}_sub`);
+        }
+    }
+    for (const edge of edges) {
+        const arrow = edge.dashed === true
+            ? edge.label !== undefined
+                ? `-. ${edge.label} .->`
+                : "-.->"
+            : edge.label !== undefined
+                ? `-->|${escapeLabel(edge.label)}|`
+                : "-->";
+        lines.push(`    ${edge.from} ${arrow} ${edge.to}`);
+    }
+    return { lines, warnings, highlighted };
+}
+export function renderNodeDiagram(nodes, options = {}) {
+    const direction = options.direction ?? "TD";
+    const lines = [];
+    if (options.title !== undefined && options.title.length > 0) {
+        // Quote the title if it contains YAML-special characters (colon-space, #,
+        // quotes, leading/trailing whitespace) to keep the frontmatter valid.
+        const raw = options.title.replace(/\n/g, " ");
+        const needsQuotes = /[:#"']|^\s|\s$/.test(raw);
+        const escaped = needsQuotes ? `"${raw.replace(/"/g, '\\"')}"` : raw;
+        lines.push("---", `title: ${escaped}`, "---");
+    }
+    lines.push(`flowchart ${direction}`);
+    const body = renderNodes(nodes, {
+        direction,
+        paid: options.paid ?? [],
+        highlight: options.highlight ?? [],
+        idPrefix: "",
+    });
+    lines.push(...body.lines);
+    // Declared once for the whole diagram, nested levels included — Mermaid takes
+    // a `classDef` name a single time.
+    if (body.highlighted.length > 0) {
+        lines.push("    classDef failing fill:#fee,stroke:#c00,stroke-width:2px");
+        lines.push(`    class ${body.highlighted.join(",")} failing`);
+    }
+    return {
+        diagram: lines.join("\n"),
+        format: "mermaid",
+        warnings: body.warnings,
+    };
+}
+// ---------------------------------------------------------------------------
+// Locating the graph in a payload
+// ---------------------------------------------------------------------------
+/** Node-shaped means: a uuid plus the fields a graph is walked by. */
+export function isNodeArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((item) => item !== null &&
+            typeof item === "object" &&
+            typeof item.uuid === "string" &&
+            ("childrenUuids" in item || "kind" in item)));
+}
+/**
+ * Pull the graph out of a CLI payload: `release get`, `release get-draft`,
+ * `template get`, an ad-hoc `run get`, or a bare node array.
+ */
+export function extractNodes(payload) {
+    if (isNodeArray(payload))
+        return payload;
+    if (payload === null || typeof payload !== "object")
+        return undefined;
+    const record = payload;
+    const containers = [
+        record["nodes"],
+        record["release"]?.["nodes"],
+        record["draftRelease"]?.["nodes"],
+        record["template"]?.["nodes"],
+        record["run"]?.["nodes"],
+    ];
+    for (const container of containers) {
+        if (isNodeArray(container))
+            return container;
+    }
+    return undefined;
+}
+/** The fenced block, ready to paste into a message, a PR, or the docs. */
+export function toMermaidBlock(diagram) {
+    return `\`\`\`mermaid\n${diagram}\n\`\`\``;
+}

package/package.json

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