@trawlme/cli 3.11.0 → 3.12.1

package/dist/lib/skills.js

@@ -24,31 +24,6 @@ function getSkillsBase(scope) {
     const base = scope === 'local' ? join(process.cwd(), '.claude') : join(homedir(), '.claude');
     return join(base, 'skills');
 }
-/**
- * #184 defect 1 — the ownership-refusal thrown below serves two different
- * audiences on two different channels, and one string can't correctly serve
- * both:
- *
- *  - A human who just typed `trawl skills install`/`update` reaches this via
- *    an uncaught throw (index.ts's generic error path prints `.message`
- *    verbatim) — that reader can decide whether to add `--force`, so the
- *    guidance belongs on this channel. `.message` (below) keeps it.
- *  - `bootstrapSkillsOnLogin` also catches this exact throw and relays its
- *    text into `skipped[].reason`, which `login.ts` prints to stderr — a
- *    channel this feature's own doc comments say must never carry a command
- *    phrased as an instruction, because this CLI is driven by AI agents and
- *    this platform can feed a CLI's own stderr back into an agent's own
- *    context. `Pass --force to overwrite it anyway` is exactly that kind of
- *    instruction: an agent "obeying" it calls `installSkill`'s own
- *    `rmSync(recursive)` on a directory the user owns and trawl did not
- *    create — the destroy-the-user's-files incident this class of bug
- *    produces.
- *
- * `.relayableReason` carries the identical fact — this path exists, trawl
- * did not create it, so it was left untouched — with the imperative sentence
- * removed, for every channel that is not a direct, synchronous reply to a
- * human's own typed command.
- */
 export class SkillOwnershipRefusalError extends Error {
     relayableReason;
     constructor(dest) {
@@ -58,18 +33,6 @@ export class SkillOwnershipRefusalError extends Error {
         this.relayableReason = `"${dest}" already exists and was not installed by trawl (no .version marker) — left untouched.`;
     }
 }
-/**
- * Ownership guard (#73, extended #86 finding 7): this does `rmSync(recursive)`
- * on the target dir before reinstalling, so it must never do that to a dir
- * the CLI didn't install. `autoUpdateInstalledSkills()` already checks this
- * itself before ever calling here (it skips marker-less dirs outright), but
- * the explicit `trawl skills install`/`update` commands used to call straight
- * through with no such check — a pre-existing user-authored
- * `.claude/skills/<name>` dir that happens to collide with a bundled skill
- * name would get silently deleted and overwritten. A missing `.version`
- * marker on an EXISTING dest now refuses the install/reinstall unless
- * `force` is passed.
- */
 export function installSkill(name, scope, opts = {}) {
     const src = join(getSkillsPackageRoot(), 'skills', name);
     if (!existsSync(src)) {
@@ -77,12 +40,6 @@ export function installSkill(name, scope, opts = {}) {
     }
     const dest = join(getSkillsBase(scope), name);
     if (existsSync(dest)) {
-        // #91 — an unreadable `.version` (e.g. EISDIR from a directory instead of
-        // a file, a corrupted/interrupted install) is NOT proof of ownership
-        // either — treat it exactly like a missing marker (unowned) instead of
-        // letting the raw fs error crash the whole batch (`skills install`/
-        // `update` with no skill argument loops over every bundled skill; one
-        // malformed dest must not block installing the others).
         let installedVersion;
         try {
             installedVersion = getInstalledVersion(name, scope);
@@ -117,20 +74,6 @@ export function getInstalledVersion(name, scope) {
 export function isSkillInstalled(name, scope) {
     return existsSync(join(getSkillsBase(scope), name));
 }
-/**
- * #86 review — orphan cleanup. The re-sync loop in autoUpdateInstalledSkills
- * iterates listBundledSkills() — the NEW package's names only. When a bundled
- * skill is RENAMED between package versions (1.0.0 shipped `trawl`, 1.3.1
- * renamed it `trawl-cli`), the old marker-owned dir is never visited again: a
- * stale ghost skill teaching outdated CLI usage stays installed forever,
- * alongside the new one. This sweeps each scope's skills base dir for
- * installed dirs that (a) carry a `.version` marker — the same ownership
- * proof as everywhere else; a marker-less user-authored dir is NEVER touched,
- * whatever its name — and (b) are no longer in the bundled set, and removes
- * them with one honest stderr line (same style as the re-sync line).
- * Returns the removed names (for the explicit `skills update` path to
- * summarize).
- */
 export function removeOrphanedSkills(scope) {
     const base = getSkillsBase(scope);
     if (!existsSync(base))
@@ -144,15 +87,10 @@ export function removeOrphanedSkills(scope) {
                 continue;
         }
         catch {
-            continue; // raced away / unreadable — nothing to clean
+            continue;
         }
         if (bundled.has(name))
             continue;
-        // No `.version` marker → not ours → never delete it. Read is wrapped:
-        // a weird `.version` (e.g. a directory instead of a file → EISDIR on
-        // readFileSync) must skip only THIS entry, not blow up the whole sweep —
-        // a single malformed install must never leave every other entry
-        // unswept. (#88 item 12)
         let installedVersion;
         try {
             installedVersion = getInstalledVersion(name, scope);
@@ -168,22 +106,6 @@ export function removeOrphanedSkills(scope) {
     }
     return removed;
 }
-/**
- * Re-installs any CLI-owned skill whose installed version doesn't match the
- * bundled one, and removes CLI-owned skills that are no longer bundled at all
- * (renamed/dropped upstream — see removeOrphanedSkills). Called on CLI
- * startup to keep skills in sync with the CLI version. Never throws —
- * failures are silent so they don't break unrelated commands.
- *
- * Ownership guard (#73): `installSkill` does `rmSync(recursive)` on the target
- * dir, so this MUST only ever touch dirs the CLI itself installed. Proof of
- * ownership is a `.version` marker. A user-created `.claude/skills/<name>` dir
- * that happens to collide with a bundled skill name carries no marker, so it is
- * left untouched instead of being silently deleted + overwritten.
- *
- * Opt-out: `TRAWL_SKILLS_SYNC=0` disables auto-sync entirely (mirrors
- * `TRAWL_TELEMETRY=0`), for users who manage their skills by hand.
- */
 export function autoUpdateInstalledSkills() {
     if (process.env['TRAWL_SKILLS_SYNC'] === '0')
         return;
@@ -193,14 +115,6 @@ export function autoUpdateInstalledSkills() {
             for (const scope of ['user', 'local']) {
                 if (!isSkillInstalled(name, scope))
                     continue;
-                // #91 — mirrors removeOrphanedSkills' guard below: a weird `.version`
-                // marker (e.g. a directory instead of a file, from a corrupted /
-                // interrupted install) throws EISDIR on readFileSync. Without this
-                // per-entry guard, that throw was caught by this function's OUTER
-                // try/catch (below) — which aborts the ENTIRE function, so every
-                // remaining bundled skill silently stopped syncing AND the orphan
-                // sweep (removeOrphanedSkills, called after this loop) never ran
-                // either. Must skip only THIS entry, never abort the whole sweep.
                 let installed;
                 try {
                     installed = getInstalledVersion(name, scope);
@@ -208,53 +122,22 @@ export function autoUpdateInstalledSkills() {
                 catch {
                     continue;
                 }
-                // No `.version` marker → not ours → never delete it.
                 if (installed === null)
                     continue;
                 if (installed === bundledVersion)
                     continue;
                 installSkill(name, scope);
-                // One honest line so a destructive-looking re-sync is never silent.
-                // stderr keeps stdout clean for --json consumers.
                 process.stderr.write(`trawl: re-synced skill "${name}" (${scope}) ${installed} → ${bundledVersion}\n`);
             }
         }
-        // Migration gap (#86 review): also drop marker-owned dirs whose skill
-        // was renamed/removed upstream, or they linger as stale ghosts forever.
         for (const scope of ['user', 'local']) {
             removeOrphanedSkills(scope);
         }
     }
     catch {
-        // Silent: skill auto-update should never block the CLI
     }
 }
-/**
- * #184 — one line, reused everywhere the CLI installs a skill mid-invocation
- * (login's bootstrap below, lib/skillsNudge.ts's two nudges): skills are
- * discovered at Claude Code SESSION START, so a skill written to disk right
- * now is invisible to whatever session is already running. Stated as a
- * fact, never an imperative ("restart Claude Code") — this text can be
- * relayed into an AI agent's own context (this CLI's whole incident was an
- * agent driving it), and a command phrased there must never read as an
- * instruction the agent is being told to obey.
- */
 export const RESTART_CLAUDE_CODE_NOTE = 'Claude Code must be restarted to see them — skills are loaded at session start, not mid-session.';
-/**
- * #184 — pure gate shared by every skills-related write/print that must
- * never fire under `--json` (a machine consumer needs pure stdout and there
- * is no human reading a suggestion anyway), on a non-TTY invocation (a CI
- * runner or an agent driving this CLI as a subprocess has no Claude Code
- * session to discover a newly-installed skill in the first place), or when
- * `TRAWL_SKILLS_SYNC=0` (the existing auto-sync opt-out, extended here: a
- * user who manages skills by hand does not want the CLI touching that dir
- * for ANY reason — install or nudge alike). Every signal is a parameter,
- * exactly like lib/tips.ts's `isReferralTipDue`, so this is testable
- * without mocking env/TTY. `isTTY`'s exact definition (stdout-only vs
- * stdin+stdout) is the CALLER's call — see bootstrapSkillsOnLogin below vs
- * lib/skillsNudge.ts for the two different answers this codebase already
- * gives elsewhere (confirm.ts's `isInteractive` vs tips.ts's own check).
- */
 export function isSkillsActionAllowed(opts) {
     if (opts.json)
         return false;
@@ -264,89 +147,6 @@ export function isSkillsActionAllowed(opts) {
         return false;
     return true;
 }
-/**
- * #184 — the "install on login, and only there" half of the never-installed
- * bootstrap (see the module doc comment on `autoUpdateInstalledSkills`
- * above for the "elsewhere: suggest, never install" half, which lives in
- * lib/skillsNudge.ts instead). `autoUpdateInstalledSkills` deliberately
- * never installs (`if (!isSkillInstalled) continue`) — it only keeps an
- * EXISTING install in sync. A user who has never run any `trawl skills`
- * command and never logged in before this shipped has nothing installed at
- * all, and nothing in the CLI's startup path ever puts anything there: the
- * CLI is competent, the agent reading its skills is not — the incident this
- * issue exists to prevent. `login` is the one intentional human setup
- * moment (the only place a human types credentials), so it is the ONLY
- * place this function is ever called from (see commands/login.ts) — never
- * from the generic startup path.
- *
- * Gated by `isSkillsActionAllowed` exactly like every other skills-related
- * side effect: a non-interactive `trawl login` (CI's `TRAWL_TOKEN=x trawl
- * login --json`, or any non-TTY invocation) writes nothing — that machine
- * has no Claude Code session to discover a skill in, and `--json`'s stdout
- * contract has no room for a plain-text confirmation line anyway. Also
- * skipped entirely under `TRAWL_SKILLS_SYNC=0`.
- *
- * Installs every bundled skill NOT YET OWNED by trawl at `scope` (default
- * 'user' — the global location a fresh `npx @trawlme/cli login` writes to;
- * 'local' is opt-in via the same --local convention `trawl skills install`
- * already uses everywhere else, kept for parity/tests). "Owned" means a
- * readable `.version` marker (#184 review MAJOR — NOT mere path existence:
- * see below for why that distinction matters here). One skill's install
- * throwing must never blank out the others (#91's posture, applied here):
- * each is wrapped individually, and the function reports exactly what
- * landed. Returns `null` (nothing written, nothing to report) ONLY when
- * gated out, or when every bundled skill is already owned (the re-sync
- * loop above already keeps an existing install's version current) — the
- * genuine "nothing to do" case. Never throws — a broken bootstrap must
- * never turn a successful login into a failed one.
- *
- * #184 review (BLOCK + MAJOR) — two cases used to collapse into the exact
- * same `null`/silence as genuine "nothing to do":
- *
- *  1. (BLOCK) Every install attempt failing outright (an unwritable
- *     `~/.claude/skills`, e.g.) used to return `null` — indistinguishable
- *     from "already installed" or "never attempted at all" on a first-run
- *     machine, the precise false-success shape #184 exists to prevent.
- *  2. (MAJOR) A bundled skill name colliding with a PRE-EXISTING,
- *     marker-less directory the CLI doesn't own. The action set here used
- *     to be computed from `isSkillInstalled` (mere `existsSync`), which
- *     can't tell "we already installed this" from "something else already
- *     lives at this path" — a foreign dir was silently read as "already
- *     installed, nothing to do", so `installSkill`'s ownership-refusal
- *     guard was never even reached and the collision went unreported
- *     anywhere. The action set below is computed from *ownership*
- *     (`getInstalledVersion(...) !== null`) instead, so a foreign
- *     collision is genuinely attempted — hits the same guard `installSkill`
- *     already enforces elsewhere, throws, and is captured below — rather
- *     than silently skipped as if it were a prior trawl install.
- *
- * Whenever there was anything to attempt, the result is now ALWAYS a
- * non-null object reporting both what landed (`installed`) and what didn't
- * (`skipped`, each with a RELAYABLE reason — see `SkillOwnershipRefusalError`
- * above: the ownership-refusal case reports `.relayableReason` [fact only,
- * no `--force` imperative], every other throw [skill-not-found, raw fs
- * errors like EACCES] reports `.message` as before, since those were never
- * imperative to begin with), so `login.ts` can print an honest, distinct
- * line for a skip instead of falling through to the generic "not installed"
- * nudge as if login had done nothing, or silently omitting a name from the
- * success line as if it had never been requested.
- *
- * #184 defect 2 — `error` (present whenever the function returns non-null)
- * distinguishes a THIRD case from both "nothing to do" (`null`) and "one or
- * more skills failed" (`skipped`): "could not even determine what to
- * install" — `listBundledSkills()` returning an empty list (its own
- * contract silently swallows a missing/renamed `skills/` dir into `[]`; see
- * its doc comment) or `getSkillsPackageRoot()` throwing outright (the
- * `@trawlme/skills` package itself unresolvable — a broken node_modules
- * entry). Both used to fall through to `notOwned.length === 0` or the outer
- * catch below, landing on the exact same `null` as a fully-up-to-date
- * install — a genuinely corrupted bundle produced ZERO signal, not even a
- * failed-attempt line, because nothing was ever attempted. `error` is
- * `null` on every ordinary path (including genuine "all already owned",
- * which still short-circuits to the `null` return below) and non-null only
- * for this diagnostic-failure case, where `installed`/`skipped` are both
- * empty because no skill name was ever known to attempt.
- */
 export function bootstrapSkillsOnLogin(opts = {}) {
     try {
         const optedOut = process.env['TRAWL_SKILLS_SYNC'] === '0';
@@ -359,9 +159,6 @@ export function bootstrapSkillsOnLogin(opts = {}) {
             bundled = listBundledSkills();
         }
         catch (err) {
-            // getSkillsPackageRoot() threw (require.resolve failed — the
-            // `@trawlme/skills` package itself isn't resolvable). Report as a
-            // diagnostic failure, not the outer catch's generic `null`.
             return {
                 installed: [],
                 skipped: [],
@@ -370,10 +167,6 @@ export function bootstrapSkillsOnLogin(opts = {}) {
             };
         }
         if (bundled.length === 0) {
-            // The package resolved but reports zero skills — in practice this
-            // package always ships at least one, so an empty list here is
-            // corruption (e.g. its `skills/` dir renamed/deleted underneath it),
-            // not a legitimate "nothing to do".
             return {
                 installed: [],
                 skipped: [],
@@ -386,9 +179,6 @@ export function bootstrapSkillsOnLogin(opts = {}) {
                 return getInstalledVersion(name, scope) === null;
             }
             catch {
-                // An unreadable `.version` (e.g. EISDIR) is no more proof of
-                // ownership than a missing one — treat it as actionable too, same
-                // as installSkill's own owned-check does (#91's posture).
                 return true;
             }
         });
@@ -402,11 +192,6 @@ export function bootstrapSkillsOnLogin(opts = {}) {
                 installed.push(name);
             }
             catch (err) {
-                // One bad skill (e.g. a marker-less foreign dir refusing overwrite,
-                // or an EACCES on an unwritable skills dir) must not blank the
-                // others — skip it, keep going, but never drop WHY silently: the
-                // caller needs this to tell "attempted and failed" apart from
-                // "nothing to do".
                 const reason = err instanceof SkillOwnershipRefusalError
                     ? err.relayableReason
                     : err instanceof Error

package/dist/lib/skillsNudge.d.ts

@@ -1,10 +1,5 @@
 export declare const SKILLS_NUDGE_TEXT = "Claude skills not installed \u2014 `trawl skills install` installs them (Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.)";
 export declare const AUTH_WALL_SKILLS_NUDGE_TEXT = "This looks like a login wall and Claude skills are not installed \u2014 `trawl skills install` installs the guidance for it too (Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.)";
-/**
- * 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 declare function isSkillsNudgeDue(opts: {
     json?: boolean;
     isTTY: boolean;
@@ -13,21 +8,9 @@ export declare function isSkillsNudgeDue(opts: {
     lastShownAt: number;
     now: number;
 }): boolean;
-/**
- * Best-effort generic nudge (#184 point 2) — called once per CLI invocation
- * from index.ts's runCli, on every command. Never throws.
- */
 export declare function maybeSuggestSkillsInstall(opts?: {
     json?: boolean;
 }): void;
-/**
- * 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 declare function maybeSuggestSkillsForAuthWall(opts?: {
     json?: boolean;
 }): void;

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

@@ -0,0 +1,55 @@
+export interface RawCdpCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    [key: string]: unknown;
+}
+export interface CookieData {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+}
+export interface RawOriginLocalStorage {
+    origin: string;
+    entries: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface OriginStorage {
+    origin: string;
+    localStorage: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface StorageState {
+    cookies: CookieData[];
+    origins: OriginStorage[];
+}
+export declare function getTargetHost(targetUrl: string): string;
+export declare function isCookieDomainInScope(rawDomain: string, targetHost: string): boolean;
+export declare function isOriginHostInScope(originHost: string, targetHost: string): boolean;
+export interface MapCookiesResult {
+    cookies: CookieData[];
+    totalSeen: number;
+    droppedOutOfScope: number;
+    droppedInvalid: number;
+}
+export declare function mapCookies(rawCookies: RawCdpCookie[], targetUrl: string): MapCookiesResult;
+export interface MapOriginsResult {
+    origins: OriginStorage[];
+    totalSeen: number;
+    droppedOutOfScope: number;
+}
+export declare function mapOrigins(rawOrigins: RawOriginLocalStorage[], targetUrl: string): MapOriginsResult;