@trawlme/cli 3.11.0 → 3.12.0

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>;

package/dist/lib/chrome-launch.js

@@ -0,0 +1,122 @@
+/**
+ * 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',
+        `--user-data-dir=${userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-sync',
+        '--password-store=basic',
+        '--use-mock-keychain',
+        '--new-window',
+        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;
+            settled = true;
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+            reject(err);
+        });
+        const writeStream = proc.stdio[3];
+        const readStream = proc.stdio[4];
+        if (!writeStream || !readStream || typeof writeStream.write !== 'function') {
+            settled = true;
+            try {
+                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;
+            settled = true;
+            resolve({ proc, cdp: new CdpPipe(writeStream, readStream) });
+        });
+    });
+}

package/dist/lib/secure-transport.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @desc Returns a factual reason string when `apiUrl` is not an
+ * acceptable transport for a session upload, or null when it is
+ * (`https:`, or any scheme against a loopback host). An unparseable URL
+ * returns null — it fails with its own clear error at the actual fetch
+ * call, not here.
+ */
+export declare function assertSecureTransport(apiUrl: string): string | null;

package/dist/lib/secure-transport.js

@@ -0,0 +1,39 @@
+/**
+ * Refuses a plaintext API base for the two commands that ship a browser
+ * session — a bearer-equivalent secret — in the request body
+ * (trawl_cli#183 review finding 5). Reproduced: `TRAWL_API_URL=http://…
+ * trawl scraps account session capture <id>` uploaded the full session in
+ * cleartext with no warning; this command is the first in the CLI to PUT
+ * that kind of secret, so the fix is scoped HERE rather than to the
+ * generic `request()` in api.ts — every other command's blast radius
+ * stays exactly what it was.
+ *
+ * Loopback hosts are exempt (by exact hostname only — a plaintext host
+ * that merely happens to RESOLVE to loopback is not detected here) so
+ * local/self-hosted dev and the test suite keep working over plain HTTP.
+ */
+// `new URL(...).hostname` returns the IPv6 form WITH its brackets
+// (`'[::1]'`, never bare `'::1'`) — both are listed defensively so this
+// never regresses silently if that ever changes.
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost']);
+/**
+ * @desc Returns a factual reason string when `apiUrl` is not an
+ * acceptable transport for a session upload, or null when it is
+ * (`https:`, or any scheme against a loopback host). An unparseable URL
+ * returns null — it fails with its own clear error at the actual fetch
+ * call, not here.
+ */
+export function assertSecureTransport(apiUrl) {
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol === 'https:')
+        return null;
+    if (LOOPBACK_HOSTS.has(url.hostname.toLowerCase()))
+        return null;
+    return `The configured API URL (${url.origin}) is not https: — a captured/uploaded browser session is a bearer-equivalent secret and this command refuses to send it in cleartext. An https:// API URL is accepted (trawl login --url https://…); so is any URL on 127.0.0.1, ::1, or localhost, for local testing.`;
+}

