@trawlme/cli 3.12.0 → 3.12.2

package/dist/index.js

@@ -24,30 +24,6 @@ import { getApiUrl } from './lib/config.js';
 import { resolveDocsUrls, docsFooterLine } from './lib/docs.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-/**
- * Derive a safe telemetry event name from a *resolved* commander Command —
- * NEVER from raw argv. Flag values (e.g. the string after --password/--email/
- * --url) don't start with '-' and would otherwise survive an argv filter and
- * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
- * (e.g. an error thrown before any action ran).
- *
- * #88 item 9 — walks the FULL parent chain, not just the immediate parent:
- * the old one-level join (`${parent.name()} ${own.name()}`) resolved a
- * 4-deep command like `scraps account session set` down to just "session
- * set", silently dropping "scraps account". The root program node (the
- * 'trawl' Command itself, which has no `.parent`) is excluded from the
- * chain — matching the pre-existing convention that a direct child of the
- * root (e.g. `scraps list`, `telemetry on`) is named relative to its
- * immediate group, never prefixed with the program name.
- *
- * #108 note: promoting a verb to a top-level command (see `createProgram`
- * below) renamed ITS resolved telemetry name from `scraps <verb>` to
- * `<verb>` — the canonical top-level attach and the legacy hidden
- * `scraps <verb>` attach are two separate Command instances (scraps.ts's
- * double-attach factories), each with its own parent chain, so they
- * resolve to two different names here even though they run the same
- * handler. Intentional (the canonical command IS now `<verb>`), not a bug.
- */
 export function resolveCommandName(actionCommand) {
     if (!actionCommand)
         return 'unknown';
@@ -57,16 +33,8 @@ export function resolveCommandName(actionCommand) {
         chain.unshift(current.name());
         current = current.parent;
     }
-    // `current` is now the root (no parent) — its name is excluded by design.
-    // If the chain came up empty, actionCommand itself IS the root (no parent
-    // at all) — fall back to its own name so the function never returns ''.
     return chain.length > 0 ? chain.join(' ') : actionCommand.name();
 }
