@vertaaux/cli 0.2.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Digitaltableteur Tmi, trading as VertaaUX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -67,12 +67,27 @@ vertaa whoami
 
 | Command | Description |
 |---------|-------------|
-| `explain <finding-id>` | Show evidence bundle for a finding |
+| `explain [finding-id]` | AI-powered audit summary, or evidence for a specific finding |
 | `comment` | Generate PR comment from audit results |
 | `fix <job-id>` | Generate a fix patch for an issue |
 | `fix-all <job-id>` | Generate fix patches for all issues |
 | `verify` | Verify that a patch fixes an issue |
 
+### AI Intelligence
+
+| Command | Description |
+|---------|-------------|
+| `suggest <intent>` | Convert natural language to exact CLI command(s) |
+| `explain` | AI-powered audit summary (also: evidence for a single finding) |
+| `triage` | Prioritize findings into P0/P1/P2 buckets with effort estimates |
+| `fix-plan` | Structured remediation plan with ordered steps |
+| `patch-review` | Review a diff for safety (SAFE/UNSAFE/NEEDS_REVIEW verdict) |
+| `release-notes` | Generate developer + PM release notes from audit diff |
+| `compare` | Before/after audit narrative with score deltas (also: URL comparison) |
+| `doc` | Generate a Team Playbook from recurring findings |
+
+All AI commands require authentication (`vertaa login` or `VERTAAUX_API_KEY`). They accept input via stdin pipe, `--file`, or `--job`.
+
 ### Utility
 
 | Command | Description |
@@ -92,7 +107,7 @@ vertaa whoami
 |---------|-----------|
 | `a11y <url>` | Accessibility-focused audit (filters for a11y issues) |
 | `scan <url>` | UX scan (alias for audit) |
-| `compare <urlA> <urlB>` | Compare audits of two URLs |
+| `compare <urlA> <urlB>` | Compare audits of two URLs (also supports `--before`/`--after` for LLM-powered comparison) |
 
 ## Output Formats
 
@@ -105,6 +120,13 @@ Formats are **per-command**, not global. Each command supports a different set o
 | `explain` | `human`, `json` | `human` |
 | `policy show` | `json`, `yaml` | `yaml` |
 | `diff` | `human`, `json` | `human` |
+| `suggest` | `human`, `json` | `human` |
+| `triage` | `human`, `json` | `human` |
+| `fix-plan` | `human`, `json` | `human` |
+| `patch-review` | `human`, `json` | `human` |
+| `release-notes` | `human`, `json`, `markdown` | `markdown` |
+| `compare` | `human`, `json` | `human` |
+| `doc` | `json`, `markdown` | `markdown` |
 
 Usage:
 
