@desplega.ai/qa-use 2.14.1 → 2.15.0

package/README.md

@@ -93,9 +93,32 @@ qa-use browser run                     # Interactive REPL mode
 | `qa-use browser screenshot <path>` | Save screenshot |
 | `qa-use browser run` | Interactive REPL mode |
 | `qa-use browser close` | Close browser session |
+| `qa-use browser status --list` | List active sessions across processes |
 
 Run `qa-use browser --help` for the full list of 29 browser commands.
 
+### Tunnel & Maintenance Commands
+
+`browser create` auto-tunnels when your target is localhost and the API is remote. For standalone tunnels (or cross-process registry inspection) use `qa-use tunnel`:
+
+```bash
+qa-use tunnel start http://localhost:3000 --hold   # Hold a public tunnel
+qa-use tunnel ls                                   # List active tunnels
+qa-use tunnel status <target|hash>                 # Detail for one entry
+qa-use tunnel close <target|hash>                  # Force-release a tunnel
+qa-use doctor                                      # Reap stale sessions/tunnels
+qa-use doctor --dry-run                            # Preview what would be reaped
+```
+
+| Command | Description |
+|---------|-------------|
+| `qa-use tunnel ls` | List active tunnels in the registry |
+| `qa-use tunnel status <target>` | Show detail for a single tunnel |
+| `qa-use tunnel close <target>` | Force-release a tunnel (kills detached holder) |
+| `qa-use doctor` | Reap stale sessions/tunnels (dead PIDs) |
+
+> **Note:** `qa-use tunnel *` is the CLI-side cross-process tunnel registry, distinct from `qa-use mcp tunnel` which is the MCP-mode persistent tunnel wrapper (see below).
+
 ### API Commands
 
 Dynamic API access powered by live OpenAPI (`/api/v1/openapi.json`) with local cache fallback.

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

@@ -6,6 +6,14 @@
  * 2. Config file (~/.qa-use.json) top-level fields (api_key, api_url, etc.)
  * 3. Config file (~/.qa-use.json) env block ({ "env": { "VAR_NAME": "value" } })
  */
