@desplega.ai/qa-use 2.14.0 → 2.15.0

package/dist/src/cli/commands/tunnel/ls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/ls.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBpC,eAAO,MAAM,SAAS,SAuDlB,CAAC"}

package/dist/src/cli/commands/tunnel/ls.js

@@ -0,0 +1,89 @@
+/**
+ * qa-use tunnel ls - List active tunnels in the registry.
+ *
+ * Scans `~/.qa-use/tunnels/*.json`, reconciles against owning PID, and
+ * renders a table (or JSON) with target, public URL, refcount, TTL
+ * remaining.
+ */
+import { Command } from 'commander';
+import { tunnelRegistry } from '../../../../lib/tunnel/registry.js';
+import { error, formatError, warning } from '../../lib/output.js';
+import { printTable, truncate } from '../../lib/table.js';
+function formatTtl(record) {
+    if (record.ttlExpiresAt === null || record.ttlExpiresAt === undefined) {
+        return '-';
+    }
+    const remaining = record.ttlExpiresAt - Date.now();
+    if (remaining <= 0)
+        return 'expiring';
+    if (remaining < 1000)
+        return '<1s';
+    const seconds = Math.ceil(remaining / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    return `${Math.ceil(seconds / 60)}m`;
+}
+function formatAge(record) {
+    const age = Math.max(0, Date.now() - record.startedAt);
+    const seconds = Math.floor(age / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m`;
+    return `${Math.floor(seconds / 3600)}h`;
+}
+export const lsCommand = new Command('ls')
+    .description('List active tunnels in the registry')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const records = tunnelRegistry.list();
+        if (options.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        const columns = [
+            { key: 'id', header: 'ID', width: 10 },
+            {
+                key: 'target',
+                header: 'TARGET',
+                width: 30,
+                format: (v) => truncate(String(v ?? '-'), 30),
+            },
+            {
+                key: 'publicUrl',
+                header: 'PUBLIC URL',
+                width: 40,
+                format: (v) => truncate(String(v ?? '-'), 40),
+            },
+            {
+                key: 'refcount',
+                header: 'REF',
+                width: 4,
+                format: (v) => String(v ?? 0),
+            },
+            { key: 'pid', header: 'PID', width: 7 },
+            {
+                key: 'age',
+                header: 'AGE',
+                width: 5,
+                format: (_v, row) => formatAge(row),
+            },
+            {
+                key: 'ttl',
+                header: 'TTL',
+                width: 8,
+                format: (_v, row) => formatTtl(row),
+            },
+        ];
+        printTable(columns, records, {
+            title: `Active Tunnels (${records.length} entr${records.length === 1 ? 'y' : 'ies'})`,
+            emptyMessage: warning('No active tunnels'),
+        });
+    }
+    catch (err) {
+        console.log(error(`Failed to list tunnels: ${formatError(err)}`));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=ls.js.map

package/dist/src/cli/commands/tunnel/ls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.js","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/ls.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAqB,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAe,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEvE,SAAS,SAAS,CAAC,MAAoB;IACrC,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtE,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACnD,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IACtC,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC5C,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,GAAG,CAAC;IACvC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC;AACvC,CAAC;AAED,SAAS,SAAS,CAAC,MAAoB;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IACvC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,GAAG,CAAC;IACvC,IAAI,OAAO,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC;IAC1D,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;KACvC,WAAW,CAAC,qCAAqC,CAAC;KAClD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,EAAE;IAC5C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC;QAEtC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAa;YACxB,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;YACtC;gBACE,GAAG,EAAE,QAAQ;gBACb,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;aAC9C;YACD;gBACE,GAAG,EAAE,WAAW;gBAChB,MAAM,EAAE,YAAY;gBACpB,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;aAC9C;YACD;gBACE,GAAG,EAAE,UAAU;gBACf,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,CAAC;gBACR,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;aAC9B;YACD,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE;YACvC;gBACE,GAAG,EAAE,KAAK;gBACV,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,CAAC;gBACR,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAA8B,CAAC;aAC/D;YACD;gBACE,GAAG,EAAE,KAAK;gBACV,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,CAAC;gBACR,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAA8B,CAAC;aAC/D;SACF,CAAC;QAEF,UAAU,CAAC,OAAO,EAAE,OAAoD,EAAE;YACxE,KAAK,EAAE,mBAAmB,OAAO,CAAC,MAAM,QAAQ,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;YACrF,YAAY,EAAE,OAAO,CAAC,mBAAmB,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,2BAA2B,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/src/cli/commands/tunnel/start.d.ts

@@ -0,0 +1,15 @@
+/**
+ * qa-use tunnel start - Acquire (or reuse) a tunnel for a localhost URL.
+ *
+ * Without `--hold`: acquires and immediately releases. That's useful for
+ * a quick "give me a public URL" probe — the tunnel stays alive while
+ * any other consumer (e.g. a detached `browser create`) holds it, else
+ * it tears down after the registry grace window.
+ *
+ * With `--hold`: the process keeps holding the handle until it's killed
+ * (Ctrl-C, SIGTERM). This is the primary "give me a public URL for this
+ * localhost and keep it up" mode.
+ */
+import { Command } from 'commander';
+export declare const startCommand: Command;
+//# sourceMappingURL=start.d.ts.map

package/dist/src/cli/commands/tunnel/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,eAAO,MAAM,YAAY,SAyDrB,CAAC"}

package/dist/src/cli/commands/tunnel/start.js

@@ -0,0 +1,65 @@
+/**
+ * qa-use tunnel start - Acquire (or reuse) a tunnel for a localhost URL.
+ *
+ * Without `--hold`: acquires and immediately releases. That's useful for
+ * a quick "give me a public URL" probe — the tunnel stays alive while
+ * any other consumer (e.g. a detached `browser create`) holds it, else
+ * it tears down after the registry grace window.
+ *
+ * With `--hold`: the process keeps holding the handle until it's killed
+ * (Ctrl-C, SIGTERM). This is the primary "give me a public URL for this
+ * localhost and keep it up" mode.
+ */
+import { Command } from 'commander';
+import { tunnelRegistry } from '../../../../lib/tunnel/registry.js';
+import { error, formatError, info, success } from '../../lib/output.js';
+export const startCommand = new Command('start')
+    .description('Start (or reuse) a tunnel for a localhost URL')
+    .argument('<url>', 'Target URL to tunnel (e.g. http://localhost:3000)')
+    .option('--hold', 'Keep the tunnel alive until this process is killed (Ctrl-C / SIGTERM)')
+    .option('--json', 'Output as JSON')
+    .action(async (url, options) => {
+    try {
+        const handle = await tunnelRegistry.acquire(url);
+        if (options.json) {
+            console.log(JSON.stringify({
+                id: handle.id,
+                target: handle.target,
+                publicUrl: handle.publicUrl,
+                refcount: handle.refcount,
+                hold: Boolean(options.hold),
+            }, null, 2));
+        }
+        else {
+            console.log(success(`Tunnel ready: ${handle.target} → ${handle.publicUrl}`));
+        }
+        if (!options.hold) {
+            // Release immediately. The registry keeps the tunnel alive for
+            // the grace window; another consumer joining in that window
+            // reuses it.
+            await tunnelRegistry.release(handle);
+            return;
+        }
+        if (!options.json) {
+            console.log(info('Holding tunnel. Press Ctrl-C to release.'));
+        }
+        const cleanup = async (signal) => {
+            if (!options.json) {
+                console.error(`\nReceived ${signal}, releasing tunnel...`);
+            }
+            await tunnelRegistry.release(handle);
+            process.exit(0);
+        };
+        process.on('SIGINT', () => void cleanup('SIGINT'));
+        process.on('SIGTERM', () => void cleanup('SIGTERM'));
+        // Keep the event loop alive.
+        await new Promise(() => {
+            /* never resolves; process exits via signal */
+        });
+    }
+    catch (err) {
+        console.log(error(`Failed to start tunnel: ${formatError(err)}`));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=start.js.map

package/dist/src/cli/commands/tunnel/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC;KAC7C,WAAW,CAAC,+CAA+C,CAAC;KAC5D,QAAQ,CAAC,OAAO,EAAE,mDAAmD,CAAC;KACtE,MAAM,CAAC,QAAQ,EAAE,uEAAuE,CAAC;KACzF,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,OAA2C,EAAE,EAAE;IACzE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAEjD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CACZ;gBACE,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;aAC5B,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,MAAM,CAAC,MAAM,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/E,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,+DAA+D;YAC/D,4DAA4D;YAC5D,aAAa;YACb,MAAM,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;YACvC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBAClB,OAAO,CAAC,KAAK,CAAC,cAAc,MAAM,uBAAuB,CAAC,CAAC;YAC7D,CAAC;YACD,MAAM,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QAErD,6BAA6B;QAC7B,MAAM,IAAI,OAAO,CAAO,GAAG,EAAE;YAC3B,8CAA8C;QAChD,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,2BAA2B,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/src/cli/commands/tunnel/status.d.ts

@@ -0,0 +1,8 @@
+/**
+ * qa-use tunnel status - Show detail for a single tunnel entry.
+ *
+ * Accepts either a target URL or a hash ID (as reported by `tunnel ls`).
+ */
+import { Command } from 'commander';
+export declare const statusCommand: Command;
+//# sourceMappingURL=status.d.ts.map

package/dist/src/cli/commands/tunnel/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,eAAO,MAAM,aAAa,SAqCtB,CAAC"}

package/dist/src/cli/commands/tunnel/status.js

@@ -0,0 +1,58 @@
+/**
+ * qa-use tunnel status - Show detail for a single tunnel entry.
+ *
+ * Accepts either a target URL or a hash ID (as reported by `tunnel ls`).
+ */
+import { Command } from 'commander';
+import { tunnelRegistry } from '../../../../lib/tunnel/registry.js';
+import { error, formatError } from '../../lib/output.js';
+const colors = {
+    reset: '\x1b[0m',
+    gray: '\x1b[90m',
+    cyan: '\x1b[36m',
+};
+function printField(label, value) {
+    console.log(`  ${colors.gray}${label.padEnd(14)}${colors.reset} ${value}`);
+}
+function resolve(identifier) {
+    // Accept bare hash (10 hex chars).
+    if (/^[a-f0-9]{10}$/i.test(identifier)) {
+        return tunnelRegistry.getByHash(identifier.toLowerCase());
+    }
+    return tunnelRegistry.get(identifier);
+}
+export const statusCommand = new Command('status')
+    .description('Show detail for a single tunnel entry (by target URL or hash ID)')
+    .argument('<target-or-hash>', 'Target URL (e.g. http://localhost:3000) or tunnel hash ID')
+    .option('--json', 'Output as JSON')
+    .action(async (identifier, options) => {
+    try {
+        const record = resolve(identifier);
+        if (!record) {
+            if (options.json) {
+                console.log('null');
+            }
+            else {
+                console.log(error(`No active tunnel for ${identifier}`));
+            }
+            process.exit(1);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(record, null, 2));
+            return;
+        }
+        console.log(`${colors.cyan}Tunnel${colors.reset}\n`);
+        printField('ID', record.id);
+        printField('Target', record.target);
+        printField('Public URL', record.publicUrl);
+        printField('PID', String(record.pid));
+        printField('Refcount', String(record.refcount));
+        printField('Started', new Date(record.startedAt).toISOString());
+        printField('TTL Expires', record.ttlExpiresAt ? new Date(record.ttlExpiresAt).toISOString() : '-');
+    }
+    catch (err) {
+        console.log(error(`Failed to fetch tunnel: ${formatError(err)}`));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=status.js.map

package/dist/src/cli/commands/tunnel/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../../../src/cli/commands/tunnel/status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAqB,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,GAAG;IACb,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF,SAAS,UAAU,CAAC,KAAa,EAAE,KAAa;IAC9C,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,OAAO,CAAC,UAAkB;IACjC,mCAAmC;IACnC,IAAI,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACvC,OAAO,cAAc,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC;KAC/C,WAAW,CAAC,kEAAkE,CAAC;KAC/E,QAAQ,CAAC,kBAAkB,EAAE,2DAA2D,CAAC;KACzF,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAkB,EAAE,OAA2B,EAAE,EAAE;IAChE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QAEnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,wBAAwB,UAAU,EAAE,CAAC,CAAC,CAAC;YAC3D,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7C,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,SAAS,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;QACrD,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,UAAU,CAAC,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3C,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAChD,UAAU,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAChE,UAAU,CACR,aAAa,EACb,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,CACxE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,2BAA2B,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/src/cli/generated/docs-content.d.ts

@@ -3,7 +3,7 @@
  * DO NOT EDIT MANUALLY — Generated from plugins/qa-use/skills/qa-use/
  * Run 'bun run generate:docs' to regenerate.
  */
-export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session\nqa-use browser create --viewport desktop\n\n# For localhost testing\nqa-use browser create --tunnel --no-headless\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run and save the (non-synced) local test to cloud\nqa-use test run login --persist\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**Persist vs Sync:**\n\nA local test is **synced** when its YAML has both an `id:` and a `version_hash:`\n(these are written back by `test sync push`/`pull`). `--persist` on `test run`\nand `qa-use test sync` are related but not the same:\n\n| Local file state | `persist` | What happens at run time |\n|---|---|---|\n| Non-synced | `false` (default) | Runs locally; nothing saved to cloud. Re-run with `--persist` or use `test sync push` to persist. |\n| Non-synced | `true` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** \u2014 prefer `test sync push` once the file tracks the cloud id. |\n| Synced | `false` | Runs against the cloud-tracked definition; no extra write. |\n| Synced | `true` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use `test sync push`/`pull` for explicit version control. |\n\nRule of thumb: `test sync push`/`pull` is the deliberate path. Reserve `--persist`\n(or `defaults.persist: true` in `.qa-use.json`) for one-off uploads of brand-new\nlocal tests.\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel` | Create local browser with API tunnel |\n| `qa-use browser create --no-headless` | Show browser window (tunnel mode only) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser close` | Close active session |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel` | Run with local browser tunnel |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api` | Show help and available subcommands |\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api info /api/v1/<route>` | Show route details: parameters, request body, responses |\n| `qa-use api info /api/v1/<route> -X POST` | Show info for specific HTTP method |\n| `qa-use api info /api/v1/<route> --json` | Route info as JSON |\n| `qa-use api examples` | Show usage examples |\n| `qa-use api openapi` | Print OpenAPI spec URL |\n| `qa-use api openapi --raw` | Dump full OpenAPI spec as JSON |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test\nqa-use test run login\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session\nqa-use browser create --tunnel --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Tunnel Mode)\n\n**When to use tunnel mode:**\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 YES \u2192 Use --tunnel\n  \u2502   \u2514\u2500 qa-use browser create --tunnel [--no-headless]\n  \u2502       (Starts local Playwright, creates localtunnel, keeps running)\n  \u2502\n  \u2514\u2500 NO (Public URL) \u2192 Use remote browser (default)\n      \u2514\u2500 qa-use browser create\n          (Uses desplega.ai cloud browser via WebSocket)\n```\n\n**The `--tunnel` flag is a binary choice:**\n- **Local tunnel mode**: Playwright on your machine + localtunnel\n- **Remote mode**: WebSocket URL to cloud-hosted browser\n\n**For test execution:**\n```bash\n# Local app\nqa-use test run my_test --tunnel [--headful]\n\n# Public app\nqa-use test run my_test\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session\nqa-use browser create --tunnel\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Testing localhost without `--tunnel` | Use `--tunnel` flag |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
+export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session (returns immediately \u2014 runs detached in the background)\nqa-use browser create --viewport desktop\n\n# For localhost testing \u2014 auto-tunnels when base URL is localhost and API is remote.\n# No flag needed for the common case:\nqa-use browser create --no-headless http://localhost:3000\n\n# Force a tunnel even in dev mode:\nqa-use browser create --tunnel on --no-headless\n\n# Opt out of auto-tunnel (e.g. backend is also local):\nqa-use browser create --no-tunnel\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Background session management:**\n\n`qa-use browser create` returns immediately \u2014 the actual browser + tunnel run in a detached child process so your terminal stays free. Manage sessions with:\n\n```bash\nqa-use browser status --list   # Show all active sessions across processes\nqa-use browser status           # Details for the auto-resolved session\nqa-use browser close <id>       # Close a specific session\nqa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)\nqa-use doctor --dry-run         # Preview what would be cleaned\n```\n\n**Tunnel commands:**\n\nCross-process tunnel registry \u2014 multiple commands share a single tunnel per target:\n\n```bash\nqa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)\nqa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C\nqa-use tunnel ls                  # List active tunnels (target, public URL, refcount)\nqa-use tunnel status <target>     # Detail for a single tunnel\nqa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact (auto-tunnels localhost)\nqa-use browser create --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run and save the (non-synced) local test to cloud\nqa-use test run login --persist\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**Persist vs Sync:**\n\nA local test is **synced** when its YAML has both an `id:` and a `version_hash:`\n(these are written back by `test sync push`/`pull`). `--persist` on `test run`\nand `qa-use test sync` are related but not the same:\n\n| Local file state | `persist` | What happens at run time |\n|---|---|---|\n| Non-synced | `false` (default) | Runs locally; nothing saved to cloud. Re-run with `--persist` or use `test sync push` to persist. |\n| Non-synced | `true` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** \u2014 prefer `test sync push` once the file tracks the cloud id. |\n| Synced | `false` | Runs against the cloud-tracked definition; no extra write. |\n| Synced | `true` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use `test sync push`/`pull` for explicit version control. |\n\nRule of thumb: `test sync push`/`pull` is the deliberate path. Reserve `--persist`\n(or `defaults.persist: true` in `.qa-use.json`) for one-off uploads of brand-new\nlocal tests.\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel [auto\\|on\\|off]` | Tunnel mode \u2014 default `auto` (localhost + remote API). `--no-tunnel` is sugar for `off`. |\n| `qa-use browser create --no-headless` | Show browser window (paired with a local/tunnel browser) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser status --list` | Show all active sessions across processes |\n| `qa-use browser close` | Close active session |\n| `qa-use browser close <id>` | Close a specific session by id |\n| `qa-use doctor` | Reap stale sessions/tunnels (dead PIDs) |\n| `qa-use tunnel ls` | List active tunnels in the registry |\n| `qa-use tunnel start <url> --hold` | Hold a public tunnel for external consumers |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed. `browser create` returns immediately \u2014 the browser + tunnel run in a detached child. Use `qa-use doctor` if stale state accumulates.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel [mode]` | Override tunnel mode (`auto`, `on`, `off`). `--no-tunnel` is sugar for `off`. Bare `--tunnel` is sugar for `on`. |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api` | Show help and available subcommands |\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api info /api/v1/<route>` | Show route details: parameters, request body, responses |\n| `qa-use api info /api/v1/<route> -X POST` | Show info for specific HTTP method |\n| `qa-use api info /api/v1/<route> --json` | Route info as JSON |\n| `qa-use api examples` | Show usage examples |\n| `qa-use api openapi` | Print OpenAPI spec URL |\n| `qa-use api openapi --raw` | Dump full OpenAPI spec as JSON |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test\nqa-use test run login\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session (auto-tunnels localhost targets)\nqa-use browser create --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Auto-Tunnel)\n\n**qa-use auto-tunnels localhost targets when the API is remote.** No flag required for the common case:\n\n```bash\nqa-use browser create --no-headless http://localhost:3000\nqa-use test run my_test   # auto-tunnels if base_url is localhost\n```\n\n**Tri-state `--tunnel` flag:**\n\n| Value | Behavior |\n|-------|----------|\n| `auto` (default) | Tunnel iff base URL is localhost AND API URL is remote |\n| `on` (or bare `--tunnel`) | Force a tunnel even in dev mode |\n| `off` (or `--no-tunnel`) | Never tunnel |\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 API remote (default)  \u2192 auto-tunnels. No flag needed.\n  \u251C\u2500 API also local (dev)  \u2192 no tunnel by default. Use --tunnel on to force.\n  \u2514\u2500 Public URL target     \u2192 no tunnel (remote cloud browser)\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session (auto-tunnels if target is localhost + API remote)\nqa-use browser create http://localhost:3000\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Forcing `--tunnel` in dev (both local) | Rely on auto-mode, or use `--tunnel on` explicitly |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
 export declare const REFERENCE_DOCS: Record<string, {
     title: string;
     content: string;

package/dist/src/cli/generated/docs-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,wwwBAgtBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA+mD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}
+{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,ih1BAgvBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAwoD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}