@trawlme/cli 3.9.1 → 3.11.0

package/dist/lib/api.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { getApiUrl, getToken, getAuthMode, getLiveAuthEnvVar } from './config.js';
 import { parseServerJson } from './json.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -518,6 +520,119 @@ async function publicGet(path, reqOpts = {}) {
         throw new Error('Invalid JSON in server response');
     }
 }
+/**
+ * A hard-bounded, PROBE-ONLY GET — never use this for a command's real work
+ * (no auth headers, no retry, no NetworkError-with-cause classification).
+ *
+ * trawl_cli#185 defect: every OTHER fetch in this file rides Node's global
+ * `fetch()` + `AbortSignal.timeout()`, which bounds the PROMISE, not the
+ * process. Aborting a fetch mid-connect does not necessarily tear down an
+ * in-flight TCP/TLS handshake — a documented Node/undici characteristic —
+ * so against a routable-but-silently-dropping host (a dropped SYN, never a
+ * RST — a realistic firewalled/air-gapped shape) the dangling socket keeps
+ * the event loop alive until Node's OWN internal connect-timeout eventually
+ * fires. Measured on this host: a bare `fetch()` + `AbortSignal.timeout(2000)`
+ * against such a host rejects its promise at ~2005ms, but the PROCESS does
+ * not exit until ~10.5s later — not configurable from here, and not paid by
+ * `ECONNREFUSED` (~0.13s) or a failed DNS lookup (~0.29s), only by the
+ * silent-drop shape. Every other command in this file accepts that risk
+ * because the user explicitly asked for that network call (`trawl ping`
+ * hanging on an unreachable host is the command doing its job — nothing to
+ * fix there). This primitive exists for the one case where the network call
+ * ITSELF is optional: `spec --json`'s own doc-discovery probe (the one
+ * command an agent runs to orient itself) has no business costing 10.5s to
+ * learn a host is unreachable, so this manages the raw socket directly.
+ *
+ * The timeout here is an INDEPENDENT `setTimeout` that calls `req.destroy()`
+ * — deliberately NOT `http.request`'s own `timeout` option (idle-based via
+ * `socket.setTimeout`, so it only fires when zero bytes arrive for that
+ * long — a coincidentally-same condition against a silent black hole, but a
+ * dishonest bound in general: it would never fire against a host that
+ * connects instantly then trickles bytes just often enough to reset the
+ * idle clock). Destroying the request/socket on this timer is what actually
+ * frees the OS-level handle so the process can exit promptly instead of
+ * waiting out Node's own multi-second connect-timeout — verified empirically
+ * (same black-holed host): total process time dropped from ~10.5s to ~2.0s
+ * with this change.
+ *
+ * Resolves to `null` on ANY failure (timeout, refusal, non-2xx, malformed
+ * JSON, an unsupported protocol) — never throws — so the one caller
+ * (spec.ts's fetchExternalDocsUrl) needs no try/catch of its own. This is
+ * NOT automatic: `node:http`/`node:https`' own `request()` throws
+ * SYNCHRONOUSLY (`ERR_INVALID_PROTOCOL`) for a URL whose protocol doesn't
+ * match the module (e.g. a stray `ftp://` in a misconfigured `TRAWL_API_URL`)
+ * — inside a Promise executor a synchronous throw becomes a REJECTED
+ * promise, which would have propagated straight through `fetchExternalDocsUrl`
+ * and turned `spec --json` into an error envelope instead of the spec.
+ * Reproduced: `TRAWL_API_URL=ftp://x node dist/index.js spec --json` failed
+ * entirely before this guard was added. The explicit protocol check below
+ * closes that.
+ *
+ * Two more deliberate departures from every other call in this file:
+ *  - `TRAWL_TIMEOUT` (getTimeoutMs's env override, #91) is NOT consulted
+ *    here — `opts.timeoutMs` is absolute. An operator raising that ceiling
+ *    for a genuinely long-running command (e.g. LONG_RUN_TIMEOUT_MS's 300s)
+ *    must never make an OPTIONAL probe wait 300s too; the two knobs measure
+ *    different things and must not share a dial.
+ *  - Redirects are NOT followed (global `fetch()`, used everywhere else in
+ *    this file, follows them by default; raw `http`/`https` `request()`
+ *    does not). For this probe a 3xx is just another non-2xx -> `null` ->
+ *    fall through to rung 2 — an acceptable degradation, not a bug.
+ */
+function probeJson(path, opts) {
+    return new Promise((settle) => {
+        let url;
+        try {
+            url = new URL(`${getApiUrl()}${path}`);
+        }
+        catch {
+            settle(null);
+            return;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            settle(null);
+            return;
+        }
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            settle(value);
+        };
+        const transport = url.protocol === 'http:' ? httpRequest : httpsRequest;
+        const req = transport(url, { headers: { 'User-Agent': USER_AGENT } }, (res) => {
+            if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                res.resume(); // drain so the socket can be released
+                finish(null);
+                return;
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    finish(JSON.parse(body));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+            res.on('error', () => finish(null));
+        });
+        // The independent, non-idle-based ceiling this function exists for —
+        // fires regardless of connect/response state and forcibly destroys the
+        // socket, unlike AbortSignal.timeout() everywhere else in this file.
+        const timer = setTimeout(() => {
+            req.destroy(new Error(`probe to ${url.href} timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs);
+        req.on('error', () => finish(null));
+        req.end();
+    });
+}
 async function getText(path, reqOpts = {}) {
     const token = getToken();
     if (!token)
@@ -537,6 +652,9 @@ async function getText(path, reqOpts = {}) {
 export const api = {
     get: (path, opts) => request(path, {}, opts),
     publicGet: (path, opts) => publicGet(path, opts),
+    /** See `probeJson`'s own doc comment — hard-bounded, probe-only, never for
+     *  a command's real work. Today's one caller: spec.ts's fetchExternalDocsUrl. */
+    probeJson: (path, opts) => probeJson(path, opts),
     getText: (path, opts) => getText(path, opts),
     post: (path, body, opts) => request(path, {
         method: 'POST',

package/dist/lib/config.d.ts

@@ -13,6 +13,7 @@ interface TrawlConfig {
      * Same optional/absent-means-enabled shape as `updateNotifier` above. */
     tips?: boolean;
     referralTipShownAt: number;
+    skillsNudgeShownAt: number;
 }
 declare const config: Conf<TrawlConfig>;
 /**

package/dist/lib/config.js

@@ -17,6 +17,7 @@ const config = new Conf({
         telemetry: true,
         telemetryUserId: '',
         referralTipShownAt: 0,
+        skillsNudgeShownAt: 0,
     },
 });
 /**

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