@desplega.ai/qa-use 2.14.1 → 2.15.0

package/dist/src/cli/lib/tunnel-banner.js

@@ -0,0 +1,55 @@
+/**
+ * Auto-tunnel banner helpers (stderr-only, TTY-aware).
+ *
+ * `printTunnelStartBanner` is the multi-line boxed notice shown when a
+ * new tunnel is started. `printTunnelReuseBanner` is the short
+ * single-line notice used when an existing tunnel is reused (Phase 3
+ * consumer, but lands here so all banner copy lives in one place).
+ *
+ * Suppression rules — banner prints nothing when ANY of the following
+ * hold:
+ *   - `process.stderr.isTTY` is falsy (piped / redirected stderr)
+ *   - `process.env.QA_USE_QUIET === '1'`
+ *   - caller passes `{ quiet: true }`
+ */
+function shouldSuppress(quiet) {
+    if (quiet)
+        return true;
+    if (process.env.QA_USE_QUIET === '1')
+        return true;
+    if (!process.stderr.isTTY)
+        return true;
+    return false;
+}
+/**
+ * Multi-line boxed banner printed on a fresh tunnel start.
+ */
+export function printTunnelStartBanner(options) {
+    if (shouldSuppress(options.quiet))
+        return;
+    const lines = [
+        '╭─ Auto-tunnel active ──────────────────────────────',
+        `│ Detected localhost target: ${options.target}`,
+        '│ Remote backend cannot reach your machine directly,',
+        '│ so qa-use is exposing it via:',
+        '│',
+        `│   ${options.publicUrl}`,
+        '│',
+        '│ Disable with --no-tunnel (or use a public URL).',
+        '╰───────────────────────────────────────────────────',
+    ];
+    for (const line of lines) {
+        console.error(line);
+    }
+}
+/**
+ * Single-line notice printed when an existing tunnel is reused.
+ * Used by the Phase-3 registry layer; lives here so all banner copy
+ * stays co-located.
+ */
+export function printTunnelReuseBanner(options) {
+    if (shouldSuppress(options.quiet))
+        return;
+    console.error(`↻ Auto-tunnel reuse: ${options.target} → ${options.publicUrl}`);
+}
+//# sourceMappingURL=tunnel-banner.js.map

package/dist/src/cli/lib/tunnel-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-banner.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,SAAS,cAAc,CAAC,KAA0B;IAChD,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA4B;IACjE,IAAI,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAE1C,MAAM,KAAK,GAAG;QACZ,sDAAsD;QACtD,gCAAgC,OAAO,CAAC,MAAM,EAAE;QAChD,sDAAsD;QACtD,iCAAiC;QACjC,GAAG;QACH,OAAO,OAAO,CAAC,SAAS,EAAE;QAC1B,GAAG;QACH,mDAAmD;QACnD,sDAAsD;KACvD,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA4B;IACjE,IAAI,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAE1C,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;AACjF,CAAC"}

package/dist/src/cli/lib/tunnel-error-hint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Triage-hint formatter for structured tunnel errors.
+ *
+ * The brainstorm defines the user-facing copy:
+ *   × Auto-tunnel failed for <target>
+ *     Attempted: start tunnel via <provider>
+ *     Likely cause: <subclass-specific>
+ *     Next steps:
+ *       • Retry: ...
+ *       • Skip tunnel: --no-tunnel ...
+ *       • Check tunnel status: `qa-use tunnel status`
+ *
+ * Each tunnel-error subclass picks its own "likely cause" line.
+ */
+import { type TunnelError } from '../../../lib/tunnel/errors.js';
+/**
+ * Return a multi-line string ready to print to stderr.
+ */
+export declare function formatTunnelFailure(err: TunnelError): string;
+//# sourceMappingURL=tunnel-error-hint.d.ts.map

package/dist/src/cli/lib/tunnel-error-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-error-hint.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-error-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,WAAW,EAGjB,MAAM,+BAA+B,CAAC;AAevC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAoB5D"}

