@vertaaux/cli 0.4.0 → 0.5.1

package/dist/utils/formatters.js

@@ -0,0 +1,277 @@
+/**
+ * Output formatting utilities for the VertaaUX CLI legacy commands.
+ * Provides markdown and JSON formatting functions for audit/fix/verify results.
+ */
+import { scoreColor, boldColor } from "@vertaaux/tui";
+import { writeOutput } from "../output/envelope.js";
+// ============================================================================
+// Data normalization
+// ============================================================================
+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 [];
+}
+export function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return null;
+}
+export function getOverallScore(scores) {
+    if (!scores)
+        return null;
+    const s = scores;
+    const direct = toNumber(s.overall ?? s.ux ?? s.total);
+    if (direct !== null)
+        return direct;
+    const numeric = Object.values(s)
+        .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);
+}
+export function getCategoryScore(scores, key) {
+    if (!scores)
+        return null;
+    return toNumber(scores[key]);
+}
+// ============================================================================
+// Markdown formatters
+// ============================================================================
+export 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");
+}
+export 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");
+}
+export 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: ${boldColor(String(overall), scoreColor(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");
+}
+export 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: ${boldColor(String(a11yScore), scoreColor(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");
+}
+export 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 !== null ? boldColor(String(compare.overallA), scoreColor(compare.overallA)) : "n/a"} | ${compare.delta ?? "n/a"} |`);
+    lines.push(`| B | ${compare.overallB !== null ? boldColor(String(compare.overallB), scoreColor(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");
+}
+export 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");
+}
+export 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");
+}
+export 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:** ${boldColor(String(v.score_delta.before), scoreColor(v.score_delta.before))} -> ${boldColor(String(v.score_delta.after), scoreColor(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",
+]);
+export function isAutoFixable(issueType) {
+    const normalized = issueType.toLowerCase().replace(/^(axe|wcag)-/, "");
+    return AUTO_FIXABLE_TYPES.has(normalized);
+}
+export 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");
+}
+export function printOutput(format, data, markdown) {
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+        return;
+    }
+    // Route through writeOutput so interactive mode can buffer the output
+    writeOutput(markdown || "");
+}

package/dist/utils/root-args.d.ts

@@ -0,0 +1,12 @@
+export declare function hasHelpOrVersionFlag(args: string[]): boolean;
+/**
+ * Return the first non-option token after skipping root global options.
+ *
+ * This keeps the "launch interactive app when no command is present" behavior
+ * while still allowing global flags to appear before the subcommand:
+ *
+ *   vertaa --machine doctor
+ *   vertaa --base https://api.example.test audit https://example.com
+ */
+export declare function getRootCommandToken(args: string[]): string | undefined;
+//# sourceMappingURL=root-args.d.ts.map

package/dist/utils/root-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-args.d.ts","sourceRoot":"","sources":["../../src/utils/root-args.ts"],"names":[],"mappings":"AAcA,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAyBtE"}

package/dist/utils/root-args.js

@@ -0,0 +1,44 @@
+const ROOT_OPTIONS_WITH_VALUES = new Set([
+    "-b",
+    "--base",
+    "-c",
+    "--config",
+]);
+const HELP_OR_VERSION_FLAGS = new Set([
+    "-h",
+    "--help",
+    "-v",
+    "--version",
+]);
+export function hasHelpOrVersionFlag(args) {
+    return args.some((arg) => HELP_OR_VERSION_FLAGS.has(arg));
+}
+/**
+ * Return the first non-option token after skipping root global options.
+ *
+ * This keeps the "launch interactive app when no command is present" behavior
+ * while still allowing global flags to appear before the subcommand:
+ *
+ *   vertaa --machine doctor
+ *   vertaa --base https://api.example.test audit https://example.com
+ */
+export function getRootCommandToken(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            return args[i + 1];
+        }
+        if (ROOT_OPTIONS_WITH_VALUES.has(arg)) {
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--base=") || arg.startsWith("--config=")) {
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            continue;
+        }
+        return arg;
+    }
+    return undefined;
+}

package/dist/utils/stdin.d.ts

@@ -16,6 +16,13 @@ export interface StdinResult {
     /** Whether the input was valid JSON */
     isJson: boolean;
 }