@@ -146,6 +168,37 @@ vertaa audit https://example.com --format json | jq '.data.scores'
 vertaa audit https://example.com --format json > results.json
 ```
 
+### Pipeline Examples
+
+Chain commands with Unix pipes for powerful workflows:
+
+```bash
+# Audit and get an AI-powered summary
+vertaa audit https://example.com --json | vertaa explain
+
+# Audit and explain with full evidence per issue
+vertaa audit https://example.com --json | vertaa explain --verbose
+
+# Audit, triage, and get a fix plan
+vertaa audit https://example.com --json | vertaa triage --verbose
+vertaa audit https://example.com --json | vertaa fix-plan --json
+
+# Review a PR diff for safety against audit findings
+gh pr diff 123 | vertaa patch-review --job <audit-job-id>
+
+# Generate release notes from a diff between two audits
+vertaa diff --job-a abc --job-b def --json | vertaa release-notes
+
+# Compare two audit snapshots with LLM narrative
+vertaa compare --before baseline.json --after current.json
+
+# Convert natural language to a CLI command
+vertaa suggest "check contrast on my site"
+
+# Generate a team playbook from audit findings
+vertaa audit https://example.com --json | vertaa doc --team "Frontend"
+```
+
 ## Global Options
 
 These options work with any command:
@@ -157,6 +210,9 @@ These options work with any command:
 | `-q, --quiet` | Suppress banner and non-essential output |
 | `--no-banner` | Hide the V-mark banner |
 | `--machine` | Strict machine-readable output mode |
+| `--dry-run` | Show what would happen without executing |
+| `-y, --yes` | Auto-confirm all interactive prompts |
+| `--verbose` | Expand output with additional details |
 | `-v, --version` | Show version number |
 | `-h, --help` | Show help for command |
 

package/dist/auth/device-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CA6B3B"}

package/dist/auth/device-flow.js

@@ -6,7 +6,7 @@
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8628
  */
-import ora from "ora";
+import { createSpinner, succeedSpinner } from "../ui/spinner.js";
 /**
  * Format remaining time as MM:SS.
  */
@@ -50,6 +50,7 @@ export async function startDeviceFlow(clientId, authBase = DEFAULT_AUTH_BASE) {
         console.log(`  Or open: ${deviceCodeResponse.verification_uri_complete}`);
         console.log("\n");
     }
+    console.log("  Press Ctrl+C to cancel.\n");
     // Step 3: Poll for token with countdown
     const tokens = await pollForToken(clientId, deviceCodeResponse.device_code, deviceCodeResponse.interval, deviceCodeResponse.expires_in, authBase);
     return tokens;
@@ -83,13 +84,20 @@ async function pollForToken(clientId, deviceCode, intervalSeconds, expiresInSeco
     const startTime = Date.now();
     const timeoutMs = Math.min(expiresInSeconds, DEFAULT_TIMEOUT_SECONDS) * 1000;
     let interval = intervalSeconds * 1000; // Convert to milliseconds
+    let cancelled = false;
+    // Handle Ctrl+C gracefully
+    const onSigint = () => {
+        cancelled = true;
+    };
+    process.on("SIGINT", onSigint);
     // Start spinner with countdown
-    const spinner = ora({
-        text: `Waiting for authorization... (${formatRemaining(Math.round(timeoutMs / 1000))} remaining)`,
-        stream: process.stderr,
-    }).start();
+    const spinner = createSpinner(`Waiting for authorization... (${formatRemaining(Math.round(timeoutMs / 1000))} remaining)`);
+    spinner.start();
     try {
         while (true) {
+            if (cancelled) {
+                throw new Error("Login cancelled.");
+            }
             // Check timeout
             const elapsed = Date.now() - startTime;
             const remaining = Math.max(0, timeoutMs - elapsed);
@@ -97,9 +105,12 @@ async function pollForToken(clientId, deviceCode, intervalSeconds, expiresInSeco
                 throw new Error("Authorization timed out. Please try again.");
             }
             // Update spinner with countdown
-            spinner.text = `Waiting for authorization... (${formatRemaining(Math.ceil(remaining / 1000))} remaining)`;
-            // Wait for poll interval
-            await sleep(interval);
+            spinner.setText(`Waiting for authorization... (${formatRemaining(Math.ceil(remaining / 1000))} remaining)`);
+            // Wait for poll interval (cancellable)
+            await sleep(interval, () => cancelled);
+            if (cancelled) {
+                throw new Error("Login cancelled.");
+            }
             // Poll token endpoint
             const response = await fetch(url, {
                 method: "POST",
@@ -115,7 +126,7 @@ async function pollForToken(clientId, deviceCode, intervalSeconds, expiresInSeco
             // Success
             if (response.ok) {
                 const tokens = (await response.json());
-                spinner.succeed("Authorization successful!");
+                succeedSpinner(spinner, "Authorization successful!");
                 return {
                     accessToken: tokens.access_token,
                     refreshToken: tokens.refresh_token,
@@ -142,15 +153,36 @@ async function pollForToken(clientId, deviceCode, intervalSeconds, expiresInSeco
         }
     }
     finally {
-        // Ensure spinner is stopped
-        if (spinner.isSpinning) {
+        process.removeListener("SIGINT", onSigint);
+        if (spinner.isRunning) {
             spinner.stop();
         }
     }
 }
 /**
- * Sleep for specified milliseconds.
+ * Sleep for specified milliseconds, with early cancellation support.
  */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, isCancelled) {
+    return new Promise((resolve) => {
+        if (isCancelled?.()) {
+            resolve();
+            return;
+        }
+        let check;
+        const timer = setTimeout(() => {
+            if (check)
+                clearInterval(check);
+            resolve();
+        }, ms);
+        // Check cancellation every 200ms to respond quickly to Ctrl+C
+        if (isCancelled) {
+            check = setInterval(() => {
+                if (isCancelled()) {
+                    clearTimeout(timer);
+                    clearInterval(check);
+                    resolve();
+                }
+            }, 200);
+        }
+    });
 }

package/dist/commands/audit.d.ts

@@ -47,9 +47,11 @@ export interface AuditCommandOptions {
     noCache?: boolean;
     cacheDir?: string;
     jsonLogs?: boolean;
+    explain?: boolean;
     base?: string;
     quiet?: boolean;
     machine?: boolean;
+    dashboard?: boolean;
 }
 /**
  * Register the audit command with the Commander program.

package/dist/commands/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8EpC,MAAM,WAAW,mBAAmB;IAElC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAG5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,WAAW,CAAC,EAAE,OAAO,CAAC;IAGtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IAGvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAGhB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IAGvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IAGvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAGnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4tBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiT3D"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyFpC,MAAM,WAAW,mBAAmB;IAElC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAG5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,WAAW,CAAC,EAAE,OAAO,CAAC;IAGtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IAGvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAGhB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IAGvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IAGvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAGnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAGlB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAu4BD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkT3D"}

package/dist/commands/audit.js

@@ -14,7 +14,9 @@ import { resolveApiBase, getApiKey, apiRequest, waitForAudit, } from "../utils/c
 import { createOutput, formatSarif, formatAuditHtml } from "../output/factory.js";
 import { createEnvelope, writeJsonOutput, writeOutput as writeStdout } from "../output/envelope.js";
 import { resolveCommandFormat } from "../output/formats.js";
+import { getVersion } from "../ui/banner.js";
 import { createSpinner, updateSpinner, succeedSpinner, failSpinner, } from "../ui/spinner.js";
+import { createRenderer, createKeyboardHandler, AuditPhase, phaseIndex, phaseTotal, } from "@vertaaux/tui";
 import { runFixWizard } from "../interactive/fix-wizard.js";
 import { isInteractive } from "../interactive/prompts.js";
 import { evaluateQualityGate, DEFAULT_QUALITY_GATE_CONFIG, } from "../quality-gate/index.js";
@@ -29,7 +31,6 @@ import semver from "semver";
 // Artifact directory
 const ARTIFACTS_DIR = ".vertaaux/artifacts";
 // CLI version for policy version requirements (read from package.json)
-import { getVersion } from "../ui/banner.js";
 const CLI_VERSION = getVersion();
 /**
  * Detect current branch from CI environment or git.
@@ -385,12 +386,31 @@ async function executeAudit(targetUrl, options, config) {
     const format = validatedFormat;
     const formatter = createOutput(format);
     const groupBy = options.groupBy || config.output?.groupBy || "severity";
-    // Create spinner for progress (only in TTY mode with wait)
-    const spinner = wait && isTTY() && !quiet
+    // Determine UI mode: dashboard (full-screen) vs spinner (inline)
+    const useDashboard = wait && !quiet && !machineMode && options.dashboard !== false;
+    const useSpinner = wait && isTTY() && !quiet && !useDashboard;
+    // Create dashboard renderer or fallback spinner
+    let renderer = null;
+    let keyboard = null;
+    let aborted = false;
+    const spinner = useSpinner
         ? createSpinner(`Auditing ${targetUrl}...`)
         : null;
+    if (useDashboard) {
+        renderer = createRenderer("auto");
+        keyboard = createKeyboardHandler();
+        keyboard.on("quit", () => {
+            aborted = true;
+            renderer?.dispose();
+            keyboard?.dispose();
+            process.stderr.write("\nAudit aborted by user.\n");
+            process.exitCode = ExitCode.ERROR;
+        });
+        keyboard.start();
+    }
+    const auditStartTime = Date.now();
     try {
-        // Start spinner
+        // Start spinner (dashboard renders on first update)
         spinner?.start();
         // Create audit job
         const created = await apiRequest(base, "/audit", {
@@ -400,6 +420,8 @@ async function executeAudit(targetUrl, options, config) {
         // If not waiting, just output the job info
         if (!wait) {
             spinner?.stop();
+            renderer?.dispose();
+            keyboard?.dispose();
             if (format === "json") {
                 if (options.output) {
                     const output = JSON.stringify(createEnvelope(created, "audit"), null, 2);
@@ -429,12 +451,45 @@ async function executeAudit(targetUrl, options, config) {
         if (!created.job_id) {
             throw new Error("Audit response missing job_id");
         }
-        const result = await waitForAudit(base, created.job_id, timeout, interval, apiKey, (progress) => {
+        const result = await waitForAudit(base, created.job_id, timeout, interval, apiKey, (progress, status) => {
+            if (aborted)
+                return;
+            if (renderer) {
+                const phase = mapStatusToPhase(status);
+                const state = {
+                    phase,
+                    phaseIndex: phaseIndex(phase),
+                    phaseTotal: phaseTotal(),
+                    url: targetUrl,
+                    mode,
+                    progress: { audit: progress },
+                    totals: { audit: 100 },
+                    issueCount: 0,
+                    scorePreview: null,
+                    verbose: false,
+                    elapsed: Date.now() - auditStartTime,
+                };
+                renderer.update(state);
+            }
             if (spinner) {
                 updateSpinner(spinner, `Auditing ${targetUrl}`, progress, 100);
             }
         });
-        // Stop spinner with success
+        // Finish dashboard or spinner
+        if (renderer) {
+            const overallScore = getOverallScoreFromResult(result);
+            const summaryResult = {
+                url: targetUrl,
+                mode,
+                overallScore: overallScore ?? 0,
+                scores: extractNumericScores(result.scores),
+                issueCount: countTotalIssues(result.issues),
+                passed: (overallScore ?? 0) >= 70,
+                elapsed: Date.now() - auditStartTime,
+            };
+            renderer.finish(summaryResult);
+            keyboard?.dispose();
+        }
         if (spinner) {
             succeedSpinner(spinner, `Audit complete: ${targetUrl}`);
         }
@@ -548,6 +603,41 @@ async function executeAudit(targetUrl, options, config) {
                 writeStdout(output);
             }
         }
+        // Inline AI explanation (--explain flag, PROG-04)
+        if (options.explain && issues.length > 0) {
+            try {
+                const explainBase = resolveApiBase(options.base);
+                const explainKey = getApiKey(config.apiKey);
+                const explainIssues = issues.map((i) => ({
+                    id: i.id || null,
+                    title: i.title || i.description || null,
+                    description: i.description || null,
+                    severity: i.severity || null,
+                    category: i.category || null,
+                    selector: i.selector || null,
+                    wcag_reference: i.wcag_reference || null,
+                    recommendation: i.recommendation || i.recommended_fix || null,
+                }));
+                const explainPayload = {
+                    job_id: result.job_id || null,
+                    url: targetUrl || null,
+                    scores: result.scores || null,
+                    issues: explainIssues,
+                };
+                const explainSpinner = createSpinner("Generating AI explanation...");
+                const explainResponse = await apiRequest(explainBase, "/cli/ai/explain", { method: "POST", body: { audit: explainPayload } }, explainKey);
+                succeedSpinner(explainSpinner, "Explanation ready");
+                console.error("");
+                console.error(chalk.bold("AI Explanation"));
+                console.error(chalk.dim("─".repeat(40)));
+                for (const bullet of explainResponse.data.summary) {
+                    console.error(`  ${chalk.cyan("*")} ${bullet}`);
+                }
+            }
+            catch (explainErr) {
+                console.error(chalk.dim(`\n(AI explanation unavailable: ${explainErr instanceof Error ? explainErr.message : String(explainErr)})`));
+            }
+        }
         // Output quality gate result
         if (!quiet) {
             console.error(""); // Blank line before gate result
@@ -595,13 +685,81 @@ async function executeAudit(targetUrl, options, config) {
         }
     }
     catch (error) {
-        // Stop spinner with failure
+        // Stop dashboard or spinner with failure
+        renderer?.dispose();
+        keyboard?.dispose();
         if (spinner) {
             failSpinner(spinner, `Audit failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         throw error;
     }
 }
