@trawlme/cli 3.10.0 → 3.12.0

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/docs.d.ts

@@ -0,0 +1,140 @@
+/**
+ * trawl_cli#185 — ONE source of truth for the docs URL(s) an agent (or
+ * human) can be pointed at from three surfaces: `spec --json` (top-level
+ * `docsUrl`/`llmsUrl` + a per-command `docs` deep link), a run's JSON
+ * payload (`doctor`/`data --errors`/`run-info`, keyed on `failureKind` —
+ * NOT errors.ts's unrelated `ErrorEnvelope.kind`, see the doc comment on
+ * `FAILURE_KIND_DOC_PATHS` below), and the `--help` footer. Three hardcoded
+ * lists here would diverge within months — that exact "same fact computed
+ * in two places" defect has recurred repeatedly across this epic — so every
+ * surface reads these same tables/functions, never its own copy.
+ *
+ * Resolution ladder (issue #185 — all three rungs REQUIRED, in this order,
+ * evaluated PER FIELD, never as one bundled decision — see `resolveDocsUrls`):
+ *
+ *  1. Prefer the server. `externalDocs.url` on the OpenAPI document at
+ *     `<apiBase>/api/spec.json` is the standard OpenAPI field for exactly
+ *     this, and reading it makes a self-hosted install work with ZERO CLI
+ *     change. It is unset (null) server-side today, so this is
+ *     forward-looking — build it anyway, and it must win outright over rung
+ *     2 when present. The one caller allowed to fetch it is `spec.ts`'s own
+ *     action, bounded and swallowed-on-failure (mirrors lib/tips.ts's
+ *     `isReferralProgramUserFacing`) — a deliberate, once-per-invocation
+ *     agent probe, not "every command". Every other surface (an error
+ *     payload on an arbitrary failing command, the `--help` footer) must
+ *     never add a network call or a failure mode to a command nobody asked
+ *     to hit the docs host for — see `resolveDocsUrls`'s `externalDocsUrl`
+ *     parameter, which only ever arrives pre-fetched.
+ *  2. Else derive, by stripping a leading `api.` host label from the
+ *     configured API base — but ONLY for a KNOWN first-party `trawl.me`
+ *     host. `api.trawl.me` -> `trawl.me` (prod: API and docs are genuinely
+ *     on different hosts); `dev.trawl.me` (no `api.` prefix) -> unchanged
+ *     (dev serves docs on the SAME host as its API). A generic, unscoped
+ *     `api.`-strip applied to ANY host is itself a guess — it assumes a
+ *     self-hosted `api.acme.internal` serves docs at `acme.internal`, which
+ *     nothing here can know. Scoping the strip to `trawl.me` is what makes
+ *     rung 3 (below) ever actually fire for a self-hosted base.
+ *  3. Else OMIT the field entirely. Never emit a guessed URL (issue's Rule
+ *     3): a wrong URL sends an agent to a 404 WITH CONFIDENCE, worse than no
+ *     URL at all — a self-hosted install with no server-declared
+ *     `externalDocs` and a base outside `trawl.me` gets no `docsUrl`/
+ *     `llmsUrl`, not a hopeful default pointed at OUR docs host.
+ *
+ * `llmsUrl` has no OpenAPI-standard field to read (rung 1 contributes
+ * nothing to it) — deriving it from the ORIGIN of a server-declared
+ * `externalDocs.url` would itself be a guess for a self-hosted install
+ * (rule 3 again), so `llmsUrl` resolves ONLY via rung 2 (the known-host
+ * derivation) or omission. It never rides along with a rung-1 `docsUrl`.
+ *
+ * PROVENANCE (defect fix, reviewer repro against a live mock server): the
+ * top-level `docsUrl` above is deliberately the FLATTENED "whichever rung
+ * won" value — right for a human reading `spec --json`'s top-level field,
+ * WRONG as an input to `resolveCommandDocsUrl`/`resolveFailureKindDocsUrl`
+ * below. Those two append one of THIS CLI's own hardcoded guide slugs
+ * (`COMMAND_DOC_PATHS`/`FAILURE_KIND_DOC_PATHS`) onto whatever `docsUrl`
+ * resolved — safe onto a rung-2 root we derived ourselves (we know
+ * trawl.me's guide tree), never safe onto a rung-1 root (an arbitrary
+ * third party's own docs site, self-hosted, with no reason to carry our
+ * slugs). A mock server declaring `externalDocs.url: 'http://h/guide'`
+ * used to get `http://h/guide/build-your-scrap/account-sessions` appended
+ * — a confidently-wrong 404. So `DocsUrls.docsUrlIsDerived` carries rung
+ * provenance ALONGSIDE the string (never flattened to a bare string again)
+ * and both deep-link functions now take the whole `DocsUrls`-shaped object
+ * and gate construction on that flag — see its own doc comment below.
+ */
+export interface DocsUrls {
+    docsUrl?: string;
+    llmsUrl?: string;
+    /**
+     * True iff `docsUrl` came from rung 2 (THIS CLI's own derivation from a
+     * KNOWN `trawl.me` host) — the only case where it is safe to append one of
+     * this CLI's own guide slugs onto it (see `resolveCommandDocsUrl`/
+     * `resolveFailureKindDocsUrl`). False when `docsUrl` is a rung-1
+     * SERVER-declared root instead — an arbitrary third party's own docs site,
+     * which has no reason to host our guide slugs, even when that server
+     * happens to run on a `trawl.me` host. Always a defined boolean whenever
+     * `docsUrl` itself is present; undefined only when `docsUrl` is undefined
+     * too (rung 3 — nothing resolved at all).
+     */
+    docsUrlIsDerived?: boolean;
+}
+/**
+ * Rung 2 — see the module doc comment. Returns `{ protocol, host }` for a
+ * KNOWN first-party API base (preserving the base's own protocol rather
+ * than assuming `https:`), or `null` when the base isn't recognized
+ * (self-hosted, a custom domain, `localhost`, an unparseable string, …) —
+ * `null` must propagate to omission (rung 3), never to a guessed host.
+ */
+export declare function deriveDocsOrigin(apiBaseUrl: string): {
+    protocol: string;
+    host: string;
+} | null;
+/** Same rung as `deriveDocsOrigin`, collapsed to just the host string —
+ *  convenience for a caller that only needs the derived host, not the
+ *  protocol (kept as its own export since `docs.test.ts` exercises the host
+ *  derivation independently of protocol handling). */
+export declare function deriveDocsHost(apiBaseUrl: string): string | null;
+/**
+ * The full ladder, PER FIELD (see module doc comment for why `llmsUrl`
+ * cannot ride along with a rung-1 `docsUrl`). Pure and synchronous — no
+ * network, safe to call from any surface (an error payload, the `--help`
+ * footer) without adding latency or a new failure mode. `externalDocsUrl`
+ * is rung 1's input: only ever supplied by `spec.ts`'s action, after its
+ * own bounded, swallowed-on-failure fetch — every other caller omits it and
+ * gets rungs 2/3 only.
+ */
+export declare function resolveDocsUrls(opts: {
+    apiBaseUrl: string;
+    externalDocsUrl?: string | null;
+}): DocsUrls;
+/**
+ * `resolveCommandDocsUrl` returns `undefined` (never a bare path or a
+ * relative link) whenever any of three things is missing — `docsUrl`
+ * unresolved (rung 3 already fired), `docsUrl` resolved but NOT derived
+ * (rung 1 — a server-declared root; see `DocsUrls.docsUrlIsDerived`'s doc
+ * comment for why appending our own guide slug onto a third party's root is
+ * exactly the confidently-wrong-404 defect this gate closes), or no guide is
+ * mapped for this command — so a spec consumer never has to special-case a
+ * partial value. Takes the whole resolved `DocsUrls` object (never a bare
+ * string) specifically so this provenance can never again be flattened away
+ * before it reaches here.
+ */
+export declare function resolveCommandDocsUrl(commandName: string, docs: Pick<DocsUrls, 'docsUrl' | 'docsUrlIsDerived'>): string | undefined;
+/** Same "undefined unless docsUrl is resolved AND derived (rung 2)" gate as
+ *  `resolveCommandDocsUrl` above, same reason — never append this CLI's own
+ *  guide slug onto a rung-1 server-declared root. Callers MUST gate the call
+ *  on their own staleness rule first (e.g. `doctor.ts`'s `isAuthWall`) — this
+ *  function only knows the string-to-path mapping, not whether a stamped
+ *  `failureKind` is still live on a run patched afterward. */
+export declare function resolveFailureKindDocsUrl(kind: string | null | undefined, docs: Pick<DocsUrls, 'docsUrl' | 'docsUrlIsDerived'>): string | undefined;
+/**
+ * `--help` footer text (issue #185 scope item 3) — a single dim line, for
+ * humans, e.g. "Docs: https://trawl.me/docs". Returns `undefined` (never an
+ * empty or guessed line) when no `docsUrl` resolved — mirrors
+ * lib/tips.ts's shape (a pure function separated from IO, so it's testable
+ * without mocking chalk/console) but NOT its TTY gate: tips.ts suppresses a
+ * promotional nudge from piped output, but a docs line inside `--help |
+ * less` is exactly the kind of thing worth keeping. Un-colored here — the
+ * caller (index.ts) applies `chalk.dim` so this stays trivially testable.
+ */
+export declare function docsFooterLine(docsUrl?: string): string | undefined;

