@trawlme/cli 3.12.0 → 3.12.1

package/dist/lib/skillsNudge.js

@@ -1,61 +1,10 @@
-/**
- * #184 — the "elsewhere: suggest, never install" half of the skills
- * bootstrap story (lib/skills.ts's `bootstrapSkillsOnLogin` is the "install
- * on login" half). Writing into `~/.claude/skills` as a side effect of an
- * unrelated command is a filesystem mutation nobody asked for — this module
- * only ever PRINTS a line naming the command that installs them. Never
- * installs anything itself.
- *
- * Two nudges, one shared "at most once per process" guard:
- *  - `maybeSuggestSkillsInstall` — the generic, throttled nudge (once per
- *    NUDGE_THROTTLE_MS across ALL commands, mirrors lib/tips.ts's referral
- *    tip throttle exactly).
- *  - `maybeSuggestSkillsForAuthWall` — the safety-net nudge (#184 point 5):
- *    fires from `doctor`/`run-info` when the run they just showed carries a
- *    live `failureKind:'auth'` verdict and skills are absent. Deliberately
- *    UNTHROTTLED by the 7-day timestamp: sharing that throttle would mean a
- *    routine command on day 0 (stamping the generic nudge's timestamp)
- *    silently suppresses THIS nudge on day 1 when the user actually hits
- *    the auth wall the whole issue exists for — the exact failure this
- *    safety net is supposed to catch. It mirrors trawl_cli#182's own
- *    login-wall hint in `formatDoctor`, which also prints unthrottled every
- *    time the condition is true.
- *  - `nudgedThisProcess` still caps the two at "one nudge per invocation"
- *    combined: `doctor` on an auth-walled, skills-absent run can print the
- *    auth-wall nudge inside its own action, and index.ts's generic
- *    post-command nudge (which does not know `doctor` already said
- *    something) would otherwise print a second, redundant line right after
- *    it. Whichever fires first wins; reset per test via a fresh module
- *    import (see skillsNudge.test.ts's `freshImport` helper, mirroring
- *    tips.test.ts).
- *
- * Gate shape mirrors lib/tips.ts's isReferralTipDue/maybeShowReferralTip
- * throughout (json/isTTY/opt-out/throttle, pure gate separated from the
- * side-effecting caller, cheap checks before any filesystem read) — same
- * reasoning applies verbatim.
- */
 import chalk from 'chalk';
 import config from './config.js';
 import { listBundledSkills, isSkillInstalled, isSkillsActionAllowed, RESTART_CLAUDE_CODE_NOTE } from './skills.js';
-/** Max once per 7 days — same window as lib/tips.ts's referral tip. */
 const NUDGE_THROTTLE_MS = 7 * 24 * 60 * 60 * 1000;
-// #184 constraint A — a FACT about CLI state plus the command name, never an
-// instruction to the reader ("install the skills"/"you should run…"). This
-// output is not only read by a human at a terminal: this platform can relay
-// a CLI's own stdout/stderr into an AI agent's context (the incident this
-// issue exists to prevent was exactly an agent driving this CLI), and
-// third-party content returned into agent context must never read as an
-// instruction the agent is being told to obey. State the fact, name the
-// command, stop there.
 export const SKILLS_NUDGE_TEXT = `Claude skills not installed — \`trawl skills install\` installs them (${RESTART_CLAUDE_CODE_NOTE})`;
 export const AUTH_WALL_SKILLS_NUDGE_TEXT = `This looks like a login wall and Claude skills are not installed — \`trawl skills install\` installs the guidance for it too (${RESTART_CLAUDE_CODE_NOTE})`;
-/** One nudge per process, whichever of the two below fires first. */
 let nudgedThisProcess = false;
