@simonfestl/husky-cli 1.9.2 → 1.12.0

package/README.md

@@ -143,6 +143,76 @@ husky e2e list --task <id>               # List artifacts
 husky e2e clean --older-than 7           # Clean old artifacts
 ```
 
+### PR Management (PR Agent)
+
+```bash
+husky pr list                          # List open PRs
+husky pr get <pr-number>               # Get PR details
+husky pr review <pr-number>            # Start review
+husky pr approve <pr-number>           # Approve PR
+husky pr request-changes <pr-number> --comment "..."
+husky pr merge <pr-number>             # Merge PR
+husky pr close <pr-number>             # Close PR
+```
+
+### Infrastructure (DevOps)
+
+```bash
+husky infra status                     # Overall infra status
+husky infra vms                        # List all VMs
+husky infra services                   # Cloud Run services
+husky infra logs <service>             # Service logs
+husky infra metrics                    # Resource metrics
+```
+
+### YouTube Summarization
+
+```bash
+husky youtube <url>                    # Summarize video with Gemini AI
+husky youtube <url> --remember         # Also store in Second Brain
+husky youtube <url> --json             # JSON output
+```
+
+### Image Generation
+
+```bash
+husky image "a futuristic city"        # Generate image with Imagen 3
+husky image "..." --output ./image.png # Save to file
+husky image "..." --aspect 16:9        # Aspect ratio
+```
+
+### Mermaid Diagrams
+
+```bash
+husky mermaid validate <file>          # Validate Mermaid syntax
+husky mermaid validate --stdin         # Validate from stdin
+```
+
+### Service Accounts
+
+```bash
+husky sa list                          # List service accounts
+husky sa create <name> --role worker   # Create service account
+husky sa get <id>                      # Get details
+husky sa delete <id>                   # Delete service account
+```
+
+### Agent Messaging
+
+```bash
+husky agent-msg send <to> "message"    # Send to another agent
+husky agent-msg inbox                  # Check inbox
+husky agent-msg read <id>              # Read message
+```
+
+### Preview Deployments
+
+```bash
+husky preview list                     # List PR previews
+husky preview get <pr-number>          # Get preview URL
+husky preview logs <pr-number>         # Preview logs
+```
+
 ### Business Strategy
 
 ```bash
@@ -249,6 +319,41 @@ husky config list
 husky config test
 ```
 
+### Authentication (Session Tokens)
+
+Session tokens provide short-lived JWT authentication for agents. They are created using `HUSKY_API_KEY` and auto-refresh when expired.
+
+```bash
+# Login (creates 1-hour session token)
+husky auth login --agent supervisor
+husky auth login --agent husky-worker-1
+
+# Check session status
+husky auth session
+husky auth session --json
+
+# Refresh token manually
+husky auth refresh
+husky auth refresh --agent supervisor
+
+# Logout (clear session)
+husky auth logout
+```
+
+**VM Startup Pattern:**
+```bash
+#!/bin/bash
+VM_NAME=$(hostname)
+husky auth login --agent "$VM_NAME"
+# All subsequent commands use Bearer token
+```
+
+**How it works:**
+1. `HUSKY_API_KEY` is used once to create a session token
+2. All subsequent API calls use `Authorization: Bearer <token>`
+3. Token auto-refreshes when expired or within 5 minutes of expiry
+4. Falls back to `x-api-key` if refresh fails
+
 ### Help & Documentation
 
 ```bash
@@ -328,6 +433,27 @@ husky --version
 
 ## Changelog
 
+### v1.12.0 (2026-01-12) - Session Token Authentication
+
+**New Features:**
+- `husky auth login --agent <name>` - Create session token from HUSKY_API_KEY
+- `husky auth logout` - Clear session token
+- `husky auth session` - Show session status (agent, role, expiry)
+- `husky auth refresh` - Manually refresh token
+
+**Improvements:**
+- All API calls now use Bearer token authentication (auto-refresh)
+- Token auto-refreshes when expired or within 5 minutes of expiry
+- Falls back to x-api-key for backwards compatibility
+- JWT_SECRET now required in production (fail-fast)
+
+**Documentation:**
+- Added missing command sections: pr, infra, youtube, image, mermaid, sa, agent-msg, preview
+- Updated architecture docs with session token flow
+
+**Code Quality:**
+- Removed `as any` type suppression in sop.ts
+
 ### v1.7.0 (2026-01-11) - E2E Agent Production Ready
 
 **New Features:**