package/dist/src/cli/lib/tunnel-error-hint.js

@@ -0,0 +1,48 @@
+/**
+ * Triage-hint formatter for structured tunnel errors.
+ *
+ * The brainstorm defines the user-facing copy:
+ *   × Auto-tunnel failed for <target>
+ *     Attempted: start tunnel via <provider>
+ *     Likely cause: <subclass-specific>
+ *     Next steps:
+ *       • Retry: ...
+ *       • Skip tunnel: --no-tunnel ...
+ *       • Check tunnel status: `qa-use tunnel status`
+ *
+ * Each tunnel-error subclass picks its own "likely cause" line.
+ */
+import { TunnelAuthError, TunnelNetworkError, TunnelQuotaError, } from '../../../lib/tunnel/errors.js';
+function likelyCause(err) {
+    if (err instanceof TunnelNetworkError) {
+        return 'network timeout or connectivity issue reaching the tunnel provider';
+    }
+    if (err instanceof TunnelAuthError) {
+        return 'authentication rejected (bad or expired API key)';
+    }
+    if (err instanceof TunnelQuotaError) {
+        return 'tunnel quota / rate-limit exceeded, or subdomain already in use';
+    }
+    return 'unknown failure from the tunnel provider';
+}
+/**
+ * Return a multi-line string ready to print to stderr.
+ */
+export function formatTunnelFailure(err) {
+    const target = err.target ?? '<unknown target>';
+    const provider = err.provider ?? 'localtunnel';
+    const lines = [
+        `× Auto-tunnel failed for ${target}`,
+        `  Attempted: start tunnel via ${provider}`,
+        `  Likely cause: ${likelyCause(err)}`,
+    ];
+    if (err.message) {
+        lines.push(`  Error: ${err.message}`);
+    }
+    lines.push('  Next steps:');
+    lines.push('    • Retry: the failure may be transient');
+    lines.push('    • Skip tunnel: rerun with --no-tunnel (only works if the backend can reach your target)');
+    lines.push('    • Check tunnel status: `qa-use tunnel status`');
+    return lines.join('\n');
+}
+//# sourceMappingURL=tunnel-error-hint.js.map

package/dist/src/cli/lib/tunnel-error-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-error-hint.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-error-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EAEf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AAEvC,SAAS,WAAW,CAAC,GAAgB;IACnC,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;QACtC,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IACD,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;QACnC,OAAO,kDAAkD,CAAC;IAC5D,CAAC;IACD,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;QACpC,OAAO,iEAAiE,CAAC;IAC3E,CAAC;IACD,OAAO,0CAA0C,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAgB;IAClD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,kBAAkB,CAAC;IAChD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;IAE/C,MAAM,KAAK,GAAa;QACtB,4BAA4B,MAAM,EAAE;QACpC,iCAAiC,QAAQ,EAAE;QAC3C,mBAAmB,WAAW,CAAC,GAAG,CAAC,EAAE;KACtC,CAAC;IACF,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,CACR,6FAA6F,CAC9F,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAEhE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/cli/lib/tunnel-option.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tri-state `--tunnel` option helper for Commander commands.
+ *
+ * Shape:
+ *   --tunnel [auto|on|off]   (default: auto; bare --tunnel = on)
+ *   --no-tunnel              (alias for --tunnel off)
+ *
+ * Invalid values are rejected at parse time with a clear error.
+ *
+ * Bare `--tunnel` (no value) is preserved as sugar for `--tunnel on`, which
+ * matches the pre-tri-state UX. Commander represents the bare form by passing
+ * the literal string `"true"` (or `undefined` depending on argv shape) through
+ * to the parser, so we map both to `'on'`.
+ */
+import { type Command } from 'commander';
+export type TunnelMode = 'auto' | 'on' | 'off';
+/**
+ * Attach the tri-state `--tunnel` option to a Commander command.
+ *
+ * The option is stored under the property name `tunnel` on the options
+ * object. Callers can read it as a `TunnelMode`.
+ *
+ * Also registers `--no-tunnel` as an alias that resolves to `'off'`, and
+ * accepts bare `--tunnel` (no value) as sugar for `--tunnel on`.
+ */
+export declare function addTunnelOption(command: Command): Command;
+//# sourceMappingURL=tunnel-option.d.ts.map

