@desplega.ai/qa-use 2.14.1 → 2.15.1

package/lib/env/index.ts

@@ -11,11 +11,24 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+export { getPortFromUrl, isLocalhostUrl } from './localhost.js';
+
+/**
+ * Tunnel mode stored in ~/.qa-use.json.
+ * Kept as a string literal here (instead of importing `TunnelMode` from
+ * `src/cli/lib/tunnel-option.ts`) to avoid pulling CLI code into the
+ * shared env loader.
+ */
+export type QaUseTunnelMode = 'auto' | 'on' | 'off';
+
+const VALID_TUNNEL_MODES: readonly QaUseTunnelMode[] = ['auto', 'on', 'off'] as const;
+
 interface QaUseConfig {
   api_key?: string;
   api_url?: string;
   app_url?: string;
   region?: string;
+  tunnel?: QaUseTunnelMode;
   env?: Record<string, string>;
 }
 
@@ -215,6 +228,44 @@ export function getCustomHeaders(): Record<string, string> | null {
   return Object.keys(headers).length > 0 ? headers : null;
 }
 
+/**
+ * Read the `tunnel` key from `~/.qa-use.json`.
+ *
+ * Returns one of `'auto' | 'on' | 'off'`, or `undefined` if unset.
+ * On an invalid value, logs a one-line stderr warning and returns `undefined`
+ * (caller will fall back to the default, typically `'auto'`).
+ *
+ * Phase 1: config-only (no env-var override layer for tunnel mode).
+ */
+let tunnelWarningLogged = false;
+export function getTunnelModeFromConfig(): QaUseTunnelMode | undefined {
+  const config = loadConfig();
+  if (!config) return undefined;
+
+  const raw = config.tunnel;
+  if (raw === undefined || raw === null) return undefined;
+
+  if (typeof raw === 'string' && VALID_TUNNEL_MODES.includes(raw as QaUseTunnelMode)) {
+    return raw as QaUseTunnelMode;
+  }
+
+  if (!tunnelWarningLogged) {
+    console.error(
+      `qa-use: invalid "tunnel" value in ~/.qa-use.json: ${JSON.stringify(raw)}. ` +
+        `Expected one of: ${VALID_TUNNEL_MODES.join(', ')}. Falling back to "auto".`
+    );
+    tunnelWarningLogged = true;
+  }
+  return undefined;
+}
+
+/**
+ * Reset the tunnel-warning latch (for tests).
+ */
+export function clearTunnelWarningLatch(): void {
+  tunnelWarningLogged = false;
+}
+
 /**
  * Get agent session ID from environment if available.
  * Used for auto-linking browser sessions and test runs to agent sessions.

package/lib/env/localhost.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import { getPortFromUrl, isLocalhostUrl } from './localhost.js';
+
+describe('isLocalhostUrl', () => {
+  test('returns true for localhost', () => {
+    expect(isLocalhostUrl('http://localhost:3000')).toBe(true);
+    expect(isLocalhostUrl('http://localhost')).toBe(true);
+    expect(isLocalhostUrl('https://localhost:8080/path')).toBe(true);
+  });
+
+  test('returns true for 127.0.0.1', () => {
+    expect(isLocalhostUrl('http://127.0.0.1:5000')).toBe(true);
+    expect(isLocalhostUrl('http://127.0.0.1')).toBe(true);
+  });
+
+  test('returns true for ::1 (IPv6)', () => {
+    expect(isLocalhostUrl('http://[::1]:3000')).toBe(true);
+    expect(isLocalhostUrl('http://[::1]')).toBe(true);
+  });
+
+  test('returns true for *.localhost', () => {
+    expect(isLocalhostUrl('http://foo.localhost:3000')).toBe(true);
+    expect(isLocalhostUrl('http://api.localhost')).toBe(true);
+  });
+
+  test('returns true for 0.0.0.0', () => {
+    expect(isLocalhostUrl('http://0.0.0.0:3000')).toBe(true);
+  });
+
+  test('returns false for example.com', () => {
+    expect(isLocalhostUrl('https://example.com')).toBe(false);
+    expect(isLocalhostUrl('http://example.com:8080')).toBe(false);
+  });
+
+  test('returns false for private IPs (not actually localhost)', () => {
+    expect(isLocalhostUrl('http://192.168.1.1')).toBe(false);
+    expect(isLocalhostUrl('http://10.0.0.1')).toBe(false);
+  });
+
+  test('returns false for invalid URLs', () => {
+    expect(isLocalhostUrl('not-a-url')).toBe(false);
+    expect(isLocalhostUrl('')).toBe(false);
+  });
+});
+
+describe('getPortFromUrl', () => {
+  test('returns explicit port', () => {
+    expect(getPortFromUrl('http://localhost:3000')).toBe(3000);
+    expect(getPortFromUrl('https://example.com:8443')).toBe(8443);
+  });
+
+  test('defaults to 443 for https without port', () => {
+    expect(getPortFromUrl('https://example.com')).toBe(443);
+  });
+
+  test('defaults to 80 for http without port', () => {
+    expect(getPortFromUrl('http://example.com')).toBe(80);
+  });
+
+  test('returns 80 for invalid URL', () => {
+    expect(getPortFromUrl('not-a-url')).toBe(80);
+  });
+});

package/lib/env/localhost.ts

@@ -0,0 +1,51 @@
+/**
+ * Canonical localhost URL helpers.
+ *
+ * These live in `lib/env/` so they are usable from both the CLI layer and
+ * library code (tunnel, browser) without forcing a dependency on `src/cli`.
+ */
+
+import { URL } from 'node:url';
+
+/**
+ * Check if a URL points to localhost.
+ *
+ * Matches:
+ *   - `localhost`
+ *   - `127.0.0.1`
+ *   - `::1`
+ *   - `*.localhost` (e.g., `foo.localhost`)
+ *   - `0.0.0.0`
+ */
+export function isLocalhostUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    // Node/Bun's URL parser returns IPv6 hosts wrapped in brackets
+    // (e.g. "[::1]"). Strip them for comparison.
+    const host = parsed.hostname.replace(/^\[|\]$/g, '');
+    return (
+      host === 'localhost' ||
+      host === '127.0.0.1' ||
+      host === '::1' ||
+      host === '0.0.0.0' ||
+      host.endsWith('.localhost')
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the port from a URL, defaulting to 443 for https and 80 otherwise.
+ */
+export function getPortFromUrl(url: string): number {
+  try {
+    const parsed = new URL(url);
+    if (parsed.port) {
+      return parseInt(parsed.port, 10);
+    }
+    return parsed.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return 80;
+  }
+}

package/lib/env/paths.ts

@@ -0,0 +1,46 @@
+/**
+ * Filesystem paths used by qa-use for CLI-side state.
+ *
+ * All paths are relative to `os.homedir()` and created lazily on first
+ * write. Reading these directories does not create them — that's important
+ * for commands like `tunnel ls` that report an empty state cleanly when
+ * nothing has ever been written.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Base dir for all qa-use CLI-side state. Defaults to `~/.qa-use` but may
+ * be overridden via `QA_USE_HOME` (test-friendly).
+ */
+export function qaUseDir(): string {
+  const override = process.env.QA_USE_HOME;
+  if (override && override.length > 0) {
+    return override;
+  }
+  return path.join(os.homedir(), '.qa-use');
+}
+
+/**
+ * Where persisted tunnel registry entries live. Each active tunnel is a
+ * single JSON file named `<sha256(target)[0..10]>.json`.
+ */
+export function tunnelsDir(): string {
+  return path.join(qaUseDir(), 'tunnels');
+}
+
+/**
+ * Where detached browser-session PID files live (used by Phase 4 onward).
+ */
+export function sessionsDir(): string {
+  return path.join(qaUseDir(), 'sessions');
+}
+
+/**
+ * Ensure a directory exists (recursively). No-op if it already does.
+ */
+export function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+}

