@trawlme/cli 3.11.0 → 3.12.1

package/dist/lib/docs.js

@@ -1,78 +1,4 @@
-/**
- * trawl_cli#185 — ONE source of truth for the docs URL(s) an agent (or
- * human) can be pointed at from three surfaces: `spec --json` (top-level
- * `docsUrl`/`llmsUrl` + a per-command `docs` deep link), a run's JSON
- * payload (`doctor`/`data --errors`/`run-info`, keyed on `failureKind` —
- * NOT errors.ts's unrelated `ErrorEnvelope.kind`, see the doc comment on
- * `FAILURE_KIND_DOC_PATHS` below), and the `--help` footer. Three hardcoded
- * lists here would diverge within months — that exact "same fact computed
- * in two places" defect has recurred repeatedly across this epic — so every
- * surface reads these same tables/functions, never its own copy.
- *
- * Resolution ladder (issue #185 — all three rungs REQUIRED, in this order,
- * evaluated PER FIELD, never as one bundled decision — see `resolveDocsUrls`):
- *
- *  1. Prefer the server. `externalDocs.url` on the OpenAPI document at
- *     `<apiBase>/api/spec.json` is the standard OpenAPI field for exactly
- *     this, and reading it makes a self-hosted install work with ZERO CLI
- *     change. It is unset (null) server-side today, so this is
- *     forward-looking — build it anyway, and it must win outright over rung
- *     2 when present. The one caller allowed to fetch it is `spec.ts`'s own
- *     action, bounded and swallowed-on-failure (mirrors lib/tips.ts's
- *     `isReferralProgramUserFacing`) — a deliberate, once-per-invocation
- *     agent probe, not "every command". Every other surface (an error
- *     payload on an arbitrary failing command, the `--help` footer) must
- *     never add a network call or a failure mode to a command nobody asked
- *     to hit the docs host for — see `resolveDocsUrls`'s `externalDocsUrl`
- *     parameter, which only ever arrives pre-fetched.
- *  2. Else derive, by stripping a leading `api.` host label from the
- *     configured API base — but ONLY for a KNOWN first-party `trawl.me`
- *     host. `api.trawl.me` -> `trawl.me` (prod: API and docs are genuinely
- *     on different hosts); `dev.trawl.me` (no `api.` prefix) -> unchanged
- *     (dev serves docs on the SAME host as its API). A generic, unscoped
- *     `api.`-strip applied to ANY host is itself a guess — it assumes a
- *     self-hosted `api.acme.internal` serves docs at `acme.internal`, which
- *     nothing here can know. Scoping the strip to `trawl.me` is what makes
- *     rung 3 (below) ever actually fire for a self-hosted base.
- *  3. Else OMIT the field entirely. Never emit a guessed URL (issue's Rule
- *     3): a wrong URL sends an agent to a 404 WITH CONFIDENCE, worse than no
- *     URL at all — a self-hosted install with no server-declared
- *     `externalDocs` and a base outside `trawl.me` gets no `docsUrl`/
- *     `llmsUrl`, not a hopeful default pointed at OUR docs host.
- *
- * `llmsUrl` has no OpenAPI-standard field to read (rung 1 contributes
- * nothing to it) — deriving it from the ORIGIN of a server-declared
- * `externalDocs.url` would itself be a guess for a self-hosted install
- * (rule 3 again), so `llmsUrl` resolves ONLY via rung 2 (the known-host
- * derivation) or omission. It never rides along with a rung-1 `docsUrl`.
- *
- * PROVENANCE (defect fix, reviewer repro against a live mock server): the
- * top-level `docsUrl` above is deliberately the FLATTENED "whichever rung
- * won" value — right for a human reading `spec --json`'s top-level field,
- * WRONG as an input to `resolveCommandDocsUrl`/`resolveFailureKindDocsUrl`
- * below. Those two append one of THIS CLI's own hardcoded guide slugs
- * (`COMMAND_DOC_PATHS`/`FAILURE_KIND_DOC_PATHS`) onto whatever `docsUrl`
- * resolved — safe onto a rung-2 root we derived ourselves (we know
- * trawl.me's guide tree), never safe onto a rung-1 root (an arbitrary
- * third party's own docs site, self-hosted, with no reason to carry our
- * slugs). A mock server declaring `externalDocs.url: 'http://h/guide'`
- * used to get `http://h/guide/build-your-scrap/account-sessions` appended
- * — a confidently-wrong 404. So `DocsUrls.docsUrlIsDerived` carries rung
- * provenance ALONGSIDE the string (never flattened to a bare string again)
- * and both deep-link functions now take the whole `DocsUrls`-shaped object
- * and gate construction on that flag — see its own doc comment below.
- */
-/** The one first-party domain this CLI knows to serve docs — see rung 2 in
- *  the module doc comment above. Deliberately not "any host", so an
- *  unrecognized (self-hosted/custom) base falls through to omission. */
 const KNOWN_DOCS_DOMAIN = 'trawl.me';
