@vertaaux/cli 0.2.0

package/README.md

@@ -0,0 +1,345 @@
+# VertaaUX CLI
+
+Run UX and accessibility audits from the terminal or CI pipelines.
+
+## Install
+
+```bash
+npm install -g @vertaaux/cli
+```
+
+Or run with npx:
+
+```bash
+npx @vertaaux/cli --help
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+vertaa login
+
+# 2. Run an audit
+vertaa audit https://example.com --wait
+
+# 3. Check CLI health
+vertaa doctor
+```
+
+## Authentication
+
+The CLI checks for credentials in this order:
+
+1. **Environment variables** (checked in order):
+   - `VERTAAUX_TOKEN`
+   - `VERTAAUX_API_KEY`
+
+2. **Stored credentials** from interactive login:
+   ```bash
+   vertaa login
+   ```
+   Credentials are stored in `~/.vertaaux/credentials.json`.
+
+3. **Direct token** for CI/non-interactive use:
+   ```bash
+   vertaa login --token <api-key>
+   ```
+
+Verify authentication:
+
+```bash
+vertaa whoami
+```
+
+## Commands
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `audit <url>` | Run UX and accessibility audit |
+| `baseline [job-id]` | Create or update audit baseline |
+| `diff` | Compare current audit against baseline |
+| `policy init\|validate\|show\|schema` | Manage policy-as-code |
+
+### Analysis and Remediation
+
+| Command | Description |
+|---------|-------------|
+| `explain <finding-id>` | Show evidence bundle for a finding |
+| `comment` | Generate PR comment from audit results |
+| `fix <job-id>` | Generate a fix patch for an issue |
+| `fix-all <job-id>` | Generate fix patches for all issues |
+| `verify` | Verify that a patch fixes an issue |
+
+### Utility
+
+| Command | Description |
+|---------|-------------|
+| `doctor` | Diagnose CLI health (config, auth, network) |
+| `login` | Authenticate with VertaaUX |
+| `logout` | Clear stored credentials |
+| `whoami` | Show current authentication status |
+| `init` | Create `.vertaaux.yml` configuration |
+| `status <job-id>` | Check audit job status |
+| `upload <file>` | Upload audit results to cloud storage |
+| `download <id>` | Download audit results from cloud storage |
+
+### Aliases
+
+| Command | Alias For |
+|---------|-----------|
+| `a11y <url>` | Accessibility-focused audit (filters for a11y issues) |
+| `scan <url>` | UX scan (alias for audit) |
+| `compare <urlA> <urlB>` | Compare audits of two URLs |
+
+## Output Formats
+
+Formats are **per-command**, not global. Each command supports a different set of formats:
+
+| Command | Formats | Default |
+|---------|---------|---------|
+| `audit` | `human`, `json`, `sarif`, `junit`, `html` | `human` |
+| `comment` | `json`, `markdown` | `markdown` |
+| `explain` | `human`, `json` | `human` |
+| `policy show` | `json`, `yaml` | `yaml` |
+| `diff` | `human`, `json` | `human` |
+
+Usage:
+
+```bash
+vertaa audit https://example.com --format json
+vertaa audit https://example.com --format sarif > results.sarif
+vertaa comment --input results.json --format markdown
+```
+
+### Machine-Readable Output
+
+The `--machine` global flag enables strict machine-readable mode:
+
+- **stdout**: JSON data only (no banners, no diagnostics)
+- **stderr**: All diagnostic and progress output
+- JSON output is wrapped in an envelope:
+
+```json
+{
+  "meta": {
+    "version": "0.1.0",
+    "timestamp": "2026-02-08T12:00:00.000Z",
+    "command": "audit",
+    "args": ["https://example.com", "--format", "json"]
+  },
+  "data": {
+    "scores": { "overall": 85 },
+    "issues": []
+  }
+}
+```
+
+### Piping
+
+All diagnostic output goes to stderr, keeping stdout clean for piping:
+
+```bash
+vertaa audit https://example.com --format json | jq '.data.scores'
+vertaa audit https://example.com --format json > results.json
+```
+
+## Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `-b, --base <url>` | API base URL override |
+| `-c, --config <path>` | Explicit config file path |
+| `-q, --quiet` | Suppress banner and non-essential output |
+| `--no-banner` | Hide the V-mark banner |
+| `--machine` | Strict machine-readable output mode |
+| `-v, --version` | Show version number |
+| `-h, --help` | Show help for command |
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| `0` | Success | Audit passed, no issues above threshold |
+| `1` | Issues found | Issues at or above `--fail-on` severity |
+| `2` | Error | Invalid input, validation errors, network failures |
+| `3` | Threshold breach | Score below `--threshold` value |
+
+Exit code `2` is used for all validation errors, including:
+- Invalid flag values (`--timeout abc`)
+- Unknown enum values (`--mode bogus`)
+- Missing required arguments
+
+## Configuration
+
+The CLI uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration file auto-detection.
+
+### Config File Search Order
+
+1. `.vertaaux.yml`
+2. `.vertaaux.yaml`
+3. `.vertaaux.json`
+4. `vertaaux.config.js`
+5. `vertaaux.config.mjs`
+6. `vertaaux.config.cjs`
+7. `package.json` (`vertaaux` key)
+
+Or specify explicitly:
+
+```bash
+vertaa audit https://example.com --config path/to/.vertaaux.yml
+```
+
+### Configuration Precedence
+
+```
+flag > env var > config file > default
+```
+
+### Key Config Fields
+
+From `VertaauxConfig` interface in `src/config/schema.ts`:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `basic\|standard\|deep` | `basic` | Audit depth |
+| `threshold` | `number` | `0` | Minimum passing score (0-100) |
+| `failOn` | `error\|warning\|info` | - | Fail on severity |
+| `output.format` | `auto\|json\|sarif\|...` | `auto` | Output format |
+| `output.groupBy` | `severity\|category\|route` | `severity` | Issue grouping |
+| `baseline.path` | `string` | `.vertaaux/baseline.json` | Baseline file path |
+| `baseline.autoUpdate` | `boolean` | `false` | Auto-update baseline |
+| `ci.template` | `github\|gitlab\|...` | `none` | CI template |
+| `timeout` | `number` | `60000` | Audit timeout (ms) |
+| `interval` | `number` | `5000` | Poll interval (ms) |
+
+### Example Configuration
+
+```yaml
+# .vertaaux.yml
+$schema: https://vertaaux.ai/schemas/config.json
+
+mode: standard
+threshold: 80
+failOn: error
+
+output:
+  format: auto
+  groupBy: severity
+
+baseline:
+  path: .vertaaux/baseline.json
+  autoUpdate: false
+
+ci:
+  template: github
+
+timeout: 60000
+interval: 5000
+```
+
+Create a starter configuration:
+
+```bash
+vertaa init
+vertaa init --ci github --yes
+```
+
+## Security
+
+### Branch Name Validation
+
+Branch names passed via `--base-branch` and `--branch` flags are validated against an allowlist regex:
+
+```
+/^[a-zA-Z0-9._\/-]+$/
+```
+
+- Maximum length: 255 characters
+- Shell metacharacters (`;`, `|`, `$`, `` ` ``, etc.) are rejected
+- Standard git branch names work as expected: `main`, `feature/login`, `release/v1.2.3`
+
+### Artifact Path Protection
+
+Downloaded artifact filenames are validated to stay within the output directory:
+
+- Path traversal attempts (`../`) are rejected with an error
+- All artifact paths are resolved and checked against the target directory boundary
+- This prevents writing to arbitrary filesystem locations
+
+### Credential Filtering
+
+JSON envelope output automatically filters CLI arguments containing API keys or Bearer tokens from the `args` metadata field.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `VERTAAUX_API_KEY` | API authentication key |
+| `VERTAAUX_TOKEN` | Alternative auth token (checked first) |
+| `VERTAAUX_API_BASE` | API base URL override |
+| `NO_COLOR` | Disable colored output |
+| `FORCE_COLOR` | Force colored output |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Run audit
+  env:
+    VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
+  run: |
+    npx @vertaaux/cli audit https://example.com \
+      --format sarif \
+      --fail-on error \
+      --threshold 80
+```
+
+### Exit Code Gating
+
+```bash
+# Fail CI if score below 80
+vertaa audit https://example.com --threshold 80
+
+# Fail CI if any error-severity issues found
+vertaa audit https://example.com --fail-on error
+
+# Both
+vertaa audit https://example.com --threshold 80 --fail-on error
+```
+
+## Error Messages
+
+The CLI provides branded error messages with contextual help:
+
+```
+vertaa error: expected a number, got "abc"
+  ──────────────────────────────────
+  │ flag: --timeout
+  │ value: abc
+  │
+  │ hint: Run vertaa <command> --help for all options
+  ──────────────────────────────────
+```
+
+For enum values, typo suggestions are provided:
+
+```
+vertaa error: invalid value for --mode
+  │ flag: --mode
+  │ value: depp
+  │
+  │ hint: Did you mean "deep"?
+  │ valid: basic, standard, deep
+```
+
+## Related
+
+- [Migration Guide](./MIGRATION.md) -- Breaking changes in this release
+- [Configuration Docs](https://vertaaux.ai/docs/cli/configuration) -- Full config reference
+- [CI/CD Integration](https://vertaaux.ai/docs/cli/cicd) -- Pipeline setup guides

package/dist/auth/ci-token.d.ts

@@ -0,0 +1,49 @@
+/**
+ * CI token handling for VertaaUX CLI.
+ *
+ * CI tokens are long-lived API keys used in CI/CD pipelines.
+ * They can be passed via environment variables or --token flag.
+ */
+/**
+ * Get CI token from environment variables.
+ *
+ * Checks VERTAAUX_TOKEN first, then VERTAAUX_API_KEY.
+ *
+ * @returns Token string or null if not found
+ */
+export declare function getCIToken(): string | null;
+/**
+ * API response for token validation.
+ */
+interface TokenValidationResponse {
+    /** Whether token is valid */
+    valid: boolean;
+    /** User or organization ID */
+    user_id?: string;
+    /** Organization name */
+    organization?: string;
+    /** Scopes granted to token */
+    scopes?: string[];
+    /** Token expiration (if any) */
+    expires_at?: string;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Validate a CI token against the API.
+ *
+ * @param token - Token to validate
+ * @param apiBase - API base URL (optional)
+ * @returns true if token is valid
+ */
+export declare function validateCIToken(token: string, apiBase?: string): Promise<boolean>;
+/**
+ * Get token info from the API.
+ *
+ * @param token - Token to check
+ * @param apiBase - API base URL (optional)
+ * @returns Token info or null if invalid/error
+ */
+export declare function getTokenInfo(token: string, apiBase?: string): Promise<TokenValidationResponse | null>;
+export {};
+//# sourceMappingURL=ci-token.d.ts.map

package/dist/auth/ci-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-token.d.ts","sourceRoot":"","sources":["../../src/auth/ci-token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAQ1C;AAED;;GAEG;AACH,UAAU,uBAAuB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAyB,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAkBzC"}

package/dist/auth/ci-token.js

@@ -0,0 +1,83 @@
+/**
+ * CI token handling for VertaaUX CLI.
+ *
+ * CI tokens are long-lived API keys used in CI/CD pipelines.
+ * They can be passed via environment variables or --token flag.
+ */
+/**
+ * Environment variable names for CI tokens.
+ * Checked in order of preference.
+ */
+const TOKEN_ENV_VARS = ["VERTAAUX_TOKEN", "VERTAAUX_API_KEY"];
+/**
+ * Get CI token from environment variables.
+ *
+ * Checks VERTAAUX_TOKEN first, then VERTAAUX_API_KEY.
+ *
+ * @returns Token string or null if not found
+ */
+export function getCIToken() {
+    for (const envVar of TOKEN_ENV_VARS) {
+        const value = process.env[envVar];
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Default API base URL.
+ */
+const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
+/**
+ * Validate a CI token against the API.
+ *
+ * @param token - Token to validate
+ * @param apiBase - API base URL (optional)
+ * @returns true if token is valid
+ */
+export async function validateCIToken(token, apiBase = DEFAULT_API_BASE) {
+    try {
+        const response = await fetch(`${apiBase}/auth/validate`, {
+            method: "GET",
+            headers: {
+                "X-API-Key": token,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const data = (await response.json());
+        return data.valid === true;
+    }
+    catch {
+        // Network errors mean we can't validate, treat as invalid
+        return false;
+    }
+}
+/**
+ * Get token info from the API.
+ *
+ * @param token - Token to check
+ * @param apiBase - API base URL (optional)
+ * @returns Token info or null if invalid/error
+ */
+export async function getTokenInfo(token, apiBase = DEFAULT_API_BASE) {
+    try {
+        const response = await fetch(`${apiBase}/auth/validate`, {
+            method: "GET",
+            headers: {
+                "X-API-Key": token,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        return response.json();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OAuth Device Code Flow implementation (RFC 8628).
+ *
+ * Used for interactive authentication where the user authenticates
+ * in a browser and the CLI polls for completion.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+/**
+ * Device code response from authorization server.
+ */
+export interface DeviceCodeResponse {
+    /** Device verification code */
+    device_code: string;
+    /** User code to display */
+    user_code: string;
+    /** Verification URL for user to visit */
+    verification_uri: string;
+    /** Optional complete URL with user_code embedded */
+    verification_uri_complete?: string;
+    /** Recommended polling interval in seconds */
+    interval: number;
+    /** Code expiration in seconds */
+    expires_in: number;
+}
+/**
+ * Token response from authorization server.
+ */
+export interface TokenResponse {
+    /** Access token */
+    access_token: string;
+    /** Token type (usually "Bearer") */
+    token_type: string;
+    /** Token lifetime in seconds */
+    expires_in: number;
+    /** Refresh token for getting new access tokens */
+    refresh_token?: string;
+    /** Scope granted */
+    scope?: string;
+}
+/**
+ * Device flow result returned to caller.
+ */
+export interface DeviceFlowResult {
+    /** Access token for API calls */
+    accessToken: string;
+    /** Refresh token for token renewal */
+    refreshToken?: string;
+    /** Token expiration in seconds from now */
+    expiresIn: number;
+}
+/**
+ * Start the OAuth Device Code Flow.
+ *
+ * 1. Request device code from authorization server
+ * 2. Display user code and verification URL
+ * 3. Poll for token with countdown
+ * 4. Return tokens on success
+ *
+ * @param clientId - OAuth client ID for the CLI
+ * @param authBase - Base URL for auth endpoints (default: https://vertaaux.ai)
+ * @returns Device flow result with tokens
+ * @throws Error if authorization fails or times out
+ */
+export declare function startDeviceFlow(clientId: string, authBase?: string): Promise<DeviceFlowResult>;
+//# sourceMappingURL=device-flow.d.ts.map

package/dist/auth/device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}

package/dist/auth/device-flow.js

@@ -0,0 +1,156 @@
+/**
+ * OAuth Device Code Flow implementation (RFC 8628).
+ *
+ * Used for interactive authentication where the user authenticates
+ * in a browser and the CLI polls for completion.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+import ora from "ora";
+/**
+ * Format remaining time as MM:SS.
+ */
+function formatRemaining(seconds) {
+    const mins = Math.floor(seconds / 60);
+    const secs = seconds % 60;
+    return `${mins}:${secs.toString().padStart(2, "0")}`;
+}
+/**
+ * Default API base URL for VertaaUX.
+ */
+const DEFAULT_AUTH_BASE = "https://vertaaux.ai";
+/**
+ * Default timeout for device flow (5 minutes).
+ */
+const DEFAULT_TIMEOUT_SECONDS = 300;
+/**
+ * Start the OAuth Device Code Flow.
+ *
+ * 1. Request device code from authorization server
+ * 2. Display user code and verification URL
+ * 3. Poll for token with countdown
+ * 4. Return tokens on success
+ *
+ * @param clientId - OAuth client ID for the CLI
+ * @param authBase - Base URL for auth endpoints (default: https://vertaaux.ai)
+ * @returns Device flow result with tokens
+ * @throws Error if authorization fails or times out
+ */
+export async function startDeviceFlow(clientId, authBase = DEFAULT_AUTH_BASE) {
+    // Step 1: Request device code
+    const deviceCodeResponse = await requestDeviceCode(clientId, authBase);
+    // Step 2: Display instructions
+    console.log("\n");
+    console.log("  To authenticate, visit:");
+    console.log(`  ${deviceCodeResponse.verification_uri}`);
+    console.log("\n");
+    console.log(`  Enter code: ${deviceCodeResponse.user_code}`);
+    console.log("\n");
+    if (deviceCodeResponse.verification_uri_complete) {
+        console.log(`  Or open: ${deviceCodeResponse.verification_uri_complete}`);
+        console.log("\n");
+    }
+    // Step 3: Poll for token with countdown
+    const tokens = await pollForToken(clientId, deviceCodeResponse.device_code, deviceCodeResponse.interval, deviceCodeResponse.expires_in, authBase);
+    return tokens;
+}
+/**
+ * Request a device code from the authorization server.
+ */
+async function requestDeviceCode(clientId, authBase) {
+    const url = `${authBase}/oauth/device/code`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            client_id: clientId,
+            scope: "audit:read audit:write baseline:read baseline:write",
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to request device code: ${response.status} ${text}`);
+    }
+    return response.json();
+}
+/**
+ * Poll the token endpoint until authorization completes.
+ */
+async function pollForToken(clientId, deviceCode, intervalSeconds, expiresInSeconds, authBase) {
+    const url = `${authBase}/oauth/token`;
+    const startTime = Date.now();
+    const timeoutMs = Math.min(expiresInSeconds, DEFAULT_TIMEOUT_SECONDS) * 1000;
+    let interval = intervalSeconds * 1000; // Convert to milliseconds
+    // Start spinner with countdown
+    const spinner = ora({
+        text: `Waiting for authorization... (${formatRemaining(Math.round(timeoutMs / 1000))} remaining)`,
+        stream: process.stderr,
+    }).start();
+    try {
+        while (true) {
+            // Check timeout
+            const elapsed = Date.now() - startTime;
+            const remaining = Math.max(0, timeoutMs - elapsed);
+            if (remaining === 0) {
+                throw new Error("Authorization timed out. Please try again.");
+            }
+            // Update spinner with countdown
+            spinner.text = `Waiting for authorization... (${formatRemaining(Math.ceil(remaining / 1000))} remaining)`;
+            // Wait for poll interval
+            await sleep(interval);
+            // Poll token endpoint
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    device_code: deviceCode,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                }),
+            });
+            // Success
+            if (response.ok) {
+                const tokens = (await response.json());
+                spinner.succeed("Authorization successful!");
+                return {
+                    accessToken: tokens.access_token,
+                    refreshToken: tokens.refresh_token,
+                    expiresIn: tokens.expires_in,
+                };
+            }
+            // Handle error responses
+            const error = (await response.json());
+            switch (error.error) {
+                case "authorization_pending":
+                    // User hasn't completed authorization yet, continue polling
+                    continue;
+                case "slow_down":
+                    // Server requests slower polling
+                    interval += 5000; // Add 5 seconds
+                    continue;
+                case "access_denied":
+                    throw new Error("Authorization denied by user.");
+                case "expired_token":
+                    throw new Error("Device code expired. Please try again.");
+                default:
+                    throw new Error(error.error_description || `Authorization failed: ${error.error}`);
+            }
+        }
+    }
+    finally {
+        // Ensure spinner is stopped
+        if (spinner.isSpinning) {
+            spinner.stop();
+        }
+    }
+}
+/**
+ * Sleep for specified milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}