package/dist/src/cli/lib/tunnel-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-option.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAgC,MAAM,WAAW,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;AAwC/C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CA4BzD"}

package/dist/src/cli/lib/tunnel-option.js

@@ -0,0 +1,77 @@
+/**
+ * Tri-state `--tunnel` option helper for Commander commands.
+ *
+ * Shape:
+ *   --tunnel [auto|on|off]   (default: auto; bare --tunnel = on)
+ *   --no-tunnel              (alias for --tunnel off)
+ *
+ * Invalid values are rejected at parse time with a clear error.
+ *
+ * Bare `--tunnel` (no value) is preserved as sugar for `--tunnel on`, which
+ * matches the pre-tri-state UX. Commander represents the bare form by passing
+ * the literal string `"true"` (or `undefined` depending on argv shape) through
+ * to the parser, so we map both to `'on'`.
+ */
+import { InvalidArgumentError, Option } from 'commander';
+const VALID_MODES = ['auto', 'on', 'off'];
+/**
+ * Parser for --tunnel [mode]. Accepts 'auto' | 'on' | 'off'.
+ * - Bare `--tunnel` (no value) → 'on' (backward-compat sugar).
+ * - `--no-tunnel` (boolean `false`) → 'off'.
+ * - Invalid strings are rejected.
+ */
+function parseTunnelMode(value) {
+    // `--no-tunnel` arrives here as the boolean `false` (Commander's
+    // --no-<flag> negation semantics). Map it to 'off'.
+    if (value === false) {
+        return 'off';
+    }
+    // Bare `--tunnel` (no value). With the `[mode]` optional-arg form,
+    // Commander substitutes the literal string `"true"` as a placeholder
+    // when the flag is present without an explicit value. Treat that and
+    // `undefined` as the backward-compat sugar → 'on'.
+    if (value === undefined || value === true || value === 'true') {
+        return 'on';
+    }
+    if (typeof value !== 'string') {
+        throw new InvalidArgumentError(`Invalid --tunnel value. Expected one of: ${VALID_MODES.join(', ')}.`);
+    }
+    const normalized = value.toLowerCase();
+    if (!VALID_MODES.includes(normalized)) {
+        throw new InvalidArgumentError(`Invalid --tunnel value: "${value}". Expected one of: ${VALID_MODES.join(', ')}.`);
+    }
+    return normalized;
+}
+/**
+ * Attach the tri-state `--tunnel` option to a Commander command.
+ *
+ * The option is stored under the property name `tunnel` on the options
+ * object. Callers can read it as a `TunnelMode`.
+ *
+ * Also registers `--no-tunnel` as an alias that resolves to `'off'`, and
+ * accepts bare `--tunnel` (no value) as sugar for `--tunnel on`.
+ */
+export function addTunnelOption(command) {
+    const option = new Option('--tunnel [mode]', 'Tunnel mode: auto (localhost-only), on (force, default when flag present without value), off (never)')
+        .default('auto')
+        .argParser(parseTunnelMode);
+    command.addOption(option);
+    // `--no-tunnel` as an alias for `--tunnel off`. Commander treats this as a
+    // separate boolean option that, when present, sets the `tunnel` property to
+    // `false`. Normalise that to `'off'` in a preAction hook so downstream
+    // consumers only ever see a `TunnelMode` string.
+    command.option('--no-tunnel', 'Disable tunnel (alias for --tunnel off)');
+    command.hook('preAction', (cmd) => {
+        const opts = cmd.opts();
+        if (opts.tunnel === false) {
+            cmd.setOptionValue('tunnel', 'off');
+        }
+        else if (opts.tunnel === true || opts.tunnel === 'true') {
+            // Bare `--tunnel` with no argParser invocation path (belt-and-braces):
+            // some Commander versions skip argParser when the optional arg is absent.
+            cmd.setOptionValue('tunnel', 'on');
+        }
+    });
+    return command;
+}
+//# sourceMappingURL=tunnel-option.js.map

