@vertaaux/cli 0.3.3 → 0.5.0

package/dist/auth/token-store.js

@@ -4,8 +4,8 @@
  * Tokens are stored in ~/.vertaaux/credentials.json with restrictive permissions.
  * This is separate from project config - tokens are user-scoped, not project-scoped.
  */
-import { readFile, writeFile, mkdir, unlink } from "fs/promises";
-import { existsSync } from "fs";
+import { readFile, writeFile, mkdir, unlink, chmod } from "fs/promises";
+import { existsSync, lstatSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
 /**
@@ -26,6 +26,10 @@ export function getCredentialsPath() {
 export async function saveToken(token) {
     const credPath = getCredentialsPath();
     const dir = dirname(credPath);
+    // SECVAL-1: Refuse to write if credentials path is a symlink
+    if (existsSync(credPath) && lstatSync(credPath).isSymbolicLink()) {
+        throw new Error(`Security error: ${credPath} is a symlink. Refusing to write credentials.`);
+    }
     // Create directory if needed
     if (!existsSync(dir)) {
         await mkdir(dir, { recursive: true, mode: 0o700 });
@@ -33,6 +37,8 @@ export async function saveToken(token) {
     // Write token with restrictive permissions
     const content = JSON.stringify(token, null, 2);
     await writeFile(credPath, content + "\n", { encoding: "utf-8", mode: 0o600 });
+    // SECVAL-2: Ensure restrictive permissions after write
+    await chmod(credPath, 0o600);
 }
 /**
  * Load token data from credentials file.
@@ -44,6 +50,10 @@ export async function loadToken() {
     if (!existsSync(credPath)) {
         return null;
     }
+    // SECVAL-1: Refuse to read if credentials path is a symlink
+    if (lstatSync(credPath).isSymbolicLink()) {
+        return null;
+    }
     try {
         const content = await readFile(credPath, "utf-8");
         return JSON.parse(content);

package/dist/baseline/diff.d.ts

@@ -38,8 +38,8 @@ export declare function computeDiff(currentIssues: Issue[], baseline: BaselineFi
  * Format diff result for human-readable output.
  *
  * Uses colors:
- * - New issues: red
- * - Fixed issues: green
+ * - New issues: red (tokens.error)
+ * - Fixed issues: green (tokens.success)
  * - Still present: dim
  *
  * @param diff - Diff result to format

package/dist/baseline/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/baseline/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAuB,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,GAAG,EAAE,KAAK,EAAE,CAAC;IACb,8CAA8C;IAC9C,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,qCAAqC;IACrC,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,qBAAqB;IACrB,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE,KAAK,EAAE,EACtB,QAAQ,EAAE,YAAY,GACrB,UAAU,CA2CZ;AA2CD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,UAAQ,GAAG,MAAM,CAsCzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/baseline/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAuB,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,GAAG,EAAE,KAAK,EAAE,CAAC;IACb,8CAA8C;IAC9C,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,qCAAqC;IACrC,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,qBAAqB;IACrB,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE,KAAK,EAAE,EACtB,QAAQ,EAAE,YAAY,GACrB,UAAU,CA2CZ;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,UAAQ,GAAG,MAAM,CAsCzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEvD"}

package/dist/baseline/diff.js

@@ -7,7 +7,7 @@
  * - Fixed: Issues in baseline but not in current
  * - Present: Issues in both current and baseline
  */
-import chalk from "chalk";
+import { boldColor, dim, tokens, text } from "@vertaaux/tui";
 import { generateFingerprint } from "./hash.js";
 /**
  * Compute diff between current issues and baseline.
@@ -60,25 +60,6 @@ export function computeDiff(currentIssues, baseline) {
 function getRuleId(issue) {
     return issue.ruleId || issue.rule_id || issue.id || "unknown";
 }
-/**
- * Format severity badge for display.
- */
-function formatSeverityBadge(severity) {
-    const upper = (severity || "info").toUpperCase();
-    switch (upper) {
-        case "ERROR":
-        case "CRITICAL":
-            return chalk.red(`[${upper}]`);
-        case "WARNING":
-        case "SERIOUS":
-            return chalk.yellow(`[${upper}]`);
-        case "INFO":
-        case "MINOR":
-            return chalk.blue(`[${upper}]`);
-        default:
-            return chalk.gray(`[${upper}]`);
-    }
-}
 /**
  * Format issue line for display.
  */
@@ -88,14 +69,14 @@ function formatIssueLine(issue) {
         ? issue.description
         : issue.description || issue.title || "";
     const severity = issue.severity || "info";
-    return `${formatSeverityBadge(severity)} ${ruleId}: ${description}`;
+    return `[${text.severityBadge(severity)}] ${ruleId}: ${description}`;
 }
 /**
  * Format diff result for human-readable output.
  *
  * Uses colors:
- * - New issues: red
- * - Fixed issues: green
+ * - New issues: red (tokens.error)
+ * - Fixed issues: green (tokens.success)
  * - Still present: dim
  *
  * @param diff - Diff result to format
@@ -104,10 +85,10 @@ function formatIssueLine(issue) {
  */
 export function formatDiffHuman(diff, verbose = false) {
     const lines = [];
-    // New issues section (red)
-    lines.push(chalk.red.bold(`NEW ISSUES (${diff.summary.newCount})`));
+    // New issues section (red bold)
+    lines.push(boldColor(`NEW ISSUES (${diff.summary.newCount})`, tokens.error));
     if (diff.new.length === 0) {
-        lines.push(chalk.dim("  No new issues"));
+        lines.push(dim("  No new issues"));
     }
     else {
         for (const issue of diff.new) {
@@ -115,10 +96,10 @@ export function formatDiffHuman(diff, verbose = false) {
         }
     }
     lines.push("");
-    // Fixed issues section (green)
-    lines.push(chalk.green.bold(`FIXED (${diff.summary.fixedCount})`));
+    // Fixed issues section (green bold)
+    lines.push(boldColor(`FIXED (${diff.summary.fixedCount})`, tokens.success));
     if (diff.fixed.length === 0) {
-        lines.push(chalk.dim("  No issues fixed"));
+        lines.push(dim("  No issues fixed"));
     }
     else {
         for (const issue of diff.fixed) {
@@ -126,18 +107,18 @@ export function formatDiffHuman(diff, verbose = false) {
         }
     }
     lines.push("");
-    // Still present section (dim)
-    lines.push(chalk.dim.bold(`STILL PRESENT (${diff.summary.presentCount})`));
+    // Still present section (dim only — no bold+dim combo per locked decisions)
+    lines.push(dim(`STILL PRESENT (${diff.summary.presentCount})`));
     if (diff.present.length === 0) {
-        lines.push(chalk.dim("  No baselined issues remain"));
+        lines.push(dim("  No baselined issues remain"));
     }
     else if (verbose) {
         for (const issue of diff.present) {
-            lines.push(chalk.dim(`  ${formatIssueLine(issue)}`));
+            lines.push(dim(`  ${formatIssueLine(issue)}`));
         }
     }
     else {
-        lines.push(chalk.dim("  (use --verbose to show all)"));
+        lines.push(dim("  (use --verbose to show all)"));
     }
     return lines.join("\n");
 }

package/dist/commands/a11y.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Legacy a11y command handler.
+ * Runs accessibility-focused audit (alias for audit with a11y filter).
+ */
+import type { Command } from "commander";
+import type { Flags } from "../types.js";
+export declare function handleA11y(rawUrl: string, cmdOptions: Flags): Promise<void>;
+export declare function registerA11yCommand(program: Command): void;
+//# sourceMappingURL=a11y.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../src/commands/a11y.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDjF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuB1D"}

package/dist/commands/a11y.js

@@ -0,0 +1,76 @@
+/**
+ * Legacy a11y command handler.
+ * Runs accessibility-focused audit (alias for audit with a11y filter).
+ */
+import { renderError, runSteps, createRenderer } from "@vertaaux/tui";
+import { ExitCode } from "../utils/exit-codes.js";
+import { parseMode, parseTimeout, parseInterval, parseScore } from "../utils/validators.js";
+import { resolveApiBase } from "../utils/api-client.js";
+import { runAuditCommand } from "./scan.js";
+export async function handleA11y(rawUrl, cmdOptions) {
+    const url = /^https?:\/\//i.test(rawUrl) ? rawUrl : `https://${rawUrl}`;
+    const renderer = createRenderer("auto");
+    const baseState = {
+        phase: "a11y",
+        phaseIndex: 1,
+        phaseTotal: 1,
+        url,
+        mode: "a11y",
+        progress: {},
+        totals: {},
+        issueCount: 0,
+        scorePreview: null,
+        verbose: false,
+        elapsed: 0,
+    };
+    const startTime = Date.now();
+    const steps = [
+        {
+            id: "a11y",
+            actionText: "Running accessibility audit...",
+            summaryText: "Accessibility audit complete",
+            run: async () => {
+                const base = resolveApiBase(cmdOptions);
+                await runAuditCommand(base, url, { ...cmdOptions, wait: cmdOptions.wait ?? true }, "a11y");
+            },
+        },
+    ];
+    const { success, states } = await runSteps(steps, {
+        failFast: true,
+        onStateChange: (stepStates) => {
+            renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+        },
+    });
+    renderer.finish({ url, mode: "a11y", overallScore: 0, scores: {}, issueCount: 0, passed: success, elapsed: Date.now() - startTime });
+    if (!success) {
+        const failed = states.find(s => s.status === "failed");
+        process.stderr.write(renderError({
+            message: failed?.failReason || "Command failed",
+            suggestion: "vertaa doctor",
+        }) + "\n");
+        process.exitCode = ExitCode.ERROR;
+    }
+}
+export function registerA11yCommand(program) {
+    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 {
+            await handleA11y(url, cmdOptions);
+        }
+        catch (error) {
+            process.stderr.write(renderError({
+                message: error instanceof Error ? error.message : String(error),
+                suggestion: "vertaa audit <url>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Artifact saving for the audit command.
+ *
+ * Handles repro artifacts (trace, HAR, screenshots, DOM snapshots)
+ * and CI artifact bundling.
+ */
+import type { AuditResponse } from "../../utils/client.js";
+import type { IssueLike, AuditCommandOptions, ArtifactManifest } from "./types.js";
+/**
+ * Count issues by severity level.
+ */
+export declare function countIssuesBySeverity(issues: IssueLike[]): ArtifactManifest["issue_count"];
+/**
+ * Save repro artifacts from API response.
+ */
+export declare function saveReproArtifacts(jobId: string, response: AuditResponse, options: AuditCommandOptions, quiet: boolean): void;
+/**
+ * Save CI artifact bundle for GitHub Actions upload.
+ *
+ * Creates a complete evidence bundle:
+ * - results.json: Full audit results
+ * - results.sarif: SARIF for Code Scanning
+ * - report.html: HTML report for viewing
+ * - manifest.json: Metadata about the bundle
+ */
+export declare function saveArtifactBundle(jobId: string, result: AuditResponse, issues: IssueLike[], exitCode: number, quiet: boolean): string;
+//# sourceMappingURL=artifacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/commands/audit/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAe1F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,OAAO,GACb,IAAI,CAmFN;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,SAAS,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,MAAM,CAkDR"}

package/dist/commands/audit/artifacts.js

@@ -0,0 +1,158 @@
+/**
+ * Artifact saving for the audit command.
+ *
+ * Handles repro artifacts (trace, HAR, screenshots, DOM snapshots)
+ * and CI artifact bundling.
+ */
+import fs from "fs";
+import path from "path";
+import { writeOutput } from "../../output/envelope.js";
+import { formatSarif, formatAuditHtml } from "../../output/factory.js";
+import { assertPathContainment } from "../../utils/sanitize.js";
+import { ARTIFACTS_DIR } from "./types.js";
+/**
+ * Count issues by severity level.
+ */
+export function countIssuesBySeverity(issues) {
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const issue of issues) {
+        const sev = (issue.severity || "info").toLowerCase();
+        if (sev === "error" || sev === "critical") {
+            counts.error++;
+        }
+        else if (sev === "warning" || sev === "serious") {
+            counts.warning++;
+        }
+        else {
+            counts.info++;
+        }
+    }
+    return counts;
+}
+/**
+ * Save repro artifacts from API response.
+ */
+export function saveReproArtifacts(jobId, response, options, quiet) {
+    const hasArtifactOptions = options.saveTrace || options.saveHar || options.screenshots || options.domSnapshots;
+    if (!hasArtifactOptions)
+        return;
+    // Create artifacts directory
+    const artifactsPath = path.resolve(process.cwd(), ARTIFACTS_DIR, jobId);
+    // Check if API response includes artifact data
+    const responseAny = response;
+    const artifacts = responseAny.artifacts;
+    if (!artifacts) {
+        if (!quiet) {
+            writeOutput("Note: Repro artifacts were requested but not available in API response.\n");
+            writeOutput("Artifact capture may require a 'deep' mode audit or premium plan.\n");
+        }
+        return;
+    }
+    // Ensure directory exists
+    if (!fs.existsSync(artifactsPath)) {
+        fs.mkdirSync(artifactsPath, { recursive: true });
+    }
+    const saved = [];
+    // Save trace file if available and requested
+    if (options.saveTrace && artifacts.trace) {
+        const tracePath = path.join(artifactsPath, "trace.zip");
+        fs.writeFileSync(tracePath, Buffer.from(artifacts.trace, "base64"));
+        saved.push("trace.zip");
+    }
+    // Save HAR file if available and requested
+    if (options.saveHar && artifacts.har) {
+        const harPath = path.join(artifactsPath, "network.har");
+        fs.writeFileSync(harPath, typeof artifacts.har === "string" ? artifacts.har : JSON.stringify(artifacts.har, null, 2));
+        saved.push("network.har");
+    }
+    // Save screenshots if available and requested
+    if (options.screenshots && artifacts.screenshots) {
+        const screenshots = artifacts.screenshots;
+        for (const screenshot of screenshots) {
+            const screenshotName = screenshot.name || "screenshot.png";
+            let screenshotPath;
+            try {
+                screenshotPath = assertPathContainment(screenshotName, artifactsPath);
+            }
+            catch {
+                writeOutput(`Security: Rejected screenshot "${screenshotName}" -- path traversal outside artifacts directory.\n`);
+                continue;
+            }
+            fs.writeFileSync(screenshotPath, Buffer.from(screenshot.data, "base64"));
+            saved.push(screenshotName);
+        }
+    }
+    // Save DOM snapshots if available and requested
+    if (options.domSnapshots && artifacts.domSnapshots) {
+        const snapshots = artifacts.domSnapshots;
+        for (const snapshot of snapshots) {
+            const snapshotName = snapshot.name || "snapshot.html";
+            let snapshotPath;
+            try {
+                snapshotPath = assertPathContainment(snapshotName, artifactsPath);
+            }
+            catch {
+                writeOutput(`Security: Rejected snapshot "${snapshotName}" -- path traversal outside artifacts directory.\n`);
+                continue;
+            }
+            fs.writeFileSync(snapshotPath, snapshot.html);
+            saved.push(snapshotName);
+        }
+    }
+    if (saved.length > 0 && !quiet) {
+        writeOutput(`Artifacts saved to: ${artifactsPath}\n`);
+        writeOutput(`  - ${saved.join("\n  - ")}\n`);
+    }
+}
+/**
+ * Save CI artifact bundle for GitHub Actions upload.
+ *
+ * Creates a complete evidence bundle:
+ * - results.json: Full audit results
+ * - results.sarif: SARIF for Code Scanning
+ * - report.html: HTML report for viewing
+ * - manifest.json: Metadata about the bundle
+ */
+export function saveArtifactBundle(jobId, result, issues, exitCode, quiet) {
+    const artifactsPath = path.resolve(process.cwd(), ARTIFACTS_DIR, jobId);
+    // Ensure directory exists
+    if (!fs.existsSync(artifactsPath)) {
+        fs.mkdirSync(artifactsPath, { recursive: true });
+    }
+    const files = [];
+    // 1. Save JSON results
+    const jsonPath = path.join(artifactsPath, "results.json");
+    fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2), "utf-8");
+    files.push("results.json");
+    // 2. Save SARIF for Code Scanning
+    const sarifContent = formatSarif(result, {
+        workingDirectory: process.cwd(),
+    });
+    const sarifPath = path.join(artifactsPath, "results.sarif");
+    fs.writeFileSync(sarifPath, sarifContent, "utf-8");
+    files.push("results.sarif");
+    // 3. Save HTML report
+    const htmlContent = formatAuditHtml(result, {
+        interactive: true,
+    });
+    const htmlPath = path.join(artifactsPath, "report.html");
+    fs.writeFileSync(htmlPath, htmlContent, "utf-8");
+    files.push("report.html");
+    // 4. Save manifest
+    const manifest = {
+        job_id: jobId,
+        timestamp: new Date().toISOString(),
+        files,
+        audit_url: result.url,
+        issue_count: countIssuesBySeverity(issues),
+        exit_code: exitCode,
+    };
+    const manifestPath = path.join(artifactsPath, "manifest.json");
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    files.push("manifest.json");
+    if (!quiet) {
+        writeOutput(`Artifacts saved to: ${artifactsPath}\n`);
+        writeOutput(`  - ${files.join("\n  - ")}\n`);
+    }
+    return artifactsPath;
+}

package/dist/commands/audit/ci-detection.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CI environment detection for the audit command.
+ *
+ * Detects current branch and PR labels from various CI providers.
+ */
+/**
+ * Detect current branch from CI environment or git.
+ */
+export declare function detectCurrentBranch(): string;
+/**
+ * Detect PR labels from CI environment variables.
+ *
+ * Supports:
+ * - GitHub Actions: GITHUB_EVENT_PATH contains event JSON with labels
+ * - GitLab CI: CI_MERGE_REQUEST_LABELS is comma-separated
+ */
+export declare function detectPRLabels(): string[];
+//# sourceMappingURL=ci-detection.d.ts.map

package/dist/commands/audit/ci-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-detection.d.ts","sourceRoot":"","sources":["../../../src/commands/audit/ci-detection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAqC5C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CA0BzC"}

package/dist/commands/audit/ci-detection.js

@@ -0,0 +1,71 @@
+/**
+ * CI environment detection for the audit command.
+ *
+ * Detects current branch and PR labels from various CI providers.
+ */
+import fs from "fs";
+/**
+ * Detect current branch from CI environment or git.
+ */
+export function detectCurrentBranch() {
+    // GitHub Actions
+    if (process.env.GITHUB_HEAD_REF) {
+        return process.env.GITHUB_HEAD_REF;
+    }
+    if (process.env.GITHUB_REF_NAME) {
+        return process.env.GITHUB_REF_NAME;
+    }
+    // GitLab CI
+    if (process.env.CI_COMMIT_REF_NAME) {
+        return process.env.CI_COMMIT_REF_NAME;
+    }
+    // Azure DevOps
+    if (process.env.BUILD_SOURCEBRANCHNAME) {
+        return process.env.BUILD_SOURCEBRANCHNAME;
+    }
+    // CircleCI
+    if (process.env.CIRCLE_BRANCH) {
+        return process.env.CIRCLE_BRANCH;
+    }
+    // Jenkins
+    if (process.env.GIT_BRANCH) {
+        // Jenkins often includes origin/, remove it
+        return process.env.GIT_BRANCH.replace(/^origin\//, "");
+    }
+    // Generic CI
+    if (process.env.BRANCH_NAME) {
+        return process.env.BRANCH_NAME;
+    }
+    // Default
+    return "";
+}
+/**
+ * Detect PR labels from CI environment variables.
+ *
+ * Supports:
+ * - GitHub Actions: GITHUB_EVENT_PATH contains event JSON with labels
+ * - GitLab CI: CI_MERGE_REQUEST_LABELS is comma-separated
+ */
+export function detectPRLabels() {
+    // GitHub Actions: GITHUB_EVENT_PATH contains event JSON with labels
+    if (process.env.GITHUB_EVENT_PATH) {
+        try {
+            const eventContent = fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf-8");
+            const event = JSON.parse(eventContent);
+            const labels = event.pull_request?.labels;
+            if (Array.isArray(labels)) {
+                return labels.map((l) => l.name || "").filter(Boolean);
+            }
+        }
+        catch {
+            // Ignore errors reading event file
+        }
+    }
+    // GitLab CI: CI_MERGE_REQUEST_LABELS is comma-separated
+    if (process.env.CI_MERGE_REQUEST_LABELS) {
+        return process.env.CI_MERGE_REQUEST_LABELS.split(",")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    return [];
+}

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

@@ -0,0 +1,11 @@
+/**
+ * AI inline explanation for the audit command.
+ */
+import type { VertaauxConfig } from "../../config/schema.js";
+import { type AuditResponse } from "../../utils/client.js";
+import type { IssueLike, AuditCommandOptions } from "./types.js";
+/**
+ * Run the inline AI explanation for audit issues.
+ */
+export declare function runInlineExplanation(issues: IssueLike[], result: AuditResponse, targetUrl: string, options: AuditCommandOptions, config: VertaauxConfig): Promise<void>;
+//# sourceMappingURL=explain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/commands/audit/explain.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjE;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAyCf"}

package/dist/commands/audit/explain.js

@@ -0,0 +1,45 @@
+/**
+ * AI inline explanation for the audit command.
+ */
+import { bold, dim, colorize, brand } from "@vertaaux/tui";
+import { writeOutput } from "../../output/envelope.js";
+import { resolveApiBase, getApiKey, apiRequest, } from "../../utils/client.js";
+import { createSpinner, succeedSpinner, } from "../../ui/spinner.js";
+import { strings } from "../../ui/strings.js";
+/**
+ * Run the inline AI explanation for audit issues.
+ */
+export async function runInlineExplanation(issues, result, targetUrl, options, config) {
+    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(strings.explain.run.action);
+        const explainResponse = await apiRequest(explainBase, "/cli/ai/explain", { method: "POST", body: { audit: explainPayload } }, explainKey);
+        succeedSpinner(explainSpinner, strings.explain.run.done(explainResponse.data.issues.length));
+        writeOutput("\n");
+        writeOutput(bold("AI Explanation") + "\n");
+        writeOutput(dim("\u2500".repeat(40)) + "\n");
+        for (const bullet of explainResponse.data.summary) {
+            writeOutput(`  ${colorize("*", brand.cyan)} ${bullet}\n`);
+        }
+    }
+    catch (explainErr) {
+        writeOutput(dim(`\n(${strings.explain.aiUnavailable(explainErr instanceof Error ? explainErr.message : String(explainErr))})\n`));
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Issue filtering helpers for the audit command.
+ */
+import type { IssueLike } from "./types.js";
+/**
+ * Normalize issues from various API response formats.
+ */
+export declare function normalizeIssues(issues: unknown): IssueLike[];
+/**
+ * Filter issues by severity.
+ */
+export declare function filterBySeverity(issues: IssueLike[], severityFilter: string): IssueLike[];
+/**
+ * Filter issues by category.
+ */
+export declare function filterByCategory(issues: IssueLike[], categoryFilter: string): IssueLike[];
+//# sourceMappingURL=filters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../../src/commands/audit/filters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,CAS5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EAAE,EACnB,cAAc,EAAE,MAAM,GACrB,SAAS,EAAE,CAab;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EAAE,EACnB,cAAc,EAAE,MAAM,GACrB,SAAS,EAAE,CASb"}

package/dist/commands/audit/filters.js

@@ -0,0 +1,40 @@
+/**
+ * Issue filtering helpers for the audit command.
+ */
+/**
+ * Normalize issues from various API response formats.
+ */
+export 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 [];
+}
+/**
+ * Filter issues by severity.
+ */
+export function filterBySeverity(issues, severityFilter) {
+    const allowed = new Set(severityFilter.split(",").map((s) => s.trim().toLowerCase()));
+    // Map common aliases
+    if (allowed.has("error"))
+        allowed.add("critical");
+    if (allowed.has("warning"))
+        allowed.add("serious");
+    return issues.filter((issue) => {
+        const sev = issue.severity?.toLowerCase() || "info";
+        return allowed.has(sev);
+    });
+}
+/**
+ * Filter issues by category.
+ */
+export function filterByCategory(issues, categoryFilter) {
+    const allowed = new Set(categoryFilter.split(",").map((c) => c.trim().toLowerCase()));
+    return issues.filter((issue) => {
+        const cat = issue.category?.toLowerCase() || "";
+        return allowed.has(cat) || Array.from(allowed).some((a) => cat.includes(a));
+    });
+}