airgen-cli 0.1.0 → 0.1.2

package/dist/client.d.ts

@@ -2,6 +2,7 @@
  * AIRGen HTTP API client with JWT authentication.
  *
  * Handles login, token caching, and automatic refresh.
+ * Persists session tokens to ~/.airgen-session for reuse across CLI invocations.
  */
 export interface ClientConfig {
     apiUrl: string;
@@ -13,6 +14,9 @@ export declare class AirgenClient {
     private auth;
     private loginPromise;
     constructor(config: ClientConfig);
+    private loadSession;
+    private saveSession;
+    private clearSession;
     /** The base API URL this client is configured for. */
     get apiUrl(): string;
     get<T = unknown>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;

package/dist/client.js

@@ -2,7 +2,12 @@
  * AIRGen HTTP API client with JWT authentication.
  *
  * Handles login, token caching, and automatic refresh.
+ * Persists session tokens to ~/.airgen-session for reuse across CLI invocations.
  */
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const SESSION_FILE = join(homedir(), ".airgen-session");
 export class AirgenClient {
     config;
     auth = {
@@ -13,6 +18,44 @@ export class AirgenClient {
     loginPromise = null;
     constructor(config) {
         this.config = config;
+        this.loadSession();
+    }
+    loadSession() {
+        try {
+            const raw = readFileSync(SESSION_FILE, "utf-8");
+            const session = JSON.parse(raw);
+            // Only reuse session if it matches current config
+            if (session.apiUrl === this.config.apiUrl && session.email === this.config.email) {
+                this.auth = {
+                    accessToken: session.accessToken,
+                    refreshToken: session.refreshToken,
+                    tokenExpiresAt: session.tokenExpiresAt,
+                };
+            }
+        }
+        catch {
+            // No session file or invalid — start fresh
+        }
+    }
+    saveSession() {
+        try {
+            writeFileSync(SESSION_FILE, JSON.stringify({
+                apiUrl: this.config.apiUrl,
+                email: this.config.email,
+                accessToken: this.auth.accessToken,
+                refreshToken: this.auth.refreshToken,
+                tokenExpiresAt: this.auth.tokenExpiresAt,
+            }), { mode: 0o600 });
+        }
+        catch {
+            // Non-fatal — session just won't persist
+        }
+    }
+    clearSession() {
+        try {
+            unlinkSync(SESSION_FILE);
+        }
+        catch { /* ignore */ }
     }
     /** The base API URL this client is configured for. */
     get apiUrl() {
@@ -53,7 +96,7 @@ export class AirgenClient {
             headers["Authorization"] = `Bearer ${this.auth.accessToken}`;
         }
         if (this.auth.refreshToken) {
-            headers["Cookie"] = `airgen_refresh=${this.auth.refreshToken}`;
+            headers["Cookie"] = `refreshToken=${this.auth.refreshToken}`;
         }
         const url = `${this.config.apiUrl}${path}`;
         const res = await globalThis.fetch(url, { method: "POST", headers, body });
@@ -105,7 +148,7 @@ export class AirgenClient {
             headers["Content-Type"] = "application/json";
         }
         if (this.auth.refreshToken) {
-            headers["Cookie"] = `airgen_refresh=${this.auth.refreshToken}`;
+            headers["Cookie"] = `refreshToken=${this.auth.refreshToken}`;
         }
         const url = `${this.config.apiUrl}${path}`;
         try {
@@ -194,11 +237,12 @@ export class AirgenClient {
         this.auth.accessToken = data.token;
         this.auth.tokenExpiresAt = decodeTokenExpiry(data.token);
         this.auth.refreshToken = extractRefreshToken(res);
+        this.saveSession();
     }
     async refresh() {
         const headers = {};
         if (this.auth.refreshToken) {
-            headers["Cookie"] = `airgen_refresh=${this.auth.refreshToken}`;
+            headers["Cookie"] = `refreshToken=${this.auth.refreshToken}`;
         }
         const res = await globalThis.fetch(`${this.config.apiUrl}/auth/refresh`, {
             method: "POST",
@@ -207,6 +251,7 @@ export class AirgenClient {
         if (!res.ok) {
             // Refresh failed — clear state and re-login
             this.auth = { accessToken: null, refreshToken: null, tokenExpiresAt: 0 };
+            this.clearSession();
             await this.login();
             return;
         }
@@ -217,6 +262,7 @@ export class AirgenClient {
         if (newRefresh) {
             this.auth.refreshToken = newRefresh;
         }
+        this.saveSession();
     }
 }
 // ── Error class ───────────────────────────────────────────────
@@ -248,8 +294,8 @@ function extractRefreshToken(res) {
     const setCookie = res.headers.get("set-cookie");
     if (!setCookie)
         return null;
-    // Parse airgen_refresh cookie value
-    const match = setCookie.match(/airgen_refresh=([^;]+)/);
+    // Parse refreshToken cookie value
+    const match = setCookie.match(/refreshToken=([^;]+)/);
     return match ? match[1] : null;
 }
 function buildQueryString(params) {

package/dist/commands/implementation.js

@@ -1,4 +1,5 @@
 import { output } from "../output.js";
+import { resolveRequirementId } from "../resolve.js";
 export function registerImplementationCommands(program, client) {
     const cmd = program.command("impl").description("Implementation tracking");
     cmd
@@ -6,12 +7,12 @@ export function registerImplementationCommands(program, client) {
         .description("Set implementation status on a requirement")
         .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}`, {
+        .action(async (tenant, project, requirement, opts) => {
+        const resolvedId = await resolveRequirementId(client, tenant, project, requirement);
+        const data = await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
             attributes: {
                 implementationStatus: opts.status,
                 implementationNotes: opts.notes,
@@ -24,17 +25,18 @@ export function registerImplementationCommands(program, client) {
         .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) => {
+        .action(async (tenant, project, requirement, opts) => {
+        const resolvedId = await resolveRequirementId(client, tenant, project, requirement);
         // 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);
+        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 ?? {};
@@ -45,7 +47,7 @@ export function registerImplementationCommands(program, client) {
         if (opts.line)
             newArtifact.line = parseInt(opts.line, 10);
         artifacts.push(newArtifact);
-        await client.patch(`/requirements/${tenant}/${project}/${requirementId}`, {
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
             attributes: { ...attrs, artifacts },
         });
         console.log("Artifact linked.");
@@ -55,20 +57,21 @@ export function registerImplementationCommands(program, client) {
         .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 filtered = artifacts.filter(a => !(a.type === opts.type && a.path === opts.path));
-        await client.patch(`/requirements/${tenant}/${project}/${requirementId}`, {
+        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, {
             attributes: { ...attrs, artifacts: filtered },
         });
         console.log("Artifact unlinked.");

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.0",
+  "version": "0.1.2",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",