package/dist/commands/auth.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const authCommand: Command;

package/dist/commands/auth.js

@@ -0,0 +1,437 @@
+import { Command } from "commander";
+import { getConfig, setSessionConfig, clearSessionConfig, getSessionConfig } from "./config.js";
+import { getPermissions, clearPermissionsCache, getCacheStatus, hasPermission, canAccessKnowledgeBase } from "../lib/permissions-cache.js";
+const API_KEY_ROLES = [
+    "admin", "supervisor", "worker", "reviewer", "support",
+    "purchasing", "ops", "e2e_agent", "pr_agent"
+];
+async function apiRequest(path, options = {}) {
+    const config = getConfig();
+    if (!config.apiUrl || !config.apiKey) {
+        throw new Error("API not configured. Run: husky config set api-url <url> && husky config set api-key <key>");
+    }
+    const url = new URL(path, config.apiUrl);
+    const res = await fetch(url.toString(), {
+        method: options.method || "GET",
+        headers: {
+            "x-api-key": config.apiKey,
+            "Content-Type": "application/json",
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (!res.ok) {
+        const error = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(error.message || error.error || `HTTP ${res.status}`);
+    }
+    return res.json();
+}
+export const authCommand = new Command("auth")
+    .description("Manage API keys and authentication");
+authCommand
+    .command("keys")
+    .description("List all API keys")
+    .option("--include-revoked", "Include revoked keys")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        const query = options.includeRevoked ? "?includeRevoked=true" : "";
+        const data = await apiRequest(`/api/auth/keys${query}`);
+        if (options.json) {
+            console.log(JSON.stringify(data.keys, null, 2));
+            return;
+        }
+        if (data.keys.length === 0) {
+            console.log("No API keys found.");
+            return;
+        }
+        console.log("\nAPI Keys:");
+        console.log("─".repeat(80));
+        for (const key of data.keys) {
+            const status = key.revoked ? "🔴 REVOKED" : "🟢 ACTIVE";
+            const expires = key.expiresAt ? new Date(key.expiresAt).toLocaleDateString() : "Never";
+            const lastUsed = key.lastUsedAt ? new Date(key.lastUsedAt).toLocaleDateString() : "Never";
+            console.log(`${status} ${key.keyPrefix}...  ${key.name}`);
+            console.log(`   Role: ${key.role}  |  Expires: ${expires}  |  Last used: ${lastUsed}`);
+            console.log(`   ID: ${key.id}`);
+            console.log("");
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("create-key")
+    .description("Create a new API key")
+    .requiredOption("--name <name>", "Human-readable name for the key")
+    .requiredOption("--role <role>", `Role: ${API_KEY_ROLES.join(", ")}`)
+    .option("--scopes <scopes>", "Comma-separated additional scopes")
+    .option("--expires-in-days <days>", "Expiration in days (1-365)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        if (!API_KEY_ROLES.includes(options.role)) {
+            console.error(`Invalid role: ${options.role}`);
+            console.error(`Valid roles: ${API_KEY_ROLES.join(", ")}`);
+            process.exit(1);
+        }
+        const body = {
+            name: options.name,
+            role: options.role,
+        };
+        if (options.scopes) {
+            body.scopes = options.scopes.split(",").map((s) => s.trim());
+        }
+        if (options.expiresInDays) {
+            const days = parseInt(options.expiresInDays, 10);
+            if (isNaN(days) || days < 1 || days > 365) {
+                console.error("--expires-in-days must be between 1 and 365");
+                process.exit(1);
+            }
+            body.expiresInDays = days;
+        }
+        const result = await apiRequest("/api/auth/keys", {
+            method: "POST",
+            body,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("\n✅ API Key Created Successfully");
+        console.log("─".repeat(60));
+        console.log(`Name:      ${result.name}`);
+        console.log(`Role:      ${result.role}`);
+        console.log(`Key ID:    ${result.id}`);
+        console.log(`Prefix:    ${result.keyPrefix}`);
+        if (result.expiresAt) {
+            console.log(`Expires:   ${new Date(result.expiresAt).toLocaleDateString()}`);
+        }
+        console.log("");
+        console.log("🔑 API KEY (store securely - shown only once):");
+        console.log("");
+        console.log(`   ${result.plainTextKey}`);
+        console.log("");
+        console.log("⚠️  " + result.warning);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("revoke-key <id>")
+    .description("Revoke an API key")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+    try {
+        const result = await apiRequest(`/api/auth/keys/${id}`, { method: "DELETE" });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`\n✅ API Key Revoked: ${result.keyPrefix}...`);
+        console.log(`   Revoked at: ${new Date(result.revokedAt).toLocaleString()}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("whoami")
+    .description("Show current authentication info")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        const data = await apiRequest("/api/auth/whoami");
+        if (options.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        console.log("\n🔐 Authentication Info");
+        console.log("─".repeat(40));
+        console.log(`Role:       ${data.role}`);
+        console.log(`Key ID:     ${data.keyId}`);
+        console.log(`Source:     ${data.source}`);
+        if (data.scopes && data.scopes.length > 0) {
+            console.log(`Scopes:     ${data.scopes.join(", ")}`);
+        }
+        console.log("");
+        console.log("Permissions:");
+        for (const perm of data.permissions) {
+            console.log(`  • ${perm}`);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("permissions")
+    .description("Show cached permissions (5-min cache)")
+    .option("--refresh", "Force refresh from API")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        if (options.refresh) {
+            clearPermissionsCache();
+        }
+        const perms = await getPermissions();
+        const cacheStatus = getCacheStatus();
+        if (options.json) {
+            console.log(JSON.stringify({
+                ...perms,
+                cache: cacheStatus,
+            }, null, 2));
+            return;
+        }
+        const cacheAge = cacheStatus.age ? Math.round(cacheStatus.age / 1000) : 0;
+        const expiresIn = cacheStatus.expiresIn ? Math.round(cacheStatus.expiresIn / 1000) : 0;
+        console.log("\n🔑 Cached Permissions");
+        console.log("─".repeat(50));
+        console.log(`Role:         ${perms.role}`);
+        console.log(`Cache age:    ${cacheAge}s (expires in ${expiresIn}s)`);
+        console.log("");
+        console.log("Permissions:");
+        for (const perm of perms.permissions) {
+            console.log(`  • ${perm}`);
+        }
+        if (perms.knowledgeBases.length > 0) {
+            console.log("");
+            console.log("Knowledge Bases:");
+            for (const kb of perms.knowledgeBases) {
+                console.log(`  • ${kb}`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("can <permission>")
+    .description("Check if current key has a specific permission")
+    .option("--json", "Output as JSON")
+    .action(async (permission, options) => {
+    try {
+        const allowed = await hasPermission(permission);
+        if (options.json) {
+            console.log(JSON.stringify({ permission, allowed }));
+            return;
+        }
+        if (allowed) {
+            console.log(`✅ Permission granted: ${permission}`);
+        }
+        else {
+            console.log(`❌ Permission denied: ${permission}`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("can-access-kb <kb>")
+    .description("Check if current key can access a knowledge base")
+    .option("--json", "Output as JSON")
+    .action(async (kb, options) => {
+    try {
+        const allowed = await canAccessKnowledgeBase(kb);
+        if (options.json) {
+            console.log(JSON.stringify({ knowledgeBase: kb, allowed }));
+            return;
+        }
+        if (allowed) {
+            console.log(`✅ Access granted to KB: ${kb}`);
+        }
+        else {
+            console.log(`❌ Access denied to KB: ${kb}`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("login")
+    .description("Create a session token for this agent")
+    .requiredOption("--agent <name>", "Agent name (must be registered in Firestore)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        const config = getConfig();
+        if (!config.apiUrl || !config.apiKey) {
+            console.error("API not configured. Run: husky config set api-url <url> && husky config set api-key <key>");
+            process.exit(1);
+        }
+        const url = new URL("/api/auth/session", config.apiUrl);
+        const res = await fetch(url.toString(), {
+            method: "POST",
+            headers: {
+                "x-api-key": config.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ agent: options.agent }),
+        });
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            if (res.status === 404) {
+                console.error(`Agent '${options.agent}' not found. Register the agent first.`);
+            }
+            else {
+                console.error(`Login failed: ${error.message || error.error || `HTTP ${res.status}`}`);
+            }
+            process.exit(1);
+        }
+        const session = await res.json();
+        setSessionConfig(session);
+        if (options.json) {
+            console.log(JSON.stringify({
+                success: true,
+                agent: session.agent,
+                role: session.role,
+                expiresAt: session.expiresAt,
+            }, null, 2));
+            return;
+        }
+        const expiresAt = new Date(session.expiresAt);
+        console.log("\n✅ Session created");
+        console.log("─".repeat(40));
+        console.log(`Agent:    ${session.agent}`);
+        console.log(`Role:     ${session.role}`);
+        console.log(`Expires:  ${expiresAt.toLocaleString()}`);
+        console.log("");
+        console.log("All API calls will now use this session token.");
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+authCommand
+    .command("logout")
+    .description("Clear the current session token")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    const session = getSessionConfig();
+    if (!session) {
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, message: "No active session" }));
+        }
+        else {
+            console.log("No active session to clear.");
+        }
+        return;
+    }
+    clearSessionConfig();
+    if (options.json) {
+        console.log(JSON.stringify({ success: true, agent: session.agent }));
+        return;
+    }
+    console.log(`✅ Session cleared for agent '${session.agent}'`);
+});
+authCommand
+    .command("session")
+    .description("Show current session status")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    const session = getSessionConfig();
+    if (!session || !session.token) {
+        if (options.json) {
+            console.log(JSON.stringify({ active: false }));
+        }
+        else {
+            console.log("No active session. Run: husky auth login --agent <name>");
+        }
+        return;
+    }
+    const expiresAt = session.expiresAt ? new Date(session.expiresAt) : null;
+    const now = new Date();
+    const isExpired = expiresAt ? expiresAt < now : true;
+    const expiresInMs = expiresAt ? expiresAt.getTime() - now.getTime() : 0;
+    const expiresInMinutes = Math.max(0, Math.floor(expiresInMs / 60000));
+    if (options.json) {
+        console.log(JSON.stringify({
+            active: !isExpired,
+            agent: session.agent,
+            role: session.role,
+            expiresAt: session.expiresAt,
+            expired: isExpired,
+            expiresInMinutes,
+        }, null, 2));
+        return;
+    }
+    console.log("\n🔐 Session Status");
+    console.log("─".repeat(40));
+    console.log(`Agent:    ${session.agent || "(unknown)"}`);
+    console.log(`Role:     ${session.role || "(unknown)"}`);
+    if (isExpired) {
+        console.log(`Status:   🔴 EXPIRED`);
+        console.log(`Expired:  ${expiresAt?.toLocaleString() || "(unknown)"}`);
+        console.log("");
+        console.log("Run: husky auth refresh --agent <name>");
+    }
+    else {
+        console.log(`Status:   🟢 ACTIVE`);
+        console.log(`Expires:  ${expiresAt?.toLocaleString()} (${expiresInMinutes} minutes)`);
+    }
+});
+authCommand
+    .command("refresh")
+    .description("Refresh the session token")
+    .option("--agent <name>", "Agent name (uses current session agent if not specified)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    try {
+        const config = getConfig();
+        if (!config.apiUrl || !config.apiKey) {
+            console.error("API not configured. Run: husky config set api-url <url> && husky config set api-key <key>");
+            process.exit(1);
+        }
+        const currentSession = getSessionConfig();
+        const agentName = options.agent || currentSession?.agent;
+        if (!agentName) {
+            console.error("No agent specified and no active session. Use: husky auth refresh --agent <name>");
+            process.exit(1);
+        }
+        const url = new URL("/api/auth/session", config.apiUrl);
+        const res = await fetch(url.toString(), {
+            method: "POST",
+            headers: {
+                "x-api-key": config.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ agent: agentName }),
+        });
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            console.error(`Refresh failed: ${error.message || error.error || `HTTP ${res.status}`}`);
+            process.exit(1);
+        }
+        const session = await res.json();
+        setSessionConfig(session);
+        if (options.json) {
+            console.log(JSON.stringify({
+                success: true,
+                agent: session.agent,
+                role: session.role,
+                expiresAt: session.expiresAt,
+            }, null, 2));
+            return;
+        }
+        const expiresAt = new Date(session.expiresAt);
+        console.log(`✅ Session refreshed for '${session.agent}' (expires: ${expiresAt.toLocaleString()})`);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});