package/dist/src/cli/lib/tunnel-option.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-option.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,oBAAoB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAIvE,MAAM,WAAW,GAA0B,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAU,CAAC;AAE1E;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,iEAAiE;IACjE,oDAAoD;IACpD,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,qEAAqE;IACrE,qEAAqE;IACrE,mDAAmD;IACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,oBAAoB,CAC5B,4CAA4C,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACtE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAgB,CAAC;IACrD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAC5B,4BAA4B,KAAK,uBAAuB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAClF,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,iBAAiB,EACjB,sGAAsG,CACvG;SACE,OAAO,CAAC,MAAoB,CAAC;SAC7B,SAAS,CAAC,eAAe,CAAC,CAAC;IAE9B,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE1B,2EAA2E;IAC3E,4EAA4E;IAC5E,uEAAuE;IACvE,iDAAiD;IACjD,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,yCAAyC,CAAC,CAAC;IAEzE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC1B,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1D,uEAAuE;YACvE,0EAA0E;YAC1E,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/cli/lib/tunnel-resolve.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the effective tunnel mode from CLI flag + config file, and
+ * turn that mode into a concrete on/off decision using the base URL
+ * and API URL.
+ *
+ * Precedence for `resolveTunnelFlag`:
+ *   1. CLI flag (if the user explicitly passed --tunnel / --no-tunnel)
+ *   2. Config file (`tunnel` key in ~/.qa-use.json)
+ *   3. Default: 'auto'
+ *
+ * `resolveTunnelMode` is the Phase-2 auto-inference: `'auto'` maps to
+ * `'on'` iff `isLocalhostUrl(baseUrl) && !isLocalhostUrl(apiUrl)`, else
+ * `'off'`. `'on'` and `'off'` are passed through untouched.
+ */
+import type { TunnelMode } from './tunnel-option.js';
+export type { TunnelMode } from './tunnel-option.js';
+/**
+ * Resolve the tunnel mode from CLI + config inputs.
+ *
+ * @param cliFlag - value of the `--tunnel` option after Commander parsing;
+ *   may be `undefined` when the caller hasn't wired the flag yet, or when
+ *   the option has no default (but in practice we default to 'auto', so
+ *   callers will usually pass 'auto' here)
+ * @param configFile - value of `~/.qa-use.json`'s `tunnel` key
+ */
+export declare function resolveTunnelFlag(cliFlag: TunnelMode | undefined, configFile: TunnelMode | undefined): TunnelMode;
+/**
+ * Resolve the concrete on/off decision for the tunnel.
+ *
+ * Matrix:
+ *   - `mode === 'on'`   → `'on'`  (force tunnel, even in dev mode)
+ *   - `mode === 'off'`  → `'off'` (never tunnel)
+ *   - `mode === 'auto'` → `'on'` iff base URL is localhost and API URL is
+ *                         *not* localhost; otherwise `'off'`.
+ *
+ * If either `baseUrl` or `apiUrl` is unknown in `'auto'` mode, we stay
+ * conservative and return `'off'`: without a localhost base URL there's
+ * nothing worth tunnelling, and without a known API URL we can't tell
+ * whether we're in dev mode (where auto-tunnel should be skipped).
+ */
+export declare function resolveTunnelMode(mode: TunnelMode, baseUrl: string | undefined, apiUrl: string | undefined): 'on' | 'off';
+//# sourceMappingURL=tunnel-resolve.d.ts.map

package/dist/src/cli/lib/tunnel-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-resolve.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,UAAU,EAAE,UAAU,GAAG,SAAS,GACjC,UAAU,CAgBZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,GAAG,KAAK,CAWd"}

package/dist/src/cli/lib/tunnel-resolve.js

