@vertaaux/cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -2,16 +2,18 @@
 /**
  * VertaaUX CLI - UX audits, accessibility checks, and CI gating.
  *
- * Refactored to use Commander.js for command parsing with config file support.
- * Maintains backward compatibility with existing command syntax.
+ * Slim entry point: sets up Commander.js program and delegates to command modules.
+ * Legacy commands (a11y, scan, status, fix, fix-all, verify) are in commands/.
+ * Modern commands are registered via registerXCommand() from commands/*.
  */
 import dotenv from "dotenv";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { Command } from "commander";
-import { setColorEnabled, shouldUseColor } from "@vertaaux/tui";
-import { showBanner, getVersion } from "./ui/banner.js";
+import { setColorEnabled, shouldUseColor, setPlainMode, renderError, setSymbolTier, detectSymbolTier } from "@vertaaux/tui";
+import { animateBanner, getVersion } from "./ui/banner.js";
+// Modern command registrations
 import { registerAuditCommand } from "./commands/audit.js";
 import { registerBaselineCommand } from "./commands/baseline.js";
 import { registerCommentCommand } from "./commands/comment.js";
@@ -30,10 +32,45 @@ import { registerPatchReviewCommand } from "./commands/patch-review.js";
 import { registerCompareCommand } from "./commands/compare.js";
 import { registerReleaseNotesCommand } from "./commands/release-notes.js";
 import { registerDocCommand } from "./commands/doc.js";
+// Legacy command registrations (backward compat)
+import { registerA11yCommand } from "./commands/a11y.js";
+import { registerScanCommand } from "./commands/scan.js";
+import { registerStatusCommand } from "./commands/status.js";
+import { registerFixCommand } from "./commands/fix.js";
+import { registerFixAllCommand } from "./commands/fix-all.js";
+import { registerVerifyCommand } from "./commands/verify.js";
 import { ExitCode } from "./utils/exit-codes.js";
 import { formatCommanderError } from "./ui/diagnostics.js";
-import { parseMode, parseTimeout, parseInterval, parseScore } from "./utils/validators.js";
-import { isInteractive, selectAction } from "./interactive/prompts.js";
+import { isInteractive } from "./interactive/prompts.js";
+import { InteractiveApp } from "./app/interactive-app.js";
+import { MenuView } from "./app/menu/menu-view.js";
+// HelpOverlayView is toggled by InteractiveApp's global H key handler
+// import { HelpOverlayView } from "./app/views/help-overlay.js";
+import { CommandRunnerView } from "./app/views/command-runner.js";
+import { recordRecent } from "./app/menu/recent.js";
+// Detect best symbol tier for this terminal (nerd > unicode > ascii)
+setSymbolTier(detectSymbolTier());
+// ============================================================================
+// Global error handlers — installed before anything else runs
+// Ensures no user ever sees a raw Node.js stack trace
+// ============================================================================
+process.on("uncaughtException", (err) => {
+    process.stderr.write(renderError({
+        message: err.message || "An unexpected error occurred",
+        suggestion: "vertaa doctor",
+        exitCode: ExitCode.ERROR,
+    }) + "\n");
+    process.exit(ExitCode.ERROR);
+});
+process.on("unhandledRejection", (reason) => {
+    const message = reason instanceof Error ? reason.message : String(reason);
+    process.stderr.write(renderError({
+        message,
+        suggestion: "vertaa doctor",
+        exitCode: ExitCode.ERROR,
+    }) + "\n");
+    process.exit(ExitCode.ERROR);
+});
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Load environment variables from multiple locations
@@ -45,8 +82,10 @@ const envCandidates = [
     path.resolve(__dirname, "../../.env.local"),
     path.resolve(__dirname, "../../.env"),
 ];
-// Silence any dotenv stdout output during loading
+// Silence any dotenv stdout output during loading.
+// eslint-disable-next-line no-console -- intentional: monkey-patching console.log to suppress dotenv banner output from a third-party lib
 const originalLog = console.log;
+// eslint-disable-next-line no-console -- intentional: temporarily replacing console.log to filter dotenv's [dotenv@x.y.z] banners
 console.log = (...args) => {
     const msg = String(args[0] || "");
     if (msg.includes("[dotenv"))
@@ -58,805 +97,8 @@ for (const candidate of envCandidates) {
         dotenv.config({ path: candidate, override: false });
     }
 }
+// eslint-disable-next-line no-console -- intentional: restoring original console.log after dotenv suppression
 console.log = originalLog;
