@trawlme/cli 3.11.0 → 3.12.1

package/dist/commands/skills.js

@@ -11,8 +11,6 @@ function pickSkills(arg) {
     if (!arg || arg === 'all')
         return all;
     if (!all.includes(arg)) {
-        // Usage error (exit 2), not a generic bug (exit 1) — the caller typed a
-        // skill name that doesn't exist. (#86 finding 3)
         throw new UsageError(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
     }
     return [arg];
@@ -39,19 +37,6 @@ skills
     for (const name of bundled) {
         const userInstalled = isSkillInstalled(name, 'user');
         const localInstalled = isSkillInstalled(name, 'local');
-        // #91 — same EISDIR class as autoUpdateInstalledSkills/installSkill: an
-        // unreadable `.version` marker on one skill must not crash the whole
-        // listing before the other skills are shown.
-        //
-        // #93 item 3 — the two scope reads must be guarded INDEPENDENTLY. A
-        // single try/catch wrapped around `getInstalledVersion(name, 'user') ??
-        // getInstalledVersion(name, 'local')` still throws the whole expression
-        // the moment the 'user' read throws (e.g. a corrupt/EISDIR `.version`
-        // marker) — `??` never gets a chance to evaluate the 'local' fallback,
-        // so a healthy local install gets masked as "not installed" too. Every
-        // other marker read in this codebase (installSkill, removeOrphanedSkills,
-        // autoUpdateInstalledSkills — all in lib/skills.ts) already guards each
-        // scope on its own; this was the one chained exception.
         let installedVersion;
         try {
             installedVersion = getInstalledVersion(name, 'user');
@@ -155,13 +140,6 @@ skills
         }
         console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
     }
-    // #86 review — same orphan sweep as the startup auto-sync: an explicit
-    // `skills update` must also drop CLI-owned dirs whose skill was renamed
-    // or removed upstream (e.g. 1.0.0's `trawl` → 1.3.1's `trawl-cli`),
-    // instead of leaving a stale ghost teaching outdated usage. Only the
-    // scope being updated is swept; marker-less dirs are never touched.
-    // removeOrphanedSkills prints its own honest stderr line per removal
-    // (stderr, so it's safe under --json too).
     const orphansRemoved = removeOrphanedSkills(scope);
     if (opts.json)
         json({ updated: results, orphansRemoved });

package/dist/commands/spec.d.ts

@@ -1,14 +1,5 @@
 import { Command } from 'commander';
 import { type DocsUrls } from '../lib/docs.js';
-/**
- * `trawl spec --json` (#170) — a versioned, machine-readable description of
- * the command tree, so an agent can learn the CLI's surface without parsing
- * ~250 lines of README prose. Everything below is DERIVED at runtime from
- * the live commander `Command` tree (`buildSpec`) — never a hand-maintained
- * file, which would be a second source of truth that silently drifts. See
- * `tests/contracts/` for the README-vs-spec cross-check that exists
- * specifically to catch that drift.
- */
 export interface CliSpecArgument {
     name: string;
     required: boolean;
@@ -18,106 +9,30 @@ export interface CliSpecOption {
     long: string;
     short?: string;
     description: string;
-    /**
-     * commander's `Option#required`/`Option#mandatory` are a false-friend pair
-     * that an earlier draft of this file collapsed into one `required` key —
-     * DON'T "simplify" it back. `Option#required` means "if this option is
-     * used, a value must follow" (true for any `<value>` flag, e.g. `--limit
-     * <n>`, whether or not the option itself is optional to pass). `mandatory`
-     * means "the user MUST pass this option at all" (only true for
-     * `.requiredOption()`). Naming the value-arity field `required` (as this
-     * did before) reads as "you must specify this option" — wrong for ~30 of
-     * the ~34 options that tripped it. See commander's option.js:15/19.
-     */
     mandatory: boolean;
     valueRequired: boolean;
     negatable: boolean;
     default?: unknown;
 }
 export interface CliSpecCommand {
-    /** Full path from the program root, e.g. "scraps account session set". */
     name: string;
     description: string;
     hidden: boolean;
-    /**
-     * True when this node has no subcommands of its own — i.e. it is an
-     * executable leaf (`.action()` actually runs something), not a pure
-     * namespace/group node like `scraps`/`skills`/`telemetry`/`scraps account`.
-     * An agent that emits one tool per spec entry needs this to skip group
-     * nodes: invoking one directly (e.g. `trawl scraps`) exits non-zero with
-     * usage text on stderr and ZERO bytes on stdout — a guaranteed-failing
-     * tool, not a --json envelope. Derived the same way
-     * `tests/contracts/readme-commands.test.ts` independently re-derives it
-     * (its own `leafNames()` walk existed ONLY because this field didn't) —
-     * that test now consumes THIS field instead of re-walking the tree itself.
-     */
     leaf: boolean;
     aliases: string[];
     arguments: CliSpecArgument[];
     options: CliSpecOption[];
-    /**
-     * #185 — a deep link into a specific guide when one is mapped for this
-     * command (docs.ts's `COMMAND_DOC_PATHS`, e.g. every `scraps account *`
-     * command -> the account-sessions guide). Omitted (never a guessed/generic
-     * link) whenever no guide is mapped, the top-level `docsUrl` itself
-     * couldn't be resolved, OR `docsUrl` resolved from rung 1 (a server-
-     * declared `externalDocs.url`) rather than rung 2 (this CLI's own known-host
-     * derivation) — appending our guide slug onto a third party's own docs root
-     * is exactly the confidently-wrong-404 defect this omission closes. See
-     * `resolveCommandDocsUrl` / `DocsUrls.docsUrlIsDerived`.
-     */
     docs?: string;
 }
 export interface CliSpec {
     specVersion: 1;
     cliVersion: string;
     commands: CliSpecCommand[];
-    /** "0".."5" → a short kind label. Same constant `classifyError` reads
-     *  (errors.ts's EXIT_CODE_LABELS) — never a second copy. Code `1` is a
-     *  SHARED bucket (several `kind`s land there, see `kindExitCodes` below
-     *  for the honest reverse mapping) — this label names the generic/unmapped
-     *  case, not an exhaustive claim that `1` means only that. */
     exitCodes: Record<string, string>;
-    /** Every `kind` a --json error envelope can carry — the classifyError
-     *  kinds PLUS the hand-built ones (`in_progress`/`run_failed`/
-     *  `upgrade_failed`). Same constant (errors.ts's ENVELOPE_KINDS) — never a
-     *  second copy, and never `ERROR_KINDS` (that one omits the hand-built
-     *  kinds by design — see its doc comment). */
     errorKinds: string[];
-    /**
-     * #170 review F7 — the inverse of `exitCodes`: `kind -> exitCode`, one
-     * entry per `errorKinds` member. `exitCodes` alone can't tell an agent
-     * which of the several kinds sharing code `1` (`api`/`refused`/`unknown`/
-     * `in_progress`/`run_failed`/`upgrade_failed`) it actually got — this
-     * field answers that directly instead of requiring the reverse lookup to
-     * be reconstructed by hand. Same source constant as `errorKinds`
-     * (errors.ts's KIND_EXIT_CODES) — never a second copy.
-     */
     kindExitCodes: Record<string, number>;
-    /**
-     * #185 — where the human-readable guides live, resolved via docs.ts's
-     * ladder (server `externalDocs.url` > derive from the API base's known
-     * `trawl.me` host > omit). Absent (never a guessed URL) when neither rung
-     * resolves — e.g. a self-hosted install with no `externalDocs` declared.
-     */
     docsUrl?: string;
-    /** #185 — the llms.txt entry point alongside `docsUrl`, when resolvable.
-     *  See docs.ts's module doc comment for why this never rides along with a
-     *  server-declared `docsUrl` it wasn't itself derived from. */
     llmsUrl?: string;
 }
-/**
- * Build the full spec from a live, already-constructed program (e.g.
- * `createProgram()`'s return value). Includes every node in the tree —
- * hidden legacy aliases (`scraps list`, …) included, flagged via `hidden`,
- * so a consumer that wants only the advertised surface can filter on it.
- *
- * #185 — `docs` is an already-RESOLVED `DocsUrls` (docs.ts's ladder run to
- * completion), never computed in here: `buildSpec` stays pure/synchronous
- * (no network, no config read) exactly as before, so every existing caller
- * (the README-vs-spec contract test, the synthetic-tree unit tests) keeps
- * working unchanged by simply omitting the parameter. Only `spec.ts`'s own
- * action resolves rung 1 (a bounded fetch) before calling this.
- */
 export declare function buildSpec(program: Command, docs?: DocsUrls): CliSpec;
 export declare const spec: Command;

package/dist/commands/spec.js

@@ -37,18 +37,6 @@ function buildCommandEntry(cmd, name, hidden, docs = {}) {
         entry.docs = docsLink;
     return entry;
 }
-/**
- * Walk `cmd.commands` recursively, collecting one entry per node under its
- * FULL path name. `hidden` is read via commander's own
- * `Help#visibleCommands()` — the same idiom this codebase already uses
- * (scraps.test.ts's #108 describe block) — rather than reaching for the
- * private, untyped `_hidden` field directly. The resolved `docs` object,
- * when present, threads through so every entry can carry its own per-command
- * `docs` deep link (#185) off the SAME resolved root — never a second lookup
- * per node, and never flattened to a bare string (see docs.ts's
- * `DocsUrls.docsUrlIsDerived` — the rung provenance must survive the walk
- * unchanged so `resolveCommandDocsUrl` can still gate on it at each leaf).
- */
 function walk(cmd, prefix, out, docs = {}) {
     const visible = new Set(new Help().visibleCommands(cmd));
     for (const sub of cmd.commands) {
@@ -57,19 +45,6 @@ function walk(cmd, prefix, out, docs = {}) {
         walk(sub, name, out, docs);
     }
 }
-/**
- * Build the full spec from a live, already-constructed program (e.g.
- * `createProgram()`'s return value). Includes every node in the tree —
- * hidden legacy aliases (`scraps list`, …) included, flagged via `hidden`,
- * so a consumer that wants only the advertised surface can filter on it.
- *
- * #185 — `docs` is an already-RESOLVED `DocsUrls` (docs.ts's ladder run to
- * completion), never computed in here: `buildSpec` stays pure/synchronous
- * (no network, no config read) exactly as before, so every existing caller
- * (the README-vs-spec contract test, the synthetic-tree unit tests) keeps
- * working unchanged by simply omitting the parameter. Only `spec.ts`'s own
- * action resolves rung 1 (a bounded fetch) before calling this.
- */
 export function buildSpec(program, docs = {}) {
     const commands = [];
     walk(program, '', commands, docs);
@@ -87,40 +62,7 @@ export function buildSpec(program, docs = {}) {
         spec.llmsUrl = docs.llmsUrl;
     return spec;
 }
-/**
- * #185 — bounds the SOCKET, not just the promise, so a slow/dead server can
- * never perceptibly slow `spec --json` down. Mirrors lib/tips.ts's
- * FLAG_CHECK_TIMEOUT_MS for the same reason: this is the one surface allowed
- * a network call at all, and only because it's a deliberate, once-per-
- * invocation agent probe.
- *
- * This is a REAL wall-clock ceiling, not merely a promise-level one: an
- * earlier version of this fetch used `api.publicGet` (Node's global
- * `fetch()` + `AbortSignal.timeout()`), which bounds the promise but not the
- * OS-level connection — against a routable-but-silently-dropping host (a
- * dropped SYN, no RST; a realistic firewalled/air-gapped shape, the very
- * audience this feature cites) the promise rejected at ~2005ms while the
- * PROCESS didn't exit until ~10.5s later, waiting out Node's own internal
- * connect-timeout. `api.probeJson` (see its own doc comment in lib/api.ts)
- * fixes this by managing the raw socket directly — an independent timer
- * that `req.destroy()`s the connection, never relying on the idle-based
- * `http.request` `timeout` option. Re-measured after the fix, same
- * black-holed host, via the exact repro command (`time env
- * TRAWL_API_URL=https://192.0.2.1 node dist/index.js spec --json`): total
- * process time ~2.43s/~2.47s across two runs (the 2000ms bound plus Node
- * startup and spec-tree construction), not ~10.68s.
- */
 const EXTERNAL_DOCS_FETCH_TIMEOUT_MS = 2_000;
-/**
- * Rung 1 — read `externalDocs.url` off the OpenAPI document the configured
- * API base itself serves at `/api/spec.json`. Unset (null) server-side
- * today, so this resolves to `null` in practice; forward-looking for when
- * it isn't. ANY failure — network error, timeout, a malformed/unexpected
- * response shape — is indistinguishable from "not declared" here: resolves
- * to `null`, never throws (api.probeJson's own contract — see its doc
- * comment). `spec --json` must stay a pure, reliable, side-effect-free probe
- * even against an unreachable or ancient server.
- */
 async function fetchExternalDocsUrl() {
     const data = await api.probeJson('/api/spec.json', {
         timeoutMs: EXTERNAL_DOCS_FETCH_TIMEOUT_MS,
@@ -132,17 +74,8 @@ export const spec = new Command('spec')
     .description('Print a versioned, machine-readable description of the command tree')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // `spec` is registered as a direct child of the program root
-    // (index.ts's createProgram), so `.parent` IS that root by the time this
-    // action ever runs — commander sets it in `addCommand()`. Falling back
-    // to `spec` itself only matters for an isolated unit invocation (e.g. a
-    // test driving `spec.parseAsync()` directly, unattached to a program).
     const root = spec.parent ?? spec;
     const apiBaseUrl = getApiUrl();
-    // #185 — rung 1 (the server fetch) only runs under --json: the
-    // plain-text branch below never reads docsUrl at all, so paying a
-    // network round-trip for it would be pure waste. Rungs 2/3 (sync,
-    // no network) still apply either way via the fallback below.
     const externalDocsUrl = opts.json ? await fetchExternalDocsUrl() : null;
     const docs = resolveDocsUrls({ apiBaseUrl, externalDocsUrl });
     const cliSpec = buildSpec(root, docs);

package/dist/commands/telemetry.js

@@ -10,7 +10,6 @@ telemetry
     .option('--json', 'Output as JSON')
     .action((opts) => {
     config.set('telemetry', true);
-    // Ensure a telemetryUserId is created on opt-in
     initPostHog();
     if (opts.json) {
         json({ telemetry: true });
@@ -41,9 +40,6 @@ telemetry
     const userId = config.get('telemetryUserId') || '(not yet generated)';
     const envOverride = process.env['TRAWL_TELEMETRY'] === '0';
     const doNotTrack = process.env['DO_NOT_TRACK'] === '1';
-    // The effective on/off state factoring in both env overrides — matches
-    // the human-mode "State:" line's own precedence (DO_NOT_TRACK >
-    // TRAWL_TELEMETRY > config).
     const effectiveEnabled = enabled && !envOverride && !doNotTrack;
     if (opts.json) {
         json({ enabled: effectiveEnabled, configEnabled: enabled, telemetryUserId: config.get('telemetryUserId') || null, envOverride, doNotTrack });

package/dist/commands/token.js

@@ -9,35 +9,16 @@ export const token = new Command('token')
     .description('Print the stored credential — a scoped API key or a session JWT (for MCP Bearer auth)')
     .option('--json', 'Output as JSON ({token, exp, expiresAt, mode}) instead of the raw credential')
     .action((opts) => {
-    // getToken() resolves TRAWL_API_KEY env first, then TRAWL_TOKEN env, then
-    // the stored config token (see config.ts) — matching every other token
-    // consumer in the CLI instead of reading the config store directly. (#86
-    // finding 1, #169)
     const stored = getToken();
     if (!stored) {
-        // Auth-classified (ApiError 401 → exit 3, kind:"auth"), not a generic
-        // exit 1 — an agent scripting `trawl token` needs to tell "not logged
-        // in" apart from an arbitrary bug. (#86 finding 1)
         process.exitCode = reportError(notLoggedInError(), { json: opts.json });
         return;
     }
-    // #169 review finding 2 — a scoped API key is not a JWT: it has no `exp`
-    // claim to decode (decodeExp() would return null for one anyway, since
-    // it isn't dot-segmented), and unlike a session JWT it does NOT expire
-    // on its own — it stays live until revoked in the dashboard. Branching
-    // on getAuthMode() explicitly (rather than silently relying on
-    // decodeExp()'s null-for-non-JWT behaviour) means the distinct advisory
-    // below is a deliberate case, not an accident of what decodeExp() happens
-    // to return — and it replaces the old "(could not decode expiry — verify
-    // the token manually)" fallback, which was written for a malformed JWT
-    // and, read against a key, wrongly implied something was wrong with it.
     if (getAuthMode(stored) === 'apiKey') {
         if (opts.json) {
             json({ token: stored, exp: null, expiresAt: null, mode: 'apiKey' });
             return;
         }
-        // Print the raw key first (so it can be piped / copied) — same
-        // stdout-only-the-credential contract `$(trawl token)` relies on.
         console.log(stored);
         console.error(chalk.dim('  This is a scoped API key (trawl_*) — it does not expire on its own. Revoke it in the dashboard to end its access.'));
         return;
@@ -45,9 +26,6 @@ export const token = new Command('token')
     const exp = decodeExp(stored);
     const nowSeconds = Math.floor(Date.now() / 1000);
     if (exp !== null && exp < nowSeconds) {
-        // Decoded entirely client-side (no HTTP call made) — AuthError, not a
-        // fabricated ApiError(401): the server never actually said this. (#88
-        // item 4)
         process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'), { json: opts.json });
         return;
     }
@@ -60,10 +38,8 @@ export const token = new Command('token')
         });
         return;
     }
-    // Print the raw token first (so it can be piped / copied)
     console.log(stored);
     if (exp === null) {
-        // Could not decode expiry (malformed/opaque JWT) — advisory only, do not block piping
         console.error(chalk.dim('  (could not decode expiry — verify the token manually)'));
     }
     else {
@@ -71,10 +47,6 @@ export const token = new Command('token')
         const daysLeft = secsLeft / 86400;
         if (daysLeft < 1) {
             const hoursLeft = Math.floor(secsLeft / 3600);
-            // stderr, not stdout — this is an advisory, not the payload. `trawl
-            // token` exists so callers can capture the raw JWT via
-            // `$(trawl token)` for `Authorization: Bearer …`; anything printed
-            // to stdout after the token corrupts that capture. (#68)
             console.error(chalk.yellow(`⚠ Token expiring in ${hoursLeft}h. Run: trawl login to refresh.`));
         }
         else {

package/dist/commands/upgrade.js

@@ -21,21 +21,12 @@ export const upgrade = new Command('upgrade')
         return;
     }
     if (opts.check) {
-        // #170 review F10 — set BEFORE the --json early return. Before this,
-        // `trawl upgrade --check` exited 1 but `trawl upgrade --check --json`
-        // (identical state) exited 0 — the exit code was set below the --json
-        // `return`, so a --json caller never saw it. README documents this gate
-        // as "exit 1 if so" with no --json carve-out; a CI step gating on the
-        // exit code alone silently never fired under --json.
         process.exitCode = 1;
         if (opts.json)
             return json({ package: PKG_NAME, current, latest, upToDate: false, upgraded: false });
         console.log(`${chalk.yellow('↑')} Update available: ${chalk.bold(current)} → ${chalk.bold(latest)}. Run ${chalk.cyan('trawl upgrade')} to install.`);
         return;
     }
-    // Install the latest globally. This shells out to the same npm the user
-    // installed the CLI with; a permission error (EACCES on a system-owned
-    // global prefix) is surfaced with the manual command rather than swallowed.
     if (!opts.json)
         console.log(chalk.dim(`Upgrading ${PKG_NAME}: ${current} → ${latest}…`));
     try {
@@ -49,19 +40,6 @@ export const upgrade = new Command('upgrade')
                 ? 'permission denied on the global npm prefix — retry with sudo, or use a Node version manager.'
                 : (e.stderr?.trim() || e.message);
         if (opts.json) {
-            // `upgrade_failed` is intentionally NOT in errors.ts's RETRY_POLICY
-            // (that map is the exhaustive set of kinds classifyError can
-            // produce — ERROR_KINDS derives from its keys) — retryFieldsFor is
-            // total, so an unmapped kind still gets the honest conservative
-            // default (`retryable:false`) instead of silently omitting the
-            // field. It IS registered in ENVELOPE_KINDS, the superset
-            // `spec --json`'s errorKinds actually publishes — see that
-            // constant's doc comment.
-            //
-            // #170 review F3 — typed as ErrorEnvelope so the compiler enforces
-            // `retryable` here too (this was one of the two emitters a
-            // mutation-test proved `tsc --noEmit` never actually guarded before
-            // this annotation).
             const envelope = {
                 message: `upgrade failed: ${hint}`,
                 kind: 'upgrade_failed',

package/dist/commands/whoami.d.ts

@@ -1,16 +1,4 @@
 import { Command } from 'commander';
-/**
- * `GET /api/users/me` response shape (users.account.controller.js#me).
- *
- * Chosen over the MCP `trawl_whoami` tool's own payload
- * (userId/organizationId/organizationName/scrapIdsAllowlist/mode) because
- * that shape lives entirely in the MCP per-call auth-bridge context
- * (developers.mcp.js) — there is no equivalent REST route exposing
- * organization/scope/mode for a session-JWT caller today. `/api/users/me`
- * is the closest REST parity match: real identity, already used by every
- * other trawl_node client. `roles` is the nearest analogue to "scopes";
- * there is currently no "plan" field on this endpoint.
- */
 export interface WhoamiResponse {
     id?: string;
     email?: string;

package/dist/commands/whoami.js

@@ -7,12 +7,6 @@ export const whoami = new Command('whoami')
     .description("Show the authenticated user's identity")
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // #169 — JWT-only route (see WhoamiResponse's own doc comment above for
-    // why it stays that way). Under a scoped API key, a real request here
-    // would 401 and surface the generic "Session expired or invalid" text —
-    // wrong twice over: this route never accepts keys at all, and no
-    // session ever "expired". Detect it client-side, before any HTTP call,
-    // and say so plainly instead.
     if (getAuthMode() === 'apiKey') {
         throw apiKeyUnsupportedError('trawl whoami');
     }

package/dist/index.d.ts

@@ -1,203 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-/**
- * 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 declare function resolveCommandName(actionCommand: Command | undefined): string;
-/**
- * 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 declare function collectCommandNames(root: Command): string[];
 export declare function createProgram(): Command;
-/**
- * #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 declare function docsFooterText(): string;
-/**
- * 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 declare function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean;
-/**
- * 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 declare function isHelpOrVersion(argv: string[]): boolean;
-/**
- * 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 declare function isBareInvocation(argv: string[]): boolean;
-/**
- * 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 declare function isSpecQuery(argv: string[]): boolean;
-/** 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 declare function hasJsonFlag(argv: string[]): boolean;
-/**
- * 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 declare function applyExitOverride(cmd: Command): void;
-/**
- * #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 declare function applyOutputConfiguration(cmd: Command): void;
-/**
- * #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 declare function bestEffortCommandName(argv: string[], allowedNames: readonly string[]): string;
 export declare function runCli(argv?: string[]): Promise<void>;