@trawlme/cli 3.12.0 → 3.12.1

package/dist/lib/cdp-pipe.js

@@ -1,39 +1,11 @@
-/** 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;
@@ -61,13 +33,6 @@ export class CdpPipe {
         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) {
@@ -83,18 +48,6 @@ export class CdpPipe {
             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;
@@ -103,11 +56,6 @@ export class CdpPipe {
         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;
@@ -122,7 +70,7 @@ export class CdpPipe {
                 }
                 catch {
                     this.onProtocolError();
-                    return; // torn down — whatever else is buffered is moot
+                    return;
                 }
                 this.dispatch(msg);
             }
@@ -146,24 +94,6 @@ export class CdpPipe {
                     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'));
@@ -172,10 +102,6 @@ export class CdpPipe {
         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);
@@ -197,24 +123,18 @@ export class CdpPipe {
             });
         });
     }
-    /** 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

@@ -1,12 +1 @@
-/**
- * @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

@@ -1,11 +1,3 @@
-/**
- * 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: [
@@ -27,17 +19,6 @@ const CANDIDATES = {
         '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) {

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

@@ -1,48 +1,8 @@
-/**
- * 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>;

package/dist/lib/chrome-launch.js

@@ -1,32 +1,5 @@
-/**
- * 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 } from 'node:child_process';
 import { CdpPipe } from './cdp-pipe.js';
-/**
- * @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 function buildChromeArgs(userDataDir, targetUrl) {
     return [
         '--remote-debugging-pipe',
@@ -40,48 +13,13 @@ export function buildChromeArgs(userDataDir, targetUrl) {
         targetUrl,
     ];
 }
-/**
- * @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 function launchChrome(executablePath, targetUrl, userDataDir, spawnFn = spawn) {
     return new Promise((resolve, reject) => {
-        // stderr is 'ignore', not 'pipe': nothing here ever reads it (unlike the
-        // rejected `ws`-over-port design, `--remote-debugging-pipe` needs none of
-        // Chrome's stderr output), and a 'pipe' nobody drains fills its OS pipe
-        // buffer — Chrome's own logging would then block on write mid-session,
-        // freezing the browser the human is mid-login in.
         const proc = spawnFn(executablePath, buildChromeArgs(userDataDir, targetUrl), {
             stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'],
-            // POSIX only: makes Chrome the leader of its OWN process group, so its
-            // helper subprocesses (renderer/GPU/network service — Chrome forks
-            // several even for one window) live in that group too, distinct from
-            // ours. Verified against a real launch (trawl_cli#183's loopback E2E):
-            // without this, `proc.kill('SIGKILL')` only killed the main Chrome
-            // process — its helpers briefly kept the user-data-dir's files open,
-            // and `rmSync` silently lost that race, leaking the temp profile on
-            // every run. session-capture.ts's cleanup kills `-proc.pid` (the whole
-            // group) instead of `proc.pid` alone, which requires this.
             detached: process.platform !== 'win32',
         });
         let settled = false;
-        // Attached as the very first thing after `spawnFn` returns — before the
-        // fd 3/4 check below, and before anything here ever awaits — so nothing
-        // can slip through unobserved. Stays attached FOREVER, including after
-        // this promise settles: a LATE error (spawn succeeded, then something
-        // else goes wrong long after this promise already resolved) must not
-        // crash the process either, and once `settled` is true this listener is
-        // a permanent no-op — whatever consumes `proc` from here on notices
-        // Chrome went away some other way (the CDP pipe closing).
         proc.on('error', (err) => {
             if (settled)
                 return;
@@ -90,7 +28,6 @@ export function launchChrome(executablePath, targetUrl, userDataDir, spawnFn = s
                 proc.kill('SIGKILL');
             }
             catch {
-                // already gone
             }
             reject(err);
         });
@@ -102,16 +39,10 @@ export function launchChrome(executablePath, targetUrl, userDataDir, spawnFn = s
                 proc.kill('SIGKILL');
             }
             catch {
-                // already gone
             }
             reject(new Error('Chrome did not expose the CDP pipe (fd 3/4) — this Chrome build or platform may not support --remote-debugging-pipe.'));
             return;
         }
-        // Only declare success once the OS confirms the process actually
-        // started — the documented signal for that ('spawn', not merely
-        // "spawn() returned without throwing") — rather than assuming
-        // immediately: that's exactly the assumption the bug this fixes was
-        // built on.
         proc.once('spawn', () => {
             if (settled)
                 return;

package/dist/lib/config.d.ts

@@ -4,67 +4,14 @@ interface TrawlConfig {
     token: string;
     telemetry: boolean;
     telemetryUserId: string;
-    /** Opt-out switch for the passive "update available" notifier
-     * (src/lib/updateNotifier.ts). Optional — absent/undefined means enabled;
-     * only an explicit `false` disables it. No default entry needed since it's
-     * optional. (#129) */
     updateNotifier?: boolean;