package/lib/env/sessions.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  type DetachedSessionRecord,
+  listSessionRecords,
+  removeSessionRecord,
+  sessionFilePath,
+  writeSessionRecord,
+} from './sessions.js';
+
+// Redirect QA_USE_HOME so `paths.ts` resolves to a throwaway dir per test.
+let originalQaUseHome: string | undefined;
+let tmpHome: string;
+
+function makeRecord(overrides: Partial<DetachedSessionRecord> = {}): DetachedSessionRecord {
+  return {
+    id: 'qa-test-1',
+    pid: 99999999,
+    target: 'http://localhost:3000',
+    publicUrl: 'https://example.tunnel',
+    startedAt: '2026-04-21T00:00:00.000Z',
+    ttlExpiresAt: Date.now() + 60_000,
+    ...overrides,
+  };
+}
+
+describe('sessions.ts', () => {
+  beforeEach(() => {
+    originalQaUseHome = process.env.QA_USE_HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'qa-use-sessions-'));
+    process.env.QA_USE_HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (originalQaUseHome !== undefined) {
+      process.env.QA_USE_HOME = originalQaUseHome;
+    } else {
+      delete process.env.QA_USE_HOME;
+    }
+    try {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  });
+
+  describe('removeSessionRecord', () => {
+    test('fast path: removes <id>.json when filename matches id', () => {
+      const record = makeRecord({ id: 'qa-fast-1' });
+      writeSessionRecord(record);
+      const p = sessionFilePath('qa-fast-1');
+      expect(fs.existsSync(p)).toBe(true);
+
+      removeSessionRecord('qa-fast-1');
+      expect(fs.existsSync(p)).toBe(false);
+    });
+
+    test('fallback: removes file when filename drifts from internal id', () => {
+      // Simulate corrupted/drifted state: filename qa-stale-2.json, internal id qa-stale-1.
+      const dir = path.join(tmpHome, 'sessions');
+      fs.mkdirSync(dir, { recursive: true });
+      const driftedPath = path.join(dir, 'qa-stale-2.json');
+      const content = JSON.stringify(makeRecord({ id: 'qa-stale-1' }));
+      fs.writeFileSync(driftedPath, content);
+
+      // No file at sessionFilePath('qa-stale-1'), but a file with id=qa-stale-1 exists as qa-stale-2.json
+      expect(fs.existsSync(sessionFilePath('qa-stale-1'))).toBe(false);
+      expect(fs.existsSync(driftedPath)).toBe(true);
+
+      removeSessionRecord('qa-stale-1');
+
+      expect(fs.existsSync(driftedPath)).toBe(false);
+    });
+
+    test('no-op when no matching record exists', () => {
+      // Create an unrelated record — scan should not touch it.
+      const dir = path.join(tmpHome, 'sessions');
+      fs.mkdirSync(dir, { recursive: true });
+      const unrelatedPath = path.join(dir, 'other.json');
+      fs.writeFileSync(unrelatedPath, JSON.stringify(makeRecord({ id: 'other' })));
+
+      removeSessionRecord('not-present');
+
+      expect(fs.existsSync(unrelatedPath)).toBe(true);
+    });
+
+    test('no-op when sessions dir is missing', () => {
+      // Should not throw even when the dir doesn't exist.
+      expect(() => removeSessionRecord('missing')).not.toThrow();
+    });
+  });
+
+  describe('listSessionRecords', () => {
+    test('returns parsed records regardless of filename drift', () => {
+      const dir = path.join(tmpHome, 'sessions');
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'drifted.json'),
+        JSON.stringify(makeRecord({ id: 'actual-id' }))
+      );
+
+      const records = listSessionRecords();
+      expect(records).toHaveLength(1);
+      expect(records[0]!.id).toBe('actual-id');
+    });
+  });
+});

