@trawlme/cli 3.10.0 → 3.12.0

package/dist/index.js

@@ -20,6 +20,8 @@ import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from '
 import { classifyError, reportError, stripCommanderErrorPrefix, retryFieldsFor } from './lib/errors.js';
 import { renderPinch, pinchEnabled } from './lib/pinch.js';
 import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
+import { getApiUrl } from './lib/config.js';
+import { resolveDocsUrls, docsFooterLine } from './lib/docs.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -142,8 +144,37 @@ export function createProgram() {
     program.addCommand(logout);
     program.addCommand(telemetry);
     program.addCommand(upgrade);
+    // #185 — one dim line pointing at the docs, appended after EVERY `--help`
+    // in the tree (registering 'afterAll' on the root fires for a subcommand's
+    // own `--help` too — commander emits the afterAllHelp event on every
+    // ancestor of whichever command's outputHelp() ran, root included).
+    // Gated the way lib/tips.ts gates its own footer-shaped output: a pure,
+    // synchronous helper (docsFooterText, exported for unit testing) wrapped
+    // in try/catch so a broken footer can never turn a clean `--help` into a
+    // crash — but deliberately WITHOUT tips.ts's TTY/--json gate: `--help`
+    // itself never emits a --json payload (nothing here can pollute that
+    // channel), and a docs line inside `--help | less` is exactly the kind of
+    // thing worth keeping, unlike a promotional nudge.
+    program.addHelpText('afterAll', docsFooterText);
     return program;
 }
