airgen-cli 0.17.2 → 0.19.0

package/dist/commands/diagrams.js

@@ -176,12 +176,15 @@ function renderTerminal(blocks, connectors) {
 function renderMermaid(blocks, connectors, direction) {
     resetMermaidIds();
     const lines = [`flowchart ${direction}`];
+    const blockIds = new Set(blocks.map(b => b.id));
     // Nodes
     for (const b of blocks) {
         lines.push(`  ${mermaidNodeShape(b)}`);
     }
-    // Edges
+    // Edges (skip orphan connectors whose source or target block is missing)
     for (const c of connectors) {
+        if (!blockIds.has(c.source) || !blockIds.has(c.target))
+            continue;
         const src = sanitizeId(c.source);
         const tgt = sanitizeId(c.target);
         const arrow = mermaidArrow(c.kind);
@@ -288,7 +291,10 @@ export function registerDiagramCommands(program, client) {
             if (opts.clean) {
                 rendered = rendered
                     .split("\n")
-                    .filter(l => !l.trim().startsWith("classDef ") && !l.trim().startsWith("class ") && !l.trim().startsWith("style "))
+                    .filter(l => {
+                    const t = l.trim();
+                    return !t.startsWith("classDef ") && !t.startsWith("class ") && !t.startsWith("style ") && t !== "";
+                })
                     .map(l => l
                     .replace(/<<[^>]+>><br\/?>/g, "") // Strip <<stereotype>><br> or <<stereotype>><br/>
                     .replace(/[a-z]+<br>/gi, (m) => m) // Keep stereo<br>label (valid Mermaid)
@@ -459,7 +465,7 @@ export function registerDiagramCommands(program, client) {
     });
     blocks
         .command("create")
-        .description("Create a new block")
+        .description("Create a new block (use --upsert to return existing if name matches)")
         .argument("<tenant>", "Tenant slug")
         .argument("<project-key>", "Project key")
         .requiredOption("--diagram <id>", "Diagram ID")
@@ -471,7 +477,22 @@ export function registerDiagramCommands(program, client) {
         .option("--height <n>", "Height")
         .option("--stereotype <s>", "Stereotype")
         .option("--description <desc>", "Description")
+        .option("--upsert", "Return existing block if name matches on this diagram instead of creating duplicate")
         .action(async (tenant, projectKey, opts) => {
+        // Upsert: check for existing block with same name on this diagram
+        if (opts.upsert) {
+            const existing = await client.get(`/architecture/blocks/${tenant}/${projectKey}/${opts.diagram}`);
+            const match = (existing.blocks ?? []).find(b => b.name.toLowerCase() === opts.name.toLowerCase());
+            if (match) {
+                if (isJsonMode()) {
+                    output({ block: match, deduplicated: true });
+                }
+                else {
+                    console.log(`Block already exists: ${match.id} (${match.name})`);
+                }
+                return;
+            }
+        }
         const data = await client.post("/architecture/blocks", {
             tenant,
             projectKey,
@@ -493,6 +514,85 @@ export function registerDiagramCommands(program, client) {
             output(data);
         }
     });
+    blocks
+        .command("deduplicate")
+        .description("Find and remove duplicate-named blocks on a diagram")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .option("--diagram <id>", "Specific diagram ID (otherwise checks all)")
+        .option("--dry-run", "Show duplicates without deleting (default)")
+        .option("--apply", "Actually delete duplicates")
+        .action(async (tenant, project, opts) => {
+        const diagramIds = [];
+        if (opts.diagram) {
+            diagramIds.push(opts.diagram);
+        }
+        else {
+            const data = await client.get(`/architecture/diagrams/${tenant}/${project}`);
+            diagramIds.push(...(data.diagrams ?? []).map(d => d.id));
+        }
+        let totalRemoved = 0;
+        for (const diagId of diagramIds) {
+            const data = await client.get(`/architecture/blocks/${tenant}/${project}/${diagId}`);
+            const allBlocks = data.blocks ?? [];
+            const byName = new Map();
+            for (const b of allBlocks) {
+                const name = b.name.toLowerCase().trim();
+                const group = byName.get(name) ?? [];
+                group.push(b);
+                byName.set(name, group);
+            }
+            for (const [, group] of byName) {
+                if (group.length <= 1)
+                    continue;
+                // Keep oldest (first created)
+                const sorted = group.sort((a, b) => (a.id < b.id ? -1 : 1));
+                const keep = sorted[0];
+                const dupes = sorted.slice(1);
+                console.log(`  "${keep.name}" on ${diagId}: keeping ${keep.id}, ${dupes.length} duplicate(s)`);
+                if (opts.apply) {
+                    for (const dup of dupes) {
+                        await client.delete(`/architecture/blocks/${tenant}/${project}/${dup.id}`);
+                        totalRemoved++;
+                    }
+                }
+                else {
+                    for (const dup of dupes) {
+                        console.log(`    [dry-run] would remove ${dup.id}`);
+                    }
+                    totalRemoved += dupes.length;
+                }
+            }
+        }
+        console.log(`${opts.apply ? "Removed" : "Would remove"} ${totalRemoved} duplicate block(s).`);
+    });
+    blocks
+        .command("find")
+        .description("Search blocks by name across project or diagram")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .requiredOption("--name <name>", "Block name to search (case-insensitive substring)")
+        .option("--diagram <id>", "Limit to specific diagram")
+        .action(async (tenant, project, opts) => {
+        if (opts.diagram) {
+            const data = await client.get(`/architecture/blocks/${tenant}/${project}/${opts.diagram}`);
+            const matches = (data.blocks ?? []).filter(b => b.name.toLowerCase().includes(opts.name.toLowerCase()));
+            if (isJsonMode()) {
+                output(matches);
+                return;
+            }
+            printTable(["ID", "Name", "Kind"], matches.map(b => [b.id, b.name, b.kind ?? ""]));
+        }
+        else {
+            const libData = await client.get(`/architecture/block-library/${tenant}/${project}`);
+            const matches = (libData.blocks ?? []).filter(b => b.name.toLowerCase().includes(opts.name.toLowerCase()));
+            if (isJsonMode()) {
+                output(matches);
+                return;
+            }
+            printTable(["ID", "Name", "Kind"], matches.map(b => [b.id, b.name, b.kind ?? ""]));
+        }
+    });
     blocks
         .command("delete")
         .description("Delete a block from the project")
@@ -505,6 +605,65 @@ export function registerDiagramCommands(program, client) {
     });
     // Connectors sub-group
     const connectors = cmd.command("connectors").alias("conn").description("Manage connectors");
+    connectors
+        .command("list")
+        .description("List connectors in a diagram")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<diagram-id>", "Diagram ID")
+        .action(async (tenant, project, diagramId) => {
+        const data = await client.get(`/architecture/connectors/${tenant}/${project}/${diagramId}`);
+        const list = data.connectors ?? [];
+        if (isJsonMode()) {
+            output(list);
+        }
+        else {
+            if (list.length === 0) {
+                console.log("No connectors in this diagram.");
+                return;
+            }
+            printTable(["ID", "Source", "Target", "Kind", "Label"], list.map(c => [c.id, c.source, c.target, c.kind ?? "", c.label ?? ""]));
+        }
+    });
+    connectors
+        .command("cleanup")
+        .description("Find and remove orphan connectors (source or target block missing)")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .option("--diagram <id>", "Specific diagram ID (otherwise checks all)")
+        .option("--apply", "Actually delete orphans (default is dry-run)")
+        .action(async (tenant, project, opts) => {
+        const diagramIds = [];
+        if (opts.diagram) {
+            diagramIds.push(opts.diagram);
+        }
+        else {
+            const data = await client.get(`/architecture/diagrams/${tenant}/${project}`);
+            diagramIds.push(...(data.diagrams ?? []).map(d => d.id));
+        }
+        let totalOrphans = 0;
+        for (const diagId of diagramIds) {
+            const [blockData, connData] = await Promise.all([
+                client.get(`/architecture/blocks/${tenant}/${project}/${diagId}`),
+                client.get(`/architecture/connectors/${tenant}/${project}/${diagId}`),
+            ]);
+            const blockIds = new Set((blockData.blocks ?? []).map(b => b.id));
+            const orphans = (connData.connectors ?? []).filter(c => !blockIds.has(c.source) || !blockIds.has(c.target));
+            if (orphans.length === 0)
+                continue;
+            console.log(`  ${diagId}: ${orphans.length} orphan connector(s)`);
+            for (const c of orphans) {
+                if (opts.apply) {
+                    await client.delete(`/architecture/connectors/${tenant}/${project}/${c.id}?diagramId=${diagId}`);
+                }
+                else {
+                    console.log(`    [dry-run] ${c.id}: ${c.source} → ${c.target} (${c.kind ?? "?"})`);
+                }
+            }
+            totalOrphans += orphans.length;
+        }
+        console.log(`${opts.apply ? "Removed" : "Would remove"} ${totalOrphans} orphan connector(s).`);
+    });
     connectors
         .command("create")
         .description("Create a connector between blocks")
@@ -518,7 +677,21 @@ export function registerDiagramCommands(program, client) {
         .option("--source-port <id>", "Source port ID")
         .option("--target-port <id>", "Target port ID")
         .option("--line-style <style>", "Line style: straight, smoothstep, step, polyline, bezier")
+        .option("--upsert", "Return existing connector if source+target+diagram matches")
         .action(async (tenant, projectKey, opts) => {
+        if (opts.upsert) {
+            const existing = await client.get(`/architecture/connectors/${tenant}/${projectKey}/${opts.diagram}`);
+            const match = (existing.connectors ?? []).find(c => c.source === opts.source && c.target === opts.target);
+            if (match) {
+                if (isJsonMode()) {
+                    output({ connector: match, deduplicated: true });
+                }
+                else {
+                    console.log(`Connector already exists: ${match.id} (${match.source} → ${match.target})`);
+                }
+                return;
+            }
+        }
         const data = await client.post("/architecture/connectors", {
             tenant,
             projectKey,

package/dist/commands/requirements.js

@@ -180,7 +180,9 @@ export function registerRequirementCommands(program, client) {
         .option("--rationale <r>", "Rationale")
         .option("--compliance <status>", "Compliance status")
         .option("--section <id>", "Section ID")
-        .option("--tags <tags>", "Comma-separated tags")
+        .option("--tags <tags>", "Comma-separated tags (replaces all)")
+        .option("--add-tags <tags>", "Comma-separated tags to add (keeps existing)")
+        .option("--remove-tags <tags>", "Comma-separated tags to remove")
         .action(async (tenant, project, id, opts) => {
         const resolvedId = await resolveRequirementId(client, tenant, project, id);
         const body = {};
@@ -196,8 +198,23 @@ export function registerRequirementCommands(program, client) {
             body.complianceStatus = opts.compliance;
         if (opts.section)
             body.sectionId = opts.section;
-        if (opts.tags)
+        if (opts.addTags || opts.removeTags) {
+            // Read-modify-write for add/remove tags
+            const existing = await client.get(`/requirements/${tenant}/${project}/${resolvedId}`);
+            let currentTags = existing.record?.tags ?? [];
+            if (opts.addTags) {
+                const toAdd = opts.addTags.split(",").map(t => t.trim());
+                currentTags = [...new Set([...currentTags, ...toAdd])];
+            }
+            if (opts.removeTags) {
+                const toRemove = new Set(opts.removeTags.split(",").map(t => t.trim()));
+                currentTags = currentTags.filter(t => !toRemove.has(t));
+            }
+            body.tags = currentTags;
+        }
+        else if (opts.tags) {
             body.tags = opts.tags.split(",").map(t => t.trim());
+        }
         await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
         if (isJsonMode()) {
             output({ ok: true });
@@ -299,7 +316,7 @@ export function registerRequirementCommands(program, client) {
         const data = await client.get(`/requirements/${tenant}/${project}`, params);
         const reqs = data.data ?? [];
         if (isJsonMode()) {
-            output(reqs);
+            output({ data: reqs, meta: { totalItems: reqs.length } });
         }
         else {
             console.log(`Filtered: ${reqs.length} requirements\n`);
@@ -396,22 +413,84 @@ export function registerRequirementCommands(program, client) {
         }
         console.log(`${opts.dryRun ? "Would create" : "Created"} ${created}. Skipped: ${skipped}. Errors: ${errors}.`);
     });
+    // ── bulk-update: update multiple requirements from JSON array ──
+    cmd
+        .command("bulk-update")
+        .description("Update multiple requirements from a JSON file (array of {ref, text?, rationale?, tags?, ...})")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .requiredOption("--file <path>", "Path to JSON file")
+        .option("--dry-run", "Validate without updating")
+        .action(async (tenant, project, opts) => {
+        const content = readFileSync(opts.file, "utf-8");
+        let items;
+        try {
+            items = JSON.parse(content);
+            if (!Array.isArray(items))
+                throw new Error("File must contain a JSON array");
+        }
+        catch (err) {
+            console.error(`Invalid JSON: ${err.message}`);
+            process.exit(1);
+        }
+        console.error(`Processing ${items.length} update(s)...`);
+        let updated = 0, errors = 0;
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const ref = String(item.ref ?? item.id ?? "");
+            if (!ref) {
+                console.error(`  [${i}] Skipped: no ref or id`);
+                errors++;
+                continue;
+            }
+            if (opts.dryRun) {
+                console.log(`  [dry-run] ${ref}: would update ${Object.keys(item).filter(k => k !== "ref" && k !== "id").join(", ")}`);
+                updated++;
+                continue;
+            }
+            try {
+                const resolvedId = await resolveRequirementId(client, tenant, project, ref);
+                const body = {};
+                if (item.text)
+                    body.text = item.text;
+                if (item.pattern)
+                    body.pattern = item.pattern;
+                if (item.verification)
+                    body.verification = item.verification;
+                if (item.rationale)
+                    body.rationale = item.rationale;
+                if (item.complianceStatus || item.compliance)
+                    body.complianceStatus = item.complianceStatus ?? item.compliance;
+                if (item.sectionId || item.section)
+                    body.sectionId = item.sectionId ?? item.section;
+                if (item.tags)
+                    body.tags = Array.isArray(item.tags) ? item.tags : String(item.tags).split(",").map(t => t.trim());
+                await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
+                updated++;
+            }
+            catch (err) {
+                console.error(`  [${i}] ${ref}: ${err.message}`);
+                errors++;
+            }
+        }
+        console.log(`${opts.dryRun ? "Would update" : "Updated"} ${updated}. Errors: ${errors}.`);
+    });
     // ── text-search: search requirements by text content ──
     cmd
         .command("text-search")
         .description("Search requirements by text content (case-insensitive substring match)")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .requiredOption("--text <query>", "Text to search for")
+        .requiredOption("-q, --query <text>", "Text to search for")
         .option("-l, --limit <n>", "Max results", "50")
         .action(async (tenant, project, opts) => {
-        const data = await client.get(`/requirements/${tenant}/${project}`, { textContains: opts.text, limit: opts.limit, sortBy: "ref", sortOrder: "asc" });
+        const data = await client.get(`/requirements/${tenant}/${project}`, { textContains: opts.query, limit: opts.limit, sortBy: "ref", sortOrder: "asc" });
         const reqs = data.data ?? [];
         if (isJsonMode()) {
             output(reqs);
         }
         else {
-            console.log(`Found ${reqs.length} requirement(s) matching "${opts.text}":\n`);
+            console.log(`Found ${reqs.length} requirement(s) matching "${opts.query}":\n`);
             printTable(["Ref", "Text", "Document", "QA"], reqs.map(r => [
                 r.ref ?? "?",
                 truncate(r.text ?? "", 55),

package/dist/commands/traceability.js

@@ -8,16 +8,24 @@ export function registerTraceabilityCommands(program, client) {
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .option("--requirement <id>", "Filter by requirement ID")
+        .option("-l, --limit <n>", "Max results to display")
+        .option("--type <type>", "Filter by link type")
         .action(async (tenant, project, opts) => {
         const path = opts.requirement
             ? `/trace-links/${tenant}/${project}/${opts.requirement}`
             : `/trace-links/${tenant}/${project}`;
         const data = await client.get(path);
-        const links = data.traceLinks ?? [];
+        let links = data.traceLinks ?? [];
+        if (opts.type)
+            links = links.filter(l => l.linkType === opts.type);
+        const total = links.length;
+        if (opts.limit)
+            links = links.slice(0, parseInt(opts.limit, 10));
         if (isJsonMode()) {
-            output(links);
+            output({ data: links, meta: { totalItems: total, showing: links.length } });
         }
         else {
+            console.log(`Trace links: ${links.length}${total > links.length ? ` of ${total}` : ""}\n`);
             printTable(["ID", "Source", "Target", "Type", "Description"], links.map(l => [
                 l.id,
                 l.sourceRef ?? l.sourceRequirementId ?? "",

package/package.json

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