package/lib/env/sessions.ts

@@ -0,0 +1,155 @@
+/**
+ * Detached browser-session PID files.
+ *
+ * Each detached `browser create` writes a JSON file under
+ * `~/.qa-use/sessions/<session-id>.json` describing the running child
+ * process. The file schema is documented in `DetachedSessionRecord`.
+ *
+ * Readers (tunnel close, browser status, doctor) cross-reference the
+ * `pid` field via `process.kill(pid, 0)` to detect stale entries.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, sessionsDir } from './paths.js';
+
+/**
+ * On-disk schema for a detached browser session.
+ *
+ * The file is created by the detached child (`__browser-detach`) shortly
+ * after it starts, and removed on clean exit. Partial writes are
+ * avoided by atomic rename (write `.tmp` + `rename`).
+ */
+export interface DetachedSessionRecord {
+  /** Backend session id (also the filename base). */
+  id: string;
+  /** PID of the detached child process. */
+  pid: number;
+  /** Tunnel target (canonical origin of the browser WS URL). */
+  target: string;
+  /** Public URL for the tunnel (from registry handle). `null` when no tunnel. */
+  publicUrl: string | null;
+  /** ISO timestamp of child startup. */
+  startedAt: string;
+  /** Epoch ms at which the backend session TTL expires. */
+  ttlExpiresAt: number;
+  /**
+   * True when the registry handle was an attach (another process owns
+   * the in-process `TunnelManager`). Informational — `browser close`
+   * prints this in diagnostics.
+   */
+  crossProcessTunnel?: boolean;
+  /** Optional: subdomain used for the tunnel. */
+  subdomain?: string;
+  /** Optional: viewport for display/debug. */
+  viewport?: string;
+  /** Optional: headless flag for display/debug. */
+  headless?: boolean;
+}
+
+export function sessionFilePath(sessionId: string): string {
+  return path.join(sessionsDir(), `${sessionId}.json`);
+}
+
+export function writeSessionRecord(record: DetachedSessionRecord): void {
+  const dir = sessionsDir();
+  ensureDir(dir);
+  const finalPath = sessionFilePath(record.id);
+  const tmp = `${finalPath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2));
+  fs.renameSync(tmp, finalPath);
+}
+
+export function readSessionRecord(sessionId: string): DetachedSessionRecord | null {
+  try {
+    const raw = fs.readFileSync(sessionFilePath(sessionId), 'utf8');
+    const parsed = JSON.parse(raw) as DetachedSessionRecord;
+    if (typeof parsed.id !== 'string' || typeof parsed.pid !== 'number') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function removeSessionRecord(sessionId: string): void {
+  try {
+    fs.unlinkSync(sessionFilePath(sessionId));
+    return;
+  } catch (err) {
+    // Fast path missed — fall through to dir-scan fallback only on ENOENT.
+    // Any other error (EPERM, EACCES, EBUSY, etc.) is propagated by
+    // simply returning: callers treat removal as best-effort and surfacing
+    // an error here would change the public contract.
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      return;
+    }
+  }
+
+  // Fallback: filename may have drifted from the internal `id` (corrupted
+  // state, manual edits, legacy data). Scan the dir and unlink the file
+  // whose parsed content has a matching `id`.
+  const dir = sessionsDir();
+  let files: string[];
+  try {
+    files = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of files) {
+    if (!name.endsWith('.json') || name.endsWith('.tmp')) continue;
+    const fullPath = path.join(dir, name);
+    try {
+      const raw = fs.readFileSync(fullPath, 'utf8');
+      const parsed = JSON.parse(raw) as DetachedSessionRecord;
+      if (parsed.id === sessionId) {
+        try {
+          fs.unlinkSync(fullPath);
+        } catch {
+          /* already gone */
+        }
+        return;
+      }
+    } catch {
+      /* skip unreadable */
+    }
+  }
+}
+
+/**
+ * List all persisted detached-session records. Does NOT reconcile
+ * against PIDs — callers decide how to handle stale entries.
+ */
+export function listSessionRecords(): DetachedSessionRecord[] {
+  const dir = sessionsDir();
+  let files: string[];
+  try {
+    files = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out: DetachedSessionRecord[] = [];
+  for (const name of files) {
+    if (!name.endsWith('.json') || name.endsWith('.tmp')) continue;
+    try {
+      const raw = fs.readFileSync(path.join(dir, name), 'utf8');
+      const parsed = JSON.parse(raw) as DetachedSessionRecord;
+      if (typeof parsed.id !== 'string' || typeof parsed.pid !== 'number') continue;
+      out.push(parsed);
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  return out;
+}
+
+/** Cheap liveness check — `kill(pid, 0)` returns true if the pid exists. */
+export function isPidAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EPERM') return true;
+    return false;
+  }
+}

package/lib/tunnel/errors.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  classifyTunnelFailure,
+  TunnelAuthError,
+  TunnelError,
+  TunnelNetworkError,
+  TunnelQuotaError,
+  TunnelUnknownError,
+} from './errors.js';
+
+describe('TunnelError', () => {
+  test('base class carries target + provider + cause', () => {
+    const cause = new Error('boom');
+    const err = new TunnelError('msg', {
+      target: 'http://localhost:3000',
+      provider: 'localtunnel',
+      cause,
+    });
+    expect(err).toBeInstanceOf(Error);
+    expect(err.target).toBe('http://localhost:3000');
+    expect(err.provider).toBe('localtunnel');
+    expect(err.cause).toBe(cause);
+  });
+
+  test('provider defaults to "localtunnel"', () => {
+    const err = new TunnelError('msg', { target: 'x' });
+    expect(err.provider).toBe('localtunnel');
+  });
+});
+
+describe('classifyTunnelFailure', () => {
+  test('classifies Node errno codes as network errors', () => {
+    const nodeErr = Object.assign(new Error('ECONNREFUSED'), { code: 'ECONNREFUSED' });
+    const out = classifyTunnelFailure(nodeErr);
+    expect(out).toBeInstanceOf(TunnelNetworkError);
+  });
+
+  test('classifies ETIMEDOUT as network', () => {
+    const err = Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' });
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelNetworkError);
+  });
+
+  test('classifies ENOTFOUND as network', () => {
+    const err = Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' });
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelNetworkError);
+  });
+
+  test('classifies message-based timeout text as network', () => {
+    const err = new Error('Connection timed out after 5s');
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelNetworkError);
+  });
+
+  test('classifies HTTP 401 as auth error', () => {
+    const err = Object.assign(new Error('Unauthorized'), { statusCode: 401 });
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelAuthError);
+  });
+
+  test('classifies HTTP 403 as auth error', () => {
+    const err = Object.assign(new Error('Forbidden'), { statusCode: 403 });
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelAuthError);
+  });
+
+  test('classifies "unauthorized" message as auth error', () => {
+    const err = new Error('Request rejected: unauthorized');
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelAuthError);
+  });
+
+  test('classifies HTTP 429 as quota error', () => {
+    const err = Object.assign(new Error('Too Many Requests'), { statusCode: 429 });
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelQuotaError);
+  });
+
+  test('classifies "rate limit" message as quota error', () => {
+    const err = new Error('rate limit exceeded');
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelQuotaError);
+  });
+
+  test('classifies "subdomain already in use" as quota error', () => {
+    const err = new Error('subdomain qa-use-foo is already in use');
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelQuotaError);
+  });
+
+  test('classifies nested response.status', () => {
+    const err = { message: 'boom', response: { status: 401 } };
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelAuthError);
+  });
+
+  test('falls back to TunnelUnknownError on unrecognised shape', () => {
+    const err = new Error('something exploded');
+    expect(classifyTunnelFailure(err)).toBeInstanceOf(TunnelUnknownError);
+  });
+
+  test('preserves target and cause in the returned error', () => {
+    const cause = new Error('root');
+    const out = classifyTunnelFailure(cause, { target: 'http://localhost:3000' });
+    expect(out.target).toBe('http://localhost:3000');
+    expect(out.cause).toBe(cause);
+  });
+
+  test('handles non-Error values', () => {
+    expect(classifyTunnelFailure('bare string')).toBeInstanceOf(TunnelUnknownError);
+    expect(classifyTunnelFailure(undefined)).toBeInstanceOf(TunnelUnknownError);
+    expect(classifyTunnelFailure(null)).toBeInstanceOf(TunnelUnknownError);
+  });
+});