@desplega.ai/qa-use 2.0.1

package/lib/api/sse.ts

@@ -0,0 +1,112 @@
+/**
+ * Server-Sent Events (SSE) parsing utilities
+ *
+ * Used for streaming test execution progress from /vibe-qa/cli/run endpoint
+ */
+
+export interface SSEEvent {
+  event: string;
+  data: any;
+  id?: string;
+}
+
+/**
+ * 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: string): SSEEvent[] {
+  const events: SSEEvent[] = [];
+  const lines = chunk.split('\n');
+
+  let currentEvent: Partial<SSEEvent> = {};
+
+  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 as SSEEvent);
+      }
+      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: Response): AsyncGenerator<SSEEvent, void, unknown> {
+  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: Response,
+  onEvent: (event: SSEEvent) => void | Promise<void>
+): Promise<void> {
+  for await (const event of streamSSE(response)) {
+    await onEvent(event);
+  }
+}

package/lib/browser/index.ts

@@ -0,0 +1,181 @@
+import { chromium } from 'playwright';
+import type { BrowserServer, Browser } from 'playwright';
+import { fork } from 'child_process';
+import path from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+export interface BrowserSession {
+  browserServer: BrowserServer;
+  wsEndpoint: string;
+  isActive: boolean;
+}
+
+export interface BrowserOptions {
+  headless?: boolean;
+  devtools?: boolean;
+  args?: string[];
+  userDataDir?: string;
+  isolated?: boolean;
+}
+
+export class BrowserManager {
+  private session: BrowserSession | null = null;
+
+  async startBrowser(options: BrowserOptions = {}): Promise<BrowserSession> {
+    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: any) {
+      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(): Promise<void> {
+    if (!this.session) {
+      return;
+    }
+
+    const session = this.session;
+    this.session = null;
+
+    try {
+      await session.browserServer.close();
+    } catch (error) {
+      // Silently handle cleanup errors
+    }
+  }
+
+  async connectToBrowser(): Promise<Browser | null> {
+    if (!this.session) {
+      return null;
+    }
+
+    try {
+      return await chromium.connect(this.session.wsEndpoint);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  getSession(): BrowserSession | null {
+    return this.session;
+  }
+
+  isActive(): boolean {
+    return this.session?.isActive ?? false;
+  }
+
+  /**
+   * Check if browser is actually alive by attempting to connect
+   */
+  async checkHealth(): Promise<boolean> {
+    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(): string | null {
+    return this.session?.wsEndpoint ?? null;
+  }
+
+  async installPlaywrightBrowsers(): Promise<void> {
+    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: string[] = [];
+
+        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: any) {
+        reject(new Error(`Failed to locate Playwright CLI: ${error.message}`));
+      }
+    });
+  }
+}

package/lib/env/index.ts

@@ -0,0 +1,156 @@
+/**
+ * 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';
+
+interface QaUseConfig {
+  env?: Record<string, string>;
+}
+
+let cachedConfig: QaUseConfig | null = null;
+let configLoadAttempted = false;
+
+/**
+ * Get the path to the config file
+ */
+function getConfigPath(): string {
+  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(): QaUseConfig | null {
+  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) as QaUseConfig;
+    return cachedConfig;
+  } catch {
+    // Invalid JSON or read error - silently ignore
+    return null;
+  }
+}
+
+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 function getEnvWithSource(name: string): EnvResult {
+  // 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: string): string | undefined {
+  return getEnvWithSource(name).value;
+}
+
+/**
+ * Clear the cached config (useful for testing)
+ */
+export function clearConfigCache(): void {
+  cachedConfig = null;
+  configLoadAttempted = false;
+}
+
+/**
+ * Check if config file exists
+ */
+export function configFileExists(): boolean {
+  return existsSync(getConfigPath());
+}
+
+/**
+ * Get human-readable source description
+ */
+function getSourceDescription(source: EnvSource): string {
+  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(): void {
+  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: string[] = [];
+
+  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));
+  }
+}