@trawlme/cli 3.11.0 → 3.12.1

package/dist/lib/chrome-discovery.js

@@ -0,0 +1,30 @@
+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',
+    ],
+};
+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,8 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { CdpPipe } from './cdp-pipe.js';
+export interface LaunchedChrome {
+    proc: ChildProcess;
+    cdp: CdpPipe;
+}
+export declare function buildChromeArgs(userDataDir: string, targetUrl: string): string[];
+export declare function launchChrome(executablePath: string, targetUrl: string, userDataDir: string, spawnFn?: typeof spawn): Promise<LaunchedChrome>;

package/dist/lib/chrome-launch.js

@@ -0,0 +1,53 @@
+import { spawn } from 'node:child_process';
+import { CdpPipe } from './cdp-pipe.js';
+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,
+    ];
+}
+export function launchChrome(executablePath, targetUrl, userDataDir, spawnFn = spawn) {
+    return new Promise((resolve, reject) => {
+        const proc = spawnFn(executablePath, buildChromeArgs(userDataDir, targetUrl), {
+            stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        let settled = false;
+        proc.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch {
+            }
+            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 {
+            }
+            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;
+        }
+        proc.once('spawn', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ proc, cdp: new CdpPipe(writeStream, readStream) });
+        });
+    });
+}

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

package/dist/lib/docs.d.ts

@@ -1,140 +1,17 @@
-/**
- * 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;