-/**
- * Rung 2 — see the module doc comment. Returns `{ protocol, host }` for a
- * KNOWN first-party API base (preserving the base's own protocol rather
- * than assuming `https:`), or `null` when the base isn't recognized
- * (self-hosted, a custom domain, `localhost`, an unparseable string, …) —
- * `null` must propagate to omission (rung 3), never to a guessed host.
- */
 export function deriveDocsOrigin(apiBaseUrl) {
     let url;
     try {
@@ -88,22 +14,9 @@ export function deriveDocsOrigin(apiBaseUrl) {
     }
     return null;
 }
-/** Same rung as `deriveDocsOrigin`, collapsed to just the host string —
- *  convenience for a caller that only needs the derived host, not the
- *  protocol (kept as its own export since `docs.test.ts` exercises the host
- *  derivation independently of protocol handling). */
 export function deriveDocsHost(apiBaseUrl) {
     return deriveDocsOrigin(apiBaseUrl)?.host ?? null;
 }
-/**
- * The full ladder, PER FIELD (see module doc comment for why `llmsUrl`
- * cannot ride along with a rung-1 `docsUrl`). Pure and synchronous — no
- * network, safe to call from any surface (an error payload, the `--help`
- * footer) without adding latency or a new failure mode. `externalDocsUrl`
- * is rung 1's input: only ever supplied by `spec.ts`'s action, after its
- * own bounded, swallowed-on-failure fetch — every other caller omits it and
- * gets rungs 2/3 only.
- */
 export function resolveDocsUrls(opts) {
     const origin = deriveDocsOrigin(opts.apiBaseUrl);
     const derived = origin
@@ -114,95 +27,29 @@ export function resolveDocsUrls(opts) {
         }
         : {};
     if (opts.externalDocsUrl) {
-        // Rung 1 wins for docsUrl outright; llmsUrl stays rung-2-only (see doc
-        // comment) — a self-hosted `externalDocsUrl` outside `trawl.me` yields
-        // `{ docsUrl: <server's own> }` with `llmsUrl` omitted, never guessed.
-        // `docsUrlIsDerived: false` regardless of whether rung 2 ALSO resolved
-        // (e.g. a `trawl.me`-hosted server declaring its own externalDocs) — a
-        // server-declared root is never "derived" by THIS CLI, and never a safe
-        // base for our own guide slugs (see DocsUrls.docsUrlIsDerived).
         return derived.llmsUrl
             ? { docsUrl: opts.externalDocsUrl, llmsUrl: derived.llmsUrl, docsUrlIsDerived: false }
             : { docsUrl: opts.externalDocsUrl, docsUrlIsDerived: false };
     }
     return derived;
 }
-/** Join a docs root (e.g. `https://trawl.me/docs`) with a guide path
- *  suffix (e.g. `build-your-scrap/account-sessions`) — plain string
- *  concatenation, deliberately NOT `new URL(suffix, docsUrl)`: a
- *  leading-slash suffix resolved against a URL with its own path component
- *  (`/docs`) would resolve relative to the ORIGIN, silently dropping
- *  `/docs` from the result (`new URL('/x', 'https://h/docs')` ==
- *  `https://h/x`, not `https://h/docs/x`). */
 function joinDocsPath(docsUrl, suffix) {
     return `${docsUrl.replace(/\/+$/, '')}/${suffix.replace(/^\/+/, '')}`;
 }
-/**
- * The single source for the account-sessions guide slug — referenced by
- * BOTH `COMMAND_DOC_PATHS` and `FAILURE_KIND_DOC_PATHS` below. Those two
- * tables key on different fields (a CLI command's full path name vs a run's
- * `failureKind`) and legitimately stay separate, but they name the SAME
- * guide, so the path literal itself must exist exactly once: this is the
- * "same fact computed in two places" defect class this module's own doc
- * comment says it exists to prevent, and it has recurred repeatedly across
- * this epic. Renaming the guide used to require editing two literals in
- * lockstep — miss one and one surface (a run's `docs` field, or `spec
- * --json`'s per-command deep link) silently 404s while the other still
- * works (trawl_cli#185 review).
- */
 const ACCOUNT_SESSIONS_GUIDE_PATH = 'build-your-scrap/account-sessions';
-/**
- * Per-command deep links (issue #185 scope item 1) — a command's FULL path
- * name (matches `CliSpecCommand.name` in spec.ts, e.g.
- * `"scraps account session set"`) is matched against `prefix` either
- * exactly or as a whole path SEGMENT prefix (`startsWith(prefix + ' ')`) —
- * never a bare substring, so a hypothetical future `scraps accounting`
- * command could never false-match the `scraps account` entry below.
- */
 const COMMAND_DOC_PATHS = Object.freeze([
-    // Every account/session-management command — set, delete, clear-session,
-    // status, and the nested `session set` — is covered by one prefix entry
-    // rather than one row per leaf, so a new leaf added under `scraps account`
-    // later (e.g. a future `session capture`, trawl_cli#183) inherits the
-    // link for free instead of needing its own row.
     { prefix: 'scraps account', path: ACCOUNT_SESSIONS_GUIDE_PATH },
 ]);
 function docsPathForCommand(commandName) {
     const match = COMMAND_DOC_PATHS.find((e) => commandName === e.prefix || commandName.startsWith(`${e.prefix} `));
     return match ? match.path : null;
 }
-/**
- * `resolveCommandDocsUrl` returns `undefined` (never a bare path or a
- * relative link) whenever any of three things is missing — `docsUrl`
- * unresolved (rung 3 already fired), `docsUrl` resolved but NOT derived
- * (rung 1 — a server-declared root; see `DocsUrls.docsUrlIsDerived`'s doc
- * comment for why appending our own guide slug onto a third party's root is
- * exactly the confidently-wrong-404 defect this gate closes), or no guide is
- * mapped for this command — so a spec consumer never has to special-case a
- * partial value. Takes the whole resolved `DocsUrls` object (never a bare
- * string) specifically so this provenance can never again be flattened away
- * before it reaches here.
- */
 export function resolveCommandDocsUrl(commandName, docs) {
     if (!docs.docsUrl || !docs.docsUrlIsDerived)
         return undefined;
     const path = docsPathForCommand(commandName);
     return path ? joinDocsPath(docs.docsUrl, path) : undefined;
 }
-/**
- * failureKind -> guide path (issue #185 scope item 2). Keyed on trawl_node's
- * run-level `failureKind` field (trawl_node#1975, surfaced by this CLI's
- * own `doctor`/`data --errors`/`run-info` JSON payloads since cli#182) —
- * this is a DIFFERENT axis from errors.ts's `ErrorEnvelope.kind` (a CLI
- * transport/execution outcome like `"auth"` meaning "you're not logged
- * into trawl", `"network"`, `"usage"`, …). Both happen to use the string
- * `"auth"` for unrelated things: this table's `'auth'` means "the SCRAPED
- * TARGET site showed a login wall", errors.ts's `'auth'` means "the TRAWL
- * API rejected your OWN credentials". Never merge these two tables — they
- * are keyed off different fields on different objects, and conflating them
- * would either miss the run-level guide or wrongly attach it to an
- * unrelated CLI auth failure.
- */
 const FAILURE_KIND_DOC_PATHS = Object.freeze({
     auth: ACCOUNT_SESSIONS_GUIDE_PATH,
 });
@@ -211,28 +58,12 @@ function docsPathForFailureKind(kind) {
         return null;
     return FAILURE_KIND_DOC_PATHS[kind] ?? null;
 }
-/** Same "undefined unless docsUrl is resolved AND derived (rung 2)" gate as
- *  `resolveCommandDocsUrl` above, same reason — never append this CLI's own
- *  guide slug onto a rung-1 server-declared root. Callers MUST gate the call
- *  on their own staleness rule first (e.g. `doctor.ts`'s `isAuthWall`) — this
- *  function only knows the string-to-path mapping, not whether a stamped
- *  `failureKind` is still live on a run patched afterward. */
 export function resolveFailureKindDocsUrl(kind, docs) {
     if (!docs.docsUrl || !docs.docsUrlIsDerived)
         return undefined;
     const path = docsPathForFailureKind(kind);
     return path ? joinDocsPath(docs.docsUrl, path) : undefined;
 }
-/**
- * `--help` footer text (issue #185 scope item 3) — a single dim line, for
- * humans, e.g. "Docs: https://trawl.me/docs". Returns `undefined` (never an
- * empty or guessed line) when no `docsUrl` resolved — mirrors
- * lib/tips.ts's shape (a pure function separated from IO, so it's testable
- * without mocking chalk/console) but NOT its TTY gate: tips.ts suppresses a
- * promotional nudge from piped output, but a docs line inside `--help |
- * less` is exactly the kind of thing worth keeping. Un-colored here — the
- * caller (index.ts) applies `chalk.dim` so this stays trivially testable.
- */
 export function docsFooterLine(docsUrl) {
     return docsUrl ? `Docs: ${docsUrl}` : undefined;
 }

package/dist/lib/errors.d.ts

@@ -1,58 +1,21 @@
-/**
- * Thrown for CLI usage / input-validation failures (bad flag value, malformed
- * JSON, invalid ObjectId, missing required prompt input, …). Distinguished
- * from ApiError/NetworkError so the top-level handler can map it to its own
- * exit code (2) instead of the generic uniform 1 every other bug collapses
- * into. (#71)
- */
 export declare class UsageError extends Error {
     constructor(message: string);
 }
-/**
- * Thrown for a business-logic REFUSAL the server explicitly reported back
- * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
- * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
- * `new Error(message)` through here, which fell through to the generic
- * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
- * though the README sells `kind` as the machine discriminant an agent
- * branches on. Same exit code (1: a business-logic refusal, not a usage
- * error) as before — only the `kind` differs. (#107 review F3)
- */
 export declare class RefusalError extends Error {
     constructor(message: string);
 }
-/**
- * Commander prefixes every one of its own usage-error messages with the
- * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
- * etc. in commander's `command.js`) — harmless for its own plain default
- * line, but redundant once this CLI reuses that message itself: (1) baked
- * into a `--json` envelope's `message` field, a human-facing "error: " prefix
- * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
- * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
- * would double up as "✗ error: unknown option …". Idempotent — a message
- * that never had the prefix passes through unchanged. (#149 items 1/2)
- */
 export declare function stripCommanderErrorPrefix(message: string): string;
 export interface ErrorEnvelope {
     message: string;
     status?: number;
     kind: string;
-    /** Is retrying the SAME command, unchanged, worth it? */
     retryable: boolean;
-    /** Commands worth running next, most useful first. Empty when there is
-     *  nothing honest to suggest — never filled to look helpful. */
     next?: string[];
 }
 export interface ClassifiedError {
     exitCode: number;
     envelope: ErrorEnvelope;
 }
-/**
- * The exit-code taxonomy (#71 findings 13/14/60), named once so
- * `classifyError` below and `spec.ts`'s `buildSpec()` (#170) read the SAME
- * numbers instead of `spec.ts` hand-listing its own copy — exactly the kind
- * of second source of truth `tests/contracts/` exists to catch drifting.
- */
 export declare const EXIT_CODES: Readonly<{
     SUCCESS: 0;
     UNKNOWN: 1;
@@ -61,116 +24,19 @@ export declare const EXIT_CODES: Readonly<{
     NOT_FOUND: 4;
     NETWORK: 5;
 }>;
-/** `trawl spec --json`'s `exitCodes` field — a short label per code. Code
- * `1` is shared by several `kind`s (`api`, `refused`, `unknown`); the label
- * names the generic/unmapped bucket it represents, not an exhaustive list. */
 export declare const EXIT_CODE_LABELS: Readonly<Record<string, string>>;
-/**
- * #170 — ONE frozen map, keyed by the existing `kind`, driving the
- * envelope's new `retryable`/`next` fields. This is also the exhaustive set
- * of `kind`s `classifyError` can produce — `ERROR_KINDS` below derives its
- * list from these keys rather than hand-listing them a second time, and
- * `spec.ts`'s `buildSpec()` reads `ERROR_KINDS`, never its own copy.
- *
- * `network` is the one kind worth retrying unchanged. `auth` isn't
- * retryable but has an honest next step (`trawl login --token <jwt>`).
- * Everything else (`usage`/`not_found`/`api`/`refused`/`unknown`) is neither
- * — retrying a bad flag, a missing resource, or an unmapped bug with no new
- * information just repeats the same failure.
- *
- * #170 review F8 — `next` must be an EXECUTABLE next command, not just a verb
- * name: bare `trawl login` still blocks on an interactive prompt (email then
- * password) — for a non-interactive caller (stdin closed, the exact
- * situation an auth failure implies) it fails immediately with its OWN usage
- * error instead of the login the agent was told to run. `trawl login --token
- * <jwt>` is the one form of `login` that never prompts.
- */
 export declare const RETRY_POLICY: Readonly<Record<string, {
     retryable: boolean;
     next?: readonly string[];
 }>>;
-/** Every `kind` string `classifyError` can produce — derived from
- * `RETRY_POLICY`'s keys (see its doc comment), never a second hand list. */
 export declare const ERROR_KINDS: readonly string[];
-/**
- * Every `kind` a real `--json` error envelope can carry — NOT the same set
- * as `ERROR_KINDS`. `ERROR_KINDS` is deliberately narrow (exactly what
- * `classifyError` produces, see its own doc comment — `RETRY_POLICY` must
- * keep meaning that, `retryFieldsFor` relies on it), but three more kinds
- * reach a real envelope from hand-built emitters that never go through
- * `classifyError` at all:
- *   - `in_progress` — `src/commands/scraps.ts`, `data <id>`'s `reportDataState`
- *     call for a run still in flight
- *   - `run_failed`  — same file, same helper, for a last run that failed
- *   - `upgrade_failed` — `src/commands/upgrade.ts`, when `npm install -g` itself fails
- *
- * `spec.ts`'s `errorKinds` field publishes THIS constant, never
- * `ERROR_KINDS` — an agent that builds its allow-list from the published
- * spec must not reject a perfectly valid `{"error":{"kind":"in_progress",…}}`
- * envelope just because it was hand-built instead of classified. Built as a
- * union (spread `ERROR_KINDS` + list the hand-built kinds) rather than a
- * second hand-copy of the first group, so the classifyError kinds are
- * PROVABLY a subset — see errors.test.ts's exhaustiveness check.
- *
- * Adding a new hand-built `kind:` literal anywhere in `src/` means
- * registering it here too, or the published spec will lie about it exactly
- * like this constant exists to prevent.
- */
 export declare const ENVELOPE_KINDS: readonly string[];
-/**
- * #170 review F7 — `spec --json`'s flat `exitCodes` map (`EXIT_CODE_LABELS`)
- * publishes ONE label per code, which is honest about code `1` being a
- * generic/unmapped bucket but says nothing about which `kind`s actually land
- * there. An agent building an `exitCode -> kind` table off `exitCodes` alone
- * reads `"1":"unknown"` and treats every other kind sharing that code
- * (`api`/`refused`/`in_progress`/`run_failed`/`upgrade_failed`) as an
- * unmapped bug it should give up on — instead of honouring the very
- * `retryable`/`next` fields those envelopes correctly carry.
- *
- * This is the inverse direction, `kind -> exitCode`, one entry per
- * `ENVELOPE_KINDS` member — additive (published as a SIBLING field,
- * `kindExitCodes`, never replacing `exitCodes`) and keyed off the same
- * `EXIT_CODES` constants every real call site already uses, so a future exit
- * code change here can't silently drift from `classifyError`/
- * `reportDataState`/`upgrade.ts`'s actual behaviour without also changing the
- * single source those all draw from. errors.test.ts asserts every entry here
- * against classifyError's REAL returned exitCode for that kind — the closest
- * an exhaustive hand-map can get to "derived", short of `classifyError`
- * itself being rewritten to loop over a shared table (out of scope here).
- */
 export declare const KIND_EXIT_CODES: Readonly<Record<string, number>>;
-/**
- * Look up the frozen default `retryable`/`next` for a `kind`. Total (never
- * throws) — a `kind` outside `RETRY_POLICY` (e.g. `scraps data`'s own
- * `run_failed`/`in_progress` states, which aren't part of `classifyError`'s
- * taxonomy) falls back to the conservative "not retryable, nothing to
- * suggest" default. Callers with a genuine kind-is-wrong override (an
- * `ApiError` 429, `scraps data`'s `in_progress` refusal) pass their own
- * `retryable`/`next` instead of trusting this lookup — see classifyError and
- * scraps.ts's `reportDataState`.
- */
 export declare function retryFieldsFor(kind: string): {
     retryable: boolean;
     next?: string[];
 };
-/**
- * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
- * CLI unattended need to tell "you're not logged in" (3) from "that id
- * doesn't exist" (4) from "the network/API is unreachable" (5) from "you
- * passed a bad flag" (2) — a uniform exit 1 collapses all of these into one
- * undifferentiable signal.
- */
 export declare function classifyError(err: unknown): ClassifiedError;
-/**
- * Print a classified error to the correct stream and return its exit code.
- * stdout is reserved for payload — under --json the error itself IS the
- * payload (`{"error":{message,status,kind,retryable,next?}}`); otherwise the
- * human-readable line goes to stderr, never stdout. (#71 findings 13/14/60)
- *
- * `quiet` skips the human-readable stderr line (used when the caller already
- * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while
- * still emitting the --json payload when requested.
- */
 export declare function reportError(err: unknown, opts?: {
     json?: boolean;
     quiet?: boolean;

package/dist/lib/errors.js

@@ -1,54 +1,20 @@
 import chalk from 'chalk';
 import { ApiError, AuthError, NetworkError } from './api.js';
-/**
- * Thrown for CLI usage / input-validation failures (bad flag value, malformed
- * JSON, invalid ObjectId, missing required prompt input, …). Distinguished
- * from ApiError/NetworkError so the top-level handler can map it to its own
- * exit code (2) instead of the generic uniform 1 every other bug collapses
- * into. (#71)
- */
 export class UsageError extends Error {
     constructor(message) {
         super(message);
         this.name = 'UsageError';
     }
 }
-/**
- * Thrown for a business-logic REFUSAL the server explicitly reported back
- * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
- * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
- * `new Error(message)` through here, which fell through to the generic
- * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
- * though the README sells `kind` as the machine discriminant an agent
- * branches on. Same exit code (1: a business-logic refusal, not a usage
- * error) as before — only the `kind` differs. (#107 review F3)
- */
 export class RefusalError extends Error {
     constructor(message) {
         super(message);
         this.name = 'RefusalError';
     }
 }
-/**
- * Commander prefixes every one of its own usage-error messages with the
- * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
- * etc. in commander's `command.js`) — harmless for its own plain default
- * line, but redundant once this CLI reuses that message itself: (1) baked
- * into a `--json` envelope's `message` field, a human-facing "error: " prefix
- * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
- * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
- * would double up as "✗ error: unknown option …". Idempotent — a message
- * that never had the prefix passes through unchanged. (#149 items 1/2)
- */
 export function stripCommanderErrorPrefix(message) {
     return message.startsWith('error: ') ? message.slice('error: '.length) : message;
 }
-/**
- * The exit-code taxonomy (#71 findings 13/14/60), named once so
- * `classifyError` below and `spec.ts`'s `buildSpec()` (#170) read the SAME
- * numbers instead of `spec.ts` hand-listing its own copy — exactly the kind
- * of second source of truth `tests/contracts/` exists to catch drifting.
- */
 export const EXIT_CODES = Object.freeze({
     SUCCESS: 0,
     UNKNOWN: 1,
@@ -57,9 +23,6 @@ export const EXIT_CODES = Object.freeze({
     NOT_FOUND: 4,
     NETWORK: 5,
 });
-/** `trawl spec --json`'s `exitCodes` field — a short label per code. Code
- * `1` is shared by several `kind`s (`api`, `refused`, `unknown`); the label
- * names the generic/unmapped bucket it represents, not an exhaustive list. */
 export const EXIT_CODE_LABELS = Object.freeze({
     [EXIT_CODES.SUCCESS]: 'success',
     [EXIT_CODES.UNKNOWN]: 'unknown',
@@ -68,26 +31,6 @@ export const EXIT_CODE_LABELS = Object.freeze({
     [EXIT_CODES.NOT_FOUND]: 'not_found',
     [EXIT_CODES.NETWORK]: 'network',
 });
-/**
- * #170 — ONE frozen map, keyed by the existing `kind`, driving the
- * envelope's new `retryable`/`next` fields. This is also the exhaustive set
- * of `kind`s `classifyError` can produce — `ERROR_KINDS` below derives its
- * list from these keys rather than hand-listing them a second time, and
- * `spec.ts`'s `buildSpec()` reads `ERROR_KINDS`, never its own copy.
- *
- * `network` is the one kind worth retrying unchanged. `auth` isn't
- * retryable but has an honest next step (`trawl login --token <jwt>`).
- * Everything else (`usage`/`not_found`/`api`/`refused`/`unknown`) is neither
- * — retrying a bad flag, a missing resource, or an unmapped bug with no new
- * information just repeats the same failure.
- *
- * #170 review F8 — `next` must be an EXECUTABLE next command, not just a verb
- * name: bare `trawl login` still blocks on an interactive prompt (email then
- * password) — for a non-interactive caller (stdin closed, the exact
- * situation an auth failure implies) it fails immediately with its OWN usage
- * error instead of the login the agent was told to run. `trawl login --token
- * <jwt>` is the one form of `login` that never prompts.
- */
 export const RETRY_POLICY = Object.freeze({
     auth: { retryable: false, next: ['trawl login --token <jwt>'] },
     network: { retryable: true },
@@ -97,60 +40,13 @@ export const RETRY_POLICY = Object.freeze({
     refused: { retryable: false },
     unknown: { retryable: false },
 });
-/** Every `kind` string `classifyError` can produce — derived from
- * `RETRY_POLICY`'s keys (see its doc comment), never a second hand list. */
 export const ERROR_KINDS = Object.freeze(Object.keys(RETRY_POLICY));
-/**
- * Every `kind` a real `--json` error envelope can carry — NOT the same set
- * as `ERROR_KINDS`. `ERROR_KINDS` is deliberately narrow (exactly what
- * `classifyError` produces, see its own doc comment — `RETRY_POLICY` must
- * keep meaning that, `retryFieldsFor` relies on it), but three more kinds
- * reach a real envelope from hand-built emitters that never go through
- * `classifyError` at all:
- *   - `in_progress` — `src/commands/scraps.ts`, `data <id>`'s `reportDataState`
- *     call for a run still in flight
- *   - `run_failed`  — same file, same helper, for a last run that failed
- *   - `upgrade_failed` — `src/commands/upgrade.ts`, when `npm install -g` itself fails
- *
- * `spec.ts`'s `errorKinds` field publishes THIS constant, never
- * `ERROR_KINDS` — an agent that builds its allow-list from the published
- * spec must not reject a perfectly valid `{"error":{"kind":"in_progress",…}}`
- * envelope just because it was hand-built instead of classified. Built as a
- * union (spread `ERROR_KINDS` + list the hand-built kinds) rather than a
- * second hand-copy of the first group, so the classifyError kinds are
- * PROVABLY a subset — see errors.test.ts's exhaustiveness check.
- *
- * Adding a new hand-built `kind:` literal anywhere in `src/` means
- * registering it here too, or the published spec will lie about it exactly
- * like this constant exists to prevent.
- */
 export const ENVELOPE_KINDS = Object.freeze([
     ...ERROR_KINDS,
     'in_progress',
     'run_failed',
     'upgrade_failed',
 ]);
-/**
- * #170 review F7 — `spec --json`'s flat `exitCodes` map (`EXIT_CODE_LABELS`)
- * publishes ONE label per code, which is honest about code `1` being a
- * generic/unmapped bucket but says nothing about which `kind`s actually land
- * there. An agent building an `exitCode -> kind` table off `exitCodes` alone
- * reads `"1":"unknown"` and treats every other kind sharing that code
- * (`api`/`refused`/`in_progress`/`run_failed`/`upgrade_failed`) as an
- * unmapped bug it should give up on — instead of honouring the very
- * `retryable`/`next` fields those envelopes correctly carry.
- *
- * This is the inverse direction, `kind -> exitCode`, one entry per
- * `ENVELOPE_KINDS` member — additive (published as a SIBLING field,
- * `kindExitCodes`, never replacing `exitCodes`) and keyed off the same
- * `EXIT_CODES` constants every real call site already uses, so a future exit
- * code change here can't silently drift from `classifyError`/
- * `reportDataState`/`upgrade.ts`'s actual behaviour without also changing the
- * single source those all draw from. errors.test.ts asserts every entry here
- * against classifyError's REAL returned exitCode for that kind — the closest
- * an exhaustive hand-map can get to "derived", short of `classifyError`
- * itself being rewritten to loop over a shared table (out of scope here).
- */
 export const KIND_EXIT_CODES = Object.freeze({
     auth: EXIT_CODES.AUTH,
     network: EXIT_CODES.NETWORK,
@@ -159,51 +55,18 @@ export const KIND_EXIT_CODES = Object.freeze({
     api: EXIT_CODES.UNKNOWN,
     refused: EXIT_CODES.UNKNOWN,
     unknown: EXIT_CODES.UNKNOWN,
-    // Hand-built kinds (never routed through classifyError) — in_progress/
-    // run_failed both set via reportDataState's literal `1` (scraps.ts),
-    // upgrade_failed via its own literal `process.exitCode = 1` (upgrade.ts).
     in_progress: EXIT_CODES.UNKNOWN,
     run_failed: EXIT_CODES.UNKNOWN,
     upgrade_failed: EXIT_CODES.UNKNOWN,
 });
-/**
- * Look up the frozen default `retryable`/`next` for a `kind`. Total (never
- * throws) — a `kind` outside `RETRY_POLICY` (e.g. `scraps data`'s own
- * `run_failed`/`in_progress` states, which aren't part of `classifyError`'s
- * taxonomy) falls back to the conservative "not retryable, nothing to
- * suggest" default. Callers with a genuine kind-is-wrong override (an
- * `ApiError` 429, `scraps data`'s `in_progress` refusal) pass their own
- * `retryable`/`next` instead of trusting this lookup — see classifyError and
- * scraps.ts's `reportDataState`.
- */
 export function retryFieldsFor(kind) {
     const policy = RETRY_POLICY[kind];
     if (!policy)
         return { retryable: false };
     return policy.next ? { retryable: policy.retryable, next: [...policy.next] } : { retryable: policy.retryable };
 }
-/**
- * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
- * CLI unattended need to tell "you're not logged in" (3) from "that id
- * doesn't exist" (4) from "the network/API is unreachable" (5) from "you
- * passed a bad flag" (2) — a uniform exit 1 collapses all of these into one
- * undifferentiable signal.
- */
 export function classifyError(err) {
     const message = err instanceof Error ? err.message : String(err);
-    // #88 item 4 — a LOCAL auth failure (no token, or a locally-decoded expired
-    // token) never made an HTTP call, so its envelope must never carry
-    // `status:401` — that would claim a server response that never happened.
-    // Same exit code / kind as a real server 401 (ApiError below); only the
-    // envelope shape differs.
-    //
-    // #169 review round 2, finding 2 — `err.next` is only ever set (in api.ts,
-    // via authNextSteps()) for an apiKey-mode failure, where the frozen
-    // `next` default ("trawl login --token <jwt>") is inert until a live
-    // TRAWL_API_KEY/TRAWL_TOKEN is unset first. Spread AFTER retryFieldsFor so
-    // it overrides that default's `next` key; every other AuthError/ApiError
-    // 401 (jwt mode, notLoggedInError — no credential at all) leaves `err.next`
-    // undefined and keeps the unmodified frozen default, unchanged from before.
     if (err instanceof AuthError) {
         return {
             exitCode: EXIT_CODES.AUTH,
@@ -226,10 +89,6 @@ export function classifyError(err) {
         if (err.status === 404) {
             return { exitCode: EXIT_CODES.NOT_FOUND, envelope: { message, status: 404, kind: 'not_found', ...retryFieldsFor('not_found') } };
         }
-        // #170 — a 429 (rate-limited / quota-exhausted) is the one `api`-kind
-        // response worth retrying, even though the frozen map's default for
-        // `api` is not retryable. Genuinely kind-is-wrong override, not a new
-        // kind — `kind` stays `"api"`.
         const retry = err.status === 429 ? { retryable: true } : retryFieldsFor('api');
         return { exitCode: EXIT_CODES.UNKNOWN, envelope: { message, status: err.status, kind: 'api', ...retry } };
     }
@@ -244,16 +103,6 @@ export function classifyError(err) {
     }
     return { exitCode: EXIT_CODES.UNKNOWN, envelope: { message, kind: 'unknown', ...retryFieldsFor('unknown') } };
 }
-/**
- * Print a classified error to the correct stream and return its exit code.
- * stdout is reserved for payload — under --json the error itself IS the
- * payload (`{"error":{message,status,kind,retryable,next?}}`); otherwise the
- * human-readable line goes to stderr, never stdout. (#71 findings 13/14/60)
- *
- * `quiet` skips the human-readable stderr line (used when the caller already
- * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while
- * still emitting the --json payload when requested.
- */
 export function reportError(err, opts = {}) {
     const { exitCode, envelope } = classifyError(err);
     if (opts.json) {

package/dist/lib/format.d.ts

@@ -1,9 +1,3 @@
 export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
 export declare function json(data: unknown): void;
-/**
- * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
- * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
- * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
- * Returns `—` for a missing/invalid date.
- */
 export declare function formatDate(value: string | number | Date | null | undefined): string;

package/dist/lib/format.js

@@ -23,12 +23,6 @@ export function table(rows, columns) {
 export function json(data) {
     console.log(JSON.stringify(data, null, 2));
 }
-/**
- * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
- * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
- * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
- * Returns `—` for a missing/invalid date.
- */
 export function formatDate(value) {
     if (value === null || value === undefined)
         return '—';