+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';
 export type EnvSource = 'env' | 'config' | 'none';
 export interface EnvResult {
     value: string | undefined;
@@ -48,6 +56,11 @@ export declare function logConfigSources(): void;
  * Priority: config file headers, then QA_USE_HEADERS env var overrides.
  */
 export declare function getCustomHeaders(): Record<string, string> | null;
+export declare function getTunnelModeFromConfig(): QaUseTunnelMode | undefined;
+/**
+ * Reset the tunnel-warning latch (for tests).
+ */
+export declare function clearTunnelWarningLatch(): void;
 /**
  * Get agent session ID from environment if available.
  * Used for auto-linking browser sessions and test runs to agent sessions.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8DH,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;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAwBxD;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;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAwBhE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;AA6DpD,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;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAwBxD;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;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAwBhE;AAYD,wBAAgB,uBAAuB,IAAI,eAAe,GAAG,SAAS,CAmBrE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}

package/dist/lib/env/index.js

@@ -9,6 +9,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+export { getPortFromUrl, isLocalhostUrl } from './localhost.js';
+const VALID_TUNNEL_MODES = ['auto', 'on', 'off'];
 /**
  * Mapping from env var names to top-level config field names.
  * Allows getEnvWithSource to check direct fields before the env block.
@@ -173,6 +175,39 @@ export function getCustomHeaders() {
     }
     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() {
+    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)) {
+        return raw;
+    }
+    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() {
+    tunnelWarningLogged = false;
+}
 /**
  * Get agent session ID from environment if available.
  * Used for auto-linking browser sessions and test runs to agent sessions.

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAUhE,MAAM,kBAAkB,GAA+B,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAU,CAAC;AAWtF;;;GAGG;AACH,MAAM,YAAY,GAAsC;IACtD,cAAc,EAAE,SAAS;IACzB,cAAc,EAAE,SAAS;IACzB,cAAc,EAAE,SAAS;IACzB,aAAa,EAAE,QAAQ;CACxB,CAAC;AAEF,IAAI,YAAY,GAAuB,IAAI,CAAC;AAC5C,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAEhC;;GAEG;AACH,SAAS,aAAa;IACpB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU;IACjB,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,mBAAmB,GAAG,IAAI,CAAC;IAE3B,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;IAEnC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAClD,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;QAClD,OAAO,YAAY,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,mCAAmC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,EAAE,CAAC;gBACjD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;YACjD,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;IACpB,mBAAmB,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAC,aAAa,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,MAAiB;IAC7C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK;YACR,OAAO,sBAAsB,CAAC;QAChC,KAAK,QAAQ;YACX,OAAO,8BAA8B,CAAC;QACxC,KAAK,MAAM;YACT,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;IAEjD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,CAAC,IAAI,CAAC,cAAc,SAAS,UAAU,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1F,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACvC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,aAAa,GAAI,MAAkC,CAAC,OAAO,CAAC;QAClE,IAAI,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YACxF,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC9C,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5E,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED;;;;;;;;GAQG;AACH,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAChC,MAAM,UAAU,uBAAuB;IACrC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAExD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,kBAAkB,CAAC,QAAQ,CAAC,GAAsB,CAAC,EAAE,CAAC;QACnF,OAAO,GAAsB,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CACX,qDAAqD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI;YAC1E,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAC/E,CAAC;QACF,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,mBAAmB,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,SAAS,CAAC;AAC1D,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * 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`.
+ */
+/**
+ * Check if a URL points to localhost.
+ *
+ * Matches:
+ *   - `localhost`
+ *   - `127.0.0.1`
+ *   - `::1`
+ *   - `*.localhost` (e.g., `foo.localhost`)
+ *   - `0.0.0.0`
+ */
+export declare function isLocalhostUrl(url: string): boolean;
+/**
+ * Get the port from a URL, defaulting to 443 for https and 80 otherwise.
+ */
+export declare function getPortFromUrl(url: string): number;
+//# sourceMappingURL=localhost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localhost.d.ts","sourceRoot":"","sources":["../../../lib/env/localhost.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAgBnD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUlD"}

package/dist/lib/env/localhost.js

@@ -0,0 +1,49 @@
+/**
+ * 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) {
+    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) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.port) {
+            return parseInt(parsed.port, 10);
+        }
+        return parsed.protocol === 'https:' ? 443 : 80;
+    }
+    catch {
+        return 80;
+    }
+}
+//# sourceMappingURL=localhost.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localhost.js","sourceRoot":"","sources":["../../../lib/env/localhost.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,+DAA+D;QAC/D,6CAA6C;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACrD,OAAO,CACL,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,KAAK;YACd,IAAI,KAAK,SAAS;YAClB,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAC5B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * Base dir for all qa-use CLI-side state. Defaults to `~/.qa-use` but may
+ * be overridden via `QA_USE_HOME` (test-friendly).
+ */
+export declare function qaUseDir(): string;
+/**
+ * Where persisted tunnel registry entries live. Each active tunnel is a
+ * single JSON file named `<sha256(target)[0..10]>.json`.
+ */
+export declare function tunnelsDir(): string;
+/**
+ * Where detached browser-session PID files live (used by Phase 4 onward).
+ */
+export declare function sessionsDir(): string;
+/**
+ * Ensure a directory exists (recursively). No-op if it already does.
+ */
+export declare function ensureDir(dir: string): void;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../lib/env/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAMjC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C"}

package/dist/lib/env/paths.js

@@ -0,0 +1,42 @@
+/**
+ * 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() {
+    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() {
+    return path.join(qaUseDir(), 'tunnels');
+}
+/**
+ * Where detached browser-session PID files live (used by Phase 4 onward).
+ */
+export function sessionsDir() {
+    return path.join(qaUseDir(), 'sessions');
+}
+/**
+ * Ensure a directory exists (recursively). No-op if it already does.
+ */
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../lib/env/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACzC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function sessionFilePath(sessionId: string): string;
+export declare function writeSessionRecord(record: DetachedSessionRecord): void;
+export declare function readSessionRecord(sessionId: string): DetachedSessionRecord | null;
+export declare function removeSessionRecord(sessionId: string): void;
+/**
+ * List all persisted detached-session records. Does NOT reconcile
+ * against PIDs — callers decide how to handle stale entries.
+ */
+export declare function listSessionRecords(): DetachedSessionRecord[];
+/** Cheap liveness check — `kill(pid, 0)` returns true if the pid exists. */
+export declare function isPidAlive(pid: number): boolean;
+//# sourceMappingURL=sessions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../lib/env/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAOtE;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CASjF;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA0C3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,EAAE,CAqB5D;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAS/C"}

package/dist/lib/env/sessions.js

@@ -0,0 +1,128 @@
+/**
+ * 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';
+export function sessionFilePath(sessionId) {
+    return path.join(sessionsDir(), `${sessionId}.json`);
+}
+export function writeSessionRecord(record) {
+    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) {
+    try {
+        const raw = fs.readFileSync(sessionFilePath(sessionId), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id !== 'string' || typeof parsed.pid !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeSessionRecord(sessionId) {
+    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.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;
+    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);
+            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() {
+    const dir = sessionsDir();
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    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);
+            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) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=sessions.js.map

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * 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 declare class TunnelError extends Error {
+    readonly target?: string;
+    readonly provider?: string;
+    readonly cause?: unknown;
+    constructor(message: string, context?: TunnelErrorContext);
+}
+/** Network / connectivity failure (DNS, timeout, ECONNREFUSED, etc.). */
+export declare class TunnelNetworkError extends TunnelError {
+    constructor(message: string, context?: TunnelErrorContext);
+}
+/** Auth failure (bad/expired API key, 401/403 from provider). */
+export declare class TunnelAuthError extends TunnelError {
+    constructor(message: string, context?: TunnelErrorContext);
+}
+/** Quota / rate-limit / subdomain-clash failure. */
+export declare class TunnelQuotaError extends TunnelError {
+    constructor(message: string, context?: TunnelErrorContext);
+}
+/** Fallback when no classification matched. */
+export declare class TunnelUnknownError extends TunnelError {
+    constructor(message: string, context?: TunnelErrorContext);
+}
+/**
+ * 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 declare function classifyTunnelFailure(err: unknown, context?: TunnelErrorContext): TunnelError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAO9D;AAED,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAI9D;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAI9D;AAED,oDAAoD;AACpD,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAI9D;AAED,+CAA+C;AAC/C,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAI9D;AAmDD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAkCjG"}