package/dist/lib/session-capture-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The non-interactive guard for `scraps account session capture`
+ * (trawl_cli#183) — deliberately its OWN function, not a reuse of
+ * `confirm.ts`'s `isInteractive`. That one returns false under `--json`,
+ * which is wrong here: `--json` + a real interactive terminal is a valid
+ * way to run this command (a human still drives the browser; only the
+ * final result on stdout is machine-shaped). What actually makes this
+ * command impossible is no TTY on stdin (nobody can press Enter) or, on
+ * Linux, no display server to open a visible window on.
+ */
+export interface NonInteractiveEnv {
+    stdinIsTTY: boolean;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * @desc Returns a factual reason string when this command cannot work in
+ * the current environment, or null when it can proceed. Never guesses —
+ * both checks are direct, observable facts (no TTY / no display var).
+ */
+export declare function detectNonInteractive({ stdinIsTTY, platform, env }: NonInteractiveEnv): string | null;

package/dist/lib/session-capture-guard.js

@@ -0,0 +1,14 @@
+/**
+ * @desc Returns a factual reason string when this command cannot work in
+ * the current environment, or null when it can proceed. Never guesses —
+ * both checks are direct, observable facts (no TTY / no display var).
+ */
+export function detectNonInteractive({ stdinIsTTY, platform, env }) {
+    if (!stdinIsTTY) {
+        return 'No interactive terminal attached (stdin is not a TTY) — this command opens a visible Chrome window for a human to log into and needs a terminal to confirm completion. It does not work headless, in CI, or piped.';
+    }
+    if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+        return 'No display detected (DISPLAY/WAYLAND_DISPLAY are both unset) — this command opens a visible Chrome window and cannot run over a plain SSH session, in a container, or headless.';
+    }
+    return null;
+}

package/dist/lib/session-capture.d.ts

@@ -0,0 +1,180 @@
+import type { ChildProcess } from 'node:child_process';
+import type { CdpPipe } from './cdp-pipe.js';
+import { type RawCdpCookie, type RawOriginLocalStorage, type StorageState } from './storage-state.js';
+export interface CaptureCounts {
+    cookiesCaptured: number;
+    cookiesDroppedOutOfScope: number;
+    cookiesDroppedInvalid: number;
+    originsCaptured: number;
+    originsDroppedOutOfScope: number;
+    /** An in-scope page's localStorage could not be captured, for one of
+     *  four reasons — never a CLI bug, which propagates as a failed capture
+     *  instead (trawl_cli#183 post-cap review finding B, sharpened by the R4
+     *  fix below): a `readPageOverCdp` rejection — ANY CDP-level rejection
+     *  scoped to THIS page's `attachToTarget`/`Runtime.evaluate` round-trip,
+     *  whatever its error class (a timeout because the page's renderer was
+     *  blocked — a native dialog, a synchronous script, a paused debugger; or
+     *  a plain rejection because the target closed mid-attach/mid-evaluate,
+     *  e.g. an OAuth popup the human closed at the wrong instant); the read
+     *  threw INSIDE the page (e.g. a `SecurityError` on partitioned/sandboxed
+     *  storage); or `Runtime.evaluate` succeeded with no exception but
+     *  returned a value that doesn't match the `{name,value}[]` shape asked
+     *  for (a page tampering with a global to hand back garbage without ever
+     *  throwing). The discriminant is PROVENANCE, not error type: did the
+     *  rejection come out of a CDP call scoped to this one page, or out of
+     *  this file's OWN code running on data CDP already handed back? Only the
+     *  latter is a CLI bug, and only the latter propagates. None of these
+     *  four is the same fact as "0 keys": CDP itself was reachable (or the
+     *  pipe wouldn't still be open), the origin just could not be read.
+     *  Counted, never the exception text/URL/value itself (a page controls
+     *  that content). */
+    originsUnreadable: number;
+    /** The tracked tab was closed before Enter — cookies were still read,
+     *  localStorage was not (the completion path the issue calls out:
+     *  "closing the window also completes"). */
+    closedEarly: boolean;
+}
+export type CaptureFailureReason = 'non_interactive' | 'no_chrome' | 'launch_failed' | 'capture_failed' | 'process_exited_before_capture' | 'cdp_protocol_error' | 'no_cookies_in_scope';
+export type CaptureResult = {
+    ok: true;
+    storageState: StorageState;
+    counts: CaptureCounts;
+    targetDomain: string;
+} | {
+    ok: false;
+    reason: CaptureFailureReason;
+    message: string;
+};
+interface RawCapture {
+    cookies: RawCdpCookie[];
+    origins: RawOriginLocalStorage[];
+    originsUnreadable: number;
+}
+/** Every effectful step captureSession needs — overridable for tests. */
+export interface CaptureDeps {
+    detectNonInteractive(): string | null;
+    findChrome(): string | null;
+    mkdtemp(): string;
+    rmSync(dir: string): void;
+    launch(chromePath: string, targetUrl: string, userDataDir: string): Promise<{
+        proc: ChildProcess;
+        cdp: CdpPipe;
+    }>;
+    /** Resolve once Chrome has opened the target URL as a page target. */
+    findPageTarget(cdp: CdpPipe): Promise<string>;
+    /**
+     * Race the "done" signal: Enter in the terminal, or the tracked tab
+     * being closed. Resolves with whether the tab closed before Enter.
+     * `cleanup` MUST be wired to the readline Interface's own `'SIGINT'`
+     * event (not just `process.on('SIGINT', …)`) — a TTY readline prompt
+     * puts stdin in raw mode, which stops Ctrl-C from ever generating a real
+     * OS SIGINT in the first place; only the Interface itself observes the
+     * raw 0x03 byte and re-synthesizes it as its own `'SIGINT'` event.
+     */
+    waitForDone(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
+        closedEarly: boolean;
+    }>;
+    /** Read the full (unscoped) cookie jar + open pages' localStorage. */
+    readCapture(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
+    /**
+     * Register `cleanup` to run on every ORDINARY terminating signal this
+     * process can still run code for: SIGINT, SIGTERM, and SIGHUP
+     * (trawl_cli#183 review finding 1 — SIGTERM/SIGHUP were missing
+     * entirely, so `timeout` without `--signal`, a bare `kill <pid>`, most
+     * supervisors, and closing the terminal tab mid-login all skipped
+     * cleanup and left Chrome running with the profile on disk). SIGKILL is
+     * the only signal that cannot be handled at all, by any process, ever —
+     * see this function's own default implementation
+     * (`registerTerminationHandlers`) for that boundary spelled out.
+     * Returns an unregister function.
+     */
+    onSigint(cleanup: () => void): () => void;
+}
+/**
+ * The three real (non-fake) CDP orchestration steps, exported for direct
+ * testing against a minimal fake CdpPipe — session-capture.test.ts covers
+ * the OUTER guard/race/cleanup logic with these swapped out entirely;
+ * session-capture-defaults.test.ts covers these directly instead, since
+ * "test the wiring" and "test the wired thing" are two different jobs.
+ */
+export declare function findPageTargetDefault(cdp: CdpPipe): Promise<string>;
+export declare function waitForDoneDefault(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
+    closedEarly: boolean;
+}>;
+/**
+ * @desc The deadline for the ONE CDP command in this file that runs inside
+ * a page's own renderer rather than Chrome's browser process:
+ * `Runtime.evaluate` reading `window.localStorage`. Deliberately the SAME
+ * 30s as `CdpPipe`'s own browser-process default, not a shorter override —
+ * a post-cap review (trawl_cli#183) found that an earlier 5s value here cut
+ * off a real, terminating synchronous computation (the shape of an
+ * anti-bot challenge solve) at ~5s: `originsUnreadable:1` for a page that
+ * would have captured cleanly at 7s. There is no value that is provably
+ * "long enough" — a renderer truly blocked forever (a native dialog, a
+ * paused debugger) costs the same whether the ceiling is 5s or 30s, while
+ * a renderer doing bounded work of unknown-but-finite length keeps a
+ * chance of finishing for as long as this stays generous. 30s is a
+ * JUDGEMENT call on that trade-off, not a provably-correct number — kept
+ * equal to the pipe's own default so this file doesn't invent a second
+ * number to defend. Passed explicitly to `send()` anyway (rather than
+ * relying on the pipe's own default silently matching) so the deadline
+ * stays a named, assertable constant here regardless of what the pipe
+ * default happens to be. Whatever the outcome, it is always COUNTED and
+ * SURFACED (`originsUnreadable`, plus the human-facing ⚠ line in
+ * scraps.ts) — never silently swallowed; see `readCaptureDefault` below
+ * for the stderr progress line that covers the wait itself.
+ */
+export declare const LOCALSTORAGE_READ_TIMEOUT_MS = 30000;
+export declare function readCaptureDefault(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
+/**
+ * @desc `rmSync` with a short, bounded, SYNCHRONOUS retry (max ~200ms
+ * total). Verified against a real Chrome launch (trawl_cli#183's loopback
+ * E2E): even after killing Chrome's whole process group (see
+ * chrome-launch.ts's `detached`), a helper subprocess can hold a file
+ * under the profile open for a few milliseconds after the kill signal is
+ * delivered — a bare `rmSync` right after `kill()` lost that race and
+ * silently leaked the temp profile every time. Stays synchronous
+ * (`Atomics.wait`, no `await`) because cleanup must be callable from a
+ * signal handler right before `process.exit()`.
+ */
+export declare function rmSyncWithRetry(dir: string): void;
+/**
+ * @desc The default `onSigint` implementation, exported for direct testing
+ * (same pattern as `findPageTargetDefault`/`waitForDoneDefault`/
+ * `readCaptureDefault` above — this file's own convention keeps "test the
+ * wiring" and "test the wired thing" separate). Registers `cleanup` on
+ * SIGINT, SIGTERM, AND SIGHUP (trawl_cli#183 review finding 1 — only
+ * SIGINT was registered before this; `timeout` without `--signal`, a bare
+ * `kill <pid>`, most supervisors, and closing the terminal tab mid-login
+ * all default-terminate a process via SIGTERM/SIGHUP, and Node runs no
+ * `finally` for a default-terminated process). SIGKILL is the one signal
+ * this — or any handler, in any process — cannot observe: the OS tears
+ * the process down directly, no userspace code runs at all, so Chrome and
+ * the temp profile are left behind whenever that specific signal is what
+ * ends this process. That gap is inherent, not something a different
+ * signal list here could close.
+ */
+export declare function registerTerminationHandlers(cleanup: () => void): () => void;
+/**
+ * @desc The same guard `captureSession` runs internally as its very first
+ * step, exposed so the command layer can call it BEFORE printing anything
+ * about a Chrome window that may never open. Without this, `scraps.ts`
+ * printed its "a Chrome window will open" banner unconditionally, ahead of
+ * this exact check inside `captureSession` — so a non-interactive run saw
+ * that banner immediately followed by "this cannot work headless"
+ * (trawl_cli#183 gap). Reads live process state once; pure
+ * `detectNonInteractive` stays the single source of truth for both call
+ * sites.
+ * @returns {string | null} a factual reason when this command cannot
+ * proceed in the current environment, or null when it can.
+ */
+export declare function checkInteractiveEnvironment(): string | null;
+/**
+ * @desc Run the full capture flow for one scrap's target URL.
+ * @param {string} targetUrl
+ * @param {Partial<CaptureDeps>} depsOverride — for tests; real deps fill in
+ * the rest.
+ * @returns {Promise<CaptureResult>}
+ */
+export declare function captureSession(targetUrl: string, depsOverride?: Partial<CaptureDeps>): Promise<CaptureResult>;
+export {};