+/**
+ * #185 — see the `addHelpText('afterAll', …)` call above for why this is
+ * unconditional (no TTY/--json gate) and why a thrown error must never
+ * escape: commander calls this synchronously while already writing help
+ * output, so a throw here would crash a `--help` invocation, the one code
+ * path this whole feature is not allowed to touch (see docs.ts's own
+ * `docsFooterLine` for the "never a guessed URL" contract this composes).
+ */
+export function docsFooterText() {
+    try {
+        const line = docsFooterLine(resolveDocsUrls({ apiBaseUrl: getApiUrl() }).docsUrl);
+        return line ? chalk.dim(line) : '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * True when this module is the process entrypoint (not merely imported by a test).
  *
@@ -228,6 +259,14 @@ export function isBareInvocation(argv) {
  * overstates its own invariant is worse than no comment, because the next
  * reader trusts it.
  *
+ * #185 — `spec --json` (not plain `spec`) now DOES make its own bounded
+ * (2s), swallowed-on-failure GET for `externalDocs.url` (see spec.ts's
+ * `fetchExternalDocsUrl`) — this is not a regression of the "no mutation"
+ * invariant above (a GET mutates nothing, and any failure — including no
+ * egress at all — degrades to the sync host-derivation fallback, never a
+ * thrown error), just a second, narrower kind of side effect this guard was
+ * never meant to suppress in the first place.
+ *
  * Before this, `trawl spec --json` silently re-synced
  * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
  * skill …` lines to stderr BEFORE the JSON payload — an agent's very first

package/dist/lib/api.d.ts

@@ -95,6 +95,11 @@ export interface RequestOptions {
 export declare const api: {
     get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
     publicGet: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+    /** See `probeJson`'s own doc comment — hard-bounded, probe-only, never for
+     *  a command's real work. Today's one caller: spec.ts's fetchExternalDocsUrl. */
+    probeJson: <T>(path: string, opts: {
+        timeoutMs: number;
+    }) => Promise<T | null>;
     getText: (path: string, opts?: RequestOptions) => Promise<string>;
     post: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;
     put: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;

package/dist/lib/api.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { getApiUrl, getToken, getAuthMode, getLiveAuthEnvVar } from './config.js';
 import { parseServerJson } from './json.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -518,6 +520,119 @@ async function publicGet(path, reqOpts = {}) {
         throw new Error('Invalid JSON in server response');
     }
 }
+/**
+ * A hard-bounded, PROBE-ONLY GET — never use this for a command's real work
+ * (no auth headers, no retry, no NetworkError-with-cause classification).
+ *
+ * trawl_cli#185 defect: every OTHER fetch in this file rides Node's global
+ * `fetch()` + `AbortSignal.timeout()`, which bounds the PROMISE, not the
+ * process. Aborting a fetch mid-connect does not necessarily tear down an
+ * in-flight TCP/TLS handshake — a documented Node/undici characteristic —
+ * so against a routable-but-silently-dropping host (a dropped SYN, never a
+ * RST — a realistic firewalled/air-gapped shape) the dangling socket keeps
+ * the event loop alive until Node's OWN internal connect-timeout eventually
+ * fires. Measured on this host: a bare `fetch()` + `AbortSignal.timeout(2000)`
+ * against such a host rejects its promise at ~2005ms, but the PROCESS does
+ * not exit until ~10.5s later — not configurable from here, and not paid by
+ * `ECONNREFUSED` (~0.13s) or a failed DNS lookup (~0.29s), only by the
+ * silent-drop shape. Every other command in this file accepts that risk
+ * because the user explicitly asked for that network call (`trawl ping`
+ * hanging on an unreachable host is the command doing its job — nothing to
+ * fix there). This primitive exists for the one case where the network call
+ * ITSELF is optional: `spec --json`'s own doc-discovery probe (the one
+ * command an agent runs to orient itself) has no business costing 10.5s to
+ * learn a host is unreachable, so this manages the raw socket directly.
+ *
+ * The timeout here is an INDEPENDENT `setTimeout` that calls `req.destroy()`
+ * — deliberately NOT `http.request`'s own `timeout` option (idle-based via
+ * `socket.setTimeout`, so it only fires when zero bytes arrive for that
+ * long — a coincidentally-same condition against a silent black hole, but a
+ * dishonest bound in general: it would never fire against a host that
+ * connects instantly then trickles bytes just often enough to reset the
+ * idle clock). Destroying the request/socket on this timer is what actually
+ * frees the OS-level handle so the process can exit promptly instead of
+ * waiting out Node's own multi-second connect-timeout — verified empirically
+ * (same black-holed host): total process time dropped from ~10.5s to ~2.0s
+ * with this change.
+ *
+ * Resolves to `null` on ANY failure (timeout, refusal, non-2xx, malformed
+ * JSON, an unsupported protocol) — never throws — so the one caller
+ * (spec.ts's fetchExternalDocsUrl) needs no try/catch of its own. This is
+ * NOT automatic: `node:http`/`node:https`' own `request()` throws
+ * SYNCHRONOUSLY (`ERR_INVALID_PROTOCOL`) for a URL whose protocol doesn't
+ * match the module (e.g. a stray `ftp://` in a misconfigured `TRAWL_API_URL`)
+ * — inside a Promise executor a synchronous throw becomes a REJECTED
+ * promise, which would have propagated straight through `fetchExternalDocsUrl`
+ * and turned `spec --json` into an error envelope instead of the spec.
+ * Reproduced: `TRAWL_API_URL=ftp://x node dist/index.js spec --json` failed
+ * entirely before this guard was added. The explicit protocol check below
+ * closes that.
+ *
+ * Two more deliberate departures from every other call in this file:
+ *  - `TRAWL_TIMEOUT` (getTimeoutMs's env override, #91) is NOT consulted
+ *    here — `opts.timeoutMs` is absolute. An operator raising that ceiling
+ *    for a genuinely long-running command (e.g. LONG_RUN_TIMEOUT_MS's 300s)
+ *    must never make an OPTIONAL probe wait 300s too; the two knobs measure
+ *    different things and must not share a dial.
+ *  - Redirects are NOT followed (global `fetch()`, used everywhere else in
+ *    this file, follows them by default; raw `http`/`https` `request()`
+ *    does not). For this probe a 3xx is just another non-2xx -> `null` ->
+ *    fall through to rung 2 — an acceptable degradation, not a bug.
+ */
+function probeJson(path, opts) {
+    return new Promise((settle) => {
+        let url;
+        try {
+            url = new URL(`${getApiUrl()}${path}`);
+        }
+        catch {
+            settle(null);
+            return;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            settle(null);
+            return;
+        }
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            settle(value);
+        };
+        const transport = url.protocol === 'http:' ? httpRequest : httpsRequest;
+        const req = transport(url, { headers: { 'User-Agent': USER_AGENT } }, (res) => {
+            if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                res.resume(); // drain so the socket can be released
+                finish(null);
+                return;
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    finish(JSON.parse(body));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+            res.on('error', () => finish(null));
+        });
+        // The independent, non-idle-based ceiling this function exists for —
+        // fires regardless of connect/response state and forcibly destroys the
+        // socket, unlike AbortSignal.timeout() everywhere else in this file.
+        const timer = setTimeout(() => {
+            req.destroy(new Error(`probe to ${url.href} timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs);
+        req.on('error', () => finish(null));
+        req.end();
+    });
+}
 async function getText(path, reqOpts = {}) {
     const token = getToken();
     if (!token)
@@ -537,6 +652,9 @@ async function getText(path, reqOpts = {}) {
 export const api = {
     get: (path, opts) => request(path, {}, opts),
     publicGet: (path, opts) => publicGet(path, opts),
+    /** See `probeJson`'s own doc comment — hard-bounded, probe-only, never for
+     *  a command's real work. Today's one caller: spec.ts's fetchExternalDocsUrl. */
+    probeJson: (path, opts) => probeJson(path, opts),
     getText: (path, opts) => getText(path, opts),
     post: (path, body, opts) => request(path, {
         method: 'POST',

package/dist/lib/cdp-pipe.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Raw Chrome DevTools Protocol client over Chrome's `--remote-debugging-pipe`
+ * transport (trawl_cli#183) — zero new dependencies. This is the SAME
+ * transport Puppeteer's own `pipe: true` mode uses: Chrome reads NUL
+ * (`\0`)-delimited JSON command messages on fd 3 and writes NUL-delimited
+ * JSON response/event messages on fd 4. No port, no `ws`, no HTTP polling
+ * of a `/json/version` endpoint, no parsing Chrome's stderr for a
+ * `DevTools listening on ws://…` line.
+ *
+ * Deliberately generic over any `Writable`/`Readable` pair (not tied to a
+ * real ChildProcess) so the framing/dispatch logic is fully testable with
+ * in-memory streams standing in for "Chrome" — see cdp-pipe.test.ts.
+ */
+import type { Readable, Writable } from 'node:stream';
+type EventHandler = (params: unknown, sessionId?: string) => void;
+/**
+ * A frame Chrome sent could not be parsed as JSON (trawl_cli#183 review
+ * finding 3). Distinguished from the generic "Chrome closed the CDP pipe"
+ * error so a caller can tell "the peer sent garbage and was cut off" apart
+ * from "the process actually exited" — `captureSession` reports the two
+ * with different, factual reasons rather than defaulting a corrupt-frame
+ * case to "Chrome exited".
+ */
+export declare class CdpProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * A `send()` command's own deadline elapsed with no response (trawl_cli#183
+ * review finding 3's fix; the gap it reopened is finding 4's bug class —
+ * see session-capture.ts's `readCaptureDefault`). Deliberately a SIBLING of
+ * `CdpProtocolError`, never a subclass: a protocol error means the pipe
+ * itself can no longer be trusted, so it is torn down (`isClosed` flips
+ * true, every OTHER pending command rejects too). A timeout means exactly
+ * ONE command never got an answer — Chrome is still running, the pipe is
+ * still open, every other in-flight/future command is unaffected. Making
+ * this a `CdpProtocolError` subclass would let a caller's
+ * `instanceof CdpProtocolError` (or a future one) treat a single slow
+ * command as proof the whole browser is gone, which is false. Carries only
+ * `method` and `timeoutMs` — never `params`, which can carry page-
+ * controlled data.
+ */
+export declare class CdpTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}
+export declare class CdpPipe {
+    private readonly writeStream;
+    private readonly commandTimeoutMs;
+    private nextId;
+    private buffer;
+    private readonly pending;
+    private readonly listeners;
+    private closed;
+    private protocolErr;
+    constructor(writeStream: Writable, readStream: Readable, commandTimeoutMs?: number);
+    private onClosed;
+    /**
+     * @desc A frame that fails to parse as JSON used to be dropped silently
+     * (`msg = undefined`, dispatch skipped) — any `send()` whose response was
+     * that exact frame then hung forever, since nothing ever rejected it.
+     * Now the whole pipe is torn down the same way a real Chrome exit is:
+     * every pending command rejects (with a `CdpProtocolError`, not the
+     * generic close message, so the cause is distinguishable), `isClosed`
+     * flips true, and `onClose` subscribers fire — the peer sent a frame
+     * that doesn't fit the protocol, so nothing it says next can be trusted
+     * either. The raw frame content is never included in the error message —
+     * it can carry page-controlled data (e.g. a `Runtime.evaluate` result).
+     */
+    private onProtocolError;
+    private onData;
+    private dispatch;
+    /**
+     * Send a CDP command and resolve with its `result`. Rejects if the pipe
+     * closes (Chrome exited, or a corrupt frame tore it down — see
+     * `onProtocolError`) before a response arrives, or with a
+     * `CdpTimeoutError` if no response arrives within `timeoutMs` (defaults
+     * to the pipe's own `commandTimeoutMs`, 30s) — the timeout names the
+     * METHOD, never `params` (which can carry page-controlled data).
+     * @param timeoutMs — per-call override. Lets a caller pin its own named
+     * deadline as an assertable constant rather than relying on the pipe's
+     * default silently matching (see session-capture.ts's
+     * `LOCALSTORAGE_READ_TIMEOUT_MS`, which currently equals this pipe's own
+     * 30s default but is passed explicitly anyway — a post-cap review found
+     * that giving `Runtime.evaluate` a SHORTER override here, on the
+     * assumption a page-blocked renderer "won't unblock itself in 30s any
+     * more than in 5", cut off real-but-slow work that finished on its own;
+     * there is no override value proven safe, so this parameter exists for
+     * callers that want one, not as a recommendation to use a shorter one).
+     */
+    send<T = unknown>(method: string, params?: unknown, sessionId?: string, timeoutMs?: number): Promise<T>;
+    /** Subscribe to a CDP event (`'Target.targetDestroyed'`, …). Returns an
+     *  unsubscribe function. */
+    on(method: string, handler: EventHandler): () => void;
+    /** Subscribe to the pipe closing (Chrome process gone). */
+    onClose(handler: () => void): () => void;
+    get isClosed(): boolean;
+    /** Set only when the pipe was torn down because of a corrupt frame — as
+     *  opposed to a real Chrome exit — so a caller can report the actual
+     *  cause instead of defaulting every close to "Chrome exited". */
+    get protocolError(): CdpProtocolError | undefined;
+}
+export {};

package/dist/lib/cdp-pipe.js

@@ -0,0 +1,221 @@
+/** Reserved internal event name — never collides with a real CDP method
+ *  (every real one is `Domain.method`, always containing a dot). Emitted
+ *  once the read side of the pipe ends/errors, so any in-flight capture
+ *  can tell "Chrome went away" apart from "the browser answered". */
+const PIPE_CLOSED = '__pipe_closed__';
+/** A per-command deadline that never fires under normal operation. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+/**
+ * A frame Chrome sent could not be parsed as JSON (trawl_cli#183 review
+ * finding 3). Distinguished from the generic "Chrome closed the CDP pipe"
+ * error so a caller can tell "the peer sent garbage and was cut off" apart
+ * from "the process actually exited" — `captureSession` reports the two
+ * with different, factual reasons rather than defaulting a corrupt-frame
+ * case to "Chrome exited".
+ */
+export class CdpProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CdpProtocolError';
+    }
+}
+/**
+ * A `send()` command's own deadline elapsed with no response (trawl_cli#183
+ * review finding 3's fix; the gap it reopened is finding 4's bug class —
+ * see session-capture.ts's `readCaptureDefault`). Deliberately a SIBLING of
+ * `CdpProtocolError`, never a subclass: a protocol error means the pipe
+ * itself can no longer be trusted, so it is torn down (`isClosed` flips
+ * true, every OTHER pending command rejects too). A timeout means exactly
+ * ONE command never got an answer — Chrome is still running, the pipe is
+ * still open, every other in-flight/future command is unaffected. Making
+ * this a `CdpProtocolError` subclass would let a caller's
+ * `instanceof CdpProtocolError` (or a future one) treat a single slow
+ * command as proof the whole browser is gone, which is false. Carries only
+ * `method` and `timeoutMs` — never `params`, which can carry page-
+ * controlled data.
+ */
+export class CdpTimeoutError extends Error {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs) {
+        super(`CDP command '${method}' timed out after ${timeoutMs}ms without a response`);
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+        this.name = 'CdpTimeoutError';
+    }
+}
+export class CdpPipe {
+    writeStream;
+    commandTimeoutMs;
+    nextId = 1;
+    buffer = '';
+    pending = new Map();
+    listeners = new Map();
+    closed = false;
+    protocolErr;
+    constructor(writeStream, readStream, commandTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+        this.writeStream = writeStream;
+        this.commandTimeoutMs = commandTimeoutMs;
+        readStream.setEncoding('utf8');
+        readStream.on('data', (chunk) => this.onData(chunk));
+        readStream.on('end', () => this.onClosed());
+        readStream.on('close', () => this.onClosed());
+        readStream.on('error', () => this.onClosed());
+        // fd 3 (write) and fd 4 (read) are separate sockets — Chrome dying can
+        // surface as an EPIPE on a write that lands before the read side's
+        // 'end'/'close' ever fires. An unhandled 'error' on a Writable is a
+        // thrown exception with no listener, which would kill the whole CLI
+        // process and skip captureSession's `finally` (so the temp profile is
+        // never cleaned up) — routing it through the same onClosed() path
+        // keeps "Chrome went away" a single, always-handled state.
+        writeStream.on('error', () => this.onClosed());
+    }
+    onClosed(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const closeErr = err ?? new Error('Chrome closed the CDP pipe');
+        for (const { reject } of this.pending.values())
+            reject(closeErr);
+        this.pending.clear();
+        const set = this.listeners.get(PIPE_CLOSED);
+        if (set)
+            for (const fn of set)
+                fn(undefined);
+    }
+    /**
+     * @desc A frame that fails to parse as JSON used to be dropped silently
+     * (`msg = undefined`, dispatch skipped) — any `send()` whose response was
+     * that exact frame then hung forever, since nothing ever rejected it.
+     * Now the whole pipe is torn down the same way a real Chrome exit is:
+     * every pending command rejects (with a `CdpProtocolError`, not the
+     * generic close message, so the cause is distinguishable), `isClosed`
+     * flips true, and `onClose` subscribers fire — the peer sent a frame
+     * that doesn't fit the protocol, so nothing it says next can be trusted
+     * either. The raw frame content is never included in the error message —
+     * it can carry page-controlled data (e.g. a `Runtime.evaluate` result).
+     */
+    onProtocolError() {
+        if (this.closed)
+            return;
+        const err = new CdpProtocolError('Chrome sent a CDP frame that failed to parse as JSON — the pipe can no longer be trusted and has been torn down; any in-flight command was rejected.');
+        this.protocolErr = err;
+        this.onClosed(err);
+    }
+    onData(chunk) {
+        // Once torn down (a real close, or a corrupt frame — onProtocolError)
+        // the read stream can still be alive and keep delivering chunks from
+        // an untrusted peer; without this, a later VALID-looking event frame
+        // would still `dispatch()` to any listener still registered instead
+        // of being ignored, and `this.buffer` would keep growing forever.
+        if (this.closed)
+            return;
+        this.buffer += chunk;
+        let idx = this.buffer.indexOf('\0');
+        while (idx !== -1) {
+            const raw = this.buffer.slice(0, idx);
+            this.buffer = this.buffer.slice(idx + 1);
+            if (raw.length > 0) {
+                let msg;
+                try {
+                    msg = JSON.parse(raw);
+                }
+                catch {
+                    this.onProtocolError();
+                    return; // torn down — whatever else is buffered is moot
+                }
+                this.dispatch(msg);
+            }
+            idx = this.buffer.indexOf('\0');
+        }
+    }
+    dispatch(msg) {
+        if (typeof msg.id === 'number' && this.pending.has(msg.id)) {
+            const entry = this.pending.get(msg.id);
+            this.pending.delete(msg.id);
+            if (msg.error)
+                entry.reject(new Error(`${msg.error.message} (code ${msg.error.code})`));
+            else
+                entry.resolve(msg.result);
+            return;
+        }
+        if (typeof msg.method === 'string') {
+            const set = this.listeners.get(msg.method);
+            if (set)
+                for (const fn of set)
+                    fn(msg.params, msg.sessionId);
+        }
+    }
+    /**
+     * Send a CDP command and resolve with its `result`. Rejects if the pipe
+     * closes (Chrome exited, or a corrupt frame tore it down — see
+     * `onProtocolError`) before a response arrives, or with a
+     * `CdpTimeoutError` if no response arrives within `timeoutMs` (defaults
+     * to the pipe's own `commandTimeoutMs`, 30s) — the timeout names the
+     * METHOD, never `params` (which can carry page-controlled data).
+     * @param timeoutMs — per-call override. Lets a caller pin its own named
+     * deadline as an assertable constant rather than relying on the pipe's
+     * default silently matching (see session-capture.ts's
+     * `LOCALSTORAGE_READ_TIMEOUT_MS`, which currently equals this pipe's own
+     * 30s default but is passed explicitly anyway — a post-cap review found
+     * that giving `Runtime.evaluate` a SHORTER override here, on the
+     * assumption a page-blocked renderer "won't unblock itself in 30s any
+     * more than in 5", cut off real-but-slow work that finished on its own;
+     * there is no override value proven safe, so this parameter exists for
+     * callers that want one, not as a recommendation to use a shorter one).
+     */
+    send(method, params = {}, sessionId, timeoutMs = this.commandTimeoutMs) {
+        if (this.closed)
+            return Promise.reject(this.protocolErr ?? new Error('Chrome closed the CDP pipe'));
+        const id = this.nextId++;
+        const req = { id, method, params };
+        if (sessionId)
+            req.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            // Every settle path (dispatch's resolve/reject, this timeout, a
+            // write-side EPIPE below, and onClosed's reject-all on a pipe
+            // teardown) goes through these two wrappers, so the timer is always
+            // cleared exactly once no matter which path wins the race.
+            const settleResolve = (v) => {
+                clearTimeout(timer);
+                resolve(v);
+            };
+            const settleReject = (e) => {
+                clearTimeout(timer);
+                reject(e);
+            };
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                settleReject(new CdpTimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: settleResolve, reject: settleReject });
+            this.writeStream.write(`${JSON.stringify(req)}\0`, (err) => {
+                if (err) {
+                    this.pending.delete(id);
+                    settleReject(err);
+                }
+            });
+        });
+    }
+    /** Subscribe to a CDP event (`'Target.targetDestroyed'`, …). Returns an
+     *  unsubscribe function. */
+    on(method, handler) {
+        if (!this.listeners.has(method))
+            this.listeners.set(method, new Set());
+        this.listeners.get(method).add(handler);
+        return () => this.listeners.get(method)?.delete(handler);
+    }
+    /** Subscribe to the pipe closing (Chrome process gone). */
+    onClose(handler) {
+        return this.on(PIPE_CLOSED, () => handler());
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    /** Set only when the pipe was torn down because of a corrupt frame — as
+     *  opposed to a real Chrome exit — so a caller can report the actual
+     *  cause instead of defaulting every close to "Chrome exited". */
+    get protocolError() {
+        return this.protocolErr;
+    }
+}

package/dist/lib/chrome-discovery.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @desc Resolve the Chrome executable to launch. Precedence: an explicit
+ * `--chrome <path>` flag (validated by the caller) > `TRAWL_CHROME_PATH` >
+ * `PUPPETEER_EXECUTABLE_PATH`/`CHROME_PATH` (common conventions other
+ * tools already set) > the well-known per-OS install paths. Returns null
+ * when nothing is found — the caller is responsible for a factual,
+ * non-guessing error message.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {NodeJS.Platform} platform
+ * @param {(path: string) => boolean} exists — injectable for tests.
+ */
+export declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;

package/dist/lib/chrome-discovery.js

@@ -0,0 +1,49 @@
+/**
+ * Locate a system Chrome/Chromium executable (trawl_cli#183). Same
+ * discovery approach as `@trawlme/skills`'s
+ * `trawl-scrap-local-test/scripts/run-local.mjs` `findChrome()` — a short
+ * list of well-known install paths per OS, first match wins — extended
+ * with an env override and a Windows list (the skill script only needed
+ * mac/Linux for a dev-machine local test; this ships to every user's OS).
+ */
+import { existsSync } from 'node:fs';
+const CANDIDATES = {
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+    ],
+    linux: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium-browser',
+        '/usr/bin/chromium',
+        '/snap/bin/chromium',
+    ],
+    win32: [
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files\\Chromium\\Application\\chrome.exe',
+    ],
+};
+/**
+ * @desc Resolve the Chrome executable to launch. Precedence: an explicit
+ * `--chrome <path>` flag (validated by the caller) > `TRAWL_CHROME_PATH` >
+ * `PUPPETEER_EXECUTABLE_PATH`/`CHROME_PATH` (common conventions other
+ * tools already set) > the well-known per-OS install paths. Returns null
+ * when nothing is found — the caller is responsible for a factual,
+ * non-guessing error message.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {NodeJS.Platform} platform
+ * @param {(path: string) => boolean} exists — injectable for tests.
+ */
+export function findChrome(env = process.env, platform = process.platform, exists = existsSync) {
+    const envCandidates = [env.TRAWL_CHROME_PATH, env.PUPPETEER_EXECUTABLE_PATH, env.CHROME_PATH].filter((p) => typeof p === 'string' && p.length > 0);
+    for (const p of envCandidates) {
+        if (exists(p))
+            return p;
+    }
+    const candidates = CANDIDATES[platform] ?? [];
+    return candidates.find(exists) ?? null;
+}

package/dist/lib/chrome-launch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Spawn a headed, isolated Chrome instance wired for raw CDP over
+ * `--remote-debugging-pipe` (trawl_cli#183). Thin glue only — the actual
+ * protocol lives in cdp-pipe.ts, kept separate so this file's job (build
+ * the right flags, wire fd 3/4, fail loudly if the platform doesn't expose
+ * them) stays small enough to unit test with a mocked `spawn`.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { CdpPipe } from './cdp-pipe.js';
+export interface LaunchedChrome {
+    proc: ChildProcess;
+    cdp: CdpPipe;
+}
+/**
+ * @desc The exact CLI flags Chrome is launched with. Pure + exported so
+ * the flag set is testable without spawning a real process.
+ * - `--remote-debugging-pipe` — CDP over fd 3 (in) / fd 4 (out), the
+ *   zero-dependency transport this command relies on.
+ * - `--user-data-dir` — an ephemeral, isolated profile (never the user's
+ *   real Chrome profile/cookies).
+ * - `--no-first-run` / `--no-default-browser-check` — skip first-run UI
+ *   that would otherwise sit in front of the target URL.
+ * - `--disable-sync` — never touches the user's real Google account sync.
+ * - `--password-store=basic` / `--use-mock-keychain` — a fresh profile
+ *   would otherwise prompt for the macOS login keychain (Safe Storage) the
+ *   first time Chrome touches its cookie/password store; these keep the
+ *   whole flow non-blocking on an ephemeral profile that's deleted right
+ *   after (mirrors Crawl4AI's `crwl profiles`, cited in the issue).
+ * - `--new-window` — always its own window, never a tab folded into an
+ *   already-running Chrome instance.
+ * - No `--no-sandbox`: this runs headed on the user's own machine, not in
+ *   a locked-down CI container — the sandbox stays on.
+ */
+export declare function buildChromeArgs(userDataDir: string, targetUrl: string): string[];
+/**
+ * @desc Launch Chrome and wire a CdpPipe to its fd 3 (write) / fd 4 (read).
+ * Returns a Promise rather than the `ChildProcess` synchronously: `spawn()`
+ * can fail AFTER returning — EACCES on a non-executable path, an ENOENT
+ * race, EPERM, E2BIG — by emitting an `'error'` event rather than throwing,
+ * and that event is attached to BEFORE the fd 3/4 check below so a failure
+ * from either cause rejects this promise instead of crashing the process
+ * (an EventEmitter with zero `'error'` listeners throws the error itself).
+ * @rejects {Error} if `spawn()` itself failed (the original error, so
+ * `.code` like `EACCES` survives), or if the platform/Chrome build didn't
+ * expose fd 3/4 as pipes (e.g. `--remote-debugging-pipe` unsupported) — a
+ * factual message, never a silent hang.
+ */
+export declare function launchChrome(executablePath: string, targetUrl: string, userDataDir: string, spawnFn?: typeof spawn): Promise<LaunchedChrome>;