airgen-cli 0.1.5 → 0.1.7

package/dist/commands/diagrams.js

@@ -1,4 +1,205 @@
+import { writeFileSync } from "node:fs";
 import { output, printTable, isJsonMode } from "../output.js";
+// ── Mermaid rendering helpers ─────────────────────────────────
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function mermaidNodeShape(block) {
+    const id = sanitizeId(block.id);
+    const label = block.name.replace(/"/g, "'");
+    const stereo = block.stereotype?.replace(/[«»<>]/g, "") ?? block.kind ?? "block";
+    const display = `"«${stereo}»\\n${label}"`;
+    switch (block.kind) {
+        case "system": return `${id}[${display}]`;
+        case "subsystem": return `${id}[${display}]`;
+        case "actor": return `${id}([${display}])`;
+        case "external": return `${id}>${display}]`;
+        case "interface": return `${id}{{${display}}}`;
+        default: return `${id}[${display}]`; // component
+    }
+}
+function mermaidArrow(kind) {
+    switch (kind) {
+        case "flow": return "==>";
+        case "dependency": return "-.->";
+        case "composition": return "--*";
+        default: return "-->"; // association
+    }
+}
+function mermaidStyle(block) {
+    const id = sanitizeId(block.id);
+    switch (block.kind) {
+        case "system": return `style ${id} fill:#ebf8ff,stroke:#1a365d,color:#1a365d`;
+        case "subsystem": return `style ${id} fill:#f0f5ff,stroke:#2c5282,color:#2c5282`;
+        case "actor": return `style ${id} fill:#f0fff4,stroke:#276749,color:#276749`;
+        case "external": return `style ${id} fill:#fffbeb,stroke:#92400e,color:#92400e`;
+        case "interface": return `style ${id} fill:#faf5ff,stroke:#6b21a8,color:#6b21a8`;
+        default: return null;
+    }
+}
+// ── Terminal (layered) rendering ─────────────────────────────
+const KIND_ICONS = {
+    system: "■", subsystem: "□", component: "◦",
+    actor: "☺", external: "◇", interface: "◈",
+};
+function kindArrow(kind) {
+    switch (kind) {
+        case "flow": return "══▶";
+        case "dependency": return "--▷";
+        case "composition": return "◆──";
+        default: return "──▶";
+    }
+}
+function renderTerminal(blocks, connectors) {
+    const blockMap = new Map(blocks.map(b => [b.id, b]));
+    // Build adjacency
+    const outEdges = new Map();
+    const inEdges = new Map();
+    const inDegree = new Map();
+    for (const b of blocks)
+        inDegree.set(b.id, 0);
+    for (const c of connectors) {
+        const out = outEdges.get(c.source) ?? [];
+        out.push({ target: c.target, label: c.label ?? "", kind: c.kind });
+        outEdges.set(c.source, out);
+        const inn = inEdges.get(c.target) ?? [];
+        inn.push({ source: c.source, label: c.label ?? "", kind: c.kind });
+        inEdges.set(c.target, inn);
+        inDegree.set(c.target, (inDegree.get(c.target) ?? 0) + 1);
+    }
+    // BFS layering (Kahn's algorithm, cycles go to last layer)
+    const layer = new Map();
+    const queue = [];
+    for (const b of blocks) {
+        if ((inDegree.get(b.id) ?? 0) === 0) {
+            queue.push(b.id);
+            layer.set(b.id, 0);
+        }
+    }
+    let maxLayer = 0;
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const curLayer = layer.get(id);
+        for (const e of outEdges.get(id) ?? []) {
+            if (layer.has(e.target))
+                continue;
+            const newDeg = (inDegree.get(e.target) ?? 1) - 1;
+            inDegree.set(e.target, newDeg);
+            if (newDeg <= 0) {
+                const nextLayer = curLayer + 1;
+                layer.set(e.target, nextLayer);
+                maxLayer = Math.max(maxLayer, nextLayer);
+                queue.push(e.target);
+            }
+        }
+    }
+    // Assign remaining (cycle members) to maxLayer + 1
+    for (const b of blocks) {
+        if (!layer.has(b.id)) {
+            layer.set(b.id, maxLayer + 1);
+            maxLayer = maxLayer + 1;
+        }
+    }
+    // Group blocks by layer
+    const layers = [];
+    for (let i = 0; i <= maxLayer; i++)
+        layers.push([]);
+    for (const b of blocks) {
+        layers[layer.get(b.id)].push(b);
+    }
+    // Compute column widths for the block name column
+    const nameColWidth = Math.max(...blocks.map(b => b.name.length + 4), 20);
+    const icon = (b) => KIND_ICONS[b.kind ?? ""] ?? "□";
+    const lines = [];
+    const PAD = "  ";
+    for (let li = 0; li < layers.length; li++) {
+        const layerBlocks = layers[li];
+        if (layerBlocks.length === 0)
+            continue;
+        // Layer header
+        const layerLabel = li === 0 ? "Sources" : li === layers.length - 1 ? "Outputs" : `Layer ${li}`;
+        lines.push(`${PAD}┄┄ ${layerLabel} ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄`);
+        lines.push("");
+        for (const b of layerBlocks) {
+            const blockIcon = icon(b);
+            const stereo = b.stereotype?.replace(/[«»<>]/g, "") ?? b.kind ?? "block";
+            const nameStr = `${blockIcon} ${b.name}`;
+            const paddedName = nameStr + " ".repeat(Math.max(0, nameColWidth - nameStr.length));
+            // Incoming connections for this block
+            const incoming = inEdges.get(b.id) ?? [];
+            // Outgoing connections
+            const outgoing = outEdges.get(b.id) ?? [];
+            // Build the box line
+            const boxTop = `${PAD}  ┌${"─".repeat(nameColWidth + 2)}┐`;
+            const boxSte = `${PAD}  │ «${stereo}»${" ".repeat(Math.max(0, nameColWidth - stereo.length - 2))} │`;
+            const boxNam = `${PAD}  │ ${paddedName} │`;
+            const boxBot = `${PAD}  └${"─".repeat(nameColWidth + 2)}┘`;
+            lines.push(boxTop);
+            lines.push(boxSte);
+            lines.push(boxNam);
+            lines.push(boxBot);
+            // Show incoming connections (who feeds this block)
+            if (incoming.length > 0) {
+                for (const e of incoming) {
+                    const srcBlock = blockMap.get(e.source);
+                    const srcName = srcBlock?.name ?? "?";
+                    const arrow = kindArrow(e.kind);
+                    const label = e.label ? ` (${e.label})` : "";
+                    lines.push(`${PAD}    ◀── ${srcName}${label}`);
+                }
+            }
+            // Show outgoing connections (where this block sends data)
+            if (outgoing.length > 0) {
+                for (const e of outgoing) {
+                    const tgtBlock = blockMap.get(e.target);
+                    const tgtName = tgtBlock?.name ?? "?";
+                    const arrow = kindArrow(e.kind);
+                    const label = e.label ? ` ${e.label} ` : " ";
+                    lines.push(`${PAD}    ${arrow}${label}──▶ ${tgtName}`);
+                }
+            }
+            lines.push("");
+        }
+        // Visual separator between layers
+        if (li < layers.length - 1) {
+            lines.push(`${PAD}        │`);
+            lines.push(`${PAD}        ▼`);
+            lines.push("");
+        }
+    }
+    // Legend
+    lines.push(`${PAD}┄┄ Legend ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄`);
+    lines.push(`${PAD}  ☺ actor   ■ system   □ subsystem   ◦ component   ◇ external   ◈ interface`);
+    lines.push(`${PAD}  ──▶ association   ══▶ flow   ◆── composition   --▷ dependency`);
+    return lines.join("\n");
+}
+function renderMermaid(blocks, connectors, direction) {
+    const lines = [`flowchart ${direction}`];
+    // Nodes
+    for (const b of blocks) {
+        lines.push(`  ${mermaidNodeShape(b)}`);
+    }
+    // Edges
+    for (const c of connectors) {
+        const src = sanitizeId(c.source);
+        const tgt = sanitizeId(c.target);
+        const arrow = mermaidArrow(c.kind);
+        if (c.label) {
+            lines.push(`  ${src} ${arrow}|"${c.label.replace(/"/g, "'")}"| ${tgt}`);
+        }
+        else {
+            lines.push(`  ${src} ${arrow} ${tgt}`);
+        }
+    }
+    // Styles
+    const styles = blocks.map(mermaidStyle).filter(Boolean);
+    if (styles.length > 0) {
+        lines.push("");
+        for (const s of styles)
+            lines.push(`  ${s}`);
+    }
+    return lines.join("\n");
+}
 export function registerDiagramCommands(program, client) {
     const cmd = program.command("diagrams").alias("diag").description("Architecture diagrams");
     cmd
@@ -35,6 +236,60 @@ export function registerDiagramCommands(program, client) {
         ]);
         output({ blocks, connectors });
     });
