@desplega.ai/qa-use 2.14.0 → 2.15.0

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);
+  });
+});

package/lib/tunnel/errors.ts

@@ -0,0 +1,169 @@
+/**
+ * Structured tunnel error classes.
+ *
+ * The CLI uses these to render triage-hint error messages on tunnel
+ * failure. `classifyTunnelFailure` inspects a thrown error from the
+ * underlying `@desplega.ai/localtunnel` provider and returns the most
+ * specific subclass we can identify.
+ *
+ * Zero retries live in this layer — classification is strictly about
+ * picking the right error shape to hand back up the stack.
+ */
+
+export interface TunnelErrorContext {
+  /** Human-readable target the user was trying to tunnel (URL or host:port). */
+  target?: string;
+  /** Identifier of the tunnel provider (kept open for future providers). */
+  provider?: string;
+  /** Original underlying error, preserved for logs / debugging. */
+  cause?: unknown;
+}
+
+/**
+ * Base class for all tunnel-layer failures surfaced to the CLI.
+ *
+ * Do not throw `TunnelError` directly — throw one of the subclasses
+ * below so the CLI can pick the right hint.
+ */
+export class TunnelError extends Error {
+  readonly target?: string;
+  readonly provider?: string;
+  readonly cause?: unknown;
+
+  constructor(message: string, context: TunnelErrorContext = {}) {
+    super(message);
+    this.name = 'TunnelError';
+    this.target = context.target;
+    this.provider = context.provider ?? 'localtunnel';
+    this.cause = context.cause;
+  }
+}
+
+/** Network / connectivity failure (DNS, timeout, ECONNREFUSED, etc.). */
+export class TunnelNetworkError extends TunnelError {
+  constructor(message: string, context: TunnelErrorContext = {}) {
+    super(message, context);
+    this.name = 'TunnelNetworkError';
+  }
+}
+
+/** Auth failure (bad/expired API key, 401/403 from provider). */
+export class TunnelAuthError extends TunnelError {
+  constructor(message: string, context: TunnelErrorContext = {}) {
+    super(message, context);
+    this.name = 'TunnelAuthError';
+  }
+}
+
+/** Quota / rate-limit / subdomain-clash failure. */
+export class TunnelQuotaError extends TunnelError {
+  constructor(message: string, context: TunnelErrorContext = {}) {
+    super(message, context);
+    this.name = 'TunnelQuotaError';
+  }
+}
+
+/** Fallback when no classification matched. */
+export class TunnelUnknownError extends TunnelError {
+  constructor(message: string, context: TunnelErrorContext = {}) {
+    super(message, context);
+    this.name = 'TunnelUnknownError';
+  }
+}
+
+function extractStatusCode(err: unknown): number | undefined {
+  if (!err || typeof err !== 'object') return undefined;
+  const obj = err as Record<string, unknown>;
+  if (typeof obj.statusCode === 'number') return obj.statusCode;
+  if (typeof obj.status === 'number') return obj.status;
+  // Some providers nest the status in a `response` object.
+  const response = obj.response;
+  if (response && typeof response === 'object') {
+    const respObj = response as Record<string, unknown>;
+    if (typeof respObj.status === 'number') return respObj.status;
+    if (typeof respObj.statusCode === 'number') return respObj.statusCode;
+  }
+  return undefined;
+}
+
+function extractErrorCode(err: unknown): string | undefined {
+  if (!err || typeof err !== 'object') return undefined;
+  const obj = err as Record<string, unknown>;
+  if (typeof obj.code === 'string') return obj.code;
+  return undefined;
+}
+
+function extractMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === 'string') return err;
+  if (err && typeof err === 'object') {
+    const obj = err as Record<string, unknown>;
+    if (typeof obj.message === 'string') return obj.message;
+  }
+  try {
+    return String(err);
+  } catch {
+    return 'unknown tunnel error';
+  }
+}
+
+const NETWORK_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_SOCKET',
+]);
+
+/**
+ * Inspect a thrown tunnel error and return the most specific
+ * `TunnelError` subclass we can identify.
+ *
+ * Heuristics:
+ *   - Node / undici error codes (`ECONNREFUSED`, `ETIMEDOUT`, …) →
+ *     `TunnelNetworkError`
+ *   - HTTP 401/403 → `TunnelAuthError`
+ *   - HTTP 429 or messages about quota / rate-limit / subdomain in use →
+ *     `TunnelQuotaError`
+ *   - Everything else → `TunnelUnknownError`
+ */
+export function classifyTunnelFailure(err: unknown, context: TunnelErrorContext = {}): TunnelError {
+  const ctx: TunnelErrorContext = {
+    ...context,
+    cause: context.cause ?? err,
+  };
+  const message = extractMessage(err);
+  const code = extractErrorCode(err);
+  const status = extractStatusCode(err);
+  const lowered = message.toLowerCase();
+
+  if (code && NETWORK_CODES.has(code)) {
+    return new TunnelNetworkError(message, ctx);
+  }
+
+  if (/timeout|timed out|econnrefused|econnreset|enotfound|network/i.test(lowered)) {
+    return new TunnelNetworkError(message, ctx);
+  }
+
+  if (
+    status === 401 ||
+    status === 403 ||
+    /\b(401|403|unauthori[sz]ed|forbidden)\b/i.test(lowered)
+  ) {
+    return new TunnelAuthError(message, ctx);
+  }
+
+  if (
+    status === 429 ||
+    /quota|rate.?limit|too many|subdomain.*(in use|taken|already)/i.test(lowered)
+  ) {
+    return new TunnelQuotaError(message, ctx);
+  }
+
+  return new TunnelUnknownError(message || 'tunnel failed', ctx);
+}

package/lib/tunnel/index.ts

@@ -3,6 +3,7 @@ import https from 'node:https';
 import { URL } from 'node:url';
 import localtunnel from '@desplega.ai/localtunnel';
 import { getEnv } from '../env/index.js';
+import { classifyTunnelFailure, TunnelError } from './errors.js';
 
 export interface TunnelSession {
   tunnel: localtunnel.Tunnel;
@@ -69,24 +70,38 @@ export class TunnelManager {
         options.apiKey,
         options.sessionIndex
       );
-      console.log(`Using deterministic subdomain: ${subdomain}`);
+      console.error(`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.error(`Using random subdomain: ${subdomain}`);
     }
 
-    console.log(`Starting tunnel on port ${port} with host ${host} in region ${region}`);
+    console.error(`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,
-    });
+    let tunnel: localtunnel.Tunnel;
+    try {
+      tunnel = await localtunnel({
+        port,
+        host,
+        subdomain,
+        local_host: options.localHost || 'localhost',
+        auth: true,
+      });
+    } catch (err) {
+      // Classify provider errors into structured TunnelError subclasses so
+      // the CLI can render a triage-hint message. Zero retries here —
+      // surface the failure immediately.
+      const classified =
+        err instanceof TunnelError
+          ? err
+          : classifyTunnelFailure(err, {
+              target: `${options.localHost || 'localhost'}:${port}`,
+            });
+      throw classified;
+    }
 
-    console.log(`Tunnel started at ${tunnel.url}`);
+    console.error(`Tunnel started at ${tunnel.url}`);
 
     this.session = {
       tunnel,