@desplega.ai/qa-use 2.14.1 → 2.15.0

package/dist/lib/tunnel/errors.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+/**
+ * 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 {
+    target;
+    provider;
+    cause;
+    constructor(message, context = {}) {
+        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, context = {}) {
+        super(message, context);
+        this.name = 'TunnelNetworkError';
+    }
+}
+/** Auth failure (bad/expired API key, 401/403 from provider). */
+export class TunnelAuthError extends TunnelError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'TunnelAuthError';
+    }
+}
+/** Quota / rate-limit / subdomain-clash failure. */
+export class TunnelQuotaError extends TunnelError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'TunnelQuotaError';
+    }
+}
+/** Fallback when no classification matched. */
+export class TunnelUnknownError extends TunnelError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'TunnelUnknownError';
+    }
+}
+function extractStatusCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const obj = err;
+    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;
+        if (typeof respObj.status === 'number')
+            return respObj.status;
+        if (typeof respObj.statusCode === 'number')
+            return respObj.statusCode;
+    }
+    return undefined;
+}
+function extractErrorCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const obj = err;
+    if (typeof obj.code === 'string')
+        return obj.code;
+    return undefined;
+}
+function extractMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    if (err && typeof err === 'object') {
+        const obj = err;
+        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, context = {}) {
+    const ctx = {
+        ...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);
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/tunnel/errors.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/index.ts"],"names":[],"mappings":"AAGA,OAAO,WAAW,MAAM,0BAA0B,CAAC;AAGnD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkB;IAEhD;;;;;OAKG;IACH,MAAM,CAAC,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAa7E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAuE9E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,UAAU,IAAI,aAAa,GAAG,IAAI;IAIlC,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA+BrC,YAAY,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAcpC,eAAe,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAe3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/index.ts"],"names":[],"mappings":"AAGA,OAAO,WAAW,MAAM,0BAA0B,CAAC;AAInD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkB;IAEhD;;;;;OAKG;IACH,MAAM,CAAC,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAa7E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAqF9E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,UAAU,IAAI,aAAa,GAAG,IAAI;IAIlC,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA+BrC,YAAY,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAcpC,eAAe,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAe3D"}

package/dist/lib/tunnel/index.js

@@ -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 class TunnelManager {
     session = null;
     defaultRegion = 'auto';
@@ -42,22 +43,36 @@ export class TunnelManager {
         if (!subdomain && options.apiKey !== undefined && options.sessionIndex !== undefined) {
             // Use deterministic subdomain based on API key and session index
             subdomain = TunnelManager.generateDeterministicSubdomain(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}`);
-        const tunnel = await localtunnel({
-            port,
-            host,
-            subdomain,
-            local_host: options.localHost || 'localhost',
-            auth: true,
-        });
-        console.log(`Tunnel started at ${tunnel.url}`);
+        console.error(`Starting tunnel on port ${port} with host ${host} in region ${region}`);
+        let 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.error(`Tunnel started at ${tunnel.url}`);
         this.session = {
             tunnel,
             publicUrl: tunnel.url,

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/tunnel/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/tunnel/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,WAAW,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAkBjE,MAAM,OAAO,aAAa;IAChB,OAAO,GAAyB,IAAI,CAAC;IAC5B,aAAa,GAAW,MAAM,CAAC;IAEhD;;;;;OAKG;IACH,MAAM,CAAC,8BAA8B,CAAC,MAAc,EAAE,YAAoB;QACxE,iCAAiC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEtE,8CAA8C;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEvC,kDAAkD;QAClD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QAE1D,OAAO,UAAU,SAAS,IAAI,UAAU,EAAE,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,UAAyB,EAAE;QACzD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC;QAC7D,IAAI,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAEjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,wDAAwD;YACxD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,IAAI,GAAG,2BAA2B,CAAC;YACrC,CAAC;iBAAM,CAAC;gBACN,8BAA8B;gBAC9B,IAAI,GAAG,wBAAwB,CAAC;YAClC,CAAC;QACH,CAAC;QAED,uDAAuD;QACvD,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACrF,iEAAiE;YACjE,SAAS,GAAG,aAAa,CAAC,8BAA8B,CACtD,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,YAAY,CACrB,CAAC;YACF,OAAO,CAAC,KAAK,CAAC,kCAAkC,SAAS,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACtB,+CAA+C;YAC/C,SAAS,GAAG,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,OAAO,CAAC,KAAK,CAAC,2BAA2B,SAAS,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,2BAA2B,IAAI,cAAc,IAAI,cAAc,MAAM,EAAE,CAAC,CAAC;QAEvF,IAAI,MAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,WAAW,CAAC;gBACzB,IAAI;gBACJ,IAAI;gBACJ,SAAS;gBACT,UAAU,EAAE,OAAO,CAAC,SAAS,IAAI,WAAW;gBAC5C,IAAI,EAAE,IAAI;aACX,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,gEAAgE;YAChE,mCAAmC;YACnC,MAAM,UAAU,GACd,GAAG,YAAY,WAAW;gBACxB,CAAC,CAAC,GAAG;gBACL,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE;oBACzB,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,WAAW,IAAI,IAAI,EAAE;iBACtD,CAAC,CAAC;YACT,MAAM,UAAU,CAAC;QACnB,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,qBAAqB,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,OAAO,GAAG;YACb,MAAM;YACN,SAAS,EAAE,MAAM,CAAC,GAAG;YACrB,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,IAAI;YACd,IAAI;YACJ,MAAM;SACP,CAAC;QAEF,uBAAuB;QACvB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YAChC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAChC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YAChC,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAEhC,IAAI,CAAC;YACH,8EAA8E;YAC9E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;gBACjC,OAAO,CAAC,aAAa,GAAG,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACrG,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;gBAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;YACpB,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;YAE3D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;gBAC3C,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,2DAA2D;YAC3D,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,KAAK;iBACF,GAAG,CAAC,uBAAuB,EAAE,CAAC,GAAG,EAAE,EAAE;gBACpC,IAAI,IAAI,GAAG,EAAE,CAAC;gBACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;gBAC3C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAC5C,CAAC,CAAC;iBACD,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACnB,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED,eAAe,CAAC,kBAA0B;QACxC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAE/B,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;YAEnC,qDAAqD;YACrD,OAAO,CACL,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,MAAM,CAC1F,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,182 @@
+/**
+ * TunnelRegistry — a shared, refcount-managed layer over `TunnelManager`.
+ *
+ * Goals:
+ *   - Two CLI commands targeting the same localhost base URL share one
+ *     remote tunnel (one public URL, one provider connection).
+ *   - State is visible and editable across sibling processes via
+ *     `~/.qa-use/tunnels/<hash>.json`, so a SECOND process targeting the
+ *     same localhost picks up the FIRST process's public URL rather than
+ *     spinning up its own tunnel.
+ *   - Last-releaser (in the OWNER process) keeps the tunnel alive for
+ *     `GRACE_MS` (30 s default) so rapid-fire invocations do not thrash
+ *     the provider.
+ *
+ * Cross-process coordination model:
+ *   - The process that first acquires a given target becomes the OWNER
+ *     and runs the in-process `TunnelManager`. Its PID is recorded in
+ *     the registry file.
+ *   - Later acquirers in OTHER processes read the file, see an alive
+ *     owner PID, increment refcount under a lockfile, and return an
+ *     "attach" handle (`isCrossProcessAttach: true`) with the owner's
+ *     `publicUrl`. They do NOT construct a `TunnelManager`.
+ *   - Read-modify-write of the record is guarded by a lockfile
+ *     (`<hash>.lock`, `O_EXCL | O_CREAT`) with bounded retry.
+ *
+ * TTL grace limitation:
+ *   - The grace window is bounded by the OWNER process's lifetime. Since
+ *     `TunnelManager` is a per-process localtunnel client, the remote
+ *     tunnel dies when the owner exits. For long-lived owners
+ *     (`tunnel start --hold`, a running `test run`, a detached
+ *     `browser create` from Phase 4) grace works as designed: a new
+ *     acquirer within `GRACE_MS` cancels tear-down. For short-lived
+ *     commands that release-and-exit immediately, grace collapses to
+ *     zero (the owner process is gone, so there is no tunnel to keep
+ *     alive anyway).
+ *
+ * Non-goals (this phase):
+ *   - Daemonised tunnel hosts. Phase 4 adds detach so short-lived
+ *     commands can leave a long-lived owner behind.
+ *   - Retries on provider failure. Zero retries, consistent with Phase 2.
+ */
+import { TunnelManager, type TunnelOptions } from './index.js';
+/**
+ * How long (ms) to keep a tunnel alive after its refcount hits zero.
+ * A new `acquire()` within this window reuses the existing tunnel.
+ * Overridable via `QA_USE_TUNNEL_GRACE_MS` env var (primarily a
+ * test-friendly knob; production callers should stick with the default).
+ */
+export declare const GRACE_MS = 30000;
+/**
+ * Max concurrent tunnels per API key. Mirrors the sessionIndex clamp at
+ * `lib/tunnel/index.ts:41` so we surface a clear error instead of silently
+ * colliding on subdomains.
+ */
+export declare const MAX_CONCURRENT_TUNNELS = 10;
+/** On-disk schema for a registry entry. */
+export interface TunnelRecord {
+    id: string;
+    target: string;
+    publicUrl: string;
+    pid: number;
+    refcount: number;
+    ttlExpiresAt: number | null;
+    startedAt: number;
+}
+/**
+ * Handle returned by `acquire()` / kept in memory by consumers.
+ *
+ * Consumers must call `registry.release(handle)` exactly once per
+ * `acquire()` call.
+ */
+export interface TunnelHandle extends TunnelRecord {
+    /**
+     * True when this handle was acquired from a foreign process's tunnel
+     * (the registry file's `pid` !== `process.pid`). The caller MUST NOT
+     * attempt to retrieve a `TunnelManager` via `getLiveManager(target)` —
+     * there isn't one in this process. Use `handle.publicUrl` directly.
+     */
+    isCrossProcessAttach: boolean;
+    /**
+     * Internal marker used to guard double-release. Not persisted.
+     */
+    _released?: boolean;
+}
+/**
+ * Canonical target key — used both as the map key and to derive the
+ * filename hash. We lowercase the hostname and drop any path/query so
+ * `http://Localhost:3000/foo` and `http://localhost:3000/` dedupe.
+ */
+export declare function canonicalTarget(target: string): string;
+/** Filename hash for a target. First 10 hex chars of sha256. */
+export declare function targetHash(target: string): string;
+/**
+ * Hook used by tests to inject a fake `TunnelManager` without booting a
+ * real tunnel. When unset (the default) the registry constructs a real
+ * `TunnelManager`.
+ */
+export type TunnelManagerFactory = () => TunnelManager;
+export interface TunnelRegistryOptions {
+    /** Override factory (tests). */
+    managerFactory?: TunnelManagerFactory;
+    /** Override grace window (tests). */
+    graceMs?: number;
+    /** Override concurrency cap (tests). */
+    maxConcurrent?: number;
+    /** Options threaded into `TunnelManager.startTunnel(...)`. */
+    tunnelOptions?: TunnelOptions;
+}
+/**
+ * Acquire / release / list API for tunnels.
+ *
+ * A singleton is exported as `tunnelRegistry` below for convenience;
+ * callers that need isolation (tests) construct their own instance.
+ */
+export declare class TunnelRegistry {
+    private readonly live;
+    private readonly graceMs;
+    private readonly maxConcurrent;
+    private readonly managerFactory;
+    constructor(opts?: TunnelRegistryOptions);
+    /**
+     * Start a tunnel for `target` (or reuse an existing one — in-process
+     * OR in a sibling process), returning a handle. Caller must pair each
+     * acquire with exactly one `release(handle)`.
+     */
+    acquire(target: string, opts?: TunnelOptions): Promise<TunnelHandle>;
+    /**
+     * Release a handle. Decrements refcount (under lock). When the
+     * refcount hits zero AND we are the owner, schedule a tear-down
+     * `graceMs` later. A subsequent `acquire()` within the grace window
+     * cancels the tear-down.
+     *
+     * Grace window is bounded by owner process lifetime — short-lived
+     * commands exit before grace expires and will tear down immediately.
+     */
+    release(handle: TunnelHandle): Promise<void>;
+    /**
+     * Force teardown of a tunnel regardless of refcount. Used by
+     * `qa-use tunnel close`. Safe to call when no such tunnel exists.
+     *
+     * If the owner is this process, tears down the in-memory manager.
+     * Otherwise just removes the registry file (and leaves the orphan
+     * remote tunnel to die with its owner).
+     */
+    forceClose(target: string): Promise<void>;
+    /**
+     * Look up a single entry by canonical target. Scans the on-disk
+     * registry; returns `null` if no record exists or the owning pid is
+     * dead.
+     */
+    get(target: string): TunnelRecord | null;
+    /**
+     * List all live entries. Reconciles against owning PID; stale entries
+     * are removed as a side-effect.
+     */
+    list(): TunnelRecord[];
+    /**
+     * Returns the live `TunnelManager` instance for `target` IF this process
+     * currently owns it. Used by callers that need health-check / WS-URL
+     * helpers on the underlying manager. Returns `null` for targets owned
+     * by a different process (file visible via `list()` / `get()` but not
+     * live in-memory here).
+     */
+    getLiveManager(target: string): TunnelManager | null;
+    /**
+     * Look up by filename hash (e.g. output of `tunnel ls`).
+     */
+    getByHash(hash: string): TunnelRecord | null;
+    private writeRecord;
+    /**
+     * Timer callback: re-check under lock whether we should tear down. A
+     * concurrent acquire may have bumped refcount back above zero.
+     */
+    private maybeTeardown;
+    /**
+     * Unconditional tear-down. Callers must hold the per-target lock.
+     */
+    private teardown;
+}
+/** Module-level singleton for CLI use. */
+export declare const tunnelRegistry: TunnelRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AASH,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAS,CAAC;AAU/B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AA+GD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;gBAE1C,IAAI,GAAE,qBAA0B;IAM5C;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsH9E;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDlD;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAaxC;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IA2BtB;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAMpD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAe5C,OAAO,CAAC,WAAW;IAKnB;;;OAGG;YACW,aAAa;IA0D3B;;OAEG;YACW,QAAQ;CAoBvB;AAED,0CAA0C;AAC1C,eAAO,MAAM,cAAc,gBAAuB,CAAC"}