airgen-cli 0.1.1 → 0.1.3

package/dist/commands/implementation.js

@@ -1,75 +1,342 @@
-import { output } from "../output.js";
+import { readFileSync } from "node:fs";
+import { output, printTable, isJsonMode, truncate } from "../output.js";
+import { resolveRequirementId } from "../resolve.js";
+const IMPL_STATUSES = ["not_started", "in_progress", "implemented", "verified", "blocked"];
+const IMPL_TAG_PREFIX = "impl:";
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+// ── Helpers ──────────────────────────────────────────────────
+async function fetchAllRequirements(client, tenant, project) {
+    const all = [];
+    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 ?? [];
+        all.push(...items);
+        const totalPages = data.meta?.totalPages ?? 1;
+        if (page >= totalPages)
+            break;
+    }
+    return all.filter((r) => !r.deleted && !r.deletedAt);
+}
+function getImplStatus(tags) {
+    if (!tags)
+        return null;
+    const implTag = tags.find((t) => t.startsWith(IMPL_TAG_PREFIX));
+    if (!implTag)
+        return null;
+    const status = implTag.slice(IMPL_TAG_PREFIX.length);
+    return IMPL_STATUSES.includes(status) ? status : null;
+}
+function parseArtifacts(attributes) {
+    if (!attributes?.artifacts || typeof attributes.artifacts !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(attributes.artifacts);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function statusEmoji(status) {
+    switch (status) {
+        case "not_started": return "[ ]";
+        case "in_progress": return "[~]";
+        case "implemented": return "[x]";
+        case "verified": return "[v]";
+        case "blocked": return "[!]";
+        default: return "[-]";
+    }
+}
+function pct(n, total) {
+    if (total === 0)
+        return "0.0%";
+    return ((n / total) * 100).toFixed(1) + "%";
+}
+// ── Command registration ─────────────────────────────────────
 export function registerImplementationCommands(program, client) {
     const cmd = program.command("impl").description("Implementation tracking");
+    // ── impl status ──────────────────────────────────────────
     cmd
         .command("status")
-        .description("Set implementation status on a requirement")
+        .description("Set implementation status on a requirement (syncs tags + attributes)")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<requirement-id>", "Requirement ID")
+        .argument("<requirement>", "Requirement ref, ID, or hashId")
         .requiredOption("--status <s>", "Status: not_started, in_progress, implemented, verified, blocked")
         .option("--notes <text>", "Notes")
-        .action(async (tenant, project, requirementId, opts) => {
-        // Implementation status is stored in requirement attributes
-        const data = await client.patch(`/requirements/${tenant}/${project}/${requirementId}`, {
-            attributes: {
-                implementationStatus: opts.status,
-                implementationNotes: opts.notes,
-            },
+        .action(async (tenant, project, requirement, opts) => {
+        if (!IMPL_STATUSES.includes(opts.status)) {
+            console.error(`Invalid status: ${opts.status}. Must be one of: ${IMPL_STATUSES.join(", ")}`);
+            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);
+        if (!req) {
+            console.error(`Requirement ${requirement} not found.`);
+            process.exit(1);
+        }
+        const now = new Date().toISOString();
+        // Update tags: remove existing impl:* tags, add new one
+        const currentTags = (req.tags ?? []).filter(t => !t.startsWith(IMPL_TAG_PREFIX));
+        currentTags.push(`${IMPL_TAG_PREFIX}${opts.status}`);
+        // Update attributes (matching MCP server's field names)
+        const updatedAttributes = {
+            ...(req.attributes ?? {}),
+            impl_status: opts.status,
+            impl_updated_at: now,
+        };
+        if (opts.notes !== undefined) {
+            updatedAttributes.impl_notes = opts.notes || null;
+        }
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
+            tags: currentTags,
+            attributes: updatedAttributes,
         });
-        output(data);
+        if (isJsonMode()) {
+            output({ ok: true, id: resolvedId, status: opts.status, tags: currentTags });
+        }
+        else {
+            console.log(`Implementation status set to ${opts.status} on ${req.ref ?? resolvedId}.`);
+        }
+    });
+    // ── impl summary ─────────────────────────────────────────
+    cmd
+        .command("summary")
+        .description("Implementation coverage report for a project")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .action(async (tenant, project) => {
+        const requirements = await fetchAllRequirements(client, tenant, project);
+        const total = requirements.length;
+        if (total === 0) {
+            console.log("No requirements found.");
+            return;
+        }
+        const statusCounts = {};
+        for (const s of IMPL_STATUSES)
+            statusCounts[s] = 0;
+        statusCounts["unset"] = 0;
+        let withArtifactCount = 0;
+        for (const req of requirements) {
+            const status = getImplStatus(req.tags);
+            if (status) {
+                statusCounts[status]++;
+            }
+            else {
+                statusCounts["unset"]++;
+            }
+            const artifacts = parseArtifacts(req.attributes);
+            if (artifacts.length > 0)
+                withArtifactCount++;
+        }
+        const done = (statusCounts["implemented"] ?? 0) + (statusCounts["verified"] ?? 0);
+        const inProgress = statusCounts["in_progress"] ?? 0;
+        const blocked = statusCounts["blocked"] ?? 0;
+        if (isJsonMode()) {
+            output({ total, statusCounts, done, inProgress, blocked, withArtifacts: withArtifactCount });
+            return;
+        }
+        console.log(`Implementation Report (${total} requirements)\n`);
+        console.log(`Coverage: ${pct(done, total)}  |  Artifacts: ${pct(withArtifactCount, total)}\n`);
+        printTable(["Status", "Count", "%", ""], [...IMPL_STATUSES, "unset"].map(s => {
+            const count = statusCounts[s] ?? 0;
+            const bar = "\u2588".repeat(Math.round((count / total) * 30));
+            const emoji = s === "unset" ? "[-]" : statusEmoji(s);
+            return [`${emoji} ${s}`, String(count), pct(count, total), bar];
+        }));
+        console.log(`\nDone (implemented + verified): ${done}`);
+        console.log(`In progress: ${inProgress}`);
+        console.log(`Blocked: ${blocked}`);
+        console.log(`Not started / unset: ${total - done - inProgress - blocked}`);
+        console.log(`With artifact links: ${withArtifactCount}`);
+    });
+    // ── impl list ────────────────────────────────────────────
+    cmd
+        .command("list")
+        .description("List requirements filtered by implementation status")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .option("--status <s>", "Filter by status: not_started, in_progress, implemented, verified, blocked, unset")
+        .action(async (tenant, project, opts) => {
+        const requirements = await fetchAllRequirements(client, tenant, project);
+        let filtered = requirements;
+        if (opts.status) {
+            if (opts.status === "unset") {
+                filtered = requirements.filter(r => getImplStatus(r.tags) === null);
+            }
+            else {
+                filtered = requirements.filter(r => getImplStatus(r.tags) === opts.status);
+            }
+        }
+        if (isJsonMode()) {
+            output(filtered.map(r => ({
+                ref: r.ref,
+                id: r.id,
+                text: r.text,
+                status: getImplStatus(r.tags) ?? "unset",
+                artifacts: parseArtifacts(r.attributes).length,
+            })));
+            return;
+        }
+        console.log(`Implementation status: ${opts.status ?? "all"} (${filtered.length} requirements)\n`);
+        if (filtered.length === 0) {
+            console.log("No matching requirements.");
+            return;
+        }
+        printTable(["Ref", "Status", "Text", "Artifacts"], filtered.map(r => [
+            r.ref ?? "?",
+            statusEmoji(getImplStatus(r.tags)) + " " + (getImplStatus(r.tags) ?? "unset"),
+            truncate(r.text ?? "", 50),
+            String(parseArtifacts(r.attributes).length),
+        ]));
+    });
+    // ── impl bulk-update ─────────────────────────────────────
+    cmd
+        .command("bulk-update")
+        .description("Bulk update implementation status from a JSON file")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .requiredOption("--file <path>", "JSON file with array of {ref, status, notes?}")
+        .action(async (tenant, project, opts) => {
+        let items;
+        try {
+            const raw = readFileSync(opts.file, "utf-8");
+            items = JSON.parse(raw);
+            if (!Array.isArray(items))
+                throw new Error("File must contain a JSON array");
+        }
+        catch (err) {
+            console.error(`Failed to read file: ${err.message}`);
+            process.exit(1);
+        }
+        let updated = 0;
+        let failed = 0;
+        const errors = [];
+        for (const item of items) {
+            if (!IMPL_STATUSES.includes(item.status)) {
+                errors.push(`${item.ref}: invalid status "${item.status}"`);
+                failed++;
+                continue;
+            }
+            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);
+                if (!req) {
+                    errors.push(`${item.ref}: not found`);
+                    failed++;
+                    continue;
+                }
+                const now = new Date().toISOString();
+                const currentTags = (req.tags ?? []).filter(t => !t.startsWith(IMPL_TAG_PREFIX));
+                currentTags.push(`${IMPL_TAG_PREFIX}${item.status}`);
+                const updatedAttributes = {
+                    ...(req.attributes ?? {}),
+                    impl_status: item.status,
+                    impl_updated_at: now,
+                };
+                if (item.notes !== undefined) {
+                    updatedAttributes.impl_notes = item.notes || null;
+                }
+                await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
+                    tags: currentTags,
+                    attributes: updatedAttributes,
+                });
+                updated++;
+            }
+            catch (err) {
+                errors.push(`${item.ref}: ${err.message}`);
+                failed++;
+            }
+        }
+        if (isJsonMode()) {
+            output({ total: items.length, updated, failed, errors });
+        }
+        else {
+            console.log(`Bulk update: ${updated} updated, ${failed} failed (${items.length} total)`);
+            for (const e of errors) {
+                console.error(`  - ${e}`);
+            }
+        }
     });
+    // ── impl link ────────────────────────────────────────────
     cmd
         .command("link")
         .description("Link a code artifact to a requirement")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<requirement-id>", "Requirement ID")
+        .argument("<requirement>", "Requirement ref, ID, or hashId")
         .requiredOption("--type <type>", "Artifact type: file, commit, pr, issue, test, url")
         .requiredOption("--path <path>", "Artifact path/reference")
         .option("--label <text>", "Label")
         .option("--line <n>", "Line number (for file type)")
-        .action(async (tenant, project, requirementId, opts) => {
-        // Fetch current requirement to get existing artifacts
-        const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "500" });
-        const req = (reqData.data ?? []).find(r => r.id === requirementId);
+        .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);
         if (!req) {
-            console.error(`Requirement ${requirementId} not found.`);
+            console.error(`Requirement ${requirement} not found.`);
             process.exit(1);
         }