@@ -0,0 +1,72 @@
+/**
+ * Resolve the effective tunnel mode from CLI flag + config file, and
+ * turn that mode into a concrete on/off decision using the base URL
+ * and API URL.
+ *
+ * Precedence for `resolveTunnelFlag`:
+ *   1. CLI flag (if the user explicitly passed --tunnel / --no-tunnel)
+ *   2. Config file (`tunnel` key in ~/.qa-use.json)
+ *   3. Default: 'auto'
+ *
+ * `resolveTunnelMode` is the Phase-2 auto-inference: `'auto'` maps to
+ * `'on'` iff `isLocalhostUrl(baseUrl) && !isLocalhostUrl(apiUrl)`, else
+ * `'off'`. `'on'` and `'off'` are passed through untouched.
+ */
+import { isLocalhostUrl } from '../../../lib/env/localhost.js';
+/**
+ * Resolve the tunnel mode from CLI + config inputs.
+ *
+ * @param cliFlag - value of the `--tunnel` option after Commander parsing;
+ *   may be `undefined` when the caller hasn't wired the flag yet, or when
+ *   the option has no default (but in practice we default to 'auto', so
+ *   callers will usually pass 'auto' here)
+ * @param configFile - value of `~/.qa-use.json`'s `tunnel` key
+ */
+export function resolveTunnelFlag(cliFlag, configFile) {
+    // Phase 1: we can't reliably distinguish "user passed --tunnel auto" from
+    // "Commander filled in the 'auto' default" without extra bookkeeping on the
+    // command. So the contract here is: the caller gives us the post-parse
+    // value. If they want config precedence to apply, they should pass
+    // `undefined` when the CLI value is the unchanged default. To keep this
+    // phase simple and predictable — and aligned with the plan's "CLI > config
+    // > default 'auto'" precedence — we treat a CLI-passed 'auto' as
+    // "no explicit override" so the config value can take effect.
+    if (cliFlag !== undefined && cliFlag !== 'auto') {
+        return cliFlag;
+    }
+    if (configFile !== undefined) {
+        return configFile;
+    }
+    return 'auto';
+}
+/**
+ * Resolve the concrete on/off decision for the tunnel.
+ *
+ * Matrix:
+ *   - `mode === 'on'`   → `'on'`  (force tunnel, even in dev mode)
+ *   - `mode === 'off'`  → `'off'` (never tunnel)
+ *   - `mode === 'auto'` → `'on'` iff base URL is localhost and API URL is
+ *                         *not* localhost; otherwise `'off'`.
+ *
+ * If either `baseUrl` or `apiUrl` is unknown in `'auto'` mode, we stay
+ * conservative and return `'off'`: without a localhost base URL there's
+ * nothing worth tunnelling, and without a known API URL we can't tell
+ * whether we're in dev mode (where auto-tunnel should be skipped).
+ */
+export function resolveTunnelMode(mode, baseUrl, apiUrl) {
+    if (mode === 'on')
+        return 'on';
+    if (mode === 'off')
+        return 'off';
+    // mode === 'auto'
+    if (!baseUrl)
+        return 'off';
+    if (!isLocalhostUrl(baseUrl))
+        return 'off';
+    // Dev-mode skip: if the API is itself local, the backend can reach
+    // localhost directly — no tunnel needed.
+    if (apiUrl && isLocalhostUrl(apiUrl))
+        return 'off';
+    return 'on';
+}
+//# sourceMappingURL=tunnel-resolve.js.map

package/dist/src/cli/lib/tunnel-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-resolve.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAK/D;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA+B,EAC/B,UAAkC;IAElC,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,mEAAmE;IACnE,wEAAwE;IACxE,2EAA2E;IAC3E,iEAAiE;IACjE,8DAA8D;IAC9D,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAgB,EAChB,OAA2B,EAC3B,MAA0B;IAE1B,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAEjC,kBAAkB;IAClB,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,mEAAmE;IACnE,yCAAyC;IACzC,IAAI,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,IAAI,CAAC;AACd,CAAC"}

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