airgen-cli 0.2.0 → 0.2.2

package/README.md

@@ -128,14 +128,21 @@ airgen trace delete <tenant> <project> <link-id>
 airgen trace linksets list <tenant> <project>          # Document linksets
 ```
 
-### Baselines
+### Baselines & Diff
 
 ```bash
 airgen bl list <tenant> <project>
 airgen bl create <tenant> <project> --name "v1.0"
 airgen bl compare <tenant> <project> --from <id1> --to <id2>
+
+# Rich diff between baselines
+airgen diff <tenant> <project> --from <bl1> --to <bl2>           # Pretty terminal output
+airgen diff <tenant> <project> --from <bl1> --to <bl2> --json    # Structured JSON
+airgen diff <tenant> <project> --from <bl1> --to <bl2> --format markdown -o diff.md
 ```
 
+`diff` shows added, modified, and removed requirements with full text, plus a summary of changes to documents, trace links, diagrams, blocks, and connectors.
+
 ### Quality & AI
 
 ```bash

package/dist/commands/diff.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { AirgenClient } from "../client.js";
+export declare function registerDiffCommand(program: Command, client: AirgenClient): void;

package/dist/commands/diff.js

@@ -0,0 +1,185 @@
+import { writeFileSync } from "node:fs";
+import { isJsonMode, truncate } from "../output.js";
+// ── Helpers ───────────────────────────────────────────────────
+/** Extract short ref from "tenant:project:REQ-001" → "REQ-001" */
+function shortRef(id) {
+    return id?.split(":").pop() ?? "?";
+}
+function counts(comp) {
+    return {
+        added: comp?.added?.length ?? 0,
+        removed: comp?.removed?.length ?? 0,
+        modified: comp?.modified?.length ?? 0,
+        unchanged: comp?.unchanged?.length ?? 0,
+    };
+}
+// ── Structured output ────────────────────────────────────────
+function buildStructured(data) {
+    const reqs = data.requirements ?? { added: [], removed: [], modified: [], unchanged: [] };
+    const r = counts(reqs);
+    return {
+        summary: {
+            from: data.fromBaseline?.ref ?? "?",
+            to: data.toBaseline?.ref ?? "?",
+            requirements: r,
+        },
+        added: reqs.added.map(v => ({ ref: shortRef(v.requirementId), text: v.text ?? "" })),
+        removed: reqs.removed.map(v => ({ ref: shortRef(v.requirementId), text: v.text ?? "" })),
+        modified: reqs.modified.map(v => ({ ref: shortRef(v.requirementId), text: v.text ?? "" })),
+    };
+}
+// ── Pretty text ──────────────────────────────────────────────
+function formatPretty(data) {
+    const from = data.fromBaseline?.ref ?? "?";
+    const to = data.toBaseline?.ref ?? "?";
+    const reqs = data.requirements ?? { added: [], removed: [], modified: [], unchanged: [] };
+    const r = counts(reqs);
+    const lines = [];
+    lines.push(`  Baseline Diff: ${from} → ${to}`);
+    lines.push(`  ${"═".repeat(20 + from.length + to.length)}`);
+    lines.push(`  ${r.added} added, ${r.modified} modified, ${r.removed} removed, ${r.unchanged} unchanged`);
+    lines.push("");
+    if (reqs.added.length > 0) {
+        lines.push("  ┄┄ Added ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        for (const v of reqs.added) {
+            lines.push(`    + ${shortRef(v.requirementId)}`);
+            lines.push(`      ${truncate(v.text ?? "", 100)}`);
+        }
+        lines.push("");
+    }
+    if (reqs.modified.length > 0) {
+        lines.push("  ┄┄ Modified ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        for (const v of reqs.modified) {
+            lines.push(`    ~ ${shortRef(v.requirementId)}`);
+            lines.push(`      ${truncate(v.text ?? "", 100)}`);
+        }
+        lines.push("");
+    }
+    if (reqs.removed.length > 0) {
+        lines.push("  ┄┄ Removed ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        for (const v of reqs.removed) {
+            lines.push(`    - ${shortRef(v.requirementId)}`);
+            lines.push(`      ${truncate(v.text ?? "", 100)}`);
+        }
+        lines.push("");
+    }
+    // Non-requirement entity summary
+    const others = [
+        ["Documents", data.documents],
+        ["Trace Links", data.traceLinks],
+        ["Diagrams", data.diagrams],
+        ["Blocks", data.blocks],
+        ["Connectors", data.connectors],
+    ];
+    const changed = others.filter(([, c]) => {
+        const n = counts(c);
+        return n.added + n.modified + n.removed > 0;
+    });
+    if (changed.length > 0) {
+        lines.push("  ┄┄ Other Changes ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        for (const [label, comp] of changed) {
+            const n = counts(comp);
+            lines.push(`    ${label}: +${n.added} ~${n.modified} -${n.removed}`);
+        }
+        lines.push("");
+    }
+    if (r.added + r.modified + r.removed === 0 && changed.length === 0) {
+        lines.push("  No changes between baselines.");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ── Markdown ─────────────────────────────────────────────────
+function formatMarkdown(data) {
+    const from = data.fromBaseline?.ref ?? "?";
+    const to = data.toBaseline?.ref ?? "?";
+    const reqs = data.requirements ?? { added: [], removed: [], modified: [], unchanged: [] };
+    const r = counts(reqs);
+    const lines = [];
+    lines.push(`## Baseline Diff: ${from} → ${to}`);
+    lines.push("");
+    lines.push(`**${r.added}** added, **${r.modified}** modified, **${r.removed}** removed, **${r.unchanged}** unchanged`);
+    lines.push("");
+    if (reqs.added.length > 0) {
+        lines.push("### Added");
+        lines.push("| Ref | Text |");
+        lines.push("|---|---|");
+        for (const v of reqs.added) {
+            lines.push(`| ${shortRef(v.requirementId)} | ${truncate(v.text ?? "", 120)} |`);
+        }
+        lines.push("");
+    }
+    if (reqs.modified.length > 0) {
+        lines.push("### Modified");
+        lines.push("| Ref | Text (current) |");
+        lines.push("|---|---|");
+        for (const v of reqs.modified) {
+            lines.push(`| ${shortRef(v.requirementId)} | ${truncate(v.text ?? "", 120)} |`);
+        }
+        lines.push("");
+    }
+    if (reqs.removed.length > 0) {
+        lines.push("### Removed");
+        lines.push("| Ref | Text |");
+        lines.push("|---|---|");
+        for (const v of reqs.removed) {
+            lines.push(`| ${shortRef(v.requirementId)} | ${truncate(v.text ?? "", 120)} |`);
+        }
+        lines.push("");
+    }
+    // Non-requirement entity summary
+    const others = [
+        ["Documents", data.documents],
+        ["Trace Links", data.traceLinks],
+        ["Diagrams", data.diagrams],
+        ["Blocks", data.blocks],
+        ["Connectors", data.connectors],
+    ];
+    const changed = others.filter(([, c]) => {
+        const n = counts(c);
+        return n.added + n.modified + n.removed > 0;
+    });
+    if (changed.length > 0) {
+        lines.push("### Other Changes");
+        lines.push("| Entity | Added | Modified | Removed |");
+        lines.push("|---|---|---|---|");
+        for (const [label, comp] of changed) {
+            const n = counts(comp);
+            lines.push(`| ${label} | ${n.added} | ${n.modified} | ${n.removed} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ── Command registration ─────────────────────────────────────
+export function registerDiffCommand(program, client) {
+    program
+        .command("diff")
+        .description("Show what changed between two baselines")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .requiredOption("--from <ref>", "Source baseline ref (earlier)")
+        .requiredOption("--to <ref>", "Target baseline ref (later)")
+        .option("--format <fmt>", "Output format: text, markdown", "text")
+        .option("-o, --output <file>", "Write report to file")
+        .action(async (tenant, project, opts) => {
+        const data = await client.get(`/baselines/${tenant}/${project}/compare`, { from: opts.from, to: opts.to });
+        let result;
+        if (isJsonMode()) {
+            result = JSON.stringify(buildStructured(data), null, 2);
+        }
+        else if (opts.format === "markdown") {
+            result = formatMarkdown(data);
+        }
+        else {
+            result = formatPretty(data);
+        }
+        if (opts.output) {
+            writeFileSync(opts.output, result + "\n", "utf-8");
+            console.log(`Diff written to ${opts.output}`);
+        }
+        else {
+            console.log(result);
+        }
+    });
+}

package/dist/commands/documents.js

@@ -99,7 +99,7 @@ export function registerDocumentCommands(program, client) {
             projectKey,
             documentSlug: document,
             name: opts.title,
-            order: opts.order ? parseInt(opts.order, 10) : undefined,
+            order: opts.order ? parseInt(opts.order, 10) : 0,
             description: opts.description,
             shortCode: opts.code,
         });

package/dist/commands/projects.js

@@ -28,9 +28,12 @@ export function registerProjectCommands(program, client) {
         .requiredOption("--name <name>", "Project name")
         .option("--key <key>", "Project key")
         .option("--code <code>", "Project code")
+        .option("--slug <slug>", "Project slug (auto-generated from name if omitted)")
         .option("--description <desc>", "Description")
         .action(async (tenant, opts) => {
+        const slug = opts.slug ?? opts.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
         const data = await client.post(`/tenants/${tenant}/projects`, {
+            slug,
             name: opts.name,
             key: opts.key,
             code: opts.code,

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerImportExportCommands } from "./commands/import-export.js";
 import { registerActivityCommands } from "./commands/activity.js";
 import { registerImplementationCommands } from "./commands/implementation.js";
 import { registerLintCommands } from "./commands/lint.js";
+import { registerDiffCommand } from "./commands/diff.js";
 const program = new Command();
 // Lazy-init: only create client when a command actually runs
 let client = null;
@@ -69,6 +70,7 @@ registerImportExportCommands(program, clientProxy);
 registerActivityCommands(program, clientProxy);
 registerImplementationCommands(program, clientProxy);
 registerLintCommands(program, clientProxy);
+registerDiffCommand(program, clientProxy);
 // Handle async errors from Commander action handlers
 process.on("uncaughtException", (err) => {
     console.error(`Error: ${err.message}`);

package/package.json

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