-        const attrs = req.attributes ?? {};
-        const artifacts = attrs.artifacts ?? [];
+        const artifacts = parseArtifacts(req.attributes);
         const newArtifact = { type: opts.type, path: opts.path };
         if (opts.label)
             newArtifact.label = opts.label;
         if (opts.line)
             newArtifact.line = parseInt(opts.line, 10);
+        // Check for duplicates
+        const exists = artifacts.some(a => a.type === newArtifact.type && a.path === newArtifact.path);
+        if (exists) {
+            console.log("Artifact already linked.");
+            return;
+        }
         artifacts.push(newArtifact);
-        await client.patch(`/requirements/${tenant}/${project}/${requirementId}`, {
-            attributes: { ...attrs, artifacts },
+        const updatedAttributes = {
+            ...(req.attributes ?? {}),
+            artifacts: JSON.stringify(artifacts),
+        };
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
+            attributes: updatedAttributes,
         });
         console.log("Artifact linked.");
     });
+    // ── impl unlink ──────────────────────────────────────────
     cmd
         .command("unlink")
         .description("Remove an artifact link from a requirement")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<requirement-id>", "Requirement ID")
+        .argument("<requirement>", "Requirement ref, ID, or hashId")
         .requiredOption("--type <type>", "Artifact type")
         .requiredOption("--path <path>", "Artifact path")