+    cmd
+        .command("render")
+        .description("Render a diagram in the terminal or as Mermaid syntax")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<id>", "Diagram ID")
+        .option("--format <fmt>", "Output format: text, mermaid", "text")
+        .option("--direction <dir>", "Layout direction for mermaid: TB, LR, BT, RL", "TB")
+        .option("-o, --output <file>", "Write to file instead of stdout")
+        .option("--wrap", "Wrap mermaid in markdown fenced code block")
+        .action(async (tenant, project, id, opts) => {
+        // Fetch diagram metadata + blocks + connectors in parallel
+        const [diagramData, blocksData, connectorsData] = await Promise.all([
+            client.get(`/architecture/diagrams/${tenant}/${project}`),
+            client.get(`/architecture/blocks/${tenant}/${project}/${id}`),
+            client.get(`/architecture/connectors/${tenant}/${project}/${id}`),
+        ]);
+        const diagram = (diagramData.diagrams ?? []).find(d => d.id === id);
+        const blocks = blocksData.blocks ?? [];
+        const connectors = connectorsData.connectors ?? [];
+        if (blocks.length === 0) {
+            console.log("Empty diagram — no blocks to render.");
+            return;
+        }
+        let rendered;
+        if (opts.format === "mermaid") {
+            rendered = renderMermaid(blocks, connectors, opts.direction);
+            if (isJsonMode()) {
+                output({ mermaid: rendered, blocks: blocks.length, connectors: connectors.length });
+                return;
+            }
+            if (opts.wrap)
+                rendered = "```mermaid\n" + rendered + "\n```";
+        }
+        else {
+            // Terminal text format
+            const header = diagram?.name ?? id;
+            const headerLine = `  ${header}`;
+            const underline = `  ${"═".repeat(header.length)}`;
+            const stats = `  ${blocks.length} blocks, ${connectors.length} connectors`;
+            rendered = [headerLine, underline, stats, "", renderTerminal(blocks, connectors)].join("\n");
+            if (isJsonMode()) {
+                output({ text: rendered, blocks: blocks.length, connectors: connectors.length });
+                return;
+            }
+        }
+        if (opts.output) {
+            writeFileSync(opts.output, rendered + "\n", "utf-8");
+            console.log(`Diagram written to ${opts.output}`);
+        }
+        else {
+            console.log(rendered);
+        }
+    });
     cmd
         .command("create")
         .description("Create a new diagram")

