@vertaaux/cli 0.2.0

package/dist/utils/exit-codes.js

@@ -0,0 +1,61 @@
+/**
+ * Semantic exit codes for CLI commands (CLI-12).
+ *
+ * CI tools depend on exit codes for gating decisions.
+ * These codes allow distinguishing between:
+ * - Success (no issues)
+ * - Issues found (but not necessarily a failure)
+ * - Runtime errors
+ * - Threshold/score failures
+ */
+export const ExitCode = {
+    /** Audit passed, no issues above threshold */
+    SUCCESS: 0,
+    /** Issues found at or above specified severity */
+    ISSUES_FOUND: 1,
+    /** Runtime error, invalid input, network failure */
+    ERROR: 2,
+    /** Score below threshold */
+    THRESHOLD_BREACH: 3,
+};
+/** Severity ranking for comparison */
+const SEVERITY_RANK = {
+    error: 3,
+    critical: 3,
+    warning: 2,
+    serious: 2,
+    info: 1,
+    minor: 1,
+    moderate: 1,
+};
+function severityRank(severity) {
+    return SEVERITY_RANK[severity.toLowerCase()] ?? 0;
+}
+/**
+ * Determine the appropriate exit code based on audit results and options.
+ *
+ * @param result - The audit result
+ * @param options - Exit code determination options
+ * @returns The semantic exit code
+ */
+export function determineExitCode(result, options = {}) {
+    // Runtime errors take precedence
+    if (result.error) {
+        return ExitCode.ERROR;
+    }
+    // Check threshold breach
+    if (options.threshold !== undefined &&
+        result.scores?.overall !== undefined &&
+        result.scores.overall < options.threshold) {
+        return ExitCode.THRESHOLD_BREACH;
+    }
+    // Check severity-based failure
+    if (options.failOn && result.issues) {
+        const hasSevereIssues = result.issues.some((issue) => issue.severity &&
+            severityRank(issue.severity) >= severityRank(options.failOn));
+        if (hasSevereIssues) {
+            return ExitCode.ISSUES_FOUND;
+        }
+    }
+    return ExitCode.SUCCESS;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Structured logging for CI environments.
+ *
+ * Provides both human-readable and JSON log output modes,
+ * with automatic CI environment detection.
+ */
+/**
+ * Log levels in order of severity.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Structured log entry.
+ */
+export interface LogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Logger configuration options.
+ */
+export interface LoggerOptions {
+    /** Minimum log level to output */
+    level: LogLevel;
+    /** Output JSON format (for CI parsing) */
+    json: boolean;
+    /** Include timestamps in output */
+    timestamps: boolean;
+    /** Automatically include context in all log calls */
+    autoContext: boolean;
+}
+/**
+ * Logger interface.
+ */
+export interface Logger {
+    /** Log debug message */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /** Log info message */
+    info(message: string, context?: Record<string, unknown>): void;
+    /** Log warning message */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /** Log error message */
+    error(message: string, context?: Record<string, unknown>): void;
+    /** Create child logger with additional context */
+    child(context: Record<string, unknown>): Logger;
+}
+/**
+ * Create a structured logger.
+ *
+ * @param options - Logger configuration options
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const logger = createLogger({ level: 'debug' });
+ * logger.info('Starting audit', { url: 'https://example.com' });
+ *
+ * // CI usage (JSON output)
+ * const ciLogger = createLogger({ json: true });
+ * ciLogger.info('Route cached', { route: '/about', contentHash: 'abc123' });
+ * // Output: {"timestamp":"2026-01-28T12:00:00Z","level":"info","message":"Route cached","context":{"route":"/about","contentHash":"abc123"}}
+ *
+ * // Child logger with bound context
+ * const wsLogger = logger.child({ workspace: 'web-app' });
+ * wsLogger.info('Auditing workspace');
+ * // Output includes workspace in context
+ * ```
+ */
+export declare function createLogger(options?: Partial<LoggerOptions>): Logger;
+/**
+ * Get a logger with CI-appropriate defaults.
+ *
+ * - JSON output in CI environments
+ * - Human-readable output in local development
+ * - Respects VERTAAUX_LOG_LEVEL and VERTAAUX_LOG_JSON env vars
+ *
+ * @returns Logger instance
+ */
+export declare function getCILogger(): Logger;
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAY3D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,QAAQ,CAAC;IAChB,0CAA0C;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,wBAAwB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,uBAAuB;IACvB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,0BAA0B;IAC1B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,wBAAwB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,kDAAkD;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACjD;AAuKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,MAAM,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAGD,eAAO,MAAM,MAAM,QAAiB,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,185 @@
+/**
+ * Structured logging for CI environments.
+ *
+ * Provides both human-readable and JSON log output modes,
+ * with automatic CI environment detection.
+ */
+/**
+ * Numeric values for log level comparison.
+ */
+const LOG_LEVEL_VALUES = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Default logger options.
+ */
+const DEFAULT_OPTIONS = {
+    level: "info",
+    json: false,
+    timestamps: true,
+    autoContext: false,
+};
+/**
+ * Detect if running in CI environment.
+ */
+function isCI() {
+    return !!(process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.CIRCLECI ||
+        process.env.JENKINS_URL ||
+        process.env.BUILDKITE ||
+        process.env.TRAVIS);
+}
+/**
+ * Get default options based on environment.
+ */
+function getDefaultOptions() {
+    const options = { ...DEFAULT_OPTIONS };
+    // In CI, prefer JSON output
+    if (isCI()) {
+        options.json = true;
+    }
+    // Check environment variables
+    if (process.env.VERTAAUX_LOG_LEVEL) {
+        const level = process.env.VERTAAUX_LOG_LEVEL.toLowerCase();
+        if (LOG_LEVEL_VALUES[level] !== undefined) {
+            options.level = level;
+        }
+    }
+    if (process.env.VERTAAUX_LOG_JSON === "true") {
+        options.json = true;
+    }
+    else if (process.env.VERTAAUX_LOG_JSON === "false") {
+        options.json = false;
+    }
+    return options;
+}
+/**
+ * Format log entry for JSON output.
+ */
+function formatJson(entry) {
+    return JSON.stringify(entry);
+}
+/**
+ * Format log entry for human-readable output.
+ */
+function formatHuman(entry, showTimestamp) {
+    const parts = [];
+    if (showTimestamp) {
+        // Use short timestamp format
+        const time = new Date(entry.timestamp).toISOString().split("T")[1].slice(0, 8);
+        parts.push(`[${time}]`);
+    }
+    // Level with color
+    const levelStr = entry.level.toUpperCase().padEnd(5);
+    parts.push(levelStr);
+    // Message
+    parts.push(entry.message);
+    // Context (if present)
+    if (entry.context && Object.keys(entry.context).length > 0) {
+        const contextStr = Object.entries(entry.context)
+            .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+            .join(" ");
+        parts.push(`(${contextStr})`);
+    }
+    return parts.join(" ");
+}
+/**
+ * Internal logger implementation.
+ */
+class LoggerImpl {
+    options;
+    baseContext;
+    constructor(options = {}, baseContext = {}) {
+        this.options = { ...getDefaultOptions(), ...options };
+        this.baseContext = baseContext;
+    }
+    log(level, message, context) {
+        // Check if this level should be logged
+        if (LOG_LEVEL_VALUES[level] < LOG_LEVEL_VALUES[this.options.level]) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+        };
+        // Merge contexts
+        const mergedContext = {
+            ...(this.options.autoContext ? this.baseContext : {}),
+            ...this.baseContext,
+            ...context,
+        };
+        if (Object.keys(mergedContext).length > 0) {
+            entry.context = mergedContext;
+        }
+        // Format and output
+        const output = this.options.json
+            ? formatJson(entry)
+            : formatHuman(entry, this.options.timestamps);
+        // All logger output goes to stderr -- logs are diagnostics, never primary command output
+        process.stderr.write(output + "\n");
+    }
+    debug(message, context) {
+        this.log("debug", message, context);
+    }
+    info(message, context) {
+        this.log("info", message, context);
+    }
+    warn(message, context) {
+        this.log("warn", message, context);
+    }
+    error(message, context) {
+        this.log("error", message, context);
+    }
+    child(context) {
+        return new LoggerImpl(this.options, {
+            ...this.baseContext,
+            ...context,
+        });
+    }
+}
+/**
+ * Create a structured logger.
+ *
+ * @param options - Logger configuration options
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const logger = createLogger({ level: 'debug' });
+ * logger.info('Starting audit', { url: 'https://example.com' });
+ *
+ * // CI usage (JSON output)
+ * const ciLogger = createLogger({ json: true });
+ * ciLogger.info('Route cached', { route: '/about', contentHash: 'abc123' });
+ * // Output: {"timestamp":"2026-01-28T12:00:00Z","level":"info","message":"Route cached","context":{"route":"/about","contentHash":"abc123"}}
+ *
+ * // Child logger with bound context
+ * const wsLogger = logger.child({ workspace: 'web-app' });
+ * wsLogger.info('Auditing workspace');
+ * // Output includes workspace in context
+ * ```
+ */
+export function createLogger(options = {}) {
+    return new LoggerImpl(options);
+}
+/**
+ * Get a logger with CI-appropriate defaults.
+ *
+ * - JSON output in CI environments
+ * - Human-readable output in local development
+ * - Respects VERTAAUX_LOG_LEVEL and VERTAAUX_LOG_JSON env vars
+ *
+ * @returns Logger instance
+ */
+export function getCILogger() {
+    return createLogger();
+}
+// Export a default logger instance for convenience
+export const logger = createLogger();

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Centralized input validation for the VertaaUX CLI.
+ *
+ * Provides validation functions to prevent:
+ * - Command injection via branch names (SEC-01)
+ * - Path traversal via artifact filenames (SEC-02)
+ *
+ * These are pure validation functions -- they throw on invalid input
+ * and return the validated value on success. Callers decide how to
+ * handle errors (exit codes, logging, etc.).
+ */
+/**
+ * Validate a git branch name against an allowlist of safe characters.
+ *
+ * Rejects branch names containing shell metacharacters, backticks,
+ * semicolons, pipes, dollar signs, or other characters that could
+ * enable command injection when interpolated into shell commands.
+ *
+ * @param branch - The branch name to validate
+ * @returns The branch name unchanged if valid
+ * @throws Error if the branch name contains disallowed characters, is empty, or exceeds 255 characters
+ */
+export declare function validateBranchName(branch: string): string;
+/**
+ * Assert that a candidate path resolves within the given root directory.
+ *
+ * Prevents path traversal attacks where filenames like "../../../etc/passwd"
+ * could write to arbitrary filesystem locations.
+ *
+ * @param candidatePath - The relative path to check (e.g., an artifact filename from an API response)
+ * @param rootDir - The root directory that the path must stay within
+ * @returns The resolved absolute path if it is contained within rootDir
+ * @throws Error if the resolved path escapes the root directory
+ */
+export declare function assertPathContainment(candidatePath: string, rootDir: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoBzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWpF"}

package/dist/utils/sanitize.js

@@ -0,0 +1,64 @@
+/**
+ * Centralized input validation for the VertaaUX CLI.
+ *
+ * Provides validation functions to prevent:
+ * - Command injection via branch names (SEC-01)
+ * - Path traversal via artifact filenames (SEC-02)
+ *
+ * These are pure validation functions -- they throw on invalid input
+ * and return the validated value on success. Callers decide how to
+ * handle errors (exit codes, logging, etc.).
+ */
+import path from "path";
+/**
+ * Allowlist regex for valid git branch names.
+ *
+ * Permits: letters, digits, dots, underscores, hyphens, forward slashes.
+ * This covers standard branch naming conventions like:
+ *   main, feature/login, release/v1.2.3, hotfix-123, my_branch
+ */
+const BRANCH_NAME_REGEX = /^[a-zA-Z0-9._\/-]+$/;
+/** Maximum allowed branch name length. */
+const MAX_BRANCH_NAME_LENGTH = 255;
+/**
+ * Validate a git branch name against an allowlist of safe characters.
+ *
+ * Rejects branch names containing shell metacharacters, backticks,
+ * semicolons, pipes, dollar signs, or other characters that could
+ * enable command injection when interpolated into shell commands.
+ *
+ * @param branch - The branch name to validate
+ * @returns The branch name unchanged if valid
+ * @throws Error if the branch name contains disallowed characters, is empty, or exceeds 255 characters
+ */
+export function validateBranchName(branch) {
+    if (!branch || branch.length === 0) {
+        throw new Error('Invalid branch name: "". Branch names may only contain letters, digits, dots, underscores, hyphens, and forward slashes.');
+    }
+    if (branch.length > MAX_BRANCH_NAME_LENGTH) {
+        throw new Error(`Invalid branch name: "${branch}". Branch names may only contain letters, digits, dots, underscores, hyphens, and forward slashes.`);
+    }
+    if (!BRANCH_NAME_REGEX.test(branch)) {
+        throw new Error(`Invalid branch name: "${branch}". Branch names may only contain letters, digits, dots, underscores, hyphens, and forward slashes.`);
+    }
+    return branch;
+}
+/**
+ * Assert that a candidate path resolves within the given root directory.
+ *
+ * Prevents path traversal attacks where filenames like "../../../etc/passwd"
+ * could write to arbitrary filesystem locations.
+ *
+ * @param candidatePath - The relative path to check (e.g., an artifact filename from an API response)
+ * @param rootDir - The root directory that the path must stay within
+ * @returns The resolved absolute path if it is contained within rootDir
+ * @throws Error if the resolved path escapes the root directory
+ */
+export function assertPathContainment(candidatePath, rootDir) {
+    const normalizedRoot = path.resolve(rootDir);
+    const resolved = path.resolve(rootDir, candidatePath);
+    if (resolved !== normalizedRoot && !resolved.startsWith(normalizedRoot + path.sep)) {
+        throw new Error(`Path traversal rejected: "${candidatePath}" resolves outside output directory "${rootDir}".`);
+    }
+    return resolved;
+}

package/dist/utils/validators.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure validation functions for CLI option parsing.
+ *
+ * All validators throw Commander's InvalidArgumentError on failure,
+ * which integrates with Commander's built-in error handling pipeline.
+ * No process.exit calls -- callers decide error handling.
+ *
+ * Includes Levenshtein distance for "Did you mean?" suggestions on enum typos.
+ */
+/**
+ * Find the closest match for `input` among `candidates` using Levenshtein distance.
+ * Returns null if no candidate is within `maxDistance`.
+ */
+export declare function closestMatch(input: string, candidates: readonly string[], maxDistance?: number): string | null;
+export interface NumericConstraint {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}
+/**
+ * Validate and parse a numeric string value.
+ * Throws InvalidArgumentError with descriptive message on failure.
+ *
+ * Uses Number() (not parseInt) to reject partial parses like "12abc".
+ */
+export declare function validateNumeric(value: string, name: string, constraints?: NumericConstraint): number;
+/**
+ * Validate a string value against an allowed set.
+ * Throws InvalidArgumentError with "Did you mean?" suggestion on typos.
+ */
+export declare function validateEnum(value: string, name: string, allowed: readonly string[]): string;
+export declare function parseTimeout(value: string): number;
+export declare function parseInterval(value: string): number;
+export declare function parseConcurrency(value: string): number;
+export declare function parseThreshold(value: string): number;
+export declare function parseScore(value: string): number;
+export declare function parseMode(value: string): string;
+export declare function parseFailOn(value: string): string;
+export declare function parseGroupBy(value: string): string;
+export declare function parseBudget(value: string): string;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsCH;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,WAAW,SAAI,GACd,MAAM,GAAG,IAAI,CAaf;AAMD,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,iBAAsB,GAClC,MAAM,CAkCR;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CASR;AAQD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/utils/validators.js

@@ -0,0 +1,123 @@
+/**
+ * Pure validation functions for CLI option parsing.
+ *
+ * All validators throw Commander's InvalidArgumentError on failure,
+ * which integrates with Commander's built-in error handling pipeline.
+ * No process.exit calls -- callers decide error handling.
+ *
+ * Includes Levenshtein distance for "Did you mean?" suggestions on enum typos.
+ */
+import { InvalidArgumentError } from "commander";
+// ---------------------------------------------------------------------------
+// Levenshtein distance (private)
+// ---------------------------------------------------------------------------
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Case-insensitive comparison.
+ */
+function levenshtein(a, b) {
+    const al = a.toLowerCase();
+    const bl = b.toLowerCase();
+    const m = al.length;
+    const n = bl.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] =
+                al[i - 1] === bl[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+// ---------------------------------------------------------------------------
+// Closest match
+// ---------------------------------------------------------------------------
+/**
+ * Find the closest match for `input` among `candidates` using Levenshtein distance.
+ * Returns null if no candidate is within `maxDistance`.
+ */
+export function closestMatch(input, candidates, maxDistance = 3) {
+    let best = null;
+    let bestDist = maxDistance + 1;
+    for (const candidate of candidates) {
+        const dist = levenshtein(input, candidate);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * Validate and parse a numeric string value.
+ * Throws InvalidArgumentError with descriptive message on failure.
+ *
+ * Uses Number() (not parseInt) to reject partial parses like "12abc".
+ */
+export function validateNumeric(value, name, constraints = {}) {
+    if (value.trim() === "") {
+        throw new InvalidArgumentError(`Invalid value for --${name}: "${value}" is not a number`);
+    }
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        throw new InvalidArgumentError(`Invalid value for --${name}: "${value}" is not a number`);
+    }
+    if (constraints.integer && !Number.isInteger(parsed)) {
+        throw new InvalidArgumentError(`Invalid value for --${name}: "${value}" must be an integer`);
+    }
+    if (constraints.min !== undefined && parsed < constraints.min) {
+        throw new InvalidArgumentError(`Invalid value for --${name}: ${parsed} is below minimum ${constraints.min}`);
+    }
+    if (constraints.max !== undefined && parsed > constraints.max) {
+        throw new InvalidArgumentError(`Invalid value for --${name}: ${parsed} exceeds maximum ${constraints.max}`);
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Enum validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a string value against an allowed set.
+ * Throws InvalidArgumentError with "Did you mean?" suggestion on typos.
+ */
+export function validateEnum(value, name, allowed) {
+    if (allowed.includes(value))
+        return value;
+    const suggestion = closestMatch(value, allowed);
+    const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
+    throw new InvalidArgumentError(`Unknown value "${value}" for --${name}.${hint} Valid values: ${allowed.join(", ")}`);
+}
+// ---------------------------------------------------------------------------
+// Convenience Commander parser factories
+// ---------------------------------------------------------------------------
+// These are used as the 3rd argument to Commander's .option() method.
+// Commander catches InvalidArgumentError and routes it through configureOutput.
+export function parseTimeout(value) {
+    return validateNumeric(value, "timeout", { min: 1, max: 300000, integer: true });
+}
+export function parseInterval(value) {
+    return validateNumeric(value, "interval", { min: 1, max: 300000, integer: true });
+}
+export function parseConcurrency(value) {
+    return validateNumeric(value, "concurrency", { min: 1, max: 50, integer: true });
+}
+export function parseThreshold(value) {
+    return validateNumeric(value, "threshold", { min: 0, max: 100, integer: true });
+}
+export function parseScore(value) {
+    return validateNumeric(value, "fail-on-score", { min: 0, max: 100, integer: true });
+}
+export function parseMode(value) {
+    return validateEnum(value, "mode", ["basic", "standard", "deep"]);
+}
+export function parseFailOn(value) {
+    return validateEnum(value, "fail-on", ["error", "warning", "info", "none"]);
+}
+export function parseGroupBy(value) {
+    return validateEnum(value, "group-by", ["severity", "category", "route"]);
+}
+export function parseBudget(value) {
+    return validateEnum(value, "budget", ["quick", "standard", "full"]);
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@vertaaux/cli",
+  "version": "0.2.0",
+  "description": "VertaaUX CLI for UX audits, accessibility checks, and CI gating.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "vertaa": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md"
+  ],
+  "keywords": [
+    "vertaaux",
+    "vertaa",
+    "cli",
+    "ux",
+    "audit",
+    "accessibility",
+    "a11y",
+    "ci"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertaaux/vertaa"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build && node scripts/verify-package.mjs",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "cosmiconfig": "^9.0.0",
+    "dotenv": "^17.2.3",
+    "minimatch": "^10.1.1",
+    "ora": "^9.1.0",
+    "semver": "^7.7.3",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/minimatch": "^5.1.2",
+    "@types/node": "^20.11.25",
+    "@types/semver": "^7.7.1",
+    "typescript": "^5.6.3"
+  }
+}