@desplega.ai/qa-use 2.0.1

package/dist/lib/api/sse.js

@@ -0,0 +1,97 @@
+/**
+ * Server-Sent Events (SSE) parsing utilities
+ *
+ * Used for streaming test execution progress from /vibe-qa/cli/run endpoint
+ */
+/**
+ * Parse SSE data from a chunk of text
+ *
+ * @param chunk - Raw SSE text chunk (may contain multiple events)
+ * @returns Array of parsed SSE events
+ */
+export function parseSSE(chunk) {
+    const events = [];
+    const lines = chunk.split('\n');
+    let currentEvent = {};
+    for (const line of lines) {
+        if (line.startsWith('event: ')) {
+            currentEvent.event = line.slice(7).trim();
+        }
+        else if (line.startsWith('data: ')) {
+            const dataStr = line.slice(6);
+            try {
+                currentEvent.data = JSON.parse(dataStr);
+            }
+            catch {
+                currentEvent.data = dataStr;
+            }
+        }
+        else if (line.startsWith('id: ')) {
+            currentEvent.id = line.slice(4).trim();
+        }
+        else if (line === '') {
+            // Empty line signals end of event
+            if (currentEvent.event && currentEvent.data !== undefined) {
+                events.push(currentEvent);
+            }
+            currentEvent = {};
+        }
+    }
+    return events;
+}
+/**
+ * Stream SSE events from a Response object
+ *
+ * @param response - Fetch Response with SSE stream
+ * @yields SSE events as they arrive
+ */
+export async function* streamSSE(response) {
+    if (!response.body) {
+        throw new Error('Response body is null');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Find complete events (separated by double newlines)
+            let pos = buffer.indexOf('\n\n');
+            while (pos !== -1) {
+                const chunk = buffer.slice(0, pos + 2);
+                buffer = buffer.slice(pos + 2);
+                const events = parseSSE(chunk);
+                for (const event of events) {
+                    yield event;
+                }
+                pos = buffer.indexOf('\n\n');
+            }
+        }
+        // Process any remaining buffer
+        if (buffer.trim()) {
+            const events = parseSSE(buffer);
+            for (const event of events) {
+                yield event;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Helper to consume an SSE stream and call a callback for each event
+ *
+ * @param response - Fetch Response with SSE stream
+ * @param onEvent - Callback to handle each event
+ * @returns Promise that resolves when stream ends
+ */
+export async function consumeSSE(response, onEvent) {
+    for await (const event of streamSSE(response)) {
+        await onEvent(event);
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/lib/api/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../lib/api/sse.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/index.d.ts

@@ -0,0 +1,28 @@
+import type { BrowserServer, Browser } from 'playwright';
+export interface BrowserSession {
+    browserServer: BrowserServer;
+    wsEndpoint: string;
+    isActive: boolean;
+}
+export interface BrowserOptions {
+    headless?: boolean;
+    devtools?: boolean;
+    args?: string[];
+    userDataDir?: string;
+    isolated?: boolean;
+}
+export declare class BrowserManager {
+    private session;
+    startBrowser(options?: BrowserOptions): Promise<BrowserSession>;
+    stopBrowser(): Promise<void>;
+    connectToBrowser(): Promise<Browser | null>;
+    getSession(): BrowserSession | null;
+    isActive(): boolean;
+    /**
+     * Check if browser is actually alive by attempting to connect
+     */
+    checkHealth(): Promise<boolean>;
+    getWebSocketEndpoint(): string | null;
+    installPlaywrightBrowsers(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/browser/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMzD,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAA+B;IAExC,YAAY,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAmDnE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B,gBAAgB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAYjD,UAAU,IAAI,cAAc,GAAG,IAAI;IAInC,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAI/B,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC;CAgDjD"}

package/dist/lib/browser/index.js

@@ -0,0 +1,145 @@
+import { chromium } from 'playwright';
+import { fork } from 'child_process';
+import path from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+export class BrowserManager {
+    session = null;
+    async startBrowser(options = {}) {
+        if (this.session) {
+            throw new Error('Browser session already active');
+        }
+        const defaultArgs = [
+            '--disable-dev-shm-usage',
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            '--disable-gpu',
+            '--disable-background-timer-throttling',
+            '--disable-renderer-backgrounding',
+            '--disable-backgrounding-occluded-windows',
+            '--mute-audio',
+            '--disable-extensions',
+            '--enable-features=NetworkService,NetworkServiceInProcess',
+            '--disable-3d-apis',
+            '--remote-debugging-port=0',
+        ];
+        try {
+            const browserServer = await chromium.launchServer({
+                headless: options.headless ?? true,
+                devtools: options.devtools ?? false,
+                args: [...defaultArgs, ...(options.args || [])],
+                handleSIGINT: false,
+                handleSIGTERM: false,
+            });
+            const wsEndpoint = browserServer.wsEndpoint();
+            this.session = {
+                browserServer,
+                wsEndpoint,
+                isActive: true,
+            };
+            return this.session;
+        }
+        catch (error) {
+            if (error.message.includes("Executable doesn't exist") ||
+                error.message.includes('browserType.launch')) {
+                throw new Error('Chromium browser is not installed. Please run ensure_installed to install browsers.');
+            }
+            throw error;
+        }
+    }
+    async stopBrowser() {
+        if (!this.session) {
+            return;
+        }
+        const session = this.session;
+        this.session = null;
+        try {
+            await session.browserServer.close();
+        }
+        catch (error) {
+            // Silently handle cleanup errors
+        }
+    }
+    async connectToBrowser() {
+        if (!this.session) {
+            return null;
+        }
+        try {
+            return await chromium.connect(this.session.wsEndpoint);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    getSession() {
+        return this.session;
+    }
+    isActive() {
+        return this.session?.isActive ?? false;
+    }
+    /**
+     * Check if browser is actually alive by attempting to connect
+     */
+    async checkHealth() {
+        if (!this.session)
+            return false;
+        try {
+            const browser = await chromium.connect(this.session.wsEndpoint, {
+                timeout: 5000, // 5 second timeout
+            });
+            await browser.close();
+            return true;
+        }
+        catch (error) {
+            this.session.isActive = false;
+            return false;
+        }
+    }
+    getWebSocketEndpoint() {
+        return this.session?.wsEndpoint ?? null;
+    }
+    async installPlaywrightBrowsers() {
+        return new Promise((resolve, reject) => {
+            try {
+                // Use the LOCAL playwright installation from package.json
+                // This ensures consistency between install and launch
+                // Create require function for ES modules
+                const require = createRequire(import.meta.url);
+                const playwrightPackagePath = require.resolve('playwright/package.json');
+                const cliPath = path.join(path.dirname(playwrightPackagePath), 'cli.js');
+                console.error(`Installing browsers using local Playwright at: ${cliPath}`);
+                // Fork the local Playwright CLI to install chromium
+                const child = fork(cliPath, ['install', 'chromium'], {
+                    stdio: 'pipe',
+                });
+                const output = [];
+                child.stdout?.on('data', (data) => {
+                    const message = data.toString();
+                    output.push(message);
+                    console.error(message); // Log progress to stderr
+                });
+                child.stderr?.on('data', (data) => {
+                    const message = data.toString();
+                    output.push(message);
+                    console.error(message); // Log errors to stderr
+                });
+                child.on('close', (code) => {
+                    if (code === 0) {
+                        console.error('✅ Playwright browsers installed successfully');
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`Failed to install browser: ${output.join('')}`));
+                    }
+                });
+                child.on('error', (error) => {
+                    reject(new Error(`Failed to start browser installation: ${error.message}`));
+                });
+            }
+            catch (error) {
+                reject(new Error(`Failed to locate Playwright CLI: ${error.message}`));
+            }
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAgBpC,MAAM,OAAO,cAAc;IACjB,OAAO,GAA0B,IAAI,CAAC;IAE9C,KAAK,CAAC,YAAY,CAAC,UAA0B,EAAE;QAC7C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,yBAAyB;YACzB,cAAc;YACd,0BAA0B;YAC1B,eAAe;YACf,uCAAuC;YACvC,kCAAkC;YAClC,0CAA0C;YAC1C,cAAc;YACd,sBAAsB;YACtB,0DAA0D;YAC1D,mBAAmB;YACnB,2BAA2B;SAC5B,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC;gBAChD,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;gBAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;gBACnC,IAAI,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;gBAC/C,YAAY,EAAE,KAAK;gBACnB,aAAa,EAAE,KAAK;aACrB,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,EAAE,CAAC;YAE9C,IAAI,CAAC,OAAO,GAAG;gBACb,aAAa;gBACb,UAAU;gBACV,QAAQ,EAAE,IAAI;aACf,CAAC;YAEF,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,IACE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC;gBAClD,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAC5C,CAAC;gBACD,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAEhC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;gBAC9D,OAAO,EAAE,IAAI,EAAE,mBAAmB;aACnC,CAAC,CAAC;YACH,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,oBAAoB;QAClB,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,yBAAyB;QAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC;gBACH,0DAA0D;gBAC1D,sDAAsD;gBACtD,yCAAyC;gBACzC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC/C,MAAM,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;gBACzE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAEzE,OAAO,CAAC,KAAK,CAAC,kDAAkD,OAAO,EAAE,CAAC,CAAC;gBAE3E,oDAAoD;gBACpD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE;oBACnD,KAAK,EAAE,MAAM;iBACd,CAAC,CAAC;gBAEH,MAAM,MAAM,GAAa,EAAE,CAAC;gBAE5B,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;oBAChC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;oBAChC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,yBAAyB;gBACnD,CAAC,CAAC,CAAC;gBAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;oBAChC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;oBAChC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;gBACjD,CAAC,CAAC,CAAC;gBAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;oBACzB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;wBACf,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;wBAC9D,OAAO,EAAE,CAAC;oBACZ,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;oBACrE,CAAC;gBACH,CAAC,CAAC,CAAC;gBAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;oBAC1B,MAAM,CAAC,IAAI,KAAK,CAAC,yCAAyC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBAC9E,CAAC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,KAAK,CAAC,oCAAoC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACzE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/lib/env/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment variable utility with config file fallback
+ *
+ * Priority order:
+ * 1. Environment variables (process.env)
+ * 2. Config file (~/.qa-use.json) with structure: { "env": { "VAR_NAME": "value" } }
+ */
+export type EnvSource = 'env' | 'config' | 'none';
+export interface EnvResult {
+    value: string | undefined;
+    source: EnvSource;
+}
+/**
+ * Get an environment variable value with fallback to config file,
+ * along with the source of the value
+ *
+ * @param name - The environment variable name (e.g., 'QA_USE_API_KEY')
+ * @returns Object containing the value and its source
+ */
+export declare function getEnvWithSource(name: string): EnvResult;
+/**
+ * Get an environment variable value with fallback to config file
+ *
+ * @param name - The environment variable name (e.g., 'QA_USE_API_KEY')
+ * @returns The value from env or config file, or undefined if not found
+ */
+export declare function getEnv(name: string): string | undefined;
+/**
+ * Clear the cached config (useful for testing)
+ */
+export declare function clearConfigCache(): void;
+/**
+ * Check if config file exists
+ */
+export declare function configFileExists(): boolean;
+/**
+ * Log the source of key configuration values
+ * Call this at startup to inform users where their credentials are coming from
+ */
+export declare function logConfigSources(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+CH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAcxD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAgBD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CA6BvC"}

package/dist/lib/env/index.js

@@ -0,0 +1,125 @@
+/**
+ * Environment variable utility with config file fallback
+ *
+ * Priority order:
+ * 1. Environment variables (process.env)
+ * 2. Config file (~/.qa-use.json) with structure: { "env": { "VAR_NAME": "value" } }
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+let cachedConfig = null;
+let configLoadAttempted = false;
+/**
+ * Get the path to the config file
+ */
+function getConfigPath() {
+    return join(homedir(), '.qa-use.json');
+}
+/**
+ * Load the config file from ~/.qa-use.json
+ * Returns null if file doesn't exist or is invalid
+ */
+function loadConfig() {
+    if (configLoadAttempted) {
+        return cachedConfig;
+    }
+    configLoadAttempted = true;
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        cachedConfig = JSON.parse(content);
+        return cachedConfig;
+    }
+    catch {
+        // Invalid JSON or read error - silently ignore
+        return null;
+    }
+}
+/**
+ * Get an environment variable value with fallback to config file,
+ * along with the source of the value
+ *
+ * @param name - The environment variable name (e.g., 'QA_USE_API_KEY')
+ * @returns Object containing the value and its source
+ */
+export function getEnvWithSource(name) {
+    // First check environment variable
+    const envValue = process.env[name];
+    if (envValue !== undefined && envValue !== '') {
+        return { value: envValue, source: 'env' };
+    }
+    // Fallback to config file
+    const config = loadConfig();
+    if (config?.env?.[name]) {
+        return { value: config.env[name], source: 'config' };
+    }
+    return { value: undefined, source: 'none' };
+}
+/**
+ * Get an environment variable value with fallback to config file
+ *
+ * @param name - The environment variable name (e.g., 'QA_USE_API_KEY')
+ * @returns The value from env or config file, or undefined if not found
+ */
+export function getEnv(name) {
+    return getEnvWithSource(name).value;
+}
+/**
+ * Clear the cached config (useful for testing)
+ */
+export function clearConfigCache() {
+    cachedConfig = null;
+    configLoadAttempted = false;
+}
+/**
+ * Check if config file exists
+ */
+export function configFileExists() {
+    return existsSync(getConfigPath());
+}
+/**
+ * Get human-readable source description
+ */
+function getSourceDescription(source) {
+    switch (source) {
+        case 'env':
+            return 'environment variable';
+        case 'config':
+            return `config file (~/.qa-use.json)`;
+        case 'none':
+            return 'not set';
+    }
+}
+/**
+ * Log the source of key configuration values
+ * Call this at startup to inform users where their credentials are coming from
+ */
+export function logConfigSources() {
+    const apiKey = getEnvWithSource('QA_USE_API_KEY');
+    const apiUrl = getEnvWithSource('QA_USE_API_URL');
+    const appUrl = getEnvWithSource('QA_USE_APP_URL');
+    const region = getEnvWithSource('QA_USE_REGION');
+    const sources = [];
+    if (apiKey.value) {
+        const maskedKey = apiKey.value.slice(0, 8) + '...' + apiKey.value.slice(-4);
+        sources.push(`  API Key: ${maskedKey} (from ${getSourceDescription(apiKey.source)})`);
+    }
+    if (apiUrl.value) {
+        sources.push(`  API URL: ${apiUrl.value} (from ${getSourceDescription(apiUrl.source)})`);
+    }
+    if (appUrl.value) {
+        sources.push(`  App URL: ${appUrl.value} (from ${getSourceDescription(appUrl.source)})`);
+    }
+    if (region.value) {
+        sources.push(`  Region: ${region.value} (from ${getSourceDescription(region.source)})`);
+    }
+    if (sources.length > 0) {
+        console.error('Configuration loaded:');
+        sources.forEach((s) => console.error(s));
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/tunnel/index.d.ts

@@ -0,0 +1,38 @@
+import localtunnel from '@desplega.ai/localtunnel';
+export interface TunnelSession {
+    tunnel: localtunnel.Tunnel;
+    publicUrl: string;
+    localPort: number;
+    isActive: boolean;
+    host: string;
+    region: string;
+}
+export interface TunnelOptions {
+    subdomain?: string;
+    localHost?: string;
+    apiKey?: string;
+    sessionIndex?: number;
+}
+export declare class TunnelManager {
+    private session;
+    private readonly defaultRegion;
+    /**
+     * Generate a deterministic subdomain based on API key and session index
+     * @param apiKey - The API key to hash
+     * @param sessionIndex - Index from 0-9 for concurrent sessions
+     * @returns Deterministic subdomain in format: qa-use-{hash}-{index}
+     */
+    static generateDeterministicSubdomain(apiKey: string, sessionIndex: number): string;
+    startTunnel(port: number, options?: TunnelOptions): Promise<TunnelSession>;
+    stopTunnel(): Promise<void>;
+    getSession(): TunnelSession | null;
+    isActive(): boolean;
+    /**
+     * Check if tunnel is actually alive by pinging the public URL
+     */
+    checkHealth(): Promise<boolean>;
+    getPublicUrl(): string | null;
+    getPublicIP(): Promise<string>;
+    getWebSocketUrl(originalWsEndpoint: string): string | null;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/tunnel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,0BAA0B,CAAC;AAMnD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkB;IAEhD;;;;;OAKG;IACH,MAAM,CAAC,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAa7E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAuE9E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,UAAU,IAAI,aAAa,GAAG,IAAI;IAIlC,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAqBrC,YAAY,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAcpC,eAAe,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAe3D"}

package/dist/lib/tunnel/index.js

@@ -0,0 +1,154 @@
+import localtunnel from '@desplega.ai/localtunnel';
+import { URL } from 'url';
+import https from 'https';
+import crypto from 'crypto';
+import { getEnv } from '../env/index.js';
+export class TunnelManager {
+    session = null;
+    defaultRegion = 'auto';
+    /**
+     * Generate a deterministic subdomain based on API key and session index
+     * @param apiKey - The API key to hash
+     * @param sessionIndex - Index from 0-9 for concurrent sessions
+     * @returns Deterministic subdomain in format: qa-use-{hash}-{index}
+     */
+    static generateDeterministicSubdomain(apiKey, sessionIndex) {
+        // Hash the API key using SHA-256
+        const hash = crypto.createHash('sha256').update(apiKey).digest('hex');
+        // Take first 6 characters of hash for brevity
+        const shortHash = hash.substring(0, 6);
+        // Ensure sessionIndex is within valid range (0-9)
+        const validIndex = Math.max(0, Math.min(9, sessionIndex));
+        return `qa-use-${shortHash}-${validIndex}`;
+    }
+    async startTunnel(port, options = {}) {
+        if (this.session) {
+            throw new Error('Tunnel session already active');
+        }
+        const region = getEnv('QA_USE_REGION') || this.defaultRegion;
+        let host = getEnv('TUNNEL_HOST');
+        if (!host) {
+            // If no manual override, determine host based on region
+            if (region === 'us') {
+                host = 'https://lt.us.desplega.ai';
+            }
+            else {
+                // Default for 'auto' or unset
+                host = 'https://lt.desplega.ai';
+            }
+        }
+        // Determine subdomain: custom > deterministic > random
+        let subdomain = options.subdomain;
+        if (!subdomain && options.apiKey !== undefined && options.sessionIndex !== undefined) {
+            // Use deterministic subdomain based on API key and session index
+            subdomain = TunnelManager.generateDeterministicSubdomain(options.apiKey, options.sessionIndex);
+            console.log(`Using deterministic subdomain: ${subdomain}`);
+        }
+        else if (!subdomain) {
+            // Fallback to timestamp-based random subdomain
+            subdomain = `qa-use-${Date.now().toString().slice(-6)}`;
+            console.log(`Using random subdomain: ${subdomain}`);
+        }
+        console.log(`Starting tunnel on port ${port} with host ${host} in region ${region}`);
+        const tunnel = await localtunnel({
+            port,
+            host,
+            subdomain,
+            local_host: options.localHost || 'localhost',
+            auth: true,
+        });
+        console.log(`Tunnel started at ${tunnel.url}`);
+        this.session = {
+            tunnel,
+            publicUrl: tunnel.url,
+            localPort: port,
+            isActive: true,
+            host,
+            region,
+        };
+        // Handle tunnel events
+        tunnel.on('close', () => {
+            if (this.session) {
+                this.session.isActive = false;
+            }
+        });
+        tunnel.on('error', (err) => {
+            if (this.session) {
+                this.session.isActive = false;
+            }
+            throw err;
+        });
+        return this.session;
+    }
+    async stopTunnel() {
+        if (!this.session) {
+            return;
+        }
+        const session = this.session;
+        this.session = null;
+        try {
+            session.tunnel.close();
+        }
+        catch (error) {
+            // Silently handle cleanup errors
+        }
+    }
+    getSession() {
+        return this.session;
+    }
+    isActive() {
+        return this.session?.isActive ?? false;
+    }
+    /**
+     * Check if tunnel is actually alive by pinging the public URL
+     */
+    async checkHealth() {
+        if (!this.session)
+            return false;
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            const response = await fetch(this.session.publicUrl, {
+                method: 'HEAD',
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            // 426 = Upgrade Required (expected for WebSocket endpoint)
+            return response.ok || response.status === 426;
+        }
+        catch (error) {
+            this.session.isActive = false;
+            return false;
+        }
+    }
+    getPublicUrl() {
+        return this.session?.publicUrl ?? null;
+    }
+    async getPublicIP() {
+        return new Promise((resolve, reject) => {
+            https
+                .get('https://api.ipify.org', (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => resolve(data.trim()));
+            })
+                .on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    getWebSocketUrl(originalWsEndpoint) {
+        if (!this.session)
+            return null;
+        try {
+            const localWsUrl = new URL(originalWsEndpoint);
+            const wsPath = localWsUrl.pathname;
+            // Convert HTTP/HTTPS URLs to WebSocket URLs (ws/wss)
+            return (this.session.publicUrl.replace('https://', 'wss://').replace('http://', 'ws://') + wsPath);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map