+/**
+ * Map API audit status to TUI phase name.
+ */
+function mapStatusToPhase(status) {
+    switch (status) {
+        case "queued":
+        case "pending":
+            return AuditPhase.Connecting;
+        case "crawling":
+            return AuditPhase.Crawling;
+        case "running":
+        case "analyzing":
+            return AuditPhase.Analyzing;
+        case "scoring":
+            return AuditPhase.Scoring;
+        case "completed":
+            return AuditPhase.Done;
+        case "failed":
+            return AuditPhase.Failed;
+        default:
+            return AuditPhase.Analyzing;
+    }
+}
+/**
+ * Extract overall score from audit result.
+ */
+function getOverallScoreFromResult(result) {
+    if (!result.scores)
+        return null;
+    const scores = result.scores;
+    const direct = scores.overall ?? scores.ux ?? scores.total;
+    if (typeof direct === "number" && Number.isFinite(direct))
+        return direct;
+    const numeric = Object.values(scores)
+        .filter((v) => typeof v === "number" && Number.isFinite(v));
+    if (numeric.length === 0)
+        return null;
+    return Math.round(numeric.reduce((a, b) => a + b, 0) / numeric.length);
+}
+/**
+ * Extract numeric scores from result scores object.
+ */
+function extractNumericScores(scores) {
+    if (!scores)
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(scores)) {
+        if (typeof value === "number" && key !== "overall") {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Count total issues from various result formats.
+ */
+function countTotalIssues(issues) {
+    if (Array.isArray(issues))
+        return issues.length;
+    if (issues && typeof issues === "object") {
+        return Object.values(issues)
+            .flatMap((v) => (Array.isArray(v) ? v : []))
+            .length;
+    }
+    return 0;
+}
 /**
  * Register the audit command with the Commander program.
  */
@@ -615,7 +773,7 @@ export function registerAuditCommand(program) {
         .option("--routes <routes>", "Comma-separated list of routes to audit")
         .option("--auth-profile <profile>", "Authentication profile for protected pages")
         .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
-        .option("--format <format>", "Output format: json|sarif|junit|html|human|auto")
+        .option("--format <format>", "Output format: json|sarif|junit|html|human (default: human in terminal, auto-detected in CI)")
         .option("-o, --output <path>", "Output file path")
         .option("--group-by <field>", "Group issues by: severity|category|route", parseGroupBy)
         .option("--wait", "Wait for audit completion (default)")
@@ -660,6 +818,7 @@ export function registerAuditCommand(program) {
         .option("--json-logs", "Output structured JSON logs for CI")
         // Policy options (CICD-17)
         .option("--policy <file>", "Path to policy file (default: auto-detect vertaa.policy.yml)")
+        .option("--explain", "Append AI explanation to audit results")
         .action(async (urlArg, cmdOptions, command) => {
         try {
             // Initialize structured logger

package/dist/commands/client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Client management commands for VertaaUX CLI.
+ *
+ * Provides agency client CRUD operations and batch auditing
+ * across client URL portfolios with bounded concurrency.
+ *
+ * Implements 46-06: CLI client management and batch audit.
+ */
+import { Command } from "commander";
+/**
+ * Register the client command with the Commander program.
+ */
+export declare function registerClientCommand(program: Command): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/commands/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/commands/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0HpC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwX5D"}