-        .action(async (tenant, project, requirementId, opts) => {
-        const reqData = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "500" });
-        const req = (reqData.data ?? []).find(r => r.id === requirementId);
+        .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);
         if (!req) {
-            console.error(`Requirement ${requirementId} not found.`);
+            console.error(`Requirement ${requirement} not found.`);
             process.exit(1);
         }
-        const attrs = req.attributes ?? {};
-        const artifacts = attrs.artifacts ?? [];
+        const artifacts = parseArtifacts(req.attributes);
         const filtered = artifacts.filter(a => !(a.type === opts.type && a.path === opts.path));
-        await client.patch(`/requirements/${tenant}/${project}/${requirementId}`, {
-            attributes: { ...attrs, artifacts: filtered },
+        if (filtered.length === artifacts.length) {
+            console.log("No matching artifact found.");
+            return;
+        }
+        const updatedAttributes = {
+            ...(req.attributes ?? {}),
+            artifacts: filtered.length > 0 ? JSON.stringify(filtered) : null,
+        };
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
+            attributes: updatedAttributes,
         });
         console.log("Artifact unlinked.");
     });

package/dist/commands/reports.js

@@ -1,4 +1,15 @@
 import { output, printTable, isJsonMode, truncate } from "../output.js";
+const IMPL_TAG_PREFIX = "impl:";
+const IMPL_STATUSES = ["not_started", "in_progress", "implemented", "verified", "blocked"];
+function getImplStatus(tags) {
+    if (!tags)
+        return null;
+    const implTag = tags.find(t => t.startsWith(IMPL_TAG_PREFIX));
+    if (!implTag)
+        return null;
+    const status = implTag.slice(IMPL_TAG_PREFIX.length);
+    return IMPL_STATUSES.includes(status) ? status : null;
+}
 export function registerReportCommands(program, client) {
     const cmd = program.command("reports").alias("report").description("Project reports");
     cmd
@@ -68,16 +79,32 @@ export function registerReportCommands(program, client) {
         .action(async (tenant, project, opts) => {
         const data = await client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: opts.limit });
         const reqs = data.data ?? [];
-        const counts = {};
+        // Compliance status
+        const compCounts = {};
         for (const r of reqs) {
             const status = r.complianceStatus || "Unset";
-            counts[status] = (counts[status] ?? 0) + 1;
+            compCounts[status] = (compCounts[status] ?? 0) + 1;
+        }
+        // Implementation status (read from tags, matching MCP server)
+        const implCounts = {};
+        for (const s of IMPL_STATUSES)
+            implCounts[s] = 0;
+        implCounts["unset"] = 0;
+        for (const r of reqs) {
+            const status = getImplStatus(r.tags);
+            if (status)
+                implCounts[status]++;
+            else
+                implCounts["unset"]++;
         }
         if (isJsonMode()) {
-            output(counts);
+            output({ compliance: compCounts, implementation: implCounts });
         }
         else {
-            printTable(["Status", "Count"], Object.entries(counts).map(([k, v]) => [k, String(v)]));
+            console.log("Compliance Status:");
+            printTable(["Status", "Count"], Object.entries(compCounts).map(([k, v]) => [k, String(v)]));
+            console.log("\nImplementation Status:");
+            printTable(["Status", "Count"], Object.entries(implCounts).filter(([, v]) => v > 0).map(([k, v]) => [k, String(v)]));
         }
     });
     cmd