package/dist/commands/implementation.js

@@ -21,6 +21,33 @@ async function fetchAllRequirements(client, tenant, project) {
     }
     return all.filter((r) => !r.deleted && !r.deletedAt);
 }
+/** Fetch a single requirement by its resolved ID (ref or full colon ID). */
+async function fetchRequirement(client, tenant, project, resolvedId) {
+    // Try direct GET by ref/ID first (works for both ref and full colon ID)
+    try {
+        const data = await client.get(`/requirements/${tenant}/${project}/${resolvedId}`);
+        if (data.record)
+            return data.record;
+    }
+    catch {
+        // Not found via direct endpoint — fall through to paginated search
+    }
+    // Paginated search as fallback
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const data = await client.get(`/requirements/${tenant}/${project}`, {
+            page: String(page),
+            limit: String(PAGE_SIZE),
+        });
+        const items = data.data ?? [];
+        const found = items.find(r => r.id === resolvedId);
+        if (found)
+            return found;
+        const totalPages = data.meta?.totalPages ?? 1;
+        if (page >= totalPages)
+            break;
+    }
+    return null;
+}
 function getImplStatus(tags) {
     if (!tags)
         return null;
@@ -74,9 +101,7 @@ export function registerImplementationCommands(program, client) {
             process.exit(1);
         }
         const resolvedId = await resolveRequirementId(client, tenant, project, requirement);
-        // Fetch current requirement to get existing tags + attributes
-        const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "100" });
-        const req = (reqData.data ?? []).find(r => r.id === resolvedId);
+        const req = await fetchRequirement(client, tenant, project, resolvedId);
         if (!req) {
             console.error(`Requirement ${requirement} not found.`);
             process.exit(1);
@@ -226,9 +251,7 @@ export function registerImplementationCommands(program, client) {
             }
             try {
                 const resolvedId = await resolveRequirementId(client, tenant, project, item.ref);
-                // Fetch requirement for current tags/attributes
-                const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "100" });
-                const req = (reqData.data ?? []).find(r => r.id === resolvedId);
+                const req = await fetchRequirement(client, tenant, project, resolvedId);
                 if (!req) {
                     errors.push(`${item.ref}: not found`);
                     failed++;
@@ -279,9 +302,7 @@ export function registerImplementationCommands(program, client) {
         .option("--line <n>", "Line number (for file type)")
         .action(async (tenant, project, requirement, opts) => {
         const resolvedId = await resolveRequirementId(client, tenant, project, requirement);
-        // Fetch current requirement
-        const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "100" });
-        const req = (reqData.data ?? []).find(r => r.id === resolvedId);
+        const req = await fetchRequirement(client, tenant, project, resolvedId);
         if (!req) {
             console.error(`Requirement ${requirement} not found.`);
             process.exit(1);
@@ -319,8 +340,7 @@ export function registerImplementationCommands(program, client) {
         .requiredOption("--path <path>", "Artifact path")
         .action(async (tenant, project, requirement, opts) => {
         const resolvedId = await resolveRequirementId(client, tenant, project, requirement);
-        const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "100" });
-        const req = (reqData.data ?? []).find(r => r.id === resolvedId);
+        const req = await fetchRequirement(client, tenant, project, resolvedId);
         if (!req) {
             console.error(`Requirement ${requirement} not found.`);
             process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airgen-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",