package/dist/lib/docs.js

@@ -0,0 +1,238 @@
+/**
+ * trawl_cli#185 — ONE source of truth for the docs URL(s) an agent (or
+ * human) can be pointed at from three surfaces: `spec --json` (top-level
+ * `docsUrl`/`llmsUrl` + a per-command `docs` deep link), a run's JSON
+ * payload (`doctor`/`data --errors`/`run-info`, keyed on `failureKind` —
+ * NOT errors.ts's unrelated `ErrorEnvelope.kind`, see the doc comment on
+ * `FAILURE_KIND_DOC_PATHS` below), and the `--help` footer. Three hardcoded
+ * lists here would diverge within months — that exact "same fact computed
+ * in two places" defect has recurred repeatedly across this epic — so every
+ * surface reads these same tables/functions, never its own copy.
+ *
+ * Resolution ladder (issue #185 — all three rungs REQUIRED, in this order,
+ * evaluated PER FIELD, never as one bundled decision — see `resolveDocsUrls`):
+ *
+ *  1. Prefer the server. `externalDocs.url` on the OpenAPI document at
+ *     `<apiBase>/api/spec.json` is the standard OpenAPI field for exactly
+ *     this, and reading it makes a self-hosted install work with ZERO CLI
+ *     change. It is unset (null) server-side today, so this is
+ *     forward-looking — build it anyway, and it must win outright over rung
+ *     2 when present. The one caller allowed to fetch it is `spec.ts`'s own
+ *     action, bounded and swallowed-on-failure (mirrors lib/tips.ts's
+ *     `isReferralProgramUserFacing`) — a deliberate, once-per-invocation
+ *     agent probe, not "every command". Every other surface (an error
+ *     payload on an arbitrary failing command, the `--help` footer) must
+ *     never add a network call or a failure mode to a command nobody asked
+ *     to hit the docs host for — see `resolveDocsUrls`'s `externalDocsUrl`
+ *     parameter, which only ever arrives pre-fetched.
+ *  2. Else derive, by stripping a leading `api.` host label from the
+ *     configured API base — but ONLY for a KNOWN first-party `trawl.me`
+ *     host. `api.trawl.me` -> `trawl.me` (prod: API and docs are genuinely
+ *     on different hosts); `dev.trawl.me` (no `api.` prefix) -> unchanged
+ *     (dev serves docs on the SAME host as its API). A generic, unscoped
+ *     `api.`-strip applied to ANY host is itself a guess — it assumes a
+ *     self-hosted `api.acme.internal` serves docs at `acme.internal`, which
+ *     nothing here can know. Scoping the strip to `trawl.me` is what makes
+ *     rung 3 (below) ever actually fire for a self-hosted base.
+ *  3. Else OMIT the field entirely. Never emit a guessed URL (issue's Rule
+ *     3): a wrong URL sends an agent to a 404 WITH CONFIDENCE, worse than no
+ *     URL at all — a self-hosted install with no server-declared
+ *     `externalDocs` and a base outside `trawl.me` gets no `docsUrl`/
+ *     `llmsUrl`, not a hopeful default pointed at OUR docs host.
+ *
+ * `llmsUrl` has no OpenAPI-standard field to read (rung 1 contributes
+ * nothing to it) — deriving it from the ORIGIN of a server-declared
+ * `externalDocs.url` would itself be a guess for a self-hosted install
+ * (rule 3 again), so `llmsUrl` resolves ONLY via rung 2 (the known-host
+ * derivation) or omission. It never rides along with a rung-1 `docsUrl`.
+ *
+ * PROVENANCE (defect fix, reviewer repro against a live mock server): the
+ * top-level `docsUrl` above is deliberately the FLATTENED "whichever rung
+ * won" value — right for a human reading `spec --json`'s top-level field,
+ * WRONG as an input to `resolveCommandDocsUrl`/`resolveFailureKindDocsUrl`
+ * below. Those two append one of THIS CLI's own hardcoded guide slugs
+ * (`COMMAND_DOC_PATHS`/`FAILURE_KIND_DOC_PATHS`) onto whatever `docsUrl`
+ * resolved — safe onto a rung-2 root we derived ourselves (we know
+ * trawl.me's guide tree), never safe onto a rung-1 root (an arbitrary
+ * third party's own docs site, self-hosted, with no reason to carry our
+ * slugs). A mock server declaring `externalDocs.url: 'http://h/guide'`
+ * used to get `http://h/guide/build-your-scrap/account-sessions` appended
+ * — a confidently-wrong 404. So `DocsUrls.docsUrlIsDerived` carries rung
+ * provenance ALONGSIDE the string (never flattened to a bare string again)
+ * and both deep-link functions now take the whole `DocsUrls`-shaped object
+ * and gate construction on that flag — see its own doc comment below.
+ */
+/** The one first-party domain this CLI knows to serve docs — see rung 2 in
+ *  the module doc comment above. Deliberately not "any host", so an
+ *  unrecognized (self-hosted/custom) base falls through to omission. */
+const KNOWN_DOCS_DOMAIN = 'trawl.me';
+/**
+ * Rung 2 — see the module doc comment. Returns `{ protocol, host }` for a
+ * KNOWN first-party API base (preserving the base's own protocol rather
+ * than assuming `https:`), or `null` when the base isn't recognized
+ * (self-hosted, a custom domain, `localhost`, an unparseable string, …) —
+ * `null` must propagate to omission (rung 3), never to a guessed host.
+ */
+export function deriveDocsOrigin(apiBaseUrl) {
+    let url;
+    try {
+        url = new URL(apiBaseUrl);
+    }
+    catch {
+        return null;
+    }
+    const hostname = url.hostname.toLowerCase();
+    const stripped = hostname.startsWith('api.') ? hostname.slice('api.'.length) : hostname;
+    if (stripped === KNOWN_DOCS_DOMAIN || stripped.endsWith(`.${KNOWN_DOCS_DOMAIN}`)) {
+        return { protocol: url.protocol, host: stripped };
+    }
+    return null;
+}
+/** Same rung as `deriveDocsOrigin`, collapsed to just the host string —
+ *  convenience for a caller that only needs the derived host, not the
+ *  protocol (kept as its own export since `docs.test.ts` exercises the host
+ *  derivation independently of protocol handling). */
+export function deriveDocsHost(apiBaseUrl) {
+    return deriveDocsOrigin(apiBaseUrl)?.host ?? null;
+}
+/**
+ * The full ladder, PER FIELD (see module doc comment for why `llmsUrl`
+ * cannot ride along with a rung-1 `docsUrl`). Pure and synchronous — no
+ * network, safe to call from any surface (an error payload, the `--help`
+ * footer) without adding latency or a new failure mode. `externalDocsUrl`
+ * is rung 1's input: only ever supplied by `spec.ts`'s action, after its
+ * own bounded, swallowed-on-failure fetch — every other caller omits it and
+ * gets rungs 2/3 only.
+ */
+export function resolveDocsUrls(opts) {
+    const origin = deriveDocsOrigin(opts.apiBaseUrl);
+    const derived = origin
+        ? {
+            docsUrl: `${origin.protocol}//${origin.host}/docs`,
+            llmsUrl: `${origin.protocol}//${origin.host}/llms.txt`,
+            docsUrlIsDerived: true,
+        }
+        : {};
+    if (opts.externalDocsUrl) {
+        // Rung 1 wins for docsUrl outright; llmsUrl stays rung-2-only (see doc
+        // comment) — a self-hosted `externalDocsUrl` outside `trawl.me` yields
+        // `{ docsUrl: <server's own> }` with `llmsUrl` omitted, never guessed.
+        // `docsUrlIsDerived: false` regardless of whether rung 2 ALSO resolved
+        // (e.g. a `trawl.me`-hosted server declaring its own externalDocs) — a
+        // server-declared root is never "derived" by THIS CLI, and never a safe
+        // base for our own guide slugs (see DocsUrls.docsUrlIsDerived).
+        return derived.llmsUrl
+            ? { docsUrl: opts.externalDocsUrl, llmsUrl: derived.llmsUrl, docsUrlIsDerived: false }
+            : { docsUrl: opts.externalDocsUrl, docsUrlIsDerived: false };
+    }
+    return derived;
+}
+/** Join a docs root (e.g. `https://trawl.me/docs`) with a guide path
+ *  suffix (e.g. `build-your-scrap/account-sessions`) — plain string
+ *  concatenation, deliberately NOT `new URL(suffix, docsUrl)`: a
+ *  leading-slash suffix resolved against a URL with its own path component
+ *  (`/docs`) would resolve relative to the ORIGIN, silently dropping
+ *  `/docs` from the result (`new URL('/x', 'https://h/docs')` ==
+ *  `https://h/x`, not `https://h/docs/x`). */
+function joinDocsPath(docsUrl, suffix) {
+    return `${docsUrl.replace(/\/+$/, '')}/${suffix.replace(/^\/+/, '')}`;
+}
+/**
+ * The single source for the account-sessions guide slug — referenced by
+ * BOTH `COMMAND_DOC_PATHS` and `FAILURE_KIND_DOC_PATHS` below. Those two
+ * tables key on different fields (a CLI command's full path name vs a run's
+ * `failureKind`) and legitimately stay separate, but they name the SAME
+ * guide, so the path literal itself must exist exactly once: this is the
+ * "same fact computed in two places" defect class this module's own doc
+ * comment says it exists to prevent, and it has recurred repeatedly across
+ * this epic. Renaming the guide used to require editing two literals in
+ * lockstep — miss one and one surface (a run's `docs` field, or `spec
+ * --json`'s per-command deep link) silently 404s while the other still
+ * works (trawl_cli#185 review).
+ */
+const ACCOUNT_SESSIONS_GUIDE_PATH = 'build-your-scrap/account-sessions';
+/**
+ * Per-command deep links (issue #185 scope item 1) — a command's FULL path
+ * name (matches `CliSpecCommand.name` in spec.ts, e.g.
+ * `"scraps account session set"`) is matched against `prefix` either
+ * exactly or as a whole path SEGMENT prefix (`startsWith(prefix + ' ')`) —
+ * never a bare substring, so a hypothetical future `scraps accounting`
+ * command could never false-match the `scraps account` entry below.
+ */
+const COMMAND_DOC_PATHS = Object.freeze([
+    // Every account/session-management command — set, delete, clear-session,
+    // status, and the nested `session set` — is covered by one prefix entry
+    // rather than one row per leaf, so a new leaf added under `scraps account`
+    // later (e.g. a future `session capture`, trawl_cli#183) inherits the
+    // link for free instead of needing its own row.
+    { prefix: 'scraps account', path: ACCOUNT_SESSIONS_GUIDE_PATH },
+]);
+function docsPathForCommand(commandName) {
+    const match = COMMAND_DOC_PATHS.find((e) => commandName === e.prefix || commandName.startsWith(`${e.prefix} `));
+    return match ? match.path : null;
+}
+/**
+ * `resolveCommandDocsUrl` returns `undefined` (never a bare path or a
+ * relative link) whenever any of three things is missing — `docsUrl`
+ * unresolved (rung 3 already fired), `docsUrl` resolved but NOT derived
+ * (rung 1 — a server-declared root; see `DocsUrls.docsUrlIsDerived`'s doc
+ * comment for why appending our own guide slug onto a third party's root is
+ * exactly the confidently-wrong-404 defect this gate closes), or no guide is
+ * mapped for this command — so a spec consumer never has to special-case a
+ * partial value. Takes the whole resolved `DocsUrls` object (never a bare
+ * string) specifically so this provenance can never again be flattened away
+ * before it reaches here.
+ */
+export function resolveCommandDocsUrl(commandName, docs) {
+    if (!docs.docsUrl || !docs.docsUrlIsDerived)
+        return undefined;
+    const path = docsPathForCommand(commandName);
+    return path ? joinDocsPath(docs.docsUrl, path) : undefined;
+}
+/**
+ * failureKind -> guide path (issue #185 scope item 2). Keyed on trawl_node's
+ * run-level `failureKind` field (trawl_node#1975, surfaced by this CLI's
+ * own `doctor`/`data --errors`/`run-info` JSON payloads since cli#182) —
+ * this is a DIFFERENT axis from errors.ts's `ErrorEnvelope.kind` (a CLI
+ * transport/execution outcome like `"auth"` meaning "you're not logged
+ * into trawl", `"network"`, `"usage"`, …). Both happen to use the string
+ * `"auth"` for unrelated things: this table's `'auth'` means "the SCRAPED
+ * TARGET site showed a login wall", errors.ts's `'auth'` means "the TRAWL
+ * API rejected your OWN credentials". Never merge these two tables — they
+ * are keyed off different fields on different objects, and conflating them
+ * would either miss the run-level guide or wrongly attach it to an
+ * unrelated CLI auth failure.
+ */
+const FAILURE_KIND_DOC_PATHS = Object.freeze({
+    auth: ACCOUNT_SESSIONS_GUIDE_PATH,
+});
+function docsPathForFailureKind(kind) {
+    if (!kind)
+        return null;
+    return FAILURE_KIND_DOC_PATHS[kind] ?? null;
+}
+/** Same "undefined unless docsUrl is resolved AND derived (rung 2)" gate as
+ *  `resolveCommandDocsUrl` above, same reason — never append this CLI's own
+ *  guide slug onto a rung-1 server-declared root. Callers MUST gate the call
+ *  on their own staleness rule first (e.g. `doctor.ts`'s `isAuthWall`) — this
+ *  function only knows the string-to-path mapping, not whether a stamped
+ *  `failureKind` is still live on a run patched afterward. */
+export function resolveFailureKindDocsUrl(kind, docs) {
+    if (!docs.docsUrl || !docs.docsUrlIsDerived)
+        return undefined;
+    const path = docsPathForFailureKind(kind);
+    return path ? joinDocsPath(docs.docsUrl, path) : undefined;
+}
+/**
+ * `--help` footer text (issue #185 scope item 3) — a single dim line, for
+ * humans, e.g. "Docs: https://trawl.me/docs". Returns `undefined` (never an
+ * empty or guessed line) when no `docsUrl` resolved — mirrors
+ * lib/tips.ts's shape (a pure function separated from IO, so it's testable
+ * without mocking chalk/console) but NOT its TTY gate: tips.ts suppresses a
+ * promotional nudge from piped output, but a docs line inside `--help |
+ * less` is exactly the kind of thing worth keeping. Un-colored here — the
+ * caller (index.ts) applies `chalk.dim` so this stays trivially testable.
+ */
+export function docsFooterLine(docsUrl) {
+    return docsUrl ? `Docs: ${docsUrl}` : undefined;
+}

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