airgen-cli 0.1.8 → 0.2.1

package/README.md

@@ -0,0 +1,268 @@
+# airgen-cli
+
+Requirements engineering from the command line. Manage requirements, architecture diagrams, traceability, baselines, and more — all from your terminal.
+
+Pairs with [AIRGen Studio](https://airgen.studio) and the AIRGen MCP server.
+
+## Install
+
+```bash
+npm install -g airgen-cli
+```
+
+## Configuration
+
+Set credentials via environment variables or `~/.airgenrc`:
+
+```bash
+# Environment variables
+export AIRGEN_API_URL=https://api.airgen.studio/api
+export AIRGEN_EMAIL=you@example.com
+export AIRGEN_PASSWORD=your-password
+```
+
+Or create `~/.airgenrc`:
+
+```json
+{
+  "apiUrl": "https://api.airgen.studio/api",
+  "email": "you@example.com",
+  "password": "your-password"
+}
+```
+
+For semantic linting, also set a UHT token:
+
+```bash
+export UHT_API_KEY=your-token    # or UHT_TOKEN
+```
+
+## Quick start
+
+```bash
+# List your tenants and projects
+airgen tenants list
+airgen projects list my-tenant
+
+# List requirements
+airgen reqs list my-tenant my-project
+
+# Render a diagram in the terminal
+airgen diag list my-tenant my-project
+airgen diag render my-tenant my-project diagram-123
+
+# Run semantic lint
+airgen lint my-tenant my-project
+
+# Get a compliance report
+airgen report compliance my-tenant my-project
+```
+
+## Global options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON (works with any command) |
+| `-V, --version` | Print version |
+| `-h, --help` | Show help |
+
+## Commands
+
+### Tenants & Projects
+
+```bash
+airgen tenants list                          # List all tenants
+airgen projects list <tenant>                # List projects in a tenant
+airgen projects create <tenant> --name "X"   # Create a project
+airgen projects delete <tenant> <project>    # Delete a project
+```
+
+### Requirements
+
+```bash
+airgen reqs list <tenant> <project>                    # List (paginated)
+airgen reqs list <tenant> <project> --page 2 --limit 50
+airgen reqs get <tenant> <project> <ref>               # Full detail
+airgen reqs create <tenant> <project> --text "The system shall..."
+airgen reqs update <tenant> <project> <id> --text "..." --tags safety,critical
+airgen reqs delete <tenant> <project> <id>             # Soft-delete
+airgen reqs history <tenant> <project> <id>            # Version history
+airgen reqs search <tenant> <project> --query "thermal" --mode semantic
+airgen reqs filter <tenant> <project> --pattern functional --tag safety
+```
+
+### Architecture Diagrams
+
+```bash
+airgen diag list <tenant> <project>                    # List diagrams
+airgen diag get <tenant> <project> <id>                # Blocks + connectors JSON
+airgen diag render <tenant> <project> <id>             # Terminal display (default)
+airgen diag render <tenant> <project> <id> --format mermaid  # Mermaid syntax
+airgen diag render <tenant> <project> <id> --format mermaid --wrap -o diagram.md
+airgen diag create <tenant> <project> --name "X" --view block
+airgen diag update <tenant> <project> <id> --name "Y"
+airgen diag delete <tenant> <project> <id>
+```
+
+**Blocks:**
+
+```bash
+airgen diag blocks library <tenant> <project>
+airgen diag blocks create <tenant> <project> --diagram <id> --name "X" --kind subsystem
+airgen diag blocks delete <tenant> <project> <block-id>
+```
+
+**Connectors:**
+
+```bash
+airgen diag conn create <tenant> <project> --diagram <id> --source <id> --target <id> --kind flow --label "data"
+airgen diag conn delete <tenant> <project> <conn-id> --diagram <id>
+```
+
+### Traceability
+
+```bash
+airgen trace list <tenant> <project>                   # List trace links
+airgen trace create <tenant> <project> --source <id> --target <id> --type derives
+airgen trace delete <tenant> <project> <link-id>
+airgen trace linksets list <tenant> <project>          # Document linksets
+```
+
+### 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
+airgen qa analyze "The system shall..."               # Analyze single requirement
+airgen qa score start <tenant> <project>               # Background QA scoring
+airgen qa draft "user needs thermal imaging"           # Draft requirements from NL
+
+airgen ai generate <tenant> <project> --prompt "..."   # Generate candidates
+airgen ai candidates <tenant> <project>                # List pending candidates
+airgen ai accept <candidate-id>                        # Promote to requirement
+airgen ai reject <candidate-id>                        # Reject candidate
+```
+
+### Reports
+
+```bash
+airgen report stats <tenant> <project>                 # Overview statistics
+airgen report quality <tenant> <project>               # QA score summary
+airgen report compliance <tenant> <project>            # Compliance + impl status
+airgen report orphans <tenant> <project>               # Untraced requirements
+```
+
+All report commands auto-paginate through the full requirement set (up to 5000).
+
+### Implementation Tracking
+
+```bash
+airgen impl status <tenant> <project> <req> --status implemented --notes "done in v2"
+airgen impl summary <tenant> <project>                 # Coverage breakdown
+airgen impl list <tenant> <project> --status blocked   # Filter by status
+airgen impl bulk-update <tenant> <project> --file updates.json
+
+# Artifact linking
+airgen impl link <tenant> <project> <req> --type file --path src/engine.ts
+airgen impl unlink <tenant> <project> <req> --artifact <id>
+```
+
+**Statuses:** `not_started`, `in_progress`, `implemented`, `verified`, `blocked`
+
+**Bulk update file format:**
+
+```json
+[
+  { "ref": "REQ-001", "status": "implemented", "notes": "shipped" },
+  { "ref": "REQ-002", "status": "in_progress" }
+]
+```
+
+### Import / Export
+
+```bash
+airgen import requirements <tenant> <project> --file reqs.csv
+airgen export requirements <tenant> <project>          # Markdown
+airgen export requirements <tenant> <project> --json   # JSON
+```
+
+### Activity
+
+```bash
+airgen activity list <tenant> <project>                # Recent activity
+airgen activity list <tenant> <project> --limit 50
+```
+
+### Documents
+
+```bash
+airgen docs list <tenant> <project>
+airgen docs get <tenant> <project> <slug>
+airgen docs create <tenant> <project> --title "X" --kind structured
+airgen docs delete <tenant> <project> <slug>
+airgen docs export <tenant> <project> <slug>           # Markdown export
+airgen docs sec list <tenant> <project> <slug>         # List sections
+```
+
+### Semantic Lint
+
+Classifies domain concepts from your requirements using the [Universal Hex Taxonomy](https://universalhex.org) and flags ontological issues, structural problems, and coverage gaps.
+
+```bash
+airgen lint <tenant> <project>                         # Full lint (top 15 concepts)
+airgen lint <tenant> <project> --concepts 20           # Classify more concepts
+airgen lint <tenant> <project> --format markdown -o lint-report.md
+airgen lint <tenant> <project> --format json           # Machine-readable
+```
+
+**What it detects:**
+
+- Ontological mismatches (e.g., non-physical entity with physical constraints)
+- Abstract metrics missing statistical parameters
+- Verification requirements mixed with functional requirements
+- Degraded modes without performance criteria
+- Ontological ambiguity between similar concepts
+- Requirements lacking "shall" keyword
+
+**Requires:** `UHT_TOKEN` or `UHT_API_KEY` environment variable. Get a token at [universalhex.org](https://universalhex.org).
+
+## JSON mode
+
+Append `--json` to any command for machine-readable output:
+
+```bash
+airgen reqs list my-tenant my-project --json | jq '.[].ref'
+airgen report compliance my-tenant my-project --json | jq '.summary'
+```
+
+## Aliases
+
+| Full command | Alias |
+|---|---|
+| `requirements` | `reqs` |
+| `diagrams` | `diag` |
+| `documents` | `docs` |
+| `connectors` | `conn` |
+| `baselines` | `bl` |
+| `traces` | `trace` |
+| `quality` | `qa` |
+| `reports` | `report` |
+| `projects` | `proj` |
+| `sections` | `sec` |
+
+## License
+
+MIT

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/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.1.8",
+  "version": "0.2.1",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "package.json"
+    "package.json",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -21,7 +22,12 @@
     "requirements",
     "engineering",
     "cli",
-    "requirements-management"
+    "requirements-management",
+    "systems-engineering",
+    "traceability",
+    "sysml",
+    "mbse",
+    "uht"
   ],
   "license": "MIT",
   "repository": {