-    /** Opt-out switch for the throttled post-run referral tip (lib/tips.ts).
-     * Same optional/absent-means-enabled shape as `updateNotifier` above. */
     tips?: boolean;
     referralTipShownAt: number;
     skillsNudgeShownAt: number;
 }
 declare const config: Conf<TrawlConfig>;
-/**
- * Resolve the effective API base URL.
- * Precedence: TRAWL_API_URL env > stored `trawl login --url` > default.
- * Mirrors the TRAWL_TOKEN / TRAWL_TELEMETRY session-override pattern so scripts
- * (e.g. infra /trawl-prod-qa against https://dev.trawl.me) can retarget the CLI
- * without mutating the operator's persisted config. (#56)
- */
 export declare function getApiUrl(): string;
-/**
- * Resolve the effective credential — a scoped API key or a session JWT.
- * Precedence: TRAWL_API_KEY env > TRAWL_TOKEN env > stored `trawl login`
- * token. TRAWL_API_KEY resolves first so an agent harness that carries BOTH
- * (e.g. a scoped key set globally alongside a leftover human TRAWL_TOKEN)
- * gets the key unambiguously, never a silent fall-through to the
- * higher-privilege JWT. Lets CI/agents authenticate headlessly
- * (`TRAWL_API_KEY=trawl_xxx trawl list` or `TRAWL_TOKEN=<jwt> trawl list`)
- * without ever touching the on-disk config — and without a stored token
- * being silently sent to whatever TRAWL_API_URL points at instead (cross-env
- * credential misuse). Every request/upload/publicGet/getText/stream call
- * site in api.ts must read the token through this, never through
- * `config.get('token')` directly. Mirrors getApiUrl(). (#68, #169)
- */
 export declare function getToken(): string;
-/**
- * Discriminate which of the two credential shapes this CLI can send a
- * `token` is: a scoped API key (`Authorization: Bearer`) or a session JWT
- * (`Cookie: TOKEN=`). The `trawl_` prefix is the SERVER's own test —
- * trawl_node's `authenticateApiKey.js` checks `rawKey.startsWith('trawl_')`
- * — not a convention invented on this side; this function exists so the two
- * sides can never quietly drift apart on what counts as a key. Defaults to
- * the live `getToken()` result so most callers (e.g. `whoami`'s JWT-only
- * guard) need no argument; `api.ts`'s `authHeaders()` instead passes the
- * exact token it already resolved for THIS request, so a request's headers
- * and its classification of that same token can never disagree. (#169)
- */
 export declare function getAuthMode(token?: string): 'apiKey' | 'jwt';
-/**
- * Which of getToken()'s two env-var overrides actually won, if either —
- * mirrors its TRAWL_API_KEY > TRAWL_TOKEN precedence exactly. Neither
- * `trawl login` nor `trawl logout` can unset a caller's OWN environment, so
- * whichever of these is set keeps overriding the stored config token
- * regardless of what those commands just did (#169 review). login.ts's
- * post-login/post-logout warnings and api.ts's apiKey-mode auth-failure
- * messages/`next` steps all need the SAME answer to "what has to be unset
- * before `trawl login` takes effect" — resolved once here rather than each
- * call site re-deriving its own copy that could quietly drift from
- * getToken()'s actual precedence. Returns null when the credential came from
- * the stored config token instead — nothing to unset there, `trawl login`
- * alone already fixes that case.
- */
 export declare function getLiveAuthEnvVar(): 'TRAWL_API_KEY' | 'TRAWL_TOKEN' | null;
 export default config;

package/dist/lib/config.js

@@ -1,12 +1,4 @@
 import Conf from 'conf';
