@trawlme/cli 3.12.0 → 3.12.1

package/dist/lib/api.js

@@ -11,15 +11,6 @@ const USER_AGENT = `@trawlme/cli/${pkg.version}`;
 export class ApiError extends Error {
     status;
     next;
-    /**
-     * `next` is an OPTIONAL per-instance override of the envelope's default
-     * `next` steps (errors.ts's frozen `RETRY_POLICY`) — set only at the two
-     * apiKey-mode 401 call sites below (via authNextSteps()), where the
-     * generic "trawl login --token <jwt>" default is inert until a live
-     * TRAWL_API_KEY/TRAWL_TOKEN is unset first (#169 review). Absent for every
-     * other error, so classifyError falls back to the frozen default exactly
-     * as before.
-     */
     constructor(status, message, next) {
         super(message);
         this.status = status;
@@ -27,164 +18,35 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-/**
- * A fetch-level failure — the request never got a response at all (DNS,
- * connection refused, timeout, TLS, …). Distinguished from ApiError (which
- * always carries a real HTTP status) so the top-level handler can map it to
- * its own exit code instead of the generic uniform 1. (#71 findings 4/58)
- */
 export class NetworkError extends Error {
     constructor(message) {
         super(message);
         this.name = 'NetworkError';
     }
 }
-/**
- * A LOCAL auth failure — no token available, or a locally-decoded token
- * that's provably expired, discovered entirely client-side before any HTTP
- * call was ever made. Distinguished from ApiError(401) (a real server-issued
- * 401 response) so the --json envelope never claims `status:401` for
- * something the server never said — that would be a fabricated fact,
- * indistinguishable from an actual server round-trip to a machine consumer.
- * Both classify to the same exit code (3) / kind "auth" in classifyError
- * (errors.ts); only the envelope's `status` field differs (present for
- * ApiError, absent here). (#88 item 4)
- */
 export class AuthError extends Error {
     next;
-    /** See ApiError's `next` for what this overrides and why. */
     constructor(message, next) {
         super(message);
         this.next = next;
         this.name = 'AuthError';
     }
 }
-/**
- * The single "no token available" error — every call site in this file that
- * needs a token (request/upload/getText/stream) used to throw its own copy
- * of `new Error('Not logged in. Run: trawl login')`, which fell through
- * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
- * from an arbitrary bug. Auth-classifying it puts it on the exact same
- * exit-3 / kind:"auth" path a real 401 response already takes — but as an
- * AuthError (no HTTP call happened here), never a fabricated ApiError(401).
- * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
- * the same thing everywhere it can be observed. (#86 findings 1/2, #88 item 4)
- */
 export function notLoggedInError() {
     return new AuthError('Not logged in. Run: trawl login');
 }
-/**
- * The actionable "how to recover" tail for an apiKey-mode auth failure —
- * shared by sessionAuthMessage's apiKey branch and apiKeyUnsupportedError so
- * neither one contradicts the other. `Run: trawl login` alone is INERT
- * whenever TRAWL_API_KEY/TRAWL_TOKEN is live: getToken()'s own precedence
- * (config.ts) keeps resolving the env credential over whatever `trawl login`
- * just stored, so the login it just told the operator to run changes
- * nothing on the very next request — reproduced end to end (`login --token
- * <jwt>` reports success; the next call 401s again with the same rejected
- * key). Leads with the unset step whenever there's a live var to unset;
- * falls back to the plain original wording when there isn't (the stored
- * config token case — `trawl login` alone already fixes that one). (#169
- * review round 2 — finding 2)
- */
 function loginRemedyText() {
     const liveVar = getLiveAuthEnvVar();
     return liveVar ? `unset ${liveVar}, then run: trawl login` : 'Run: trawl login';
 }
-/**
- * The machine-readable counterpart to loginRemedyText() — feeds `ApiError`/
- * `AuthError`'s `next` override (see ApiError's doc comment) so an agent
- * reading `--json` on stdout gets the SAME "unset first" step the prose
- * message carries, never a `next` that quietly disagrees with the message
- * next to it. Only ever called from a branch that already knows the auth
- * mode is 'apiKey' — see both call sites. (#169 review round 2 — finding 2)
- */
 function authNextSteps() {
     const liveVar = getLiveAuthEnvVar();
     const login = 'trawl login --token <jwt>';
     return liveVar ? [`unset ${liveVar}`, login] : [login];
 }
-/**
- * The "this route is JWT-only" error — thrown client-side, before any HTTP
- * call, by a command that only works with a session JWT (today: `whoami`,
- * see its own doc comment for why `GET /api/users/me` was descoped rather
- * than relocated) when the resolved credential is a scoped API key instead.
- * Distinct from notLoggedInError(): there IS a credential here, it's just
- * the wrong shape for this one route. Left unhandled, that route would 401
- * and surface the generic `notLoggedInError`-adjacent message ("Session
- * expired or invalid. Run: trawl login") — wrong twice over under a key: the
- * route never accepts keys at all (no session ever "expired"), and
- * re-running `trawl login` genuinely IS the fix here, just not because
- * anything expired. Classifies to the SAME exit 3 / kind:"auth" as every
- * other auth failure (#169) — reusing the existing `auth` kind rather than
- * minting a new one, since the taxonomy question is still "not
- * authenticated the way this route needs," never a new category.
- *
- * Always called already knowing authMode is 'apiKey' (see whoami.ts) — the
- * message and `next` both route through loginRemedyText()/authNextSteps()
- * so this never emits the same inert "Run: trawl login" that finding 2
- * corrects everywhere else. (#169 review round 2 — finding 2)
- */
 export function apiKeyUnsupportedError(command) {
     return new AuthError(`${command} requires a session (JWT) — this credential is a scoped API key, which this route does not accept. ${loginRemedyText()}`, authNextSteps());
 }
-/**
- * The ONE place that decides what a real server-issued 401 means, for
- * whichever credential shape produced it (#169 review finding 1). Before this, a
- * genuine 401 always got the same "Session expired or invalid" text — true
- * for a JWT, but wrong twice over for a scoped API key: an API key doesn't
- * have a "session" to expire, and re-running `trawl login` fixes nothing
- * when the ROUTE itself is JWT-only (`scraps update`/`delete`, `scraps
- * account *`/`scraps session *`, `scraps banner`, the SSE `scraps watch` —
- * `whoami` already catches this client-side, see apiKeyUnsupportedError
- * above, but those five/six never had an equivalent guard).
- *
- * #169 review round 2 — finding 1: the FIRST fix here asserted two things
- * never established — that the route is JWT-only, AND that "the API key in
- * use is valid." Both are false whenever the 401 is the KEY's own fault
- * (revoked/rotated/malformed) rather than the route's — reproduced live
- * against `GET /api/scraps` (dual-auth, works with a key) using a revoked
- * key: the old text confidently certified the key as valid and blamed the
- * route, which sends the operator away from the actual problem. trawl_node's
- * authenticateApiKey.js (modules/developers/middlewares/authenticateApiKey.js)
- * already tells the two cases apart in the response body — `responses.error`
- * puts the real reason in `description` ("Invalid or expired API key" /
- * "Invalid API key format" / "Missing or invalid Authorization header") for
- * a REJECTED key, while a JWT-only route's `passport.authenticate('jwt')`
- * (cookie-only extractor — a Bearer header never even reaches the verify
- * step) sends passport's own bare `Unauthorized` body with nothing to
- * disambiguate. `extractErrorMessage` already unwraps that envelope and
- * prefers `description` over a `message` that only echoes the reason phrase
- * — reused here instead of re-parsing, and its plain-text fallback (`return
- * raw`) is exactly the bare `Unauthorized` case. So: a body that resolves to
- * anything other than that bare word IS the server naming the real cause —
- * trust it over any guess. Anything else (unrecoverable, or genuinely just
- * "Unauthorized") gets an honest hedge between the two live possibilities,
- * never a pick.
- *
- * Deliberately driven off the REAL response (called only where a 401 just
- * came back from the server), not a client-side allow-list of "routes a key
- * can reach" duplicated into every command handler — the server is the only
- * side that actually knows which routes accept a key, and a second,
- * hand-maintained list here would silently drift the moment trawl_node opens
- * (or closes) a route to keys. That's also why the message can't name the
- * specific CLI command the way apiKeyUnsupportedError does: this function
- * only ever sees the HTTP response, never which `trawl` verb issued the
- * request.
- *
- * `res` is optional and read defensively (`typeof res.text === 'function'`,
- * `.catch(() => '')`) — the SSE call site (`stream()`) passes a real
- * `Response` in production, but its own unit tests mock a bare `{ok,
- * status}` with no `text()` at all; a missing/failed body read just falls
- * through to the honest hedge rather than throwing a SECOND error while
- * already handling the first.
- *
- * Still an ApiError(401), not an AuthError — a real HTTP round-trip
- * happened, so the envelope's `status:401` field must stay honest about
- * that (see AuthError's own doc comment on why a LOCAL failure never
- * fabricates one). Same exit 3 / kind:"auth" either way — only the message
- * text differs. (#169 review)
- */
 async function sessionAuthMessage(authMode, res) {
     if (authMode === 'jwt')
         return 'Session expired or invalid. Run: trawl login';
@@ -195,52 +57,11 @@ async function sessionAuthMessage(authMode, res) {
     }
     return `The API key was rejected (401) — either this route requires a session (JWT), or the key is invalid or revoked. ${loginRemedyText()}.`;
 }
-/**
- * One shared header set for whichever credential `getToken()` resolved: a
- * scoped API key (`trawl_*`) goes in `Authorization: Bearer`; a session JWT
- * stays in the `TOKEN` cookie — trawl_node's passport JWT strategy is
- * cookie-only on the REST surface, so a Bearer header there is silently
- * ignored, which is why this is a SWITCH and not an addition. Never sends
- * both — two credentials on one request is an ambiguity the server does not
- * have to resolve in our favour. Takes the token the caller already
- * resolved (never re-calls getToken() itself) so a request's headers and its
- * own classification of that same token can't drift mid-flight. Used at all
- * 5 call sites that attach a credential: request/upload/publicGet/getText/
- * stream. (#169)
- */
 function authHeaders(token) {
     return getAuthMode(token) === 'apiKey' ? { Authorization: `Bearer ${token}` } : { Cookie: `TOKEN=${token}` };
 }
 const DEFAULT_TIMEOUT_MS = 30_000;
-/**
- * #91 P0 — some endpoints legitimately run 30–250s server-side: a scrap
- * execute (worker-puppeteer navigation + antibot tier escalation + AI-fix
- * dry-run retries). The generic 30s default was aborting those mid-flight
- * and surfacing a fabricated `NetworkError timed out` (exit 5) for a request
- * that was always going to succeed given enough time. Passed as the per-call
- * `{timeoutMs}` override at exactly the 4 call sites that hit those
- * endpoints: `scraps run` / `data --fresh` (GET /api/scraps/load/:id) and
- * `scraps trigger --wait` (POST /api/scraps/worker/:id, synchronous branch
- * only — the default async `?wait=false` POST returns almost immediately and
- * keeps the 30s default) — all three in src/commands/scraps.ts — plus (#114)
- * `create` (POST /api/ai/wizard, src/commands/create.ts), whose AI-generation
- * + scrap creation + first run + autofix pipeline runs the same 30–250s+
- * server-side. 300s leaves margin over the ~250s worst case without being
- * unboundedly long.
- */
 export const LONG_RUN_TIMEOUT_MS = 300_000;
-/**
- * Effective fetch timeout for one request.
- *
- * Precedence (#91): TRAWL_TIMEOUT (env) ALWAYS wins when set to a valid
- * positive number — an operator/CI override must be able to force a shorter
- * or longer ceiling globally (e.g. a slow CI network, or a deliberately tight
- * smoke-test budget) without editing call sites. Only when the env var is
- * unset/invalid does the caller-supplied per-call `overrideMs` apply (e.g.
- * LONG_RUN_TIMEOUT_MS for the 3 long-run call sites); otherwise
- * DEFAULT_TIMEOUT_MS. This preserves #71's original "env always overrides"
- * contract while layering the new per-call default beneath it, never above.
- */
 function getTimeoutMs(overrideMs) {
     const raw = process.env['TRAWL_TIMEOUT']?.trim();
     if (raw) {
@@ -250,19 +71,6 @@ function getTimeoutMs(overrideMs) {
     }
     return overrideMs !== undefined && overrideMs > 0 ? overrideMs : DEFAULT_TIMEOUT_MS;
 }
-/**
- * Wrap a `fetch()` call so connection-level failures (ECONNREFUSED, DNS,
- * timeout, …) surface as a NetworkError carrying the effective URL + the
- * unwrapped `err.cause` detail, instead of a bare "fetch failed" with no
- * actionable information. (#71 findings 4/58)
- *
- * `effectiveTimeoutMs` is the ACTUAL timeout that was armed for this specific
- * call (already resolved via getTimeoutMs by the caller) — used only to
- * report an honest number in the timeout message; #91 — before this it
- * always re-derived a fresh `getTimeoutMs()` with no override, so a request
- * armed with LONG_RUN_TIMEOUT_MS that timed out would have lied and reported
- * "timed out after 30000ms".
- */
 async function safeFetch(url, options, effectiveTimeoutMs) {
     try {
         return await fetch(url, options);
@@ -277,23 +85,10 @@ async function safeFetch(url, options, effectiveTimeoutMs) {
         throw new NetworkError(`Network error reaching ${url}${causeDetail}: ${e?.message ?? String(err)}`);
     }
 }
-/**
- * Extract the honest client-facing error string from a raw response body.
- * The server envelope (lib/helpers/responses.js) shape is
- * `{ type, message, code, status, errorCode, description, error? }` — where
- * `message` is sometimes a bare HTTP reason phrase (e.g. "Payment Required")
- * duplicating `res.statusText`, producing a tautology like
- * "402 Payment Required: Payment Required". When that happens, prefer the
- * richer `description` field instead. (#71 finding 76 — error-copy part only)
- */
 function extractErrorMessage(raw, statusText) {
     if (!raw)
         return '';
     try {
-        // #159 — an error envelope's message/description/nested `error` string can
-        // carry the same raw-control-char server quirk as a success payload;
-        // recover it here too instead of falling all the way back to the raw,
-        // unparsed blob as the "error message".
         const parsed = parseServerJson(raw);
         if (parsed && typeof parsed === 'object') {
             const env = parsed;
@@ -323,18 +118,9 @@ function extractErrorMessage(raw, statusText) {
         }
     }
     catch {
-        // not JSON — fall through
     }
     return raw;
 }
-/**
- * Best-effort extraction of an upgrade URL from a 402 response body. In
- * production the envelope rarely carries it directly (billing.quota.service
- * nests `upgradeUrl` inside AppError.details, which `responses.error` only
- * serializes to the dev-only `error` string) — so this checks the top-level
- * field, `details.upgradeUrl`, and the dev-only nested `error` JSON string,
- * and returns null (never fabricates) when none are present. (#71 finding 76)
- */
 function extractUpgradeUrl(raw) {
     try {
         const parsed = parseServerJson(raw);
@@ -357,23 +143,15 @@ function extractUpgradeUrl(raw) {
                 }
             }
             catch {
-                // dev-only nested string wasn't JSON — nothing to extract
             }
         }
     }
     catch {
-        // not JSON — nothing to extract
     }
     return null;
 }
 async function throwIfError(res, isPublic = false, authMode = 'jwt') {
     if (res.status === 401 && !isPublic) {
-        // #169 review round 2 — finding 1: sessionAuthMessage now reads the body
-        // itself (the bug this whole branch used to have was discarding it
-        // without ever calling res.text()), so it's awaited here instead of
-        // called synchronously. `next` is only overridden in apiKey mode — see
-        // authNextSteps()'s own doc comment for why jwt mode keeps the frozen
-        // default (finding 2).
         throw new ApiError(401, await sessionAuthMessage(authMode, res), authMode === 'apiKey' ? authNextSteps() : undefined);
     }
     if (!res.ok) {
@@ -418,7 +196,6 @@ async function request(path, options = {}, reqOpts = {}) {
         if (!text)
             return {};
         const parsed = parseServerJson(text);
-        // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;
         }
@@ -434,7 +211,6 @@ async function upload(path, formData, reqOpts = {}) {
         throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     const timeoutMs = getTimeoutMs(reqOpts.timeoutMs);
-    // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
     const res = await safeFetch(url, {
         method: 'POST',
         body: formData,
@@ -450,7 +226,6 @@ async function upload(path, formData, reqOpts = {}) {
         if (!text)
             return {};
         const parsed = parseServerJson(text);
-        // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;
         }
@@ -479,20 +254,6 @@ async function publicPost(path, body, baseUrlOverride, reqOpts = {}) {
         throw new Error('Invalid JSON in server response');
     }
 }
-/**
- * Unauthenticated GET — for endpoints the server itself treats as public/
- * optional-auth (e.g. `GET /api/health`, home.route.js's `optionalAuth`
- * middleware: enriches the response for an admin JWT, passes through
- * otherwise). Unlike `request()`, this NEVER throws `notLoggedInError()` for
- * a missing token — that guard exists for endpoints that genuinely require
- * auth, and applying it here defeated the whole point of a pre-login
- * sanity-check (#148). The token is still attached as a best-effort Cookie
- * when one happens to be stored/env-set, so an already-authenticated caller
- * still gets the admin-enriched payload — it's just never REQUIRED.
- * `throwIfError(res, true)` mirrors `publicPost`'s "public endpoint" 401
- * wording, even though this route's optionalAuth middleware never actually
- * rejects a request for lacking/invalid credentials.
- */
 async function publicGet(path, reqOpts = {}) {
     const token = getToken();
     const url = `${getApiUrl()}${path}`;
@@ -510,7 +271,6 @@ async function publicGet(path, reqOpts = {}) {
         if (!text)
             return {};
         const parsed = parseServerJson(text);
-        // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;
         }
@@ -520,65 +280,6 @@ 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;
@@ -604,7 +305,7 @@ function probeJson(path, opts) {
         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
+                res.resume();
                 finish(null);
                 return;
             }
@@ -623,9 +324,6 @@ function probeJson(path, opts) {
             });
             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);
@@ -652,8 +350,6 @@ 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, {
@@ -672,11 +368,6 @@ export const api = {
         if (!token)
             throw notLoggedInError();
         const url = `${getApiUrl()}${path}`;
-        // No AbortSignal.timeout here — a long-running `watch`/`--watch` stream is
-        // expected to sit open indefinitely; only connection-level failures
-        // (never a timeout) should surface via safeFetch's cause-unwrapping. (#71)
-        // effectiveTimeoutMs passed to safeFetch here is only ever used to format
-        // a timeout message that can't actually fire (no signal attached).
         const res = await safeFetch(url, {
             headers: {
                 Accept: 'text/event-stream',
@@ -684,15 +375,6 @@ export const api = {
                 ...authHeaders(token),
             },
         }, getTimeoutMs());
-        // `scraps watch` is one of the JWT-only routes (#169 review finding 1) —
-        // singled out here (not routed through throwIfError, since this call
-        // never sets `isPublic` and the SSE fetch has no timeout signal to
-        // thread through) so a real 401 gets the same honest, auth-mode-aware
-        // message every other JWT-only route does, instead of the opaque `SSE
-        // failed: 401`. sessionAuthMessage reads `res` defensively — a real SSE
-        // Response supports `.text()` in production; only this file's own mocks
-        // sometimes don't, and that falls through to the honest hedge rather
-        // than throwing a second error (see sessionAuthMessage's doc comment).
         if (res.status === 401) {
             const mode = getAuthMode(token);
             throw new ApiError(401, await sessionAuthMessage(mode, res), mode === 'apiKey' ? authNextSteps() : undefined);
@@ -716,7 +398,6 @@ export const api = {
                 }
             }
         }
-        // Flush any remaining data in buffer (stream ended without trailing newline)
         if (buffer.startsWith('data: ')) {
             yield buffer.slice(6);
         }

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

@@ -1,44 +1,8 @@
-/**
- * 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;
@@ -55,49 +19,13 @@ export declare class CdpPipe {
     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 {};