@vertaaux/cli 0.2.3 → 0.3.0

package/dist/output/human.d.ts

@@ -2,7 +2,7 @@
  * Human-readable output formatter for CLI.
  *
  * Outputs audit results as colorful, formatted text for terminal display.
- * Uses chalk for colors and cli-table3 for table formatting.
+ * Delegates to @vertaaux/tui for consistent rendering.
  */
 import { type FormatTableOptions } from "../ui/table.js";
 export interface AuditResult {
@@ -19,23 +19,14 @@ export interface AuditResult {
     error?: string;
 }
 export interface FormatHumanOptions {
-    /** How to group issues: severity (default), category, route */
     groupBy?: "severity" | "category" | "route";
-    /** Whether to show detailed scores table */
     showScores?: boolean;
-    /** Whether to show the summary at the end */
     showSummary?: boolean;
-    /** Maximum issues to display per group */
     maxIssuesPerGroup?: number;
-    /** Table formatting options */
     tableOptions?: FormatTableOptions;
 }
 /**
  * Format audit result as human-readable string.
- *
- * @param result - Audit result object
- * @param options - Formatting options
- * @returns Formatted string for terminal display
  */
 export declare function formatAuditHuman(result: AuditResult, options?: FormatHumanOptions): string;
 //# sourceMappingURL=human.d.ts.map

package/dist/output/human.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"human.d.ts","sourceRoot":"","sources":["../../src/output/human.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAC5C,4CAA4C;IAC5C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+BAA+B;IAC/B,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAmRD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAkDR"}
+{"version":3,"file":"human.d.ts","sourceRoot":"","sources":["../../src/output/human.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAC5C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAuND;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAuCR"}

package/dist/output/human.js

@@ -2,11 +2,10 @@
  * Human-readable output formatter for CLI.
  *
  * Outputs audit results as colorful, formatted text for terminal display.
- * Uses chalk for colors and cli-table3 for table formatting.
+ * Delegates to @vertaaux/tui for consistent rendering.
  */
-import chalk from "chalk";
+import { text, getTerminalWidth, scoreColor, boldColor, } from "@vertaaux/tui";
 import { formatIssuesTable, formatScoresTable, formatIssueSummary, groupBySeverity, groupByCategory, } from "../ui/table.js";
-import { shouldUseColor, getTerminalWidth } from "../utils/detect-env.js";
 /**
  * Normalize issues from various API response formats.
  */
@@ -34,41 +33,22 @@ function getOverallScore(scores) {
         return null;
     return Math.round(numeric.reduce((a, b) => a + b, 0) / numeric.length);
 }
-/**
- * Format a horizontal rule.
- */
-function hr() {
-    const width = Math.min(getTerminalWidth(), 80);
-    return shouldUseColor()
-        ? chalk.dim("-".repeat(width))
-        : "-".repeat(width);
-}
 /**
  * Format the header section.
  */
 function formatHeader(result) {
-    const useColor = shouldUseColor();
     const lines = [];
-    // Title
-    const title = useColor
-        ? chalk.bold.cyan("Audit Complete")
-        : "AUDIT COMPLETE";
-    lines.push(title);
-    // URL
+    lines.push(text.heading("Audit Complete"));
     if (result.url) {
-        const urlLine = useColor
-            ? chalk.dim("URL: ") + chalk.white(result.url)
-            : `URL: ${result.url}`;
-        lines.push(urlLine);
+        lines.push(`${text.dim("URL:")} ${text.link(result.url)}`);
     }
-    // Mode and Job ID
     const meta = [];
     if (result.mode)
         meta.push(`Mode: ${result.mode}`);
     if (result.job_id)
         meta.push(`Job: ${result.job_id}`);
     if (meta.length) {
-        lines.push(useColor ? chalk.dim(meta.join(" | ")) : meta.join(" | "));
+        lines.push(text.dim(meta.join(" | ")));
     }
     return lines.join("\n");
 }
@@ -76,34 +56,20 @@ function formatHeader(result) {
  * Format the scores section.
  */
 function formatScoresSection(scores) {
-    const useColor = shouldUseColor();
     const lines = [];
     lines.push("");
-    lines.push(useColor ? chalk.bold("Scores") : "SCORES");
-    lines.push(hr());
+    lines.push(text.bold("Scores"));
+    lines.push(text.hr(Math.min(getTerminalWidth(), 80)));
     if (!scores || Object.keys(scores).length === 0) {
-        lines.push(useColor ? chalk.dim("No scores available.") : "No scores available.");
+        lines.push(text.dim("No scores available."));
         return lines.join("\n");
     }
-    // Overall score with color coding
     const overall = getOverallScore(scores);
     if (overall !== null) {
-        let scoreDisplay = String(overall);
-        if (useColor) {
-            if (overall >= 90) {
-                scoreDisplay = chalk.green.bold(scoreDisplay);
-            }
-            else if (overall >= 70) {
-                scoreDisplay = chalk.yellow.bold(scoreDisplay);
-            }
-            else {
-                scoreDisplay = chalk.red.bold(scoreDisplay);
-            }
-        }
-        lines.push(`Overall: ${scoreDisplay}/100`);
+        const scoreStr = boldColor(String(overall), scoreColor(overall));
+        lines.push(`Overall: ${scoreStr}/100`);
         lines.push("");
     }
-    // Detailed scores table
     const numericScores = {};
     for (const [key, value] of Object.entries(scores)) {
         if (typeof value === "number" && key !== "overall") {
@@ -119,40 +85,29 @@ function formatScoresSection(scores) {
  * Format issues section grouped by severity.
  */
 function formatIssuesBySeverity(issues, maxPerGroup, tableOptions) {
-    const useColor = shouldUseColor();
     const lines = [];
     lines.push("");
-    lines.push(useColor ? chalk.bold("Issues") : "ISSUES");
-    lines.push(hr());
+    lines.push(text.bold("Issues"));
+    lines.push(text.hr(Math.min(getTerminalWidth(), 80)));
     if (issues.length === 0) {
-        lines.push(useColor ? chalk.green("No issues found!") : "No issues found!");
+        lines.push(text.success("No issues found!"));
         return lines.join("\n");
     }
-    // Group by severity
     const groups = groupBySeverity(issues);
-    const severityOrder = ["critical", "error", "serious", "warning", "minor", "moderate", "info"];
-    for (const severity of severityOrder) {
-        const groupIssues = groups.get(severity);
+    const order = ["critical", "error", "serious", "warning", "minor", "moderate", "info"];
+    for (const sev of order) {
+        const groupIssues = groups.get(sev);
         if (!groupIssues || groupIssues.length === 0)
             continue;
         const displayIssues = maxPerGroup
             ? groupIssues.slice(0, maxPerGroup)
             : groupIssues;
-        // Section header
-        const label = severity.toUpperCase();
-        const count = groupIssues.length;
-        const header = useColor
-            ? chalk.bold(`${label} (${count})`)
-            : `${label} (${count})`;
         lines.push("");
-        lines.push(header);
-        // Issues table for this severity
+        lines.push(text.bold(`${text.severityBadge(sev)} (${groupIssues.length})`));
         lines.push(formatIssuesTable(displayIssues, tableOptions));
-        // Show truncation message if needed
         if (maxPerGroup && groupIssues.length > maxPerGroup) {
             const remaining = groupIssues.length - maxPerGroup;
-            const msg = `...and ${remaining} more ${severity} issues`;
-            lines.push(useColor ? chalk.dim(msg) : msg);
+            lines.push(text.dim(`...and ${remaining} more ${sev} issues`));
         }
     }
     return lines.join("\n");
@@ -161,34 +116,25 @@ function formatIssuesBySeverity(issues, maxPerGroup, tableOptions) {
  * Format issues section grouped by category.
  */
 function formatIssuesByCategory(issues, maxPerGroup, tableOptions) {
-    const useColor = shouldUseColor();
     const lines = [];
     lines.push("");
-    lines.push(useColor ? chalk.bold("Issues by Category") : "ISSUES BY CATEGORY");
-    lines.push(hr());
+    lines.push(text.bold("Issues by Category"));
+    lines.push(text.hr(Math.min(getTerminalWidth(), 80)));
     if (issues.length === 0) {
-        lines.push(useColor ? chalk.green("No issues found!") : "No issues found!");
+        lines.push(text.success("No issues found!"));
         return lines.join("\n");
     }
-    // Group by category
     const groups = groupByCategory(issues);
     for (const [category, groupIssues] of groups) {
         const displayIssues = maxPerGroup
             ? groupIssues.slice(0, maxPerGroup)
             : groupIssues;
-        // Section header
-        const header = useColor
-            ? chalk.bold(`${category} (${groupIssues.length})`)
-            : `${category} (${groupIssues.length})`;
         lines.push("");
-        lines.push(header);
-        // Issues table for this category
+        lines.push(text.bold(`${category} (${groupIssues.length})`));
         lines.push(formatIssuesTable(displayIssues, tableOptions));
-        // Show truncation message if needed
         if (maxPerGroup && groupIssues.length > maxPerGroup) {
             const remaining = groupIssues.length - maxPerGroup;
-            const msg = `...and ${remaining} more issues`;
-            lines.push(useColor ? chalk.dim(msg) : msg);
+            lines.push(text.dim(`...and ${remaining} more issues`));
         }
     }
     return lines.join("\n");
@@ -197,14 +143,11 @@ function formatIssuesByCategory(issues, maxPerGroup, tableOptions) {
  * Format the summary section.
  */
 function formatSummary(issues, scores, threshold) {
-    const useColor = shouldUseColor();
     const lines = [];
     lines.push("");
-    lines.push(hr());
-    // Summary line
+    lines.push(text.hr(Math.min(getTerminalWidth(), 80)));
     const summary = formatIssueSummary(issues);
     lines.push(summary);
-    // Pass/fail status
     const overall = getOverallScore(scores);
     const hasErrors = issues.some((i) => i.severity?.toLowerCase() === "critical" || i.severity?.toLowerCase() === "error");
     let status;
@@ -223,50 +166,35 @@ function formatSummary(issues, scores, threshold) {
         passed = !hasErrors;
         status = passed ? "PASSED" : "FAILED";
     }
-    if (useColor) {
-        status = passed ? chalk.green.bold(status) : chalk.red.bold(status);
-    }
+    status = passed ? text.success(status) : text.error(status);
     lines.push(status);
     return lines.join("\n");
 }
 /**
  * Format audit result as human-readable string.
- *
- * @param result - Audit result object
- * @param options - Formatting options
- * @returns Formatted string for terminal display
  */
 export function formatAuditHuman(result, options = {}) {
     const { groupBy = "severity", showScores = true, showSummary = true, maxIssuesPerGroup = 10, tableOptions, } = options;
     const sections = [];
-    // Header
     sections.push(formatHeader(result));
-    // Handle non-completed audits
     if (result.status !== "completed") {
-        const useColor = shouldUseColor();
         sections.push("");
-        sections.push(useColor
-            ? chalk.yellow(`Status: ${result.status || "unknown"}`)
-            : `Status: ${result.status || "unknown"}`);
+        sections.push(text.warning(`Status: ${result.status || "unknown"}`));
         if (typeof result.progress === "number") {
             sections.push(`Progress: ${result.progress}%`);
         }
         return sections.join("\n");
     }
-    // Scores section
     if (showScores) {
         sections.push(formatScoresSection(result.scores));
     }
-    // Issues section
     const issues = normalizeIssues(result.issues);
     if (groupBy === "category") {
         sections.push(formatIssuesByCategory(issues, maxIssuesPerGroup, tableOptions));
     }
     else {
-        // Default: group by severity
         sections.push(formatIssuesBySeverity(issues, maxIssuesPerGroup, tableOptions));
     }
-    // Summary
     if (showSummary) {
         sections.push(formatSummary(issues, result.scores));
     }

package/dist/prompts/command-catalog.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Command catalog for the `suggest` command.
+ *
+ * Maps natural-language intents to exact CLI commands.
+ * Used for local fuzzy matching before falling back to LLM API.
+ */
+export interface CatalogEntry {
+    /** Exact CLI command to run */
+    command: string;
+    /** Short explanation of what the command does */
+    description: string;
+    /** Keywords that trigger this entry */
+    keywords: string[];
+}
+/**
+ * Full command catalog for VertaaUX CLI.
+ *
+ * Each entry has keywords that are matched against user intent
+ * using simple substring/word-overlap scoring.
+ */
+export declare const COMMAND_CATALOG: CatalogEntry[];
+/**
+ * Score a catalog entry against user intent.
+ *
+ * Uses a combined scoring approach:
+ * - Each exact keyword match earns 1 point (multi-word keywords earn 2)
+ * - Partial word overlap earns fractional points
+ * - Final score = matchPoints / max(totalWeight, 3) to avoid penalizing
+ *   entries with many keywords when only a few match.
+ *
+ * Returns a number between 0 and 1 where higher = better match.
+ */
+export declare function scoreMatch(intent: string, entry: CatalogEntry): number;
+/**
+ * Find the best matching command(s) for a user intent.
+ *
+ * @param intent - Natural language intent from the user
+ * @param threshold - Minimum score to include (0-1)
+ * @param maxResults - Maximum number of results to return
+ * @returns Sorted matches with scores
+ */
+export declare function findMatches(intent: string, threshold?: number, maxResults?: number): Array<{
+    entry: CatalogEntry;
+    score: number;
+}>;
+//# sourceMappingURL=command-catalog.d.ts.map

package/dist/prompts/command-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/prompts/command-catalog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,YAAY,EAwIzC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAuBtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,SAAM,EACf,UAAU,SAAI,GACb,KAAK,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAU/C"}

package/dist/prompts/command-catalog.js

@@ -0,0 +1,187 @@
+/**
+ * Command catalog for the `suggest` command.
+ *
+ * Maps natural-language intents to exact CLI commands.
+ * Used for local fuzzy matching before falling back to LLM API.
+ */
+/**
+ * Full command catalog for VertaaUX CLI.
+ *
+ * Each entry has keywords that are matched against user intent
+ * using simple substring/word-overlap scoring.
+ */
+export const COMMAND_CATALOG = [
+    // --- Audit Commands ---
+    {
+        command: "vertaa audit <url> --wait",
+        description: "Run a UX audit on a URL and wait for results",
+        keywords: ["audit", "scan", "check", "test", "run", "url", "website", "page", "site"],
+    },
+    {
+        command: "vertaa audit <url> --mode standard --wait",
+        description: "Run a standard-depth audit (more thorough than basic)",
+        keywords: ["standard", "thorough", "detailed", "full", "deep scan"],
+    },
+    {
+        command: "vertaa audit <url> --mode deep --wait",
+        description: "Run a deep audit with maximum coverage",
+        keywords: ["deep", "comprehensive", "maximum", "everything", "all checks"],
+    },
+    {
+        command: "vertaa audit <url> --wait --json",
+        description: "Run an audit and output JSON for piping to other commands",
+        keywords: ["json", "pipe", "machine", "ci", "scripting", "output json", "structured"],
+    },
+    {
+        command: "vertaa audit <url> --wait --fail-on-score 80",
+        description: "Run audit and fail CI if score is below 80",
+        keywords: ["ci", "gate", "fail", "threshold", "score", "pipeline", "quality gate"],
+    },
+    // --- Accessibility ---
+    {
+        command: "vertaa a11y <url> --wait",
+        description: "Run accessibility-focused audit",
+        keywords: ["accessibility", "a11y", "wcag", "aria", "screen reader", "accessible"],
+    },
+    {
+        command: "vertaa audit <url> --wait --json | vertaa explain",
+        description: "Audit a site and get an AI explanation of findings",
+        keywords: ["explain", "understand", "what", "why", "summary", "meaning"],
+    },
+    // --- Contrast & Color ---
+    {
+        command: "vertaa audit <url> --wait --json | vertaa triage",
+        description: "Audit and prioritize findings by severity",
+        keywords: ["contrast", "color", "triage", "prioritize", "priority", "important", "critical", "p0"],
+    },
+    // --- Compare ---
+    {
+        command: "vertaa compare <urlA> <urlB> --wait",
+        description: "Compare UX audits of two URLs",
+        keywords: ["compare", "diff", "versus", "vs", "difference", "before after", "regression"],
+    },
+    // --- Explain ---
+    {
+        command: "vertaa explain <finding-id> --job <job-id>",
+        description: "Show detailed evidence for a specific finding",
+        keywords: ["explain", "finding", "evidence", "detail", "issue", "specific"],
+    },
+    // --- Triage ---
+    {
+        command: "vertaa audit <url> --wait --json | vertaa triage",
+        description: "Prioritize audit findings into P0/P1/P2 buckets with effort estimates",
+        keywords: ["triage", "prioritize", "priority", "bucket", "effort", "plan", "what first"],
+    },
+    // --- Fix ---
+    {
+        command: "vertaa fix <jobId> --issue <id> --file-content \"...\"",
+        description: "Generate an auto-fix patch for a specific issue",
+        keywords: ["fix", "patch", "auto-fix", "repair", "resolve", "remediate"],
+    },
+    {
+        command: "vertaa fix-all <jobId> --file-content \"...\"",
+        description: "Generate fix patches for all issues in an audit",
+        keywords: ["fix all", "batch", "all issues", "bulk fix"],
+    },
+    // --- Diff ---
+    {
+        command: "vertaa diff --job-a <id> --job-b <id>",
+        description: "Compare two audit jobs to see what changed",
+        keywords: ["diff", "delta", "change", "compare jobs", "what changed"],
+    },
+    // --- Baseline ---
+    {
+        command: "vertaa baseline save",
+        description: "Save current audit results as a baseline for future comparison",
+        keywords: ["baseline", "save", "snapshot", "reference", "lock"],
+    },
+    // --- Policy ---
+    {
+        command: "vertaa policy show",
+        description: "Show the current audit policy configuration",
+        keywords: ["policy", "rules", "config", "configuration", "show policy"],
+    },
+    // --- Init & Setup ---
+    {
+        command: "vertaa init",
+        description: "Initialize a new VertaaUX project with configuration file",
+        keywords: ["init", "setup", "start", "new", "configure", "initialize", "create config"],
+    },
+    {
+        command: "vertaa login",
+        description: "Authenticate with VertaaUX API",
+        keywords: ["login", "auth", "authenticate", "sign in", "connect", "api key"],
+    },
+    {
+        command: "vertaa doctor",
+        description: "Run diagnostics on CLI configuration and connectivity",
+        keywords: ["doctor", "diagnostic", "health", "check", "debug", "troubleshoot", "problem"],
+    },
+    // --- Comment ---
+    {
+        command: "vertaa comment --job <id> --github-pr <number>",
+        description: "Post audit results as a GitHub PR comment",
+        keywords: ["comment", "pr", "pull request", "github", "gitlab", "post"],
+    },
+    // --- Upload/Download ---
+    {
+        command: "vertaa upload --file baseline.json",
+        description: "Upload a baseline file to the VertaaUX API",
+        keywords: ["upload", "push", "send"],
+    },
+    {
+        command: "vertaa download --job <id> --output results.json",
+        description: "Download audit results to a local file",
+        keywords: ["download", "pull", "fetch", "get", "save results"],
+    },
+];
+/**
+ * Score a catalog entry against user intent.
+ *
+ * Uses a combined scoring approach:
+ * - Each exact keyword match earns 1 point (multi-word keywords earn 2)
+ * - Partial word overlap earns fractional points
+ * - Final score = matchPoints / max(totalWeight, 3) to avoid penalizing
+ *   entries with many keywords when only a few match.
+ *
+ * Returns a number between 0 and 1 where higher = better match.
+ */
+export function scoreMatch(intent, entry) {
+    const lower = intent.toLowerCase();
+    const words = lower.split(/\s+/).filter(Boolean);
+    let matchPoints = 0;
+    for (const keyword of entry.keywords) {
+        const kw = keyword.toLowerCase();
+        const weight = kw.includes(" ") ? 2 : 1;
+        if (lower.includes(kw)) {
+            matchPoints += weight;
+        }
+        else {
+            // Partial word overlap
+            const kwWords = kw.split(/\s+/);
+            const overlap = kwWords.filter((w) => words.includes(w)).length / kwWords.length;
+            matchPoints += weight * overlap * 0.5;
+        }
+    }
+    // Normalize: divide by a minimum of 3 so that 1 exact match = 0.33 (above threshold)
+    const normalizer = Math.max(entry.keywords.length, 3);
+    return normalizer > 0 ? Math.min(matchPoints / normalizer, 1) : 0;
+}
+/**
+ * Find the best matching command(s) for a user intent.
+ *
+ * @param intent - Natural language intent from the user
+ * @param threshold - Minimum score to include (0-1)
+ * @param maxResults - Maximum number of results to return
+ * @returns Sorted matches with scores
+ */
+export function findMatches(intent, threshold = 0.1, maxResults = 3) {
+    const scored = COMMAND_CATALOG.map((entry) => ({
+        entry,
+        score: scoreMatch(intent, entry),
+    }));
+    return scored
+        .filter((m) => m.score >= threshold)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}

package/dist/ui/spinner.d.ts

@@ -1,61 +1,36 @@
 /**
  * Progress spinner wrapper for CLI.
  *
- * Provides a consistent interface for showing progress during long-running operations.
- * Uses ora for elegant terminal spinners with TTY detection.
+ * Delegates to @vertaaux/tui for consistent terminal rendering.
+ * Writes ONLY to stderr — never pollutes stdout.
  */
-import { type Ora } from "ora";
-export interface SpinnerOptions {
-    /** Initial text to display */
-    text: string;
-    /** Color for the spinner (default: brand lime) */
-    color?: string;
-}
+import { type SpinnerInstance } from "@vertaaux/tui";
+export type { SpinnerInstance };
 /**
  * Create a new spinner instance.
  *
  * Spinner only displays in TTY mode. In non-TTY environments,
  * returns a no-op spinner that still tracks state.
- *
- * @param text - Initial text to display next to spinner
- * @returns An ora spinner instance
  */
-export declare function createSpinner(text: string): Ora;
+export declare function createSpinner(text: string): SpinnerInstance;
 /**
  * Update spinner text with optional progress indicator.
- *
- * @param spinner - The spinner instance to update
- * @param text - New text to display
- * @param current - Current progress count (optional)
- * @param total - Total items count (optional)
  */
-export declare function updateSpinner(spinner: Ora, text: string, current?: number, total?: number): void;
+export declare function updateSpinner(spinner: SpinnerInstance, text: string, current?: number, total?: number): void;
 /**
  * Complete spinner with success state.
- *
- * @param spinner - The spinner instance
- * @param text - Success message to display
  */
-export declare function succeedSpinner(spinner: Ora, text: string): void;
+export declare function succeedSpinner(spinner: SpinnerInstance, text: string): void;
 /**
  * Complete spinner with failure state.
- *
- * @param spinner - The spinner instance
- * @param text - Failure message to display
  */
-export declare function failSpinner(spinner: Ora, text: string): void;
+export declare function failSpinner(spinner: SpinnerInstance, text: string): void;
 /**
  * Complete spinner with warning state.
- *
- * @param spinner - The spinner instance
- * @param text - Warning message to display
  */
-export declare function warnSpinner(spinner: Ora, text: string): void;
+export declare function warnSpinner(spinner: SpinnerInstance, text: string): void;
 /**
  * Complete spinner with info state.
- *
- * @param spinner - The spinner instance
- * @param text - Info message to display
  */
-export declare function infoSpinner(spinner: Ora, text: string): void;
+export declare function infoSpinner(spinner: SpinnerInstance, text: string): void;
 //# sourceMappingURL=spinner.d.ts.map

package/dist/ui/spinner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/ui/spinner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAY,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAapC,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAiB/C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAcN;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D"}
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/ui/spinner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAE3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAQN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAExE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAExE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAExE"}