-/**
- * TRAWL_CONFIG_DIR overrides where Conf stores the config file (its `cwd`
- * option). Without this, the CLI has zero config isolation on macOS — Conf's
- * env-paths dependency hardcodes `~/Library/Preferences/...` and ignores
- * XDG_CONFIG_HOME — so CI/agent runs and concurrent `trawl login`s race on
- * one shared on-disk file. Point at an ephemeral dir for hermetic runs, e.g.
- * `TRAWL_CONFIG_DIR=$(mktemp -d) trawl login --token …`. Rescope of #59. (#68)
- */
 const configDir = process.env['TRAWL_CONFIG_DIR']?.trim();
 const config = new Conf({
     projectName: 'trawl-cli',
@@ -20,31 +12,10 @@ const config = new Conf({
         skillsNudgeShownAt: 0,
     },
 });
-/**
- * Resolve the effective API base URL.
- * Precedence: TRAWL_API_URL env > stored `trawl login --url` > default.
- * Mirrors the TRAWL_TOKEN / TRAWL_TELEMETRY session-override pattern so scripts
- * (e.g. infra /trawl-prod-qa against https://dev.trawl.me) can retarget the CLI
- * without mutating the operator's persisted config. (#56)
- */
 export function getApiUrl() {
     const override = process.env['TRAWL_API_URL']?.trim();
     return override ? override : config.get('apiUrl');
 }
-/**
- * Resolve the effective credential — a scoped API key or a session JWT.
- * Precedence: TRAWL_API_KEY env > TRAWL_TOKEN env > stored `trawl login`
- * token. TRAWL_API_KEY resolves first so an agent harness that carries BOTH
- * (e.g. a scoped key set globally alongside a leftover human TRAWL_TOKEN)
- * gets the key unambiguously, never a silent fall-through to the
- * higher-privilege JWT. Lets CI/agents authenticate headlessly
- * (`TRAWL_API_KEY=trawl_xxx trawl list` or `TRAWL_TOKEN=<jwt> trawl list`)
- * without ever touching the on-disk config — and without a stored token
- * being silently sent to whatever TRAWL_API_URL points at instead (cross-env
- * credential misuse). Every request/upload/publicGet/getText/stream call
- * site in api.ts must read the token through this, never through
- * `config.get('token')` directly. Mirrors getApiUrl(). (#68, #169)
- */
 export function getToken() {
     const apiKey = process.env['TRAWL_API_KEY']?.trim();
     if (apiKey)
@@ -52,35 +23,9 @@ export function getToken() {
     const override = process.env['TRAWL_TOKEN']?.trim();
     return override ? override : config.get('token');
 }
-/**
- * Discriminate which of the two credential shapes this CLI can send a
- * `token` is: a scoped API key (`Authorization: Bearer`) or a session JWT
- * (`Cookie: TOKEN=`). The `trawl_` prefix is the SERVER's own test —
- * trawl_node's `authenticateApiKey.js` checks `rawKey.startsWith('trawl_')`
- * — not a convention invented on this side; this function exists so the two
- * sides can never quietly drift apart on what counts as a key. Defaults to
- * the live `getToken()` result so most callers (e.g. `whoami`'s JWT-only
- * guard) need no argument; `api.ts`'s `authHeaders()` instead passes the
- * exact token it already resolved for THIS request, so a request's headers
- * and its classification of that same token can never disagree. (#169)
- */
 export function getAuthMode(token = getToken()) {
     return token.startsWith('trawl_') ? 'apiKey' : 'jwt';
 }
-/**
- * Which of getToken()'s two env-var overrides actually won, if either —
- * mirrors its TRAWL_API_KEY > TRAWL_TOKEN precedence exactly. Neither
- * `trawl login` nor `trawl logout` can unset a caller's OWN environment, so
- * whichever of these is set keeps overriding the stored config token
- * regardless of what those commands just did (#169 review). login.ts's
- * post-login/post-logout warnings and api.ts's apiKey-mode auth-failure
- * messages/`next` steps all need the SAME answer to "what has to be unset
- * before `trawl login` takes effect" — resolved once here rather than each
- * call site re-deriving its own copy that could quietly drift from
- * getToken()'s actual precedence. Returns null when the credential came from
- * the stored config token instead — nothing to unset there, `trawl login`
- * alone already fixes that case.
- */
 export function getLiveAuthEnvVar() {
     if (process.env['TRAWL_API_KEY']?.trim())
         return 'TRAWL_API_KEY';

package/dist/lib/confirm.d.ts

@@ -1,70 +1,15 @@
-/**
- * #107 — the machine contract's non-interactive rule, in one place. True only
- * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
- * consumer needs pure stdout, and there's no human reading a prompt anyway)
- * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
- * an agent driving this CLI as a subprocess — has nowhere for a human to type
- * an answer; a blocking `readline` prompt in that situation hangs forever
- * instead of ever returning.
- */
 export declare function isInteractive(opts?: {
     json?: boolean;
 }): boolean;
 export interface ConfirmOutcome {
-    /** True when the caller should proceed with the guarded action. */
     proceed: boolean;
-    /**
-     * True when refused because the invocation is non-interactive (`--json`,
-     * or stdin/stdout isn't a real TTY) — a structured usage error has ALREADY
-     * been reported (the stderr line and/or the `--json` envelope) and
-     * `process.exitCode` set to 2. The caller must return immediately without
-     * printing anything else (mirrors every other `usageError()` call site).
-     */
     blocked: boolean;
 }
-/**
- * Shared guard for every destructive y/N confirmation in the CLI (`scraps
- * delete`, `scraps account delete`, …). #107 — before this, each call site
- * hand-rolled its own `readline` question with no non-interactive escape
- * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
- * forever waiting for a y/N answer that could never arrive.
- *
- * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
- * caller already gave explicit consent up front. Otherwise:
- *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
- *    prompts. Reports a structured usage error (exit 2) instead, via the same
- *    central `reportError` formatting path every other error in this CLI
- *    uses (stderr human line, or the `--json` envelope on stdout).
- *  - Interactive: prompts via `readline` exactly like the pre-#107 call
- *    sites did.
- *
- * `message` MUST be plain, unstyled text — it feeds both the refusal
- * UsageError's message (human stderr line AND the `--json` error envelope on
- * stdout) and the fallback prompt text. Before this, call sites passed a
- * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
- * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
- * refusal path emitted a message with the raw bold-on/off escape sequence
- * wrapped around the id) — unusable for a script/agent parsing that string.
- * `promptMessage` is the OPTIONAL styled variant shown only for the
- * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
- * reads it); it defaults to `message` when omitted. (#107 review F2)
- */
 export declare function confirmDestructive(message: string, opts?: {
     force?: boolean;
     json?: boolean;
     promptMessage?: string;
 }): Promise<ConfirmOutcome>;
-/**
- * Guard for a required interactive value that has no flag-supplied value yet
- * (login's email prompt, …) — for call sites that propagate errors by
- * `throw`ing and let the top-level handler in index.ts classify + report
- * (login.ts's existing convention), as opposed to `scraps.ts`'s local
- * exitCode-setting `usageError()` style (which should check `isInteractive`
- * directly instead of using this). Same non-interactive contract as
- * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
- * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
- * pass instead. (#107)
- */
 export declare function requireInteractive(message: string, opts?: {
     json?: boolean;
 }): void;

package/dist/lib/confirm.js

@@ -1,47 +1,11 @@
 import chalk from 'chalk';
 import { UsageError } from './errors.js';
 import { reportError } from './errors.js';
-/**
- * #107 — the machine contract's non-interactive rule, in one place. True only
- * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
- * consumer needs pure stdout, and there's no human reading a prompt anyway)
- * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
- * an agent driving this CLI as a subprocess — has nowhere for a human to type
- * an answer; a blocking `readline` prompt in that situation hangs forever
- * instead of ever returning.
- */
 export function isInteractive(opts = {}) {
     if (opts.json)
         return false;
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 }
-/**
- * Shared guard for every destructive y/N confirmation in the CLI (`scraps
- * delete`, `scraps account delete`, …). #107 — before this, each call site
- * hand-rolled its own `readline` question with no non-interactive escape
- * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
- * forever waiting for a y/N answer that could never arrive.
- *
- * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
- * caller already gave explicit consent up front. Otherwise:
- *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
- *    prompts. Reports a structured usage error (exit 2) instead, via the same
- *    central `reportError` formatting path every other error in this CLI
- *    uses (stderr human line, or the `--json` envelope on stdout).
- *  - Interactive: prompts via `readline` exactly like the pre-#107 call
- *    sites did.
- *
- * `message` MUST be plain, unstyled text — it feeds both the refusal
- * UsageError's message (human stderr line AND the `--json` error envelope on
- * stdout) and the fallback prompt text. Before this, call sites passed a
- * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
- * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
- * refusal path emitted a message with the raw bold-on/off escape sequence
- * wrapped around the id) — unusable for a script/agent parsing that string.
- * `promptMessage` is the OPTIONAL styled variant shown only for the
- * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
- * reads it); it defaults to `message` when omitted. (#107 review F2)
- */
 export async function confirmDestructive(message, opts = {}) {
     if (opts.force)
         return { proceed: true, blocked: false };
@@ -61,17 +25,6 @@ export async function confirmDestructive(message, opts = {}) {
         rl.close();
     }
 }
-/**
- * Guard for a required interactive value that has no flag-supplied value yet
- * (login's email prompt, …) — for call sites that propagate errors by
- * `throw`ing and let the top-level handler in index.ts classify + report
- * (login.ts's existing convention), as opposed to `scraps.ts`'s local
- * exitCode-setting `usageError()` style (which should check `isInteractive`
- * directly instead of using this). Same non-interactive contract as
- * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
- * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
- * pass instead. (#107)
- */
 export function requireInteractive(message, opts = {}) {
     if (!isInteractive(opts)) {
         throw new UsageError(message);