airgen-cli 0.22.0 → 0.23.1

package/dist/commands/baselines.js

@@ -1,4 +1,10 @@
+import { writeFileSync } from "node:fs";
 import { output, printTable, isJsonMode } from "../output.js";
+function refFromRequirementId(id) {
+    // Composite IDs are tenant:project:REF
+    const parts = id.split(":");
+    return parts[parts.length - 1];
+}
 export function registerBaselineCommands(program, client) {
     const cmd = program.command("baselines").alias("bl").description("Baseline snapshots");
     cmd
@@ -52,4 +58,200 @@ export function registerBaselineCommands(program, client) {
         const data = await client.get(`/baselines/${tenant}/${project}/compare`, { from: opts.from, to: opts.to });
         output(data);
     });
+    cmd
+        .command("show")
+        .description("Show baseline contents (requirements with full text, rationale, tags)")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("--ref <pattern>", "Filter to requirements whose ref matches this substring")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        let reqs = snap.requirementVersions ?? [];
+        if (opts.ref) {
+            const needle = opts.ref;
+            reqs = reqs.filter(r => refFromRequirementId(r.requirementId).includes(needle));
+        }
+        if (isJsonMode()) {
+            output({ baseline: snap.baseline, requirementVersions: reqs });
+            return;
+        }
+        console.log(`Baseline: ${snap.baseline.ref ?? snap.baseline.id}`);
+        console.log(`Label:    ${snap.baseline.label ?? ""}`);
+        console.log(`Created:  ${snap.baseline.createdAt ?? ""}`);
+        console.log(`Requirements: ${reqs.length}\n`);
+        for (const r of reqs) {
+            const ref = refFromRequirementId(r.requirementId);
+            console.log(`── ${ref} (v${r.versionNumber}) ──`);
+            console.log(`text:       ${r.text}`);
+            if (r.pattern)
+                console.log(`pattern:    ${r.pattern}`);
+            if (r.verification)
+                console.log(`verify:     ${r.verification}`);
+            if (r.rationale)
+                console.log(`rationale:  ${r.rationale}`);
+            if (r.complianceStatus)
+                console.log(`compliance: ${r.complianceStatus}`);
+            if (r.tags?.length)
+                console.log(`tags:       ${r.tags.join(", ")}`);
+            console.log("");
+        }
+    });
+    cmd
+        .command("export")
+        .description("Export full baseline snapshot as JSON")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("-o, --output <file>", "Write JSON to file instead of stdout")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        const json = JSON.stringify(snap, null, 2);
+        if (opts.output) {
+            writeFileSync(opts.output, json);
+            console.error(`Wrote ${opts.output} (${(json.length / 1024).toFixed(1)} KB, ${snap.requirementVersions?.length ?? 0} requirements)`);
+        }
+        else {
+            process.stdout.write(json + "\n");
+        }
+    });
+    cmd
+        .command("restore")
+        .description("Restore requirements from a baseline (PATCHes live requirements with snapshot values). Joins on immutable internal id, so survives reqs reassign.")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("--ref <pattern>", "Restore only requirements whose original ref includes this substring")
+        .option("--fields <list>", "Comma-separated fields to restore (default: rationale,text,pattern,verification,complianceStatus,complianceRationale,tags)", "rationale,text,pattern,verification,complianceStatus,complianceRationale,tags")
+        .option("--dry-run", "Print what would be restored without making changes")
+        .option("--yes", "Skip confirmation prompt")
+        .option("--match-by-text", "Fall back to text-content matching for requirements not found by id (e.g. recreated entities)")
+        .option("--strict", "Exit non-zero if any requirement fails to restore")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        let reqs = snap.requirementVersions ?? [];
+        if (opts.ref) {
+            const needle = opts.ref;
+            reqs = reqs.filter(r => refFromRequirementId(r.requirementId).includes(needle));
+        }
+        const fields = opts.fields.split(",").map(f => f.trim()).filter(Boolean);
+        const allowed = new Set(["text", "pattern", "verification", "rationale", "complianceStatus", "complianceRationale", "tags"]);
+        const invalid = fields.filter(f => !allowed.has(f));
+        if (invalid.length > 0) {
+            console.error(`Invalid fields: ${invalid.join(", ")}`);
+            console.error(`Allowed: ${[...allowed].join(", ")}`);
+            process.exit(1);
+        }
+        console.error(`Baseline:    ${snap.baseline.ref ?? snap.baseline.id}`);
+        console.error(`Label:       ${snap.baseline.label ?? ""}`);
+        console.error(`Created:     ${snap.baseline.createdAt ?? ""}`);
+        console.error(`Requirements to restore: ${reqs.length}`);
+        console.error(`Fields:      ${fields.join(", ")}`);
+        console.error(`Join key:    immutable id (survives reqs reassign)${opts.matchByText ? " + text-match fallback" : ""}`);
+        console.error("");
+        // Optionally fetch current requirements for text-match fallback
+        let textIndex = null;
+        if (opts.matchByText) {
+            console.error("Fetching current project requirements for text-match fallback...");
+            const allCurrent = [];
+            let page = 1;
+            const limit = 200;
+            while (true) {
+                const pageData = await client.get(`/requirements/${tenant}/${project}`, { page: String(page), limit: String(limit) });
+                const items = pageData.data ?? [];
+                allCurrent.push(...items);
+                if (page >= (pageData.meta?.totalPages ?? 1))
+                    break;
+                page++;
+            }
+            textIndex = new Map();
+            for (const c of allCurrent) {
+                if (c.text && c.ref) {
+                    textIndex.set(c.text.trim(), c.ref);
+                }
+            }
+            console.error(`Indexed ${textIndex.size} current requirements by text.\n`);
+        }
+        if (opts.dryRun) {
+            for (const r of reqs) {
+                const origRef = refFromRequirementId(r.requirementId);
+                const summary = fields.map(f => {
+                    const v = r[f];
+                    if (v == null)
+                        return `${f}=(none)`;
+                    const s = typeof v === "string" ? v : JSON.stringify(v);
+                    return `${f}=${s.length > 40 ? s.slice(0, 40) + "…" : s}`;
+                }).join(" | ");
+                console.log(`[dry-run] ${origRef}: ${summary}`);
+            }
+            console.error(`\n[dry-run] Would restore ${reqs.length} requirements. Re-run without --dry-run to apply.`);
+            return;
+        }
+        if (!opts.yes) {
+            console.error(`This will OVERWRITE current values for ${reqs.length} requirements.`);
+            console.error("Pass --yes to proceed, or --dry-run to preview.");
+            process.exit(1);
+        }
+        let ok = 0;
+        let failed = 0;
+        let skipped = 0;
+        let textMatched = 0;
+        const failures = [];
+        for (const r of reqs) {
+            const origRef = refFromRequirementId(r.requirementId);
+            const body = {};
+            for (const f of fields) {
+                const v = r[f];
+                if (v !== undefined)
+                    body[f] = v;
+            }
+            // Skip requirements where the baseline has no values for any of the requested fields.
+            // (e.g. restoring --fields tags on a requirement that had no tags at baseline time)
+            if (Object.keys(body).length === 0) {
+                skipped++;
+                continue;
+            }
+            // Primary: PATCH by immutable composite id (the baseline's requirementId).
+            // Backend resolver matches r.id, which is set on creation and never mutates.
+            try {
+                await client.patch(`/requirements/${tenant}/${project}/${encodeURIComponent(r.requirementId)}`, body);
+                ok++;
+                if (ok % 25 === 0)
+                    console.error(`  restored ${ok}/${reqs.length}…`);
+                continue;
+            }
+            catch (err) {
+                // Fall through to text-match fallback if enabled
+                const errMsg = err instanceof Error ? err.message : String(err);
+                if (textIndex && r.text) {
+                    const liveRef = textIndex.get(r.text.trim());
+                    if (liveRef) {
+                        try {
+                            await client.patch(`/requirements/${tenant}/${project}/${encodeURIComponent(liveRef)}`, body);
+                            ok++;
+                            textMatched++;
+                            console.error(`  text-matched ${origRef} -> ${liveRef}`);
+                            continue;
+                        }
+                        catch (err2) {
+                            failed++;
+                            failures.push({ ref: origRef, reason: `text-match to ${liveRef}: ${err2 instanceof Error ? err2.message : String(err2)}` });
+                            continue;
+                        }
+                    }
+                }
+                failed++;
+                failures.push({ ref: origRef, reason: errMsg });
+                console.error(`  FAILED ${origRef}: ${errMsg}`);
+            }
+        }
+        console.error(`\nDone. Restored ${ok}${textMatched > 0 ? ` (${textMatched} via text-match)` : ""}, skipped ${skipped} (no baseline values for requested fields), failed ${failed}.`);
+        if (failed > 0 && !opts.matchByText) {
+            console.error(`\nHint: re-run with --match-by-text to attempt content-based recovery for the ${failed} failures.`);
+        }
+        if (failed > 0 && opts.strict) {
+            console.error("\n--strict: exiting non-zero due to failures.");
+            process.exit(2);
+        }
+    });
 }

