@trawlme/cli 3.10.0 → 3.12.0

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