-const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
-// ============================================================================
-// Legacy helper functions (kept for backward compatibility with other commands)
-// ============================================================================
-function parseArgs(args) {
-    const positional = [];
-    const flags = {};
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--") {
-            positional.push(...args.slice(i + 1));
-            break;
-        }
-        if (arg.startsWith("--")) {
-            const [rawKey, rawValue] = arg.slice(2).split("=", 2);
-            if (rawValue !== undefined) {
-                flags[rawKey] = rawValue;
-                continue;
-            }
-            const next = args[i + 1];
-            if (next && !next.startsWith("-")) {
-                flags[rawKey] = next;
-                i += 1;
-            }
-            else {
-                flags[rawKey] = true;
-            }
-            continue;
-        }
-        if (arg.startsWith("-") && arg.length > 1) {
-            const key = arg.slice(1);
-            if (key === "u") {
-                const next = args[i + 1];
-                if (next && !next.startsWith("-")) {
-                    flags.url = next;
-                    i += 1;
-                }
-                else {
-                    flags.url = true;
-                }
-                continue;
-            }
-            if (key === "b") {
-                const next = args[i + 1];
-                if (next && !next.startsWith("-")) {
-                    flags.base = next;
-                    i += 1;
-                }
-                else {
-                    flags.base = true;
-                }
-                continue;
-            }
-            if (key === "f") {
-                const next = args[i + 1];
-                if (next && !next.startsWith("-")) {
-                    flags.format = next;
-                    i += 1;
-                }
-                else {
-                    flags.format = true;
-                }
-                continue;
-            }
-            if (key === "h") {
-                flags.help = true;
-                continue;
-            }
-            if (key === "q") {
-                flags.quiet = true;
-                continue;
-            }
-            const next = args[i + 1];
-            if (next && !next.startsWith("-")) {
-                flags[key] = next;
-                i += 1;
-            }
-            else {
-                flags[key] = true;
-            }
-            continue;
-        }
-        positional.push(arg);
-    }
-    return { positional, flags };
-}
-function getString(flags, key) {
-    const value = flags[key];
-    if (typeof value === "string")
-        return value;
-    // Fallback: try camelCase version (Commander.js converts --multi-word to multiWord)
-    const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-    if (camelKey !== key) {
-        const camelValue = flags[camelKey];
-        if (typeof camelValue === "string")
-            return camelValue;
-    }
-    return undefined;
-}
-function getBool(flags, key) {
-    if (flags[key] === true)
-        return true;
-    // Fallback: try camelCase version (Commander.js converts --multi-word to multiWord)
-    const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-    if (camelKey !== key)
-        return flags[camelKey] === true;
-    return false;
-}
-function getNumber(flags, key) {
-    const raw = getString(flags, key);
-    if (raw === undefined)
-        return undefined;
-    const parsed = Number(raw);
-    if (Number.isNaN(parsed)) {
-        throw new Error(`Invalid --${key} value: ${raw}`);
-    }
-    return parsed;
-}
-function resolveFormat(flags) {
-    if (getBool(flags, "json"))
-        return "json";
-    if (getBool(flags, "md") || getBool(flags, "markdown"))
-        return "md";
-    const raw = getString(flags, "format") || "json";
-    if (raw === "md" || raw === "markdown")
-        return "md";
-    return "json";
-}
-function resolveApiBase(flags) {
-    const raw = getString(flags, "base") || process.env.VERTAAUX_API_BASE || DEFAULT_API_BASE;
-    return raw.replace(/\/$/, "");
-}
-function getApiKey() {
-    const key = process.env.VERTAAUX_API_KEY;
-    if (!key) {
-        throw new Error("VERTAAUX_API_KEY is required");
-    }
-    return key;
-}
-async function apiRequest(base, reqPath, options) {
-    const apiKey = getApiKey();
-    const url = `${base}${reqPath}`;
-    const res = await fetch(url, {
-        method: options.method,
-        headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": apiKey,
-        },
-        body: options.body ? JSON.stringify(options.body) : undefined,
-    });
-    if (!res.ok) {
-        let detail = res.statusText;
-        try {
-            const data = (await res.json());
-            detail =
-                (data && (data.error || data.message)) ||
-                    JSON.stringify(data) ||
-                    detail;
-        }
-        catch {
-            try {
-                detail = await res.text();
-            }
-            catch {
-                // ignore
-            }
-        }
-        throw new Error(`HTTP ${res.status}: ${detail}`);
-    }
-    return (await res.json().catch(() => ({})));
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function waitForAudit(base, jobId, timeoutMs, intervalMs) {
-    const start = Date.now();
-    while (true) {
-        const status = await apiRequest(base, `/audit/${jobId}`, {
-            method: "GET",
-        });
-        if (status.status === "completed")
-            return status;
-        if (status.status === "failed")
-            return status;
-        if (Date.now() - start > timeoutMs) {
-            throw new Error(`Timed out waiting for audit ${jobId}`);
-        }
-        await sleep(intervalMs);
-    }
-}
-function normalizeIssues(issues) {
-    if (Array.isArray(issues))
-        return issues;
-    if (issues && typeof issues === "object") {
-        const values = Object.values(issues);
-        return values.flatMap((value) => (Array.isArray(value) ? value : []));
-    }
-    return [];
-}
-function toNumber(value) {
-    if (typeof value === "number" && Number.isFinite(value))
-        return value;
-    return null;
-}
-function getOverallScore(scores) {
-    if (!scores)
-        return null;
-    const direct = toNumber(scores.overall ?? scores.ux ?? scores.total);
-    if (direct !== null)
-        return direct;
-    const numeric = Object.values(scores)
-        .map((value) => toNumber(value))
-        .filter((value) => value !== null);
-    if (numeric.length === 0)
-        return null;
-    const avg = numeric.reduce((sum, value) => sum + value, 0) / numeric.length;
-    return Math.round(avg);
-}
-function getCategoryScore(scores, key) {
-    if (!scores)
-        return null;
-    return toNumber(scores[key]);
-}
-function formatScoresTable(scores) {
-    if (!scores)
-        return "No scores available.";
-    const entries = Object.entries(scores).filter(([, value]) => typeof value === "number");
-    if (entries.length === 0)
-        return "No scores available.";
-    const lines = ["| Category | Score |", "| --- | --- |"];
-    for (const [key, value] of entries) {
-        lines.push(`| ${key} | ${value} |`);
-    }
-    return lines.join("\n");
-}
-function formatIssuesList(issues, limit = 5) {
-    if (!issues.length)
-        return "No issues.";
-    const lines = issues.slice(0, limit).map((issue, index) => {
-        const label = issue.title || issue.id || "Issue";
-        const severity = issue.severity ? issue.severity.toUpperCase() : "INFO";
-        return `${index + 1}. [${severity}] ${label}`;
-    });
-    if (issues.length > limit) {
-        lines.push(`...and ${issues.length - limit} more`);
-    }
-    return lines.join("\n");
-}
-function formatAuditMarkdown(result) {
-    const status = result.status || "unknown";
-    const lines = [`## Audit Results`, `- Status: ${status}`];
-    if (result.job_id)
-        lines.push(`- Job ID: ${result.job_id}`);
-    if (result.url)
-        lines.push(`- URL: ${result.url}`);
-    if (result.mode)
-        lines.push(`- Mode: ${result.mode}`);
-    if (typeof result.progress === "number" && status !== "completed") {
-        lines.push(`- Progress: ${result.progress}%`);
-    }
-    if (status !== "completed")
-        return lines.join("\n");
-    const overall = getOverallScore(result.scores);
-    if (overall !== null)
-        lines.push(`- Overall score: ${overall}`);
-    lines.push("\n### Scores");
-    lines.push(formatScoresTable(result.scores));
-    const issues = normalizeIssues(result.issues);
-    lines.push("\n### Issues");
-    lines.push(`Total issues: ${issues.length}`);
-    lines.push(formatIssuesList(issues));
-    return lines.join("\n");
-}
-function formatA11yMarkdown(result) {
-    const lines = [`## Accessibility Audit`, `- Status: ${result.status || "unknown"}`];
-    if (result.url)
-        lines.push(`- URL: ${result.url}`);
-    if (result.mode)
-        lines.push(`- Mode: ${result.mode}`);
-    if (result.status !== "completed")
-        return lines.join("\n");
-    const a11yScore = getCategoryScore(result.scores, "accessibility");
-    if (a11yScore !== null)
-        lines.push(`- Accessibility score: ${a11yScore}`);
-    const issues = normalizeIssues(result.issues).filter((issue) => {
-        const category = (issue.category || "").toLowerCase();
-        return (category.includes("accessibility") ||
-            category.includes("a11y") ||
-            category.includes("wcag"));
-    });
-    lines.push("\n### Accessibility Issues");
-    lines.push(`Total accessibility issues: ${issues.length}`);
-    lines.push(formatIssuesList(issues));
-    return lines.join("\n");
-}
-function formatCompareMarkdown(compare) {
-    const lines = ["## Audit Comparison"];
-    lines.push(`- URL A: ${compare.urlA}`);
-    lines.push(`- URL B: ${compare.urlB}`);
-    lines.push(`- Job A: ${compare.jobA}`);
-    lines.push(`- Job B: ${compare.jobB}`);
-    lines.push("\n### Overall Scores");
-    lines.push("| Site | Score | Delta |");
-    lines.push("| --- | --- | --- |");
-    lines.push(`| A | ${compare.overallA ?? "n/a"} | ${compare.delta ?? "n/a"} |`);
-    lines.push(`| B | ${compare.overallB ?? "n/a"} | ${compare.delta ?? "n/a"} |`);
-    lines.push("\n### Category Scores");
-    lines.push("| Category | A | B | Delta |");
-    lines.push("| --- | --- | --- | --- |");
-    for (const [key, values] of Object.entries(compare.categoryDeltas)) {
-        lines.push(`| ${key} | ${values.a ?? "n/a"} | ${values.b ?? "n/a"} | ${values.delta ?? "n/a"} |`);
-    }
-    lines.push("\n### Issue Counts");
-    lines.push(`- A: ${compare.issuesA}`);
-    lines.push(`- B: ${compare.issuesB}`);
-    return lines.join("\n");
-}
-function formatExplainMarkdown(issue) {
-    const lines = ["## Issue Explanation"];
-    if (issue.id)
-        lines.push(`- ID: ${issue.id}`);
-    if (issue.severity)
-        lines.push(`- Severity: ${issue.severity}`);
-    if (issue.category)
-        lines.push(`- Category: ${issue.category}`);
-    if (issue.selector)
-        lines.push(`- Selector: ${issue.selector}`);
-    if (issue.description) {
-        lines.push("\n### Description");
-        lines.push(issue.description);
-    }
-    const recommendation = issue.recommendation || issue.recommended_fix;
-    if (recommendation) {
-        lines.push("\n### Recommendation");
-        lines.push(recommendation);
-    }
-    if (issue.wcag_reference) {
-        lines.push("\n### WCAG Reference");
-        lines.push(issue.wcag_reference);
-    }
-    return lines.join("\n");
-}
-function formatPatchMarkdown(patch) {
-    if (!patch)
-        return "No patch generated.";
-    const lines = [
-        "## Patch Generated",
-        "",
-        `**Confidence:** ${patch.confidence.label} (${patch.confidence.percentage}%)`,
-        `**Classification:** ${patch.classification}`,
-        "",
-        "### Explanation",
-        patch.explanation,
-        "",
-        "### Search",
-        "```",
-        patch.search,
-        "```",
-        "",
-        "### Replace",
-        "```",
-        patch.replace,
-        "```",
-    ];
-    return lines.join("\n");
-}
-function formatVerifyMarkdown(result) {
-    if (!result.success || !result.verification) {
-        return `## Verification Failed\n\n${result.error?.message || "Unknown error"}`;
-    }
-    const v = result.verification;
-    const deltaSign = v.score_delta.delta >= 0 ? "+" : "";
-    const lines = [
-        "## Verification Result",
-        "",
-        `**Issue Fixed:** ${v.issue_fixed ? "Yes" : "No"}`,
-        `**Score Delta:** ${v.score_delta.before} -> ${v.score_delta.after} (${deltaSign}${v.score_delta.delta})`,
-        `**Component:** ${v.component_audited}`,
-        `**Duration:** ${v.duration_ms}ms`,
-    ];
-    if (v.regressions.length > 0) {
-        lines.push("", "### Regressions");
-        for (const r of v.regressions) {
-            lines.push(`- [${r.impact.toUpperCase()}] ${r.rule_id}: ${r.description}`);
-        }
-    }
-    else {
-        lines.push("", "### Regressions", "None");
-    }
-    if (v.error) {
-        lines.push("", `**Warning:** ${v.error}`);
-    }
-    return lines.join("\n");
-}
-// Auto-fixable issue types (from lib/patch/classifier.ts)
-const AUTO_FIXABLE_TYPES = new Set([
-    "label",
-    "input-missing-label",
-    "form-field-label",
-    "button-name",
-    "missing-button-name",
-    "link-name",
-    "html-has-lang",
-    "missing-lang-attribute",
-    "html-lang-valid",
-    "document-title",
-    "bypass",
-    "region",
-    "landmark-one-main",
-    "color-contrast",
-    "autocomplete-valid",
-    "aria-required-attr",
-    "aria-valid-attr",
-    "aria-valid-attr-value",
-]);
-function isAutoFixable(issueType) {
-    const normalized = issueType.toLowerCase().replace(/^(axe|wcag)-/, "");
-    return AUTO_FIXABLE_TYPES.has(normalized);
-}
-function formatBatchMarkdown(results) {
-    const lines = [
-        "## Batch Patch Results",
-        "",
-        `**Total Requested:** ${results.totalRequested}`,
-        `**Succeeded:** ${results.successes.length}`,
-        `**Failed:** ${results.failures.length}`,
-        `**Skipped:** ${results.totalSkipped}`,
-    ];
-    if (results.successes.length > 0) {
-        lines.push("", "### Successful Patches");
-        for (const s of results.successes) {
-            const conf = s.patch?.confidence;
-            const cls = s.patch?.classification || "unknown";
-            const confStr = conf ? `${conf.label} (${conf.percentage}%)` : "n/a";
-            lines.push(`- ${s.issueId}: ${confStr} [${cls}]`);
-        }
-    }
-    if (results.failures.length > 0) {
-        lines.push("", "### Failed");
-        for (const f of results.failures) {
-            const details = f.details ? ` - ${f.details}` : "";
-            lines.push(`- ${f.issueId}: ${f.reason}${details}`);
-        }
-    }
-    return lines.join("\n");
-}
-function printOutput(format, data, markdown) {
-    if (format === "md") {
-        console.log(markdown || "");
-        return;
-    }
-    console.log(JSON.stringify(data, null, 2));
-}
-// ============================================================================
-// Legacy command handlers (a11y, scan, compare, status, explain, fix, etc.)
-// ============================================================================
-async function runAuditCommand(base, url, flags, label) {
-    const mode = getString(flags, "mode") || "basic";
-    const timeout = getNumber(flags, "timeout");
-    const userAgent = getString(flags, "user-agent");
-    const engineVersion = getString(flags, "engine-version");
-    const failOnScore = getNumber(flags, "fail-on-score");
-    const created = await apiRequest(base, "/audit", {
-        method: "POST",
-        body: {
-            url,
-            mode,
-            timeout,
-            user_agent: userAgent,
-            engine_version: engineVersion,
-            fail_on_score: failOnScore,
-        },
-    });
-    const format = resolveFormat(flags);
-    if (!getBool(flags, "wait")) {
-        const markdown = `## Audit queued\n- Job ID: ${created.job_id}\n- URL: ${created.url}\n- Mode: ${created.mode}`;
-        printOutput(format, created, markdown);
-        return;
-    }
-    if (!created.job_id) {
-        throw new Error("Audit response missing job_id");
-    }
-    const waitTimeout = getNumber(flags, "timeout") || 60000;
-    const interval = getNumber(flags, "interval") || 5000;
-    const result = await waitForAudit(base, created.job_id, waitTimeout, interval);
-    if (label === "a11y") {
-        const a11yScore = getCategoryScore(result.scores, "accessibility");
-        if (failOnScore !== undefined && a11yScore !== null && a11yScore < failOnScore) {
-            process.exitCode = 1;
-        }
-        const issues = normalizeIssues(result.issues).filter((issue) => {
-            const category = (issue.category || "").toLowerCase();
-            return (category.includes("accessibility") ||
-                category.includes("a11y") ||
-                category.includes("wcag"));
-        });
-        const payload = {
-            ...result,
-            accessibility_score: a11yScore,
-            accessibility_issues: issues,
-        };
-        printOutput(format, payload, formatA11yMarkdown(result));
-        return;
-    }
-    const overall = getOverallScore(result.scores);
-    if (failOnScore !== undefined && overall !== null && overall < failOnScore) {
-        process.exitCode = 1;
-    }
-    printOutput(format, result, formatAuditMarkdown(result));
-}
-async function runCompareCommand(base, urls, flags) {
-    const mode = getString(flags, "mode") || "basic";
-    const wait = getBool(flags, "wait");
-    const format = resolveFormat(flags);
-    const [urlA, urlB] = urls;
-    const jobA = await apiRequest(base, "/audit", {
-        method: "POST",
-        body: { url: urlA, mode },
-    });
-    const jobB = await apiRequest(base, "/audit", {
-        method: "POST",
-        body: { url: urlB, mode },
-    });
-    if (!wait) {
-        const payload = { job_a: jobA, job_b: jobB };
-        const markdown = `## Audit comparison queued\n- Job A: ${jobA.job_id}\n- Job B: ${jobB.job_id}`;
-        printOutput(format, payload, markdown);
-        return;
-    }
-    if (!jobA.job_id || !jobB.job_id) {
-        throw new Error("Compare response missing job_id");
-    }
-    const timeout = getNumber(flags, "timeout") || 60000;
-    const interval = getNumber(flags, "interval") || 5000;
-    const resultA = await waitForAudit(base, jobA.job_id, timeout, interval);
-    const resultB = await waitForAudit(base, jobB.job_id, timeout, interval);
-    const overallA = getOverallScore(resultA.scores);
-    const overallB = getOverallScore(resultB.scores);
-    const delta = overallA !== null && overallB !== null ? overallB - overallA : null;
-    const scoresA = resultA.scores || {};
-    const scoresB = resultB.scores || {};
-    const keys = new Set([...Object.keys(scoresA), ...Object.keys(scoresB)]);
-    const categoryDeltas = {};
-    for (const key of keys) {
-        const a = toNumber(scoresA[key]);
-        const b = toNumber(scoresB[key]);
-        categoryDeltas[key] = {
-            a,
-            b,
-            delta: a !== null && b !== null ? b - a : null,
-        };
-    }
-    const issuesA = normalizeIssues(resultA.issues).length;
-    const issuesB = normalizeIssues(resultB.issues).length;
-    const compare = {
-        urlA,
-        urlB,
-        jobA: resultA.job_id || "",
-        jobB: resultB.job_id || "",
-        overallA,
-        overallB,
-        delta,
-        categoryDeltas,
-        issuesA,
-        issuesB,
-    };
-    const failOnScore = getNumber(flags, "fail-on-score");
-    if (failOnScore !== undefined &&
-        ((overallA !== null && overallA < failOnScore) ||
-            (overallB !== null && overallB < failOnScore))) {
-        process.exitCode = 1;
-    }
-    printOutput(format, compare, formatCompareMarkdown(compare));
-}
-async function runFixCommand(base, jobId, issueId, flags, globalFlags = {}) {
-    const fileContent = getString(flags, "file-content");
-    const format = resolveFormat(flags);
-    if (!fileContent) {
-        throw new Error("fix requires --file-content <code>");
-    }
-    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
-    if (isTTYOutput) {
-        process.stderr.write("Generating patch...\r");
-    }
-    const result = await apiRequest(base, "/patch", {
-        method: "POST",
-        body: {
-            job_id: jobId,
-            issue_id: issueId,
-            file_content: fileContent,
-        },
-    });
-    if (isTTYOutput) {
-        process.stderr.write("                    \r");
-    }
-    if (!result.success) {
-        process.exitCode = 1;
-    }
-    if (globalFlags.dryRun && isTTYOutput) {
-        process.stderr.write("[dry-run] Showing patch preview — no changes applied.\n\n");
-    }
-    if (format === "json") {
-        const output = globalFlags.dryRun ? { ...result, dry_run: true } : result;
-        console.log(JSON.stringify(output, null, 2));
-    }
-    else {
-        if (result.success && result.patch) {
-            console.log(formatPatchMarkdown(result.patch));
-        }
-        else {
-            console.log(`## Patch Generation Failed\n\n${result.error?.message || "Unknown error"}`);
-        }
-    }
-}
-async function runVerifyCommand(base, flags) {
-    const search = getString(flags, "search");
-    const replace = getString(flags, "replace");
-    const issueId = getString(flags, "issue");
-    const url = getString(flags, "url");
-    const selector = getString(flags, "selector");
-    const timeoutMs = getNumber(flags, "timeout");
-    const format = resolveFormat(flags);
-    if (!search || !replace || !issueId || !url || !selector) {
-        throw new Error("verify requires --search, --replace, --issue, --url, and --selector");
-    }
-    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
-    if (isTTYOutput) {
-        process.stderr.write("Running verification...\r");
-    }
-    const result = await apiRequest(base, "/verify", {
-        method: "POST",
-        body: {
-            patch: {
-                search,
-                replace,
-                issue_id: issueId,
-            },
-            url,
-            selector,
-            timeout_ms: timeoutMs || 60000,
-        },
-    });
-    if (isTTYOutput) {
-        process.stderr.write("                         \r");
-    }
-    // Exit code: 1 if verification failed OR issue not fixed OR regressions
-    if (!result.success) {
-        process.exitCode = 1;
-    }
-    else if (result.verification &&
-        (!result.verification.issue_fixed || result.verification.regressions.length > 0)) {
-        process.exitCode = 1;
-    }
-    if (format === "json") {
-        console.log(JSON.stringify(result, null, 2));
-    }
-    else {
-        console.log(formatVerifyMarkdown(result));
-    }
-}
-const BATCH_LIMIT = 10;
-async function runFixAllCommand(base, jobId, flags, globalFlags = {}) {
-    const fileContent = getString(flags, "file-content");
-    const autoFixOnly = getBool(flags, "auto-fix-only");
-    const format = resolveFormat(flags);
-    if (!fileContent) {
-        throw new Error("fix-all requires --file-content <code>");
-    }
-    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
-    // Fetch audit to get issues
-    if (isTTYOutput) {
-        process.stderr.write("Fetching audit...\r");
-    }
-    const audit = await apiRequest(base, `/audit/${jobId}`, {
-        method: "GET",
-    });
-    if (audit.status !== "completed") {
-        throw new Error(`Audit ${jobId} is not completed (status: ${audit.status})`);
-    }
-    // Normalize and filter issues
-    let issues = normalizeIssues(audit.issues);
-    const totalRequested = issues.length;
-    if (autoFixOnly) {
-        issues = issues.filter((issue) => {
-            const typeId = issue.id || "";
-            return isAutoFixable(typeId);
-        });
-    }
-    // Respect batch limit
-    const totalSkipped = Math.max(0, issues.length - BATCH_LIMIT);
-    const issuesToProcess = issues.slice(0, BATCH_LIMIT);
-    if (isTTYOutput) {
-        process.stderr.write("                    \r");
-    }
-    // --dry-run: show what would be processed and exit
-    if (globalFlags.dryRun) {
-        process.stderr.write(`[dry-run] Would generate patches for ${issuesToProcess.length} issues:\n`);
-        for (const issue of issuesToProcess) {
-            process.stderr.write(`  - ${issue.id || "unknown"}: ${issue.title || issue.description || "(no title)"}\n`);
-        }
-        if (totalSkipped > 0) {
-            process.stderr.write(`  (${totalSkipped} additional issues skipped — batch limit ${BATCH_LIMIT})\n`);
-        }
-        process.stderr.write("\nNo patches generated. Remove --dry-run to execute.\n");
-        return;
-    }
-    // --yes is available for future interactive confirmation steps
-    // Currently fix-all runs non-interactively, but --yes suppresses any
-    // confirmation prompts that may be added (e.g., "Apply all N patches?")
-    const results = {
-        successes: [],
-        failures: [],
-        totalRequested,
-        totalSkipped,
-    };
-    // Process issues sequentially to avoid overwhelming LLM API
-    for (let i = 0; i < issuesToProcess.length; i++) {
-        const issue = issuesToProcess[i];
-        const curIssueId = issue.id || `issue-${i}`;
-        if (isTTYOutput) {
-            process.stderr.write(`Generating patch ${i + 1}/${issuesToProcess.length}...\r`);
-        }
-        try {
-            const patchResult = await apiRequest(base, "/patch", {
-                method: "POST",
-                body: {
-                    job_id: jobId,
-                    issue_id: curIssueId,
-                    file_content: fileContent,
-                },
-            });
-            if (patchResult.success && patchResult.patch) {
-                results.successes.push({
-                    issueId: curIssueId,
-                    patch: patchResult.patch,
-                });
-            }
-            else {
-                results.failures.push({
-                    issueId: curIssueId,
-                    reason: patchResult.error?.code || "PATCH_FAILED",
-                    details: patchResult.error?.message,
-                });
-            }
-        }
-        catch (err) {
-            results.failures.push({
-                issueId: curIssueId,
-                reason: "REQUEST_ERROR",
-                details: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-    // Clear progress line
-    if (isTTYOutput) {
-        process.stderr.write("                                      \r");
-    }
-    // Exit code 1 if any failures
-    if (results.failures.length > 0) {
-        process.exitCode = 1;
-    }
-    if (format === "json") {
-        console.log(JSON.stringify(results, null, 2));
-    }
-    else {
-        console.log(formatBatchMarkdown(results));
-    }
-}
-async function runExplainCommand(base, flags) {
-    const format = resolveFormat(flags);
-    const issueJson = getString(flags, "issue");
-    const issueFile = getString(flags, "file");
-    const jobId = getString(flags, "job") || getString(flags, "job-id");
-    const issueId = getString(flags, "issue-id") || getString(flags, "id");
-    let issue = null;
-    if (issueJson) {
-        issue = JSON.parse(issueJson);
-    }
-    else if (issueFile) {
-        const raw = fs.readFileSync(issueFile, "utf-8");
-        issue = JSON.parse(raw);
-    }
-    else if (jobId && issueId) {
-        const result = await apiRequest(base, `/audit/${jobId}`, {
-            method: "GET",
-        });
-        const issues = normalizeIssues(result.issues);
-        issue = issues.find((item) => item.id === issueId) || null;
-        if (!issue) {
-            throw new Error(`Issue ${issueId} not found in job ${jobId}`);
-        }
-    }
-    if (!issue) {
-        throw new Error("Provide --issue, --file, or --job with --issue-id");
-    }
-    const payload = { issue };
-    printOutput(format, payload, formatExplainMarkdown(issue));
-}
 // ============================================================================
 // Commander.js CLI setup
 // ============================================================================
@@ -874,11 +116,18 @@ program
     .option("--machine", "Strict machine-readable output (JSON stdout, diagnostics stderr)")
     .option("--color", "Force color output")
     .option("--no-color", "Disable color output")
+    .option("--plain", "Strip all color and use ASCII-only output (auto-enabled when stdout is not a TTY)")
     .option("--dashboard", "Force live dashboard during audit --wait")
     .option("--no-dashboard", "Disable live dashboard (use spinner instead)")
     .option("--dry-run", "Show what would happen without executing")
     .option("-y, --yes", "Auto-confirm all interactive prompts")
     .option("--verbose", "Expand output with additional details")
+    .addHelpText("after", `
+Authentication:
+  SDK handles auth by default (reads VERTAAUX_API_KEY or ~/.vertaaux/credentials.json).
+  Use --api-key <key> or VERTAAUX_API_KEY env var to override for scripts and CI.
+  Run "vertaa login" to set up default credentials.
+`)
     .configureOutput({
     outputError: (str, _write) => {
         const formatted = formatCommanderError(str);
@@ -895,31 +144,41 @@ program
     // For other Commander errors (help, version), use Commander's default exit code
     process.exit(err.exitCode);
 })
-    .hook("preAction", (thisCommand) => {
+    .hook("preAction", async (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     const machineMode = opts.machine || false;
-    // Apply color settings from flags or environment
-    if (opts.color === false || process.env.NO_COLOR !== undefined) {
-        setColorEnabled(false);
-    }
-    else if (opts.color === true || process.env.FORCE_COLOR !== undefined) {
-        setColorEnabled(true);
+    // Plain mode: explicit --plain or auto-detect when stdout is not a TTY
+    // Precedence: explicit --plain > explicit --color/--no-color > NO_COLOR/FORCE_COLOR > TTY check
+    const explicitColor = opts.color === true;
+    const autoPlain = !process.stdout.isTTY && !explicitColor;
+    const plain = Boolean(opts.plain) || autoPlain;
+    if (plain && !machineMode) {
+        setPlainMode(true);
     }
     else {
-        setColorEnabled(shouldUseColor());
+        // Apply color settings from flags or environment
+        if (opts.color === false || process.env.NO_COLOR !== undefined) {
+            setColorEnabled(false);
+        }
+        else if (opts.color === true || process.env.FORCE_COLOR !== undefined) {
+            setColorEnabled(true);
+        }
+        else {
+            setColorEnabled(shouldUseColor());
+        }
     }
     if (machineMode) {
         opts.quiet = true;
         opts.banner = false;
         setColorEnabled(false);
     }
-    showBanner({
+    await animateBanner({
         version,
         quiet: opts.quiet || machineMode,
         noBanner: opts.banner === false || machineMode,
     });
 });
-// Register commands (new Commander.js implementations)
+// Register modern Commander.js commands
 registerAuditCommand(program);
 registerBaselineCommand(program);
 registerCommentCommand(program);
@@ -938,187 +197,63 @@ registerPatchReviewCommand(program);
 registerCompareCommand(program);
 registerReleaseNotesCommand(program);
 registerDocCommand(program);
-// Legacy commands using old argument parsing
-// These will be migrated in subsequent plans
-program
-    .command("a11y <url>")
-    .description("Run accessibility-focused audit (alias for audit with a11y filter)")
-    .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
-    .option("--wait", "Wait for audit completion")
-    .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout, 60000)
-    .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval, 5000)
-    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
-    .action(async (url, cmdOptions) => {
-    try {
-        const base = resolveApiBase(cmdOptions);
-        await runAuditCommand(base, url, { ...cmdOptions, wait: cmdOptions.wait ?? true }, "a11y");
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
-program
-    .command("scan <url>")
-    .description("Run UX scan (alias for audit)")
-    .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
-    .option("--wait", "Wait for audit completion")
-    .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout, 60000)
-    .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval, 5000)
-    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
-    .action(async (url, cmdOptions) => {
-    try {
-        const base = resolveApiBase(cmdOptions);
-        await runAuditCommand(base, url, { ...cmdOptions, wait: cmdOptions.wait ?? true }, "scan");
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
-// compare is now registered via registerCompareCommand (Phase 60)
-program
-    .command("status <jobId>")
-    .description("Get status of an audit job")
-    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
-    .action(async (jobId, cmdOptions) => {
-    try {
-        const base = resolveApiBase(cmdOptions);
-        const result = await apiRequest(base, `/audit/${jobId}`, {
-            method: "GET",
-        });
-        const format = resolveFormat(cmdOptions);
-        const overall = getOverallScore(result.scores);
-        const payload = { ...result, overall_score: overall };
-        const markdown = formatAuditMarkdown(result);
-        const failOnScore = getNumber(cmdOptions, "fail-on-score");
-        if (failOnScore !== undefined && overall !== null && overall < failOnScore) {
-            process.exitCode = 1;
-        }
-        printOutput(format, payload, markdown);
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
-// Legacy explain command removed - using new registerExplainCommand
-program
-    .command("fix <jobId>")
-    .description("Generate a fix patch for an issue")
-    .requiredOption("--issue <id>", "Issue ID to fix")
-    .requiredOption("--file-content <code>", "Source code content")
-    .action(async (jobId, cmdOptions, command) => {
-    try {
-        const globalOpts = command.optsWithGlobals();
-        const base = resolveApiBase(cmdOptions);
-        const issueId = getString(cmdOptions, "issue");
-        if (!issueId)
-            throw new Error("--issue is required");
-        await runFixCommand(base, jobId, issueId, cmdOptions, { dryRun: !!globalOpts.dryRun });
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
-program
-    .command("fix-all <jobId>")
-    .description("Generate fix patches for all issues in an audit")
-    .requiredOption("--file-content <code>", "Source code content")
-    .option("--auto-fix-only", "Only process auto-fixable issues")
-    .action(async (jobId, cmdOptions, command) => {
-    try {
-        const globalOpts = command.optsWithGlobals();
-        const base = resolveApiBase(cmdOptions);
-        await runFixAllCommand(base, jobId, cmdOptions, { dryRun: !!globalOpts.dryRun, yes: !!globalOpts.yes });
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
-program
-    .command("verify")
-    .description("Verify that a patch fixes an issue")
-    .requiredOption("--search <text>", "Search pattern")
-    .requiredOption("--replace <text>", "Replace pattern")
-    .requiredOption("--issue <id>", "Issue ID")
-    .requiredOption("--url <url>", "Target URL")
-    .requiredOption("--selector <css>", "CSS selector")
-    .option("--timeout <ms>", "Timeout in milliseconds (1-300000)", parseTimeout, 60000)
-    .action(async (cmdOptions) => {
-    try {
-        const base = resolveApiBase(cmdOptions);
-        await runVerifyCommand(base, cmdOptions);
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(ExitCode.ERROR);
-    }
-});
+// Register legacy commands (backward compatibility)
+registerA11yCommand(program);
+registerScanCommand(program);
+registerStatusCommand(program);
+registerFixCommand(program);
+registerFixAllCommand(program);
+registerVerifyCommand(program);
+// ============================================================================
+// Interactive app (when no command given in TTY)
+// ============================================================================
 /**
- * Interactive menu when no command given in TTY.
+ * Launch the full InteractiveApp — categorized menu, search, recent commands,
+ * help overlay, and command dispatch within the persistent 3-section layout.
+ *
+ * Replaces the previous showInteractiveMenu() (5-item select prompt) with the
+ * full interactive experience designed in Phase 102.
  */
-async function showInteractiveMenu() {
-    const action = await selectAction("What would you like to do?", [
-        {
-            name: "Run audit",
-            value: "audit",
-            description: "Audit a URL for UX and accessibility issues",
-        },
-        {
-            name: "Initialize project",
-            value: "init",
-            description: "Create .vertaaux.yml configuration",
-        },
-        {
-            name: "Check health",
-            value: "doctor",
-            description: "Run diagnostics on CLI configuration and connectivity",
-        },
-        {
-            name: "View help",
-            value: "help",
-            description: "Show all available commands",
-        },
-        {
-            name: "Exit",
-            value: "exit",
-        },
-    ]);
-    switch (action) {
-        case "audit":
-            // Re-parse with audit command
-            process.argv.push("audit");
-            program.parse();
-            break;
-        case "init":
-            // Re-parse with init command
-            process.argv.push("init");
-            program.parse();
-            break;
-        case "doctor":
-            process.argv.push("doctor");
-            program.parse();
-            break;
-        case "help":
-            program.outputHelp();
-            break;
-        case "exit":
-            process.exit(0);
-            break;
-    }
+async function launchInteractiveApp() {
+    const app = new InteractiveApp();
+    /** Create a menu onSelect handler */
+    const makeOnSelect = () => {
+        return (command) => {
+            void (async () => {
+                await recordRecent(command);
+                // CommandRunnerView handles its own suspend/resume lifecycle:
+                // - Collects args on alt screen (raw mode, no stdin transition)
+                // - Suspends only when running the command
+                // - Resumes and returns to menu after user reads output
+                const runner = new CommandRunnerView(command, app, returnToMenu);
+                await app.setView(runner);
+            })();
+        };
+    };
+    /** Navigate back to the menu from any view */
+    const returnToMenu = () => {
+        const menu = new MenuView(makeOnSelect());
+        void app.setView(menu);
+    };
+    // Start with the menu
+    const initialMenu = new MenuView(makeOnSelect());
+    await app.setView(initialMenu);
+    await app.run();
 }
+// ============================================================================
 // Parse and execute
-// If no command and TTY, show interactive menu
+// ============================================================================
 const args = process.argv.slice(2);
 const hasCommand = args.length > 0 && !args[0].startsWith("-");
-if (!hasCommand && isInteractive()) {
-    // Show banner first
-    showBanner({ version, quiet: false, noBanner: false });
-    showInteractiveMenu().catch((error) => {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+const hasGlobalFlag = args.some((a) => ["-h", "--help", "-v", "--version"].includes(a));
+if (!hasCommand && !hasGlobalFlag && isInteractive()) {
+    // InteractiveApp renders its own banner in the header section — no pre-banner needed
+    launchInteractiveApp().catch((error) => {
+        process.stderr.write(renderError({
+            message: error instanceof Error ? error.message : String(error),
+            suggestion: "vertaa doctor",
+            exitCode: ExitCode.ERROR,
+        }) + "\n");
         process.exit(ExitCode.ERROR);
     });
 }