@cargo-ai/cli 1.0.55 → 1.0.57

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/build/credentials.d.ts

@@ -1,2 +1,2 @@
-export { clearCredentials, type StoredCredentials as Credentials, getConfigDir, getCredentialsPath, loadCredentials, type RefreshableSession, saveCredentials, } from "@cargo-ai/cdk/cli";
+export { clearCredentials, type StoredCredentials as Credentials, CredentialsNotClearedError, getConfigDir, getCredentialsPath, loadCredentials, type RefreshableSession, saveCredentials, } from "@cargo-ai/cdk/cli";
 //# sourceMappingURL=credentials.d.ts.map

package/build/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,gBAAgB,EAChB,KAAK,iBAAiB,IAAI,WAAW,EACrC,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,gBAAgB,EAChB,KAAK,iBAAiB,IAAI,WAAW,EACrC,0BAA0B,EAC1B,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC"}

package/build/credentials.js

@@ -1,4 +1,4 @@
 // The credentials file is shared with `cargo-cdk`, so its format and access
 // live in @cargo-ai/cdk/cli — one login serves both binaries and neither can
 // drift from the other's idea of what is on disk.
-export { clearCredentials, getConfigDir, getCredentialsPath, loadCredentials, saveCredentials, } from "@cargo-ai/cdk/cli";
+export { clearCredentials, CredentialsNotClearedError, getConfigDir, getCredentialsPath, loadCredentials, saveCredentials, } from "@cargo-ai/cdk/cli";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.55",
+  "version": "1.0.57",
   "private": false,
   "license": "UNLICENSED",
   "homepage": "https://getcargo.ai",
@@ -61,7 +61,7 @@
   "dependencies": {
     "@cargo-ai/api": "^1.0.60",
     "@cargo-ai/app-sdk": "^1.0.6",
-    "@cargo-ai/cdk": "^1.0.45",
+    "@cargo-ai/cdk": "^1.0.46",
     "@cargo-ai/types": "^1.0.57",
     "@cargo-ai/worker-sdk": "^1.0.12",
     "@modelcontextprotocol/sdk": "1.29.0",