package/dist/commands/import-export.js

@@ -42,12 +42,18 @@ export function registerImportExportCommands(program, client) {
     const exp = program.command("export").description("Export data");
     exp
         .command("requirements")
-        .description("Export requirements as markdown or JSON")
+        .description("Export requirements as markdown or JSON (current state or from a baseline)")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .option("--document <slug>", "Export specific document as markdown")
         .option("--format <fmt>", "Format: json, markdown", "json")
+        .option("--baseline <ref>", "Export requirement state captured in a baseline (instead of current)")
         .action(async (tenant, project, opts) => {
+        if (opts.baseline) {
+            const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(opts.baseline)}`);
+            output({ baseline: snap.baseline, requirements: snap.requirementVersions ?? [] });
+            return;
+        }
         if (opts.document && opts.format === "markdown") {
             const data = await client.get(`/markdown/${tenant}/${project}/${opts.document}/content`);
             if (isJsonMode()) {

package/dist/commands/requirements.js

@@ -221,12 +221,16 @@ export function registerRequirementCommands(program, client) {
         else if (opts.tags) {
             body.tags = opts.tags.split(",").map(t => t.trim());
         }
-        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
+        const result = await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
+        const warnings = result?.warnings ?? [];
         if (isJsonMode()) {
-            output({ ok: true });
+            output({ ok: true, warnings });
         }
         else {
             console.log("Requirement updated.");
+            for (const w of warnings) {
+                console.error(`  warning: ${w}`);
+            }
         }
     });
     cmd

package/package.json

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