-/**
- * Walk the full command tree and produce every valid resolveCommandName()
- * token — the allowlist registered with posthog.ts so captureCommand can
- * never be handed a free-form string.
- */
 export function collectCommandNames(root) {
     const names = [];
     const walk = (cmd) => {
@@ -78,16 +46,6 @@ export function collectCommandNames(root) {
     walk(root);
     return names;
 }
-/**
- * #108 — surface reorg into two `trawl --help` tiers. Core verbs are
- * agent+human, `--json` first-class, non-interactive; Management is the
- * existing human/CI surface, kept but grouped so top-level help reads
- * simple. Commander v14's native per-command help group (`.commandsGroup()`
- * sets the default a subsequently-registered command inherits via
- * `.helpGroup()`) drives the section headings — group ORDER in the printed
- * help follows first-seen insertion order into `program.commands`, so every
- * Core command is registered below before any Management one.
- */
 const CORE_GROUP = 'Core commands (agent + human):';
 const MANAGEMENT_GROUP = 'Management commands (human/CI):';
 export function createProgram() {
@@ -96,28 +54,6 @@ export function createProgram() {
         .description('Trawl CLI — manage scraps from the terminal')
         .version(pkg.version)
         .option('--debug', 'Show full error stack traces');
-    // Core verbs (#108) — promoted/listed first, registration order now
-    // follows the guided flow a new user (or agent) actually walks: create it
-    // → list/get to see it → run/trigger to execute it → data to read the
-    // result → history/run-info for deeper diagnostics → whoami/token/ping as
-    // standalone identity/credential/health utilities (#149 item 6 — the
-    // pre-#149 order had `run` wedged between `create` and `list`, and
-    // `trigger` stranded after `run-info`, both ahead of ever having listed or
-    // inspected anything). `list`/`get`/`run`/`data`/`history`/`run-info`/
-    // `trigger` are built via scraps.ts's exported attachXCommand() factories —
-    // the SAME definition also stays wired (hidden) under `scraps` there, so
-    // every pre-#108 `trawl scraps <verb>` invocation keeps resolving (no
-    // breaking change).
-    //
-    // #114 — `create` replaced `fetch` in this slot: `POST /api/ai/wizard`
-    // (AI-generate + persist + first-run + autofix), a distinct command from
-    // the still-untouched `trawl scraps create` (raw-script management verb).
-    //
-    // #149 item 5 — `token` promoted from Management into Core: it satisfies
-    // every criterion the CORE_GROUP heading itself claims (agent + human,
-    // `--json` first-class, never interactive) at least as well as `whoami`/
-    // `ping` do, and exists specifically to feed an agent's MCP Bearer auth
-    // header (`$(trawl token)`) — a Management/human-CI bucket undersells that.
     program.commandsGroup(CORE_GROUP);
     program.addCommand(create);
     attachListCommand(program);
@@ -130,13 +66,7 @@ export function createProgram() {
     program.addCommand(whoami);
     program.addCommand(token);
     program.addCommand(ping);
-    // #170 — `spec` last: it describes the whole tree above it, so it reads
-    // naturally as the final "and here's the full machine-readable map" entry
-    // rather than being wedged between identity/credential/health utilities.
     program.addCommand(spec);
-    // Management (#108) — human/CI surface, grouped below. `scraps` still
-    // holds every pre-#108 management command (create/update/delete/banner/
-    // watch/account.*/session.*/doctor/autofix/snapshot) exactly as before.
     program.commandsGroup(MANAGEMENT_GROUP);
     program.addCommand(scraps);
     program.addCommand(skills);
@@ -144,28 +74,9 @@ export function createProgram() {
     program.addCommand(logout);
     program.addCommand(telemetry);
     program.addCommand(upgrade);
-    // #185 — one dim line pointing at the docs, appended after EVERY `--help`
-    // in the tree (registering 'afterAll' on the root fires for a subcommand's
-    // own `--help` too — commander emits the afterAllHelp event on every
-    // ancestor of whichever command's outputHelp() ran, root included).
-    // Gated the way lib/tips.ts gates its own footer-shaped output: a pure,
-    // synchronous helper (docsFooterText, exported for unit testing) wrapped
-    // in try/catch so a broken footer can never turn a clean `--help` into a
-    // crash — but deliberately WITHOUT tips.ts's TTY/--json gate: `--help`
-    // itself never emits a --json payload (nothing here can pollute that
-    // channel), and a docs line inside `--help | less` is exactly the kind of
-    // thing worth keeping, unlike a promotional nudge.
     program.addHelpText('afterAll', docsFooterText);
     return program;
 }
-/**
- * #185 — see the `addHelpText('afterAll', …)` call above for why this is
- * unconditional (no TTY/--json gate) and why a thrown error must never
- * escape: commander calls this synchronously while already writing help
- * output, so a throw here would crash a `--help` invocation, the one code
- * path this whole feature is not allowed to touch (see docs.ts's own
- * `docsFooterLine` for the "never a guessed URL" contract this composes).
- */
 export function docsFooterText() {
     try {
         const line = docsFooterLine(resolveDocsUrls({ apiBaseUrl: getApiUrl() }).docsUrl);
@@ -175,18 +86,6 @@ export function docsFooterText() {
         return '';
     }
 }
-/**
- * True when this module is the process entrypoint (not merely imported by a test).
- *
- * npm installs the global bin as a SYMLINK (`bin/trawl` -> `dist/index.js`). For an
- * ESM entrypoint Node realpaths the module URL (`import.meta.url` = the real
- * `dist/index.js`) but leaves `process.argv[1]` as the symlink path — so a raw
- * `moduleUrl === pathToFileURL(argv1).href` compare is FALSE for the normal global
- * invocation, the guard never fires, and `runCli()` never runs (silent no-op, #103).
- * Canonicalise both sides with `realpathSync` before comparing. A genuine entrypoint
- * was just loaded by Node, so both realpath calls resolve; the catch only trips for a
- * non-file module URL (exotic loaders) — correctly "not the entrypoint".
- */
 export function isEntryPoint(argv1, moduleUrl) {
     if (argv1 === undefined)
         return false;
@@ -197,15 +96,6 @@ export function isEntryPoint(argv1, moduleUrl) {
         return false;
     }
 }
-/**
- * True when the invocation is a pure `--help`/`--version` query, a bare
- * `trawl` with no subcommand (commander prints top-level help and exits), or
- * `trawl help [command]`. None of these should trigger the skills auto-sync
- * (a filesystem-mutating startup side effect) — a user running `trawl
- * --version` (or just `trawl`) never expects it to rewrite their skills
- * dirs. (#73, extended #86 finding 7 for the bare-invocation + `help`
- * subcommand cases)
- */
 export function isHelpOrVersion(argv) {
     if (argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version'))
         return true;
@@ -216,76 +106,9 @@ export function isHelpOrVersion(argv) {
         return true;
     return false;
 }
-/**
- * True for a bare `trawl` invocation — no subcommand, no flags at all. This
- * is the CLI's "first thing a new user sees" moment (commander prints its
- * own top-level help right after), distinct from `isHelpOrVersion` which is
- * intentionally broader (also matches `--help`/`--version`/`trawl help`
- * anywhere in argv) — the Pinch wave banner (#94) only wants the narrowest
- * case so it never shows up ahead of e.g. `trawl scraps --help`.
- */
 export function isBareInvocation(argv) {
     return argv.slice(2).length === 0;
 }
-/**
- * True for `trawl spec` (with or without `--json`) — deliberately NOT folded
- * into `isHelpOrVersion` above: that predicate's name and doc comment are
- * about help/version queries specifically, and `spec` is a real, data-
- * bearing command (see `isHelpOrVersion`'s own #170 test case), not a help
- * query. This is its own narrow predicate for a DIFFERENT reason: `spec
- * --json` is documented (docs/agent-quickstart.md) as the first call an AI
- * agent makes against this CLI, so it must not mutate anything the caller
- * did not ask it to — same requirement `--help`/`--version` already got
- * from `isHelpOrVersion` (#73), extended here to cover `spec` too.
- *
- * Scope, stated honestly rather than aspirationally: this guard suppresses
- * the skills auto-sync (an `rmSync(recursive)` + `cpSync` over the user's
- * `~/.claude/skills`) and the update notifier (a config write plus a
- * DETACHED CHILD that queries the npm registry — fatal in an
- * egress-restricted sandbox). It does NOT suppress `initPostHog()`, which
- * still creates the `conf` config file and mints a persistent
- * `telemetryUserId` on first run, exactly as it does for every other
- * command. That one is deliberate: `spec` is the signal that tells us
- * whether agents are actually adopting the CLI, so it stays measured, and
- * the caller's own controls (`TRAWL_TELEMETRY=0`, `DO_NOT_TRACK=1`) are the
- * opt-out. That same first run also has `initPostHog()` write a one-time
- * telemetry disclosure line (`ℹ Trawl CLI collects anonymous usage
- * telemetry…`) to STDERR, ahead of the JSON payload — this guard does not
- * suppress that either. `stdout` stays pure JSON either way, so this only
- * bites a caller that merges the two streams (e.g. `2>&1`); whether a `spec`
- * probe specifically should suppress the notice is a product call,
- * deliberately not taken here. Do not upgrade this paragraph back to "no
- * filesystem side effect" without also gating telemetry — a comment that
- * overstates its own invariant is worse than no comment, because the next
- * reader trusts it.
- *
- * #185 — `spec --json` (not plain `spec`) now DOES make its own bounded
- * (2s), swallowed-on-failure GET for `externalDocs.url` (see spec.ts's
- * `fetchExternalDocsUrl`) — this is not a regression of the "no mutation"
- * invariant above (a GET mutates nothing, and any failure — including no
- * egress at all — degrades to the sync host-derivation fallback, never a
- * thrown error), just a second, narrower kind of side effect this guard was
- * never meant to suppress in the first place.
- *
- * Before this, `trawl spec --json` silently re-synced
- * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
- * skill …` lines to stderr BEFORE the JSON payload — an agent's very first
- * probe of the CLI mutated the user's filesystem and polluted the channel
- * it was about to parse.
- *
- * Matches `spec` as the FIRST positional token, skipping any leading
- * `-`-prefixed tokens first (a global flag ahead of the subcommand, e.g.
- * `trawl --debug spec --json`) — the same argv-scan discipline `hasJsonFlag`
- * below already applies. #170 review F4 — before this, a bare
- * `argv.slice(2)[0] === 'spec'` check was defeated by ANY leading flag:
- * `trawl --debug spec --json` read `--debug` as the first positional, missed
- * the match entirely, and fell through to the normal startup path — running
- * the filesystem-mutating skills auto-sync during what's documented
- * (docs/agent-quickstart.md) as an agent's read-only first probe of the CLI.
- * Still never a bare substring search: e.g. `trawl scraps create --title
- * spec` (the literal string "spec" as a FLAG VALUE, not a leading flag) never
- * matches, since `scraps` — the first non-`-`-prefixed token — isn't `spec`.
- */
 export function isSpecQuery(argv) {
     const args = argv.slice(2);
     let i = 0;
@@ -293,62 +116,16 @@ export function isSpecQuery(argv) {
         i++;
     return args[i] === 'spec';
 }
-/** Best-effort scan for a `--json` flag in raw argv, used only when parsing
- * itself failed before any command's own `.opts()` could be resolved (a
- * commander usage error — unknown option/command, missing required arg). Same
- * "argv scan, never trust flag values" caveat as isHelpOrVersion: positional
- * values are never mistaken for `--json` since they don't equal the literal
- * string. (#86 finding 3)
- *
- * #88 item 5 — only scans tokens BEFORE the first bare `--`. Commander treats
- * `--` as "end of options": everything after it is a positional operand, not
- * a flag, even if the literal text is `--json`. `scraps list -- --json`
- * passes `--json` as an (excess) positional argument, not the flag — an
- * unscoped `argv.includes('--json')` would still match it and wrongly emit a
- * JSON envelope for what is actually a plain usage error with no --json
- * requested at all.
- */
 export function hasJsonFlag(argv) {
     const dashDashIdx = argv.indexOf('--');
     const scanned = dashDashIdx === -1 ? argv : argv.slice(0, dashDashIdx);
     return scanned.includes('--json');
 }
-/**
- * Commander's default (no exitOverride) calls `process.exit()` directly for
- * a usage error (unknown option/command, missing required arg) or a
- * --help/--version/`help` query — bypassing runCli's try/catch/finally
- * entirely, so the telemetry shutdown() flush below never runs and a usage
- * error exits 1 (the generic bug bucket) instead of its own distinct code.
- * `program.exitOverride()` on the root command alone does NOT fix this for
- * subcommands added via `addCommand()` (login/scraps/skills/telemetry/token
- * are each built as standalone Command instances in their own module and
- * only ever copy inherited settings — including exitOverride — from a parent
- * at `.command()` construction time, which for these root-level modules never
- * happens). Every node in the tree needs its own exitOverride() call, so this
- * walks the whole tree and installs it everywhere. (#86 finding 3)
- */
 export function applyExitOverride(cmd) {
     cmd.exitOverride();
     for (const sub of cmd.commands)
         applyExitOverride(sub);
 }
-/**
- * #149 item 1 — commander's own usage-error line (unknown option, missing
- * required arg, unknown command, …) is written via `Command#error()` ->
- * `outputError()` straight to `process.stderr` BEFORE the exitOverride throw
- * below is ever caught — in commander's own plain, uncolored `"error: …"`
- * format, a visibly different convention from every other error this CLI
- * prints (`reportError`'s `chalk.red('✗ ' + message)`). `configureOutput`'s
- * `outputError` hook is exactly the one commander documents for reformatting
- * the error text itself (`writeErr` also carries unrelated help output, e.g.
- * `showHelpAfterError` — never enabled in this CLI, but out of scope to
- * touch here). Overriding it on every node in the tree (same walk shape as
- * applyExitOverride, for the same reason: addCommand()-attached subtrees
- * don't otherwise inherit a parent's configureOutput) reformats that one line
- * through the same red ✗ convention, stripping the redundant "error: " prefix
- * first (stripCommanderErrorPrefix — the same prefix also leaks verbatim
- * into the --json envelope's `message` field, see runCli's catch below).
- */
 export function applyOutputConfiguration(cmd) {
     cmd.configureOutput({
         outputError: (str, write) => {
@@ -359,27 +136,7 @@ export function applyOutputConfiguration(cmd) {
     for (const sub of cmd.commands)
         applyOutputConfiguration(sub);
 }
-/** Commander's own codes for a successful --help/--version/`help` query —
- * these already printed their own output (to stdout) via commander itself;
- * runCli's catch must treat them as a clean exit, not an error. (#86 finding 3) */
 const HELP_OR_VERSION_CODES = new Set(['commander.helpDisplayed', 'commander.help', 'commander.version']);
-/**
- * #88 item 6 — best-effort command-name recovery for a commander parse error
- * that happened BEFORE any action ran, so `currentCommand` (the preAction
- * hook's resolved command) is still undefined — e.g. an unknown option on an
- * otherwise-valid subcommand, or excess arguments. Without this, EVERY such
- * failure previously collapsed to resolveCommandName(undefined) === 'unknown'
- * — and since 'unknown' was never itself allowlisted at the
- * registerAllowedCommands call site (see runCli below), that capture was
- * silently dropped by captureCommand's allowlist check: a dead branch that
- * looked like it reported telemetry but never actually did.
- *
- * Matches ONLY a name already present in `allowedNames` (the real command
- * tree, from collectCommandNames) — never invents one from raw argv text.
- * Checks the two-token form first (`scraps boom`) since most usage errors
- * happen on a nested leaf command; falls back to the single top-level token,
- * then to 'unknown' (now itself allowlisted, so that capture fires too).
- */
 export function bestEffortCommandName(argv, allowedNames) {
     const a2 = argv[2];
     const a3 = argv[3];
@@ -395,31 +152,16 @@ export function bestEffortCommandName(argv, allowedNames) {
 export async function runCli(argv = process.argv) {
     if (!isHelpOrVersion(argv) && !isSpecQuery(argv))
         autoUpdateInstalledSkills();
-    // Pinch wave banner (#94) — bare `trawl` only, guarded so it never shows
-    // under NO_COLOR/non-TTY/piped output (pinchEnabled() covers all three).
     if (isBareInvocation(argv) && pinchEnabled()) {
         console.log(renderPinch('wave'));
         console.log();
     }
     initPostHog();
     const program = createProgram();
-    // Must run before parseAsync — installs on every node in the tree,
-    // including subcommands added via addCommand() that don't otherwise
-    // inherit it. (#86 finding 3)
     applyExitOverride(program);
-    // Same tree-walk requirement as applyExitOverride, same reason — installs
-    // the unified red ✗ error formatting on every node. (#149 item 1)
     applyOutputConfiguration(program);
     const commandNames = collectCommandNames(program);
-    // #88 item 6 — 'unknown' is a legitimate resolveCommandName() output (the
-    // fallback for "no command resolved at all"), not free-form user input —
-    // it must be explicitly allowlisted here or every capture that falls back
-    // to it is silently dropped by captureCommand's allowlist check (a dead
-    // branch that looks like it reports telemetry but never does).
     registerAllowedCommands([...commandNames, 'unknown']);
-    // Track start times + the currently-resolved command per instance, so the
-    // catch handler below can derive the exact same safe name the success path
-    // uses — it must never re-derive anything from argv.
     const startTimes = new WeakMap();
     let currentCommand;
     program.hook('preAction', (_thisCommand, actionCommand) => {
@@ -429,8 +171,6 @@ export async function runCli(argv = process.argv) {
     program.hook('postAction', (_thisCommand, actionCommand) => {
         const start = startTimes.get(actionCommand);
         if (start !== undefined) {
-            // Actions can fail without throwing (process.exitCode set directly) —
-            // report the real outcome instead of hardcoding success.
             const exitCode = typeof process.exitCode === 'number' ? process.exitCode : 0;
             void captureCommand(resolveCommandName(actionCommand), {
                 duration_ms: Date.now() - start,
@@ -439,22 +179,6 @@ export async function runCli(argv = process.argv) {
         }
     });
     try {
-        // #148 — a bare `trawl` (no args at all) reads as "let me look around",
-        // not a failure: it should behave exactly like `trawl --help` (same
-        // text, stdout, exit 0). Left to commander's own default, a program with
-        // subcommands and no root action handler treats zero args as "probably
-        // missing subcommand" and calls `this.help({ error: true })` internally
-        // (see node_modules/commander/lib/command.js `_parseCommand`) — which
-        // writes the SAME help text to stderr and throws a CommanderError with
-        // exitCode 1 (caught below, bucketed into HELP_OR_VERSION_CODES since its
-        // code is 'commander.help', so only the exit code carries the mistake
-        // through — text already went to the wrong stream by then). Intercepting
-        // here, before parseAsync ever runs, avoids fighting that internal
-        // decision entirely and can't affect a genuine unknown top-level command
-        // (`trawl frobnicate`) — that path only runs when `isBareInvocation` is
-        // false, so it still reaches `this.unknownCommand()` unchanged (stderr,
-        // exit 2, code 'commander.unknownCommand' — never in
-        // HELP_OR_VERSION_CODES).
         if (isBareInvocation(argv)) {
             program.outputHelp();
             process.exitCode = 0;
@@ -467,40 +191,13 @@ export async function runCli(argv = process.argv) {
         const { debug } = program.opts();
         const isDebug = Boolean(debug || process.env['DEBUG']);
         if (err instanceof CommanderError) {
-            // Commander's own parse-time errors (exitOverride, #86 finding 3) —
-            // a distinct family from our ApiError/NetworkError/UsageError/generic
-            // Error taxonomy, so classifyError/reportError don't apply here.
             if (HELP_OR_VERSION_CODES.has(err.code)) {
-                // --help / --version / `trawl help` already printed their own
-                // output via commander itself — nothing else to print, just adopt
-                // commander's suggested exit code (0) and fall through to the
-                // shared shutdown() flush below.
                 process.exitCode = err.exitCode;
             }
             else {
-                // A usage error (unknown option/command, missing required arg, …) —
-                // commander already wrote its own human-readable line to stderr via
-                // Command#error() (now reformatted through the same red ✗ convention
-                // by applyOutputConfiguration, #149 item 1), so this never duplicates
-                // it. Force exit code 2 (usage) regardless of whichever code
-                // commander suggests (it defaults these to 1), and add the --json
-                // machine envelope when resolvable — parsing failed before any
-                // command's own --json flag could be read off `currentCommand`
-                // (preAction never fired), so scan raw argv instead. (#86 finding 3)
                 if (isDebug)
                     console.error(err);
                 if (hasJsonFlag(argv)) {
-                    // #149 item 2 — err.message still carries commander's own literal
-                    // "error: " prefix (set on the CommanderError itself, independent
-                    // of the outputError override above, which only reformats what
-                    // gets WRITTEN to stderr) — strip it so the envelope's `message`
-                    // stays clean for a machine parser.
-                    //
-                    // #170 review F3 — typed as ErrorEnvelope (not a bare object
-                    // literal) so the compiler enforces `retryable` being non-optional
-                    // here too. Mutation-proven: `tsc --noEmit` stayed at exit 0 with
-                    // `...retryFieldsFor('usage')` removed entirely before this
-                    // annotation existed.
                     const envelope = {
                         message: stripCommanderErrorPrefix(err.message),
                         kind: 'usage',
@@ -509,11 +206,6 @@ export async function runCli(argv = process.argv) {
                     console.log(JSON.stringify({ error: envelope }));
                 }
                 process.exitCode = 2;
-                // #88 item 6 — currentCommand is still undefined here whenever the
-                // parse error happened before preAction fired (the common case for a
-                // usage error — commander validates flags/arity before invoking the
-                // action). Try a best-effort match against the real command tree
-                // instead of collapsing straight to 'unknown'.
                 const commandName = currentCommand
                     ? resolveCommandName(currentCommand)
                     : bestEffortCommandName(argv, commandNames);
@@ -521,73 +213,33 @@ export async function runCli(argv = process.argv) {
             }
         }
         else {
-            // Map the error to a distinct exit code + machine envelope instead of a
-            // uniform 1 — agents driving this CLI unattended need to tell
-            // auth-expired (3) from not-found (4) from network-down (5) from a bad
-            // flag (2) apart from an arbitrary bug (1). (#71)
             const { exitCode } = classifyError(err);
-            // Capture error telemetry from the resolved command only — never argv.
             void captureCommand(resolveCommandName(currentCommand), {
                 exit_code: exitCode,
                 error: err.name,
             });
-            // A --json subcommand must keep stdout pure JSON even on failure — read
-            // the resolved command's own --json flag (never argv) so the error
-            // envelope lands on the same channel the success path would have used.
             const wantsJson = Boolean(currentCommand?.opts()?.json);
             if (isDebug)
                 console.error(err);
-            // reportError is the single formatting path (#86 finding 9) — prints
-            // EITHER the --json envelope (stdout) OR the human "✗ message" line
-            // (stderr), never both; `quiet` skips the human line when the raw
-            // stack was already dumped above under --debug.
             process.exitCode = reportError(err, { json: wantsJson, quiet: isDebug });
-            // Pinch confused frame (#94) — never under --json (stdout must stay
-            // pure JSON) and guarded by pinchEnabled() (NO_COLOR/non-TTY/piped).
-            // Printed to stderr, alongside reportError's own human line above.
             if (!wantsJson && pinchEnabled()) {
                 console.error(renderPinch('confused'));
             }
         }
     }
     finally {
-        // Flush + close telemetry before the process exits. A `process.on('exit')`
-        // handler cannot reliably run async work, so this must happen here.
         await shutdown();
-        // Passive "update available" notifier (#129) — never on a help/version
-        // query, and each half individually guarded so a notifier bug can never
-        // turn a successful command into a failure or change its exit code.
-        // #170 review F5 — never on a `spec` query either: `maybeNotifyUpdate`/
-        // `scheduleUpdateCheck` write to disk (`Library/Preferences/…/config.json`,
-        // `update-check.json`) and the latter spawns a DETACHED child that queries
-        // the npm registry — real filesystem + network side effects `isSpecQuery`'s
-        // own doc comment already promises `spec --json` never has. Before this,
-        // `spec`'s only protection was skipping the skills auto-sync above; this
-        // finally block ran unconditionally regardless.
         if (!isHelpOrVersion(argv) && !isSpecQuery(argv)) {
             try {
                 maybeNotifyUpdate();
             }
             catch {
-                // swallow — see updateNotifier.ts, this is already self-guarded too.
             }
             try {
                 scheduleUpdateCheck();
             }
             catch {
-                // swallow — background refresh must never affect this invocation.
             }
-            // #184 — "elsewhere: suggest, never install" half of the skills
-            // bootstrap story (lib/skills.ts's bootstrapSkillsOnLogin is the
-            // "install on login" half). Only on a clean exit — mirrors the
-            // referral tip's own success-only precedent (lib/tips.ts, called only
-            // after a run genuinely succeeds) and sidesteps a whole class of
-            // parse-error edge cases where `currentCommand` never resolved (so
-            // its own `--json` flag can't be read reliably here either). Running
-            // AFTER the command completed also means a `login` that just
-            // bootstrapped is already reflected in this nudge's own "any skill
-            // installed?" read — no separate command-name exclusion needed, and
-            // no double-message risk with the line `login` may have just printed.
             if (process.exitCode === undefined || process.exitCode === 0) {
                 try {
                     maybeSuggestSkillsInstall({
@@ -595,7 +247,6 @@ export async function runCli(argv = process.argv) {
                     });
                 }
                 catch {
-                    // swallow — see skillsNudge.ts, this is already self-guarded too.
                 }
             }
         }

package/dist/lib/api.d.ts

@@ -1,102 +1,24 @@
 export declare class ApiError extends Error {
     status: number;
     next?: string[] | undefined;
-    /**
-     * `next` is an OPTIONAL per-instance override of the envelope's default
-     * `next` steps (errors.ts's frozen `RETRY_POLICY`) — set only at the two
-     * apiKey-mode 401 call sites below (via authNextSteps()), where the
-     * generic "trawl login --token <jwt>" default is inert until a live
-     * TRAWL_API_KEY/TRAWL_TOKEN is unset first (#169 review). Absent for every
-     * other error, so classifyError falls back to the frozen default exactly
-     * as before.
-     */
     constructor(status: number, message: string, next?: string[] | undefined);
 }
-/**
- * A fetch-level failure — the request never got a response at all (DNS,
- * connection refused, timeout, TLS, …). Distinguished from ApiError (which
- * always carries a real HTTP status) so the top-level handler can map it to
- * its own exit code instead of the generic uniform 1. (#71 findings 4/58)
- */
 export declare class NetworkError extends Error {
     constructor(message: string);
 }
-/**
- * A LOCAL auth failure — no token available, or a locally-decoded token
- * that's provably expired, discovered entirely client-side before any HTTP
- * call was ever made. Distinguished from ApiError(401) (a real server-issued
- * 401 response) so the --json envelope never claims `status:401` for
- * something the server never said — that would be a fabricated fact,
- * indistinguishable from an actual server round-trip to a machine consumer.
- * Both classify to the same exit code (3) / kind "auth" in classifyError
- * (errors.ts); only the envelope's `status` field differs (present for
- * ApiError, absent here). (#88 item 4)
- */
 export declare class AuthError extends Error {
     next?: string[] | undefined;
-    /** See ApiError's `next` for what this overrides and why. */
     constructor(message: string, next?: string[] | undefined);
 }
-/**
- * The single "no token available" error — every call site in this file that
- * needs a token (request/upload/getText/stream) used to throw its own copy
- * of `new Error('Not logged in. Run: trawl login')`, which fell through
- * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
- * from an arbitrary bug. Auth-classifying it puts it on the exact same
- * exit-3 / kind:"auth" path a real 401 response already takes — but as an
- * AuthError (no HTTP call happened here), never a fabricated ApiError(401).
- * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
- * the same thing everywhere it can be observed. (#86 findings 1/2, #88 item 4)
- */
 export declare function notLoggedInError(): AuthError;
-/**
- * The "this route is JWT-only" error — thrown client-side, before any HTTP
- * call, by a command that only works with a session JWT (today: `whoami`,
- * see its own doc comment for why `GET /api/users/me` was descoped rather
- * than relocated) when the resolved credential is a scoped API key instead.
- * Distinct from notLoggedInError(): there IS a credential here, it's just
- * the wrong shape for this one route. Left unhandled, that route would 401
- * and surface the generic `notLoggedInError`-adjacent message ("Session
- * expired or invalid. Run: trawl login") — wrong twice over under a key: the
- * route never accepts keys at all (no session ever "expired"), and
- * re-running `trawl login` genuinely IS the fix here, just not because
- * anything expired. Classifies to the SAME exit 3 / kind:"auth" as every
- * other auth failure (#169) — reusing the existing `auth` kind rather than
- * minting a new one, since the taxonomy question is still "not
- * authenticated the way this route needs," never a new category.
- *
- * Always called already knowing authMode is 'apiKey' (see whoami.ts) — the
- * message and `next` both route through loginRemedyText()/authNextSteps()
- * so this never emits the same inert "Run: trawl login" that finding 2
- * corrects everywhere else. (#169 review round 2 — finding 2)
- */
 export declare function apiKeyUnsupportedError(command: string): AuthError;
-/**
- * #91 P0 — some endpoints legitimately run 30–250s server-side: a scrap
- * execute (worker-puppeteer navigation + antibot tier escalation + AI-fix
- * dry-run retries). The generic 30s default was aborting those mid-flight
- * and surfacing a fabricated `NetworkError timed out` (exit 5) for a request
- * that was always going to succeed given enough time. Passed as the per-call
- * `{timeoutMs}` override at exactly the 4 call sites that hit those
- * endpoints: `scraps run` / `data --fresh` (GET /api/scraps/load/:id) and
- * `scraps trigger --wait` (POST /api/scraps/worker/:id, synchronous branch
- * only — the default async `?wait=false` POST returns almost immediately and
- * keeps the 30s default) — all three in src/commands/scraps.ts — plus (#114)
- * `create` (POST /api/ai/wizard, src/commands/create.ts), whose AI-generation
- * + scrap creation + first run + autofix pipeline runs the same 30–250s+
- * server-side. 300s leaves margin over the ~250s worst case without being
- * unboundedly long.
- */
 export declare const LONG_RUN_TIMEOUT_MS = 300000;
 export interface RequestOptions {
-    /** Per-call timeout override in ms (e.g. LONG_RUN_TIMEOUT_MS). Ignored — env wins — when TRAWL_TIMEOUT is set; see getTimeoutMs. */
     timeoutMs?: number;
 }
 export declare const api: {
     get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
     publicGet: <T>(path: string, opts?: RequestOptions) => Promise<T>;
-    /** 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: <T>(path: string, opts: {
         timeoutMs: number;
     }) => Promise<T | null>;