package/dist/commands/requirements.js

@@ -1,4 +1,5 @@
 import { output, printTable, isJsonMode, truncate } from "../output.js";
+import { resolveRequirementId } from "../resolve.js";
 export function registerRequirementCommands(program, client) {
     const cmd = program.command("requirements").alias("reqs").description("Manage requirements");
     cmd
@@ -96,7 +97,7 @@ export function registerRequirementCommands(program, client) {
         .description("Update a requirement")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<id>", "Requirement ID")
+        .argument("<id>", "Requirement ref, ID, or hashId")
         .option("--text <text>", "Requirement text")
         .option("--pattern <p>", "Pattern")
         .option("--verification <v>", "Verification method")
@@ -105,6 +106,7 @@ export function registerRequirementCommands(program, client) {
         .option("--section <id>", "Section ID")
         .option("--tags <tags>", "Comma-separated tags")
         .action(async (tenant, project, id, opts) => {
+        const resolvedId = await resolveRequirementId(client, tenant, project, id);
         const body = {};
         if (opts.text)
             body.text = opts.text;
@@ -120,7 +122,7 @@ export function registerRequirementCommands(program, client) {
             body.sectionId = opts.section;
         if (opts.tags)
             body.tags = opts.tags.split(",").map(t => t.trim());
-        await client.patch(`/requirements/${tenant}/${project}/${id}`, body);
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
         if (isJsonMode()) {
             output({ ok: true });
         }
@@ -133,9 +135,10 @@ export function registerRequirementCommands(program, client) {
         .description("Soft-delete a requirement")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<id>", "Requirement ID")
+        .argument("<id>", "Requirement ref, ID, or hashId")
         .action(async (tenant, project, id) => {
-        await client.delete(`/requirements/${tenant}/${project}/${id}`);
+        const resolvedId = await resolveRequirementId(client, tenant, project, id);
+        await client.delete(`/requirements/${tenant}/${project}/${resolvedId}`);
         console.log("Requirement deleted.");
     });
     cmd
@@ -143,9 +146,10 @@ export function registerRequirementCommands(program, client) {
         .description("Get version history of a requirement")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .argument("<id>", "Requirement ID")
+        .argument("<id>", "Requirement ref, ID, or hashId")
         .action(async (tenant, project, id) => {
-        const data = await client.get(`/requirements/${tenant}/${project}/${id}/history`);
+        const resolvedId = await resolveRequirementId(client, tenant, project, id);
+        const data = await client.get(`/requirements/${tenant}/${project}/${resolvedId}/history`);
         output(data);
     });
     cmd

package/dist/resolve.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve any requirement identifier to its full ID.
+ *
+ * Accepts: full ID, ref, short ID (REQ-XXX), or hashId.
+ * Returns the full colon-separated ID (tenant:project:REQ-XXX).
+ */
+import type { AirgenClient } from "./client.js";
+export declare function resolveRequirementId(client: AirgenClient, tenant: string, project: string, identifier: string): Promise<string>;

package/dist/resolve.js

@@ -0,0 +1,41 @@
+/**
+ * Resolve any requirement identifier to its full ID.
+ *
+ * Accepts: full ID, ref, short ID (REQ-XXX), or hashId.
+ * Returns the full colon-separated ID (tenant:project:REQ-XXX).
+ */
+export async function resolveRequirementId(client, tenant, project, identifier) {
+    // Already a full ID (contains colons)
+    if (identifier.includes(":")) {
+        return identifier;
+    }
+    // Try as ref first (GET /requirements/{tenant}/{project}/{ref})
+    try {
+        const data = await client.get(`/requirements/${tenant}/${project}/${identifier}`);
+        if (data.record?.id)
+            return data.record.id;
+    }
+    catch {
+        // Not found by ref — continue
+    }
+    // Search through requirements for short ID or hashId match
+    let page = 1;
+    const limit = 100;
+    while (true) {
+        const data = await client.get(`/requirements/${tenant}/${project}`, { page: String(page), limit: String(limit) });
+        const reqs = data.data ?? [];
+        for (const r of reqs) {
+            // Match by short ID (the REQ-XXX part of tenant:project:REQ-XXX)
+            if (r.id?.endsWith(`:${identifier}`))
+                return r.id;
+            // Match by hashId
+            if (r.hashId === identifier)
+                return r.id;
+        }
+        if (page >= (data.meta?.totalPages ?? 1))
+            break;
+        page++;
+    }
+    // Nothing found — return as-is and let the API error
+    return identifier;
+}

package/package.json

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