-/**
- * Pure gate — true when the throttled, generic "elsewhere" suggestion
- * should print. Every external signal is a parameter, exactly like
- * isReferralTipDue, so this is testable without mocking fs/env/Date.
- */
 export function isSkillsNudgeDue(opts) {
     if (!isSkillsActionAllowed({ json: opts.json, isTTY: opts.isTTY, optedOut: opts.optedOut }))
         return false;
@@ -63,14 +12,6 @@ export function isSkillsNudgeDue(opts) {
         return false;
     return opts.now - opts.lastShownAt >= NUDGE_THROTTLE_MS;
 }
-/**
- * Read-only — checks both scopes, mirrors `trawl skills list`'s own
- * "installed anywhere" question. Failing toward `false` (not installed) on
- * an unreadable skills dir is the safe default here: the worst case is one
- * extra nudge line, never a missed one — the opposite failure (silently
- * assuming "present" and staying quiet) is the exact gap this issue exists
- * to close.
- */
 function anyBundledSkillInstalled() {
     try {
         return listBundledSkills().some((name) => isSkillInstalled(name, 'user') || isSkillInstalled(name, 'local'));
@@ -79,15 +20,6 @@ function anyBundledSkillInstalled() {
         return false;
     }
 }
-/**
- * Shared body for both exported nudges below: the cheap json/TTY/opt-out
- * gate, the "one nudge per process" cap, the skills-presence check, and the
- * actual print — everything the two nudges have in common. `useThrottle`
- * is the one real difference between them (see the module doc comment for
- * why the safety-net nudge deliberately opts out of it), so it stays an
- * explicit parameter here rather than two near-identical function bodies.
- * Never throws.
- */
 function tryPrintNudge(opts, text, useThrottle) {
     try {
         if (nudgedThisProcess)
@@ -95,8 +27,6 @@ function tryPrintNudge(opts, text, useThrottle) {
         const json = Boolean(opts.json);
         const isTTY = Boolean(process.stdout.isTTY);
         const optedOut = process.env['TRAWL_SKILLS_SYNC'] === '0';
-        // Cheap checks first (mirrors tips.ts #153's "never pay when not due")
-        // — only touch the filesystem once json/TTY/opt-out already say "maybe".
         if (!isSkillsActionAllowed({ json, isTTY, optedOut }))
             return;
         if (useThrottle) {
@@ -114,24 +44,11 @@ function tryPrintNudge(opts, text, useThrottle) {
         console.error(chalk.dim(text));
     }
     catch {
-        // silent — a broken nudge must never break a command
     }
 }
-/**
- * Best-effort generic nudge (#184 point 2) — called once per CLI invocation
- * from index.ts's runCli, on every command. Never throws.
- */
 export function maybeSuggestSkillsInstall(opts = {}) {
     tryPrintNudge(opts, SKILLS_NUDGE_TEXT, true);
 }
-/**
- * Safety-net nudge (#184 point 5) — called from `doctor`/`run-info` right
- * when the run they just showed carries a live `failureKind:'auth'` verdict
- * (see commands/doctor.ts's `isAuthWall`). Deliberately unthrottled by the
- * 7-day timestamp — see this module's doc comment for why — but still
- * capped to one nudge per process via the same `nudgedThisProcess` flag the
- * generic nudge sets. Never throws.
- */
 export function maybeSuggestSkillsForAuthWall(opts = {}) {
     tryPrintNudge(opts, AUTH_WALL_SKILLS_NUDGE_TEXT, false);
 }

package/dist/lib/spinner.d.ts

@@ -5,45 +5,6 @@ type SpinOptions<T> = string | {
     failText?: string | ((error: Error) => string);
     [key: string]: unknown;
 };
-/**
- * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
- *
- * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
- * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
- * twice. An agent/CI never wants spinner chrome; here we just run the action.
- * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
- * to stderr, stdout stays clean either way).
- */
 export declare function spin<T>(action: Action<T>, options?: SpinOptions<T>): Promise<T>;
-/**
- * The counterpart to `spin()`'s silence — print a plain-text confirmation on
- * stdout when, and only when, stdout is not a TTY.
- *
- * #160 then #166. `spin()` above deliberately emits nothing when stderr is not
- * a TTY, so for every command whose only non-`--json` feedback was its
- * `successText`, a piped or redirected invocation wrote **zero bytes to both
- * streams while exiting 0**. Our ICP is agent builders, and agents pipe stdout:
- * a verb that writes nothing on success is unusable from a script, because the
- * caller cannot tell success from a no-op. Two of the affected commands were
- * deletes, where that ambiguity is at its worst.
- *
- * Lives here, next to the silence it compensates for, because #160 fixed
- * `trigger` by inlining this rule and #166 then found five siblings carrying
- * the identical defect — five more inlined copies is how the next one gets
- * missed. Callers pass the message; the gate lives in one place.
- *
- * Gated on **stdout**, not stderr: stdout is the stream a script actually reads
- * (`$(trawl …)`, `> out.txt`, `| jq`), independent of whatever `spin()` decides
- * about stderr. So an interactive session, where the ora spinner already
- * confirmed on stderr, never gets a duplicate line here.
- *
- * Never call this on a `--json` path: under `--json`, stdout must stay exactly
- * one parseable document.
- *
- * Known residual, unchanged from #160: stdout attached to a real terminal while
- * stderr is separately redirected still prints nothing on either stream. That is
- * not the reported or common shape (full redirection, or stdout-only capture),
- * and widening the gate would put a duplicate line in front of interactive users.
- */
 export declare function confirmNonTTY(message: string): void;
 export {};

package/dist/lib/spinner.js

@@ -1,50 +1,10 @@
 import { oraPromise } from 'ora';
-/**
- * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
- *
- * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
- * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
- * twice. An agent/CI never wants spinner chrome; here we just run the action.
- * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
- * to stderr, stdout stays clean either way).
- */
 export function spin(action, options) {
     if (!process.stderr.isTTY) {
         return Promise.resolve(typeof action === 'function' ? action() : action);
     }
-    // oraPromise's own overloads accept (action, string) and (action, options).
     return oraPromise(action, options);
 }
-/**
- * The counterpart to `spin()`'s silence — print a plain-text confirmation on
- * stdout when, and only when, stdout is not a TTY.
- *
- * #160 then #166. `spin()` above deliberately emits nothing when stderr is not
- * a TTY, so for every command whose only non-`--json` feedback was its
- * `successText`, a piped or redirected invocation wrote **zero bytes to both
- * streams while exiting 0**. Our ICP is agent builders, and agents pipe stdout:
- * a verb that writes nothing on success is unusable from a script, because the
- * caller cannot tell success from a no-op. Two of the affected commands were
- * deletes, where that ambiguity is at its worst.
- *
- * Lives here, next to the silence it compensates for, because #160 fixed
- * `trigger` by inlining this rule and #166 then found five siblings carrying
- * the identical defect — five more inlined copies is how the next one gets
- * missed. Callers pass the message; the gate lives in one place.
- *
- * Gated on **stdout**, not stderr: stdout is the stream a script actually reads
- * (`$(trawl …)`, `> out.txt`, `| jq`), independent of whatever `spin()` decides
- * about stderr. So an interactive session, where the ora spinner already
- * confirmed on stderr, never gets a duplicate line here.
- *
- * Never call this on a `--json` path: under `--json`, stdout must stay exactly
- * one parseable document.
- *
- * Known residual, unchanged from #160: stdout attached to a real terminal while
- * stderr is separately redirected still prints nothing on either stream. That is
- * not the reported or common shape (full redirection, or stdout-only capture),
- * and widening the gate would put a duplicate line in front of interactive users.
- */
 export function confirmNonTTY(message) {
     if (!process.stdout.isTTY)
         console.log(message);

package/dist/lib/storage-state.d.ts

@@ -1,33 +1,14 @@
-/**
- * Pure CDP -> storageState mapping + domain scoping for `scraps account
- * session capture` (trawl_cli#183). No I/O here — every function takes
- * plain data and returns plain data, so the full cookie/localStorage
- * matrix (sameSite casing, expires-in-seconds, domain scoping, …) is
- * testable without a real Chrome.
- *
- * The output shape mirrors trawl_node#1976's ingest validator
- * (modules/scraps/helpers/sessionShape.js) — CookieData fields, `sameSite`
- * in `Strict|Lax|None`, `expires` in seconds, `domain` required. This file
- * pre-normalizes to that shape so the server's validator never has to
- * reject the WHOLE batch over one anomalous cookie the client could have
- * caught itself (see normalizeCdpCookie's sameSite=None handling below).
- */
-/** A cookie as CDP's `Storage.getCookies`/`Network.Cookie` returns it. */
 export interface RawCdpCookie {
     name: string;
     value: string;
     domain: string;
     path?: string;
-    /** Unix seconds; -1 denotes a session cookie (matches chrome.cookies shape). */
     expires?: number;
     httpOnly?: boolean;
     secure?: boolean;
-    /** CDP's `Network.CookieSameSite` enum — nominally `Strict|Lax|None`, but
-     *  normalized defensively (case-insensitively) rather than trusted as-is. */
     sameSite?: string;
     [key: string]: unknown;
 }
-/** trawl_node sessionShape.js's `CookieData` — only these fields are ever forwarded. */
 export interface CookieData {
     name: string;
     value: string;
@@ -38,7 +19,6 @@ export interface CookieData {
     sameSite?: 'Strict' | 'Lax' | 'None';
     expires?: number;
 }
-/** One origin's captured localStorage, pre-dedup/pre-scope. */
 export interface RawOriginLocalStorage {
     origin: string;
     entries: Array<{
@@ -57,83 +37,8 @@ export interface StorageState {
     cookies: CookieData[];
     origins: OriginStorage[];
 }
-/**
- * Domain scoping (trawl_cli#183 review finding 2 — cross-tenant leak). The
- * previous version of this file peeled a hostname down to a "registrable
- * domain" (last 2-3 labels, with a small hardcoded allowlist for
- * `co.uk`-shaped suffixes) and treated any host sharing that suffix as in
- * scope. That is wrong for any multi-tenant hosting domain NOT in the
- * allowlist — `getRegistrableDomain('alice.github.io')` collapsed to
- * `'github.io'`, so `isHostInScope('bob.github.io', 'github.io')` came back
- * `true`: a scrap targeting `alice.github.io` would upload `bob.github.io`'s
- * cookies too (same for `herokuapp.com`, `vercel.app`, `s3.amazonaws.com`,
- * …) — every one of them would need its own allowlist entry, which is
- * exactly the Public Suffix List this file deliberately avoids depending
- * on.
- *
- * The fix NARROWS instead: scope every capture to RFC 6265 §5.1.3
- * domain-matching against the scrap URL's own host (`getTargetHost`) —
- * never a peeled/derived domain, so there is nothing left to get wrong
- * about a given hosting provider's suffix.
- *
- * Verified against a real Chrome 152 (loopback probe, `--host-resolver-rules`
- * remapping `alice.github.io`/`app.example.com`/etc. to 127.0.0.1, no real
- * network traffic):
- *  - Chrome REFUSES to let a page at `alice.github.io` set a cookie with
- *    `Domain=github.io` at all — it never reaches the cookie jar. That's
- *    Chrome's own PSL enforcement on the SET side, and it's what makes the
- *    zero-PSL-dependency approach below safe: a public-suffix-scoped cookie
- *    simply cannot exist in a real jar to be mis-scoped in the first place.
- *  - `Storage.getCookies` DOES distinguish a host-only cookie from an
- *    explicit-`Domain=` one at the CDP layer, even when the explicit domain
- *    string equals the current host exactly: a bare `document.cookie="k=v"`
- *    on `alice.github.io` comes back with `domain:"alice.github.io"` (no
- *    leading dot); `document.cookie="k=v; domain=alice.github.io"` — same
- *    effective host — comes back `domain:".alice.github.io"` (leading dot).
- *    That leading dot is real, load-bearing information: it is exactly
- *    RFC 6265's own signal for "this is a domain-match cookie, not a
- *    host-only one" and `isCookieDomainInScope` below reads it as such
- *    rather than stripping it.
- *
- * One deliberate loss, not a bug: a host-only cookie set on a SIBLING host
- * (e.g. `auth.example.com` while the scrap targets `app.example.com`) is
- * out of scope here. A real browser would never send that cookie to
- * `app.example.com` either — host-only means exactly that host — so
- * nothing replay-relevant is lost; it would only matter if the scrap
- * script itself later navigates to `auth.example.com`, which this capture
- * has no visibility into anyway.
- */
-/**
- * @desc The exact host `targetUrl` will actually be requested at — the
- * single anchor every scope decision in this file is relative to. NOT a
- * peeled "registrable domain": no suffix list, no label-counting, no
- * allowlist to keep up to date.
- */
 export declare function getTargetHost(targetUrl: string): string;
-/**
- * @desc RFC 6265 §5.1.3 domain-matching for one captured cookie's `domain`
- * attribute exactly as CDP's `Storage.getCookies` reports it (leading dot
- * preserved when Chrome ever wrote one, absent for a host-only cookie —
- * see the module doc comment for how that was verified against a real
- * Chrome).
- *  - Leading dot (a domain-match cookie): in scope for the target host
- *    itself, or any subdomain of it.
- *  - No leading dot (a host-only cookie): in scope ONLY for that exact
- *    host — never a subdomain, never a sibling, never a parent. This is
- *    what excludes `bob.github.io` from a capture targeting
- *    `alice.github.io`, and `auth.example.com` from one targeting
- *    `app.example.com`.
- */
 export declare function isCookieDomainInScope(rawDomain: string, targetHost: string): boolean;
-/**
- * @desc True when a captured page's own hostname (`originHost` — an
- * origin's localStorage has no "domain attribute" concept, unlike a
- * cookie) is the target host itself, or a subdomain of it. Anchored the
- * opposite way from a host-only cookie check: here the TARGET is the root
- * and the origin must fall under it, so a sibling (`auth.example.com` for
- * a scrap on `app.example.com`) is still excluded, but a genuine
- * subdomain page opened during the same login flow is not.
- */
 export declare function isOriginHostInScope(originHost: string, targetHost: string): boolean;
 export interface MapCookiesResult {
     cookies: CookieData[];
@@ -141,27 +46,10 @@ export interface MapCookiesResult {
     droppedOutOfScope: number;
     droppedInvalid: number;
 }
-/**
- * @desc Scope + normalize a raw CDP cookie jar down to the cookies a real
- * browser would actually send to `targetUrl`'s host (`isCookieDomainInScope`
- * — RFC 6265 domain-matching, never a peeled registrable domain). Never
- * throws — a structurally broken cookie is counted and dropped, not fatal
- * to the rest of the capture (see the "batch same class failures" rule:
- * this IS the sweep of the offending class, applied once here rather than
- * duplicated at each call site).
- */
 export declare function mapCookies(rawCookies: RawCdpCookie[], targetUrl: string): MapCookiesResult;
 export interface MapOriginsResult {
     origins: OriginStorage[];
     totalSeen: number;
     droppedOutOfScope: number;
 }
-/**
- * @desc Scope raw per-origin localStorage dumps down to origins that are
- * `targetUrl`'s own host or a subdomain of it (`isOriginHostInScope`).
- * `origin` is passed through unchanged (it is already a bare
- * `scheme://host[:port]` by construction — callers build it via
- * `new URL(pageUrl).origin`) so it satisfies sessionShape.js's bare-origin
- * check untouched.
- */
 export declare function mapOrigins(rawOrigins: RawOriginLocalStorage[], targetUrl: string): MapOriginsResult;

package/dist/lib/storage-state.js

@@ -1,86 +1,6 @@
-/**
- * Pure CDP -> storageState mapping + domain scoping for `scraps account
- * session capture` (trawl_cli#183). No I/O here — every function takes
- * plain data and returns plain data, so the full cookie/localStorage
- * matrix (sameSite casing, expires-in-seconds, domain scoping, …) is
- * testable without a real Chrome.
- *
- * The output shape mirrors trawl_node#1976's ingest validator
- * (modules/scraps/helpers/sessionShape.js) — CookieData fields, `sameSite`
- * in `Strict|Lax|None`, `expires` in seconds, `domain` required. This file
- * pre-normalizes to that shape so the server's validator never has to
- * reject the WHOLE batch over one anomalous cookie the client could have
- * caught itself (see normalizeCdpCookie's sameSite=None handling below).
- */
-/**
- * Domain scoping (trawl_cli#183 review finding 2 — cross-tenant leak). The
- * previous version of this file peeled a hostname down to a "registrable
- * domain" (last 2-3 labels, with a small hardcoded allowlist for
- * `co.uk`-shaped suffixes) and treated any host sharing that suffix as in
- * scope. That is wrong for any multi-tenant hosting domain NOT in the
- * allowlist — `getRegistrableDomain('alice.github.io')` collapsed to
- * `'github.io'`, so `isHostInScope('bob.github.io', 'github.io')` came back
- * `true`: a scrap targeting `alice.github.io` would upload `bob.github.io`'s
- * cookies too (same for `herokuapp.com`, `vercel.app`, `s3.amazonaws.com`,
- * …) — every one of them would need its own allowlist entry, which is
- * exactly the Public Suffix List this file deliberately avoids depending
- * on.
- *
- * The fix NARROWS instead: scope every capture to RFC 6265 §5.1.3
- * domain-matching against the scrap URL's own host (`getTargetHost`) —
- * never a peeled/derived domain, so there is nothing left to get wrong
- * about a given hosting provider's suffix.
- *
- * Verified against a real Chrome 152 (loopback probe, `--host-resolver-rules`
- * remapping `alice.github.io`/`app.example.com`/etc. to 127.0.0.1, no real
- * network traffic):
- *  - Chrome REFUSES to let a page at `alice.github.io` set a cookie with
- *    `Domain=github.io` at all — it never reaches the cookie jar. That's
- *    Chrome's own PSL enforcement on the SET side, and it's what makes the
- *    zero-PSL-dependency approach below safe: a public-suffix-scoped cookie
- *    simply cannot exist in a real jar to be mis-scoped in the first place.
- *  - `Storage.getCookies` DOES distinguish a host-only cookie from an
- *    explicit-`Domain=` one at the CDP layer, even when the explicit domain
- *    string equals the current host exactly: a bare `document.cookie="k=v"`
- *    on `alice.github.io` comes back with `domain:"alice.github.io"` (no
- *    leading dot); `document.cookie="k=v; domain=alice.github.io"` — same
- *    effective host — comes back `domain:".alice.github.io"` (leading dot).
- *    That leading dot is real, load-bearing information: it is exactly
- *    RFC 6265's own signal for "this is a domain-match cookie, not a
- *    host-only one" and `isCookieDomainInScope` below reads it as such
- *    rather than stripping it.
- *
- * One deliberate loss, not a bug: a host-only cookie set on a SIBLING host
- * (e.g. `auth.example.com` while the scrap targets `app.example.com`) is
- * out of scope here. A real browser would never send that cookie to
- * `app.example.com` either — host-only means exactly that host — so
- * nothing replay-relevant is lost; it would only matter if the scrap
- * script itself later navigates to `auth.example.com`, which this capture
- * has no visibility into anyway.
- */
-/**
- * @desc The exact host `targetUrl` will actually be requested at — the
- * single anchor every scope decision in this file is relative to. NOT a
- * peeled "registrable domain": no suffix list, no label-counting, no
- * allowlist to keep up to date.
- */
 export function getTargetHost(targetUrl) {
     return new URL(targetUrl).hostname.toLowerCase();
 }
-/**
- * @desc RFC 6265 §5.1.3 domain-matching for one captured cookie's `domain`
- * attribute exactly as CDP's `Storage.getCookies` reports it (leading dot
- * preserved when Chrome ever wrote one, absent for a host-only cookie —
- * see the module doc comment for how that was verified against a real
- * Chrome).
- *  - Leading dot (a domain-match cookie): in scope for the target host
- *    itself, or any subdomain of it.
- *  - No leading dot (a host-only cookie): in scope ONLY for that exact
- *    host — never a subdomain, never a sibling, never a parent. This is
- *    what excludes `bob.github.io` from a capture targeting
- *    `alice.github.io`, and `auth.example.com` from one targeting
- *    `app.example.com`.
- */
 export function isCookieDomainInScope(rawDomain, targetHost) {
     const host = targetHost.toLowerCase();
     if (rawDomain.startsWith('.')) {
@@ -89,15 +9,6 @@ export function isCookieDomainInScope(rawDomain, targetHost) {
     }
     return host === rawDomain.toLowerCase();
 }
-/**
- * @desc True when a captured page's own hostname (`originHost` — an
- * origin's localStorage has no "domain attribute" concept, unlike a
- * cookie) is the target host itself, or a subdomain of it. Anchored the
- * opposite way from a host-only cookie check: here the TARGET is the root
- * and the origin must fall under it, so a sibling (`auth.example.com` for
- * a scrap on `app.example.com`) is still excluded, but a genuine
- * subdomain page opened during the same login flow is not.
- */
 export function isOriginHostInScope(originHost, targetHost) {
     const h = originHost.toLowerCase();
     const target = targetHost.toLowerCase();
@@ -108,29 +19,9 @@ const CANONICAL_SAME_SITE = {
     lax: 'Lax',
     none: 'None',
 };
-/**
- * @desc Recase any CDP/browser sameSite spelling onto CookieData's exact
- * casing. Returns null for anything unrecognized (CDP's own "unspecified"
- * included) — the field is then omitted entirely rather than guessed,
- * mirroring sessionShape.js's own 'unspecified' handling.
- */
 function canonicalizeSameSite(value) {
     return CANONICAL_SAME_SITE[value.toLowerCase()] ?? null;
 }
-/**
- * @desc Map one CDP cookie onto CookieData, or null if it's structurally
- * unusable (no domain, no name/value). A `sameSite=None` cookie missing
- * `secure` is NOT dropped outright — dropping only the `sameSite`
- * attribute (rather than the whole cookie) is deliberate: sessionShape.js's
- * `normalizeCookies` throws on that combination, and since it processes
- * the array with a single `.map()`, ONE such cookie would reject the
- * ENTIRE upload with a 422 — a capture that otherwise succeeded would be
- * thrown away over one anomalous cookie. A real, currently-live browser
- * cookie can't actually be in this state (Chrome refuses to store a `None`
- * cookie without `Secure`), so in practice this only guards a defensive
- * edge; when it does happen, omitting `sameSite` keeps the cookie (and the
- * rest of the batch) valid.
- */
 function normalizeCdpCookie(raw) {
     if (typeof raw.name !== 'string' || raw.name.length === 0)
         return null;
@@ -156,15 +47,6 @@ function normalizeCdpCookie(raw) {
     }
     return cookie;
 }
-/**
- * @desc Scope + normalize a raw CDP cookie jar down to the cookies a real
- * browser would actually send to `targetUrl`'s host (`isCookieDomainInScope`
- * — RFC 6265 domain-matching, never a peeled registrable domain). Never
- * throws — a structurally broken cookie is counted and dropped, not fatal
- * to the rest of the capture (see the "batch same class failures" rule:
- * this IS the sweep of the offending class, applied once here rather than
- * duplicated at each call site).
- */
 export function mapCookies(rawCookies, targetUrl) {
     const targetHost = getTargetHost(targetUrl);
     let droppedOutOfScope = 0;
@@ -175,11 +57,6 @@ export function mapCookies(rawCookies, targetUrl) {
             droppedInvalid++;
             continue;
         }
-        // The leading '.' (or its absence) is meaningful — see
-        // isCookieDomainInScope's own doc comment — so it is NOT stripped here;
-        // only the OUTPUT cookie's `domain` field stays untouched either way
-        // (normalizeCdpCookie passes raw.domain through as-is, dot included),
-        // since the server needs the exact original attribute to replay it.
         if (!isCookieDomainInScope(raw.domain, targetHost)) {
             droppedOutOfScope++;
             continue;
@@ -193,14 +70,6 @@ export function mapCookies(rawCookies, targetUrl) {
     }
     return { cookies, totalSeen: rawCookies.length, droppedOutOfScope, droppedInvalid };
 }
-/**
- * @desc Scope raw per-origin localStorage dumps down to origins that are
- * `targetUrl`'s own host or a subdomain of it (`isOriginHostInScope`).
- * `origin` is passed through unchanged (it is already a bare
- * `scheme://host[:port]` by construction — callers build it via
- * `new URL(pageUrl).origin`) so it satisfies sessionShape.js's bare-origin
- * check untouched.
- */
 export function mapOrigins(rawOrigins, targetUrl) {
     const targetHost = getTargetHost(targetUrl);
     let droppedOutOfScope = 0;

package/dist/lib/tips.d.ts

@@ -1,13 +1,3 @@
-/**
- * Pure gate: true when the tip should print. Every external signal (json
- * flag, TTY-ness, opt-out, persisted timestamp, current time) is a
- * parameter rather than read internally, so this is trivially testable
- * without mocking process.env/stdout/Date/config. Does NOT cover the
- * server-side `invitations.userFacing` flag (#153) — that check requires a
- * network round-trip, so it's kept out of this pure/sync gate and only
- * consulted once this gate is already true (see
- * isReferralProgramUserFacing + maybeShowReferralTip below).
- */
 export declare function isReferralTipDue(opts: {
     json?: boolean;
     isTTY: boolean;
@@ -15,34 +5,6 @@ export declare function isReferralTipDue(opts: {
     lastShownAt: number;
     now: number;
 }): boolean;
-/**
- * Best-effort: print one subtle line inviting the user to refer a builder,
- * throttled to once per 7 days via a timestamp persisted in the CLI's
- * existing Conf-backed config store (lib/config.ts — same store as
- * apiUrl/token/telemetry/updateNotifier), AND gated on the server's
- * `invitations.userFacing` flag (#153) once that throttle window is open.
- *
- * This only gates on throttle/TTY/`--json`/opt-out/server-flag — it does
- * NOT know whether the underlying command actually succeeded. Callers must
- * only invoke it on a genuine success (see commands/scraps.ts `run <id>`'s
- * action, which also checks pollRunProgress's exit code under `--watch`
- * before calling this). Any state read/write/network failure (corrupt
- * config file, disk error, unreachable server, …) is swallowed silently —
- * a broken tip must never break a run.
- *
- * #153 — the timestamp is now persisted BEFORE the print (#151 originally
- * had it after). Two overlapping calls that both read `due=true` before
- * either has persisted can still both decide to print (a file-based config
- * store can't fully arbitrate that without a lock this feature doesn't
- * warrant) — but persist-before-print closes the narrower, guaranteed-
- * recurring failure mode: previously, if the print succeeded but the
- * subsequent config.set failed (or simply hadn't landed yet when a second
- * call read the same stale timestamp), the tip could print again on every
- * later run forever, since the "already shown" state never advanced. With
- * persist first, a lost race collapses to "tip skipped this time, timestamp
- * still unset, next due window free to retry" — never a guaranteed
- * repeat print.
- */
 export declare function maybeShowReferralTip(opts?: {
     json?: boolean;
 }): Promise<void>;