+/**
+ * Unwrap the standard CLI JSON envelope shape ({ meta, data }).
+ *
+ * Commands that consume the output of other VertaaUX commands usually want
+ * the payload under `data`, not the outer provenance metadata.
+ */
+export declare function unwrapJsonEnvelope<T = unknown>(input: unknown): T;
 /**
  * Check if stdin has piped data available.
  */

package/dist/utils/stdin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../../src/utils/stdin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA2B7D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA+B9E;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG5D"}
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../../src/utils/stdin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;CACjB;AAqBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAKjE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA2B7D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA+B9E;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG5D"}

package/dist/utils/stdin.js

@@ -5,6 +5,36 @@
  * and provides a consistent interface for all commands that accept
  * piped data (explain, triage, fix-plan, patch-review, etc.).
  */
+/**
+ * Detect the standard CLI JSON envelope shape ({ meta, data }).
+ *
+ * Only matches when `meta` contains `command` and `version` — the fields
+ * that `createEnvelope()` always emits — so legitimate JSON payloads that
+ * happen to have a top-level `data` key are left untouched.
+ */
+function isVertaaEnvelope(input) {
+    if (!input || typeof input !== "object" || !("meta" in input) || !("data" in input)) {
+        return false;
+    }
+    const meta = input.meta;
+    if (!meta || typeof meta !== "object") {
+        return false;
+    }
+    const { command, version } = meta;
+    return command !== undefined && version !== undefined;
+}
+/**
+ * Unwrap the standard CLI JSON envelope shape ({ meta, data }).
+ *
+ * Commands that consume the output of other VertaaUX commands usually want
+ * the payload under `data`, not the outer provenance metadata.
+ */
+export function unwrapJsonEnvelope(input) {
+    if (isVertaaEnvelope(input)) {
+        return input.data;
+    }
+    return input;
+}
 /**
  * Check if stdin has piped data available.
  */
@@ -64,7 +94,7 @@ export async function readJsonInput(filePath) {
         }
         const content = fs.readFileSync(resolved, "utf-8");
         try {
-            return JSON.parse(content);
+            return unwrapJsonEnvelope(JSON.parse(content));
         }
         catch {
             throw new Error(`Invalid JSON in file: ${filePath}`);
@@ -77,7 +107,7 @@ export async function readJsonInput(filePath) {
             throw new Error("Could not parse input as JSON. If piping from vertaa, use --json flag:\n" +
                 "  vertaa audit https://example.com --json | vertaa explain");
         }
-        return stdin.json;
+        return unwrapJsonEnvelope(stdin.json);
     }
     // No input found
     return null;

package/dist/utils/url-classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url-classify.d.ts","sourceRoot":"","sources":["../../src/utils/url-classify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA2BtD;AA4CD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGrD"}
+{"version":3,"file":"url-classify.d.ts","sourceRoot":"","sources":["../../src/utils/url-classify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA8BtD;AAgED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGrD"}

package/dist/utils/url-classify.js

@@ -25,9 +25,12 @@ export function classifyUrl(urlString) {
         hostname.endsWith(".localhost")) {
         return "localhost";
     }
-    // IP literal check
-    if (net.isIP(hostname)) {
-        if (isPrivateIp(hostname))
+    // IP literal check — strip brackets from IPv6 literals
+    const ip = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    if (net.isIP(ip)) {
+        if (isPrivateIp(ip))
             return "private";
         return "public";
     }
@@ -40,6 +43,24 @@ function isPrivateIp(address) {
     const version = net.isIP(address);
     if (version === 6) {
         const lower = address.toLowerCase();
+        // IPv4-mapped IPv6 — extract and check as IPv4
+        // Handles both dotted form (::ffff:127.0.0.1) and hex form (::ffff:7f00:1)
+        if (lower.startsWith("::ffff:")) {
+            const mapped = lower.slice(7); // strip "::ffff:"
+            if (net.isIPv4(mapped)) {
+                return isPrivateIp(mapped);
+            }
+            // Hex form: two 16-bit groups (e.g. "7f00:1" = 127.0.0.1)
+            const hexParts = mapped.split(":");
+            if (hexParts.length === 2) {
+                const hi = parseInt(hexParts[0], 16);
+                const lo = parseInt(hexParts[1], 16);
+                if (!isNaN(hi) && !isNaN(lo) && hi <= 0xffff && lo <= 0xffff) {
+                    const ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+                    return isPrivateIp(ipv4);
+                }
+            }
+        }
         return (lower === "::" ||
             lower === "::1" ||
             lower.startsWith("fc") ||