@trawlme/cli 3.12.0 → 3.12.2

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 '—';

package/dist/lib/json.d.ts

@@ -1,37 +1,2 @@
-/**
- * Shared, tolerant JSON parsing for server response bodies (#159).
- *
- * The Trawl API is known to occasionally emit a raw, unescaped control
- * character (U+0000–U+001F — a literal newline, NUL, BEL, …) inside a JSON
- * string value, most often nested inside `scrap.history[0].data` (a
- * worker-envelope blob embedded as a string field of the outer response —
- * the exact server-side emission point is not yet pinned down; tracked in
- * comes-io/trawl_node#1768). That is invalid per RFC 8259 — our own QA
- * tooling already works around it by parsing raw API responses with
- * Python's `json.loads(text, strict=False)` — but native `JSON.parse`
- * has no equivalent lenient mode: it throws outright, and until this fix
- * every one of `api.ts`'s response-parsing call sites (`request`, `upload`,
- * `publicGet`, `publicPost`) turned that into a bare "Invalid JSON in server
- * response" error, discarding the ENTIRE response — even a successful
- * create/run whose scrap was already persisted server-side. Exactly the
- * "payload-dependent, not a constant break" shape reported in #159: it only
- * fires when the specific scraped content/log text happens to carry a raw
- * control byte.
- *
- * `parseServerJson` recovers from that ONE known shape — nothing else. It
- * tries a normal strict `JSON.parse` first (the common case, zero extra
- * cost) and only falls back to a sanitizing re-parse when that throws.
- * Genuinely malformed JSON (truncated body, stray token, …) still throws
- * after the fallback also fails — this is a targeted recovery, not a
- * general-purpose lenient parser.
- */
 export declare function escapeRawControlCharsInJsonStrings(text: string): string;
-/**
- * Parse a server response body, tolerating the known #159 quirk above. Never
- * silently drops data: a byte that reaches here as a real control character
- * comes back out as the same character (via the escape → JSON.parse
- * unescape round trip) once parsed, and JSON.stringify guarantees it is
- * re-escaped correctly on the way back out through the shared `--json`
- * output seam (`lib/format.ts#json`).
- */
 export declare function parseServerJson(text: string): unknown;

package/dist/lib/json.js

@@ -1,40 +1,3 @@
-/**
- * Shared, tolerant JSON parsing for server response bodies (#159).
- *
- * The Trawl API is known to occasionally emit a raw, unescaped control
- * character (U+0000–U+001F — a literal newline, NUL, BEL, …) inside a JSON
- * string value, most often nested inside `scrap.history[0].data` (a
- * worker-envelope blob embedded as a string field of the outer response —
- * the exact server-side emission point is not yet pinned down; tracked in
- * comes-io/trawl_node#1768). That is invalid per RFC 8259 — our own QA
- * tooling already works around it by parsing raw API responses with
- * Python's `json.loads(text, strict=False)` — but native `JSON.parse`
- * has no equivalent lenient mode: it throws outright, and until this fix
- * every one of `api.ts`'s response-parsing call sites (`request`, `upload`,
- * `publicGet`, `publicPost`) turned that into a bare "Invalid JSON in server
- * response" error, discarding the ENTIRE response — even a successful
- * create/run whose scrap was already persisted server-side. Exactly the
- * "payload-dependent, not a constant break" shape reported in #159: it only
- * fires when the specific scraped content/log text happens to carry a raw
- * control byte.
- *
- * `parseServerJson` recovers from that ONE known shape — nothing else. It
- * tries a normal strict `JSON.parse` first (the common case, zero extra
- * cost) and only falls back to a sanitizing re-parse when that throws.
- * Genuinely malformed JSON (truncated body, stray token, …) still throws
- * after the fallback also fails — this is a targeted recovery, not a
- * general-purpose lenient parser.
- */
-/**
- * Escape any raw control character (U+0000–U+001F) found INSIDE a JSON
- * string literal, leaving everything else — including legitimate raw
- * whitespace between tokens (space/tab/CR/LF are valid there per RFC 8259) —
- * untouched. A small state machine tracks whether the scan is currently
- * inside a `"…"` string and whether the previous character was an unescaped
- * backslash; it does not otherwise validate structure, so text that is
- * invalid JSON for any OTHER reason still fails the subsequent `JSON.parse`
- * call unchanged.
- */
 const NAMED_CONTROL_CHAR_ESCAPES = {
     '\n': '\\n',
     '\r': '\\r',
@@ -71,9 +34,6 @@ export function escapeRawControlCharsInJsonStrings(text) {
             continue;
         }
         if (code <= 0x1f) {
-            // Raw control character inside a string literal — recover the same
-            // way JSON.stringify would have escaped it on the way out, instead of
-            // losing the whole response to a SyntaxError.
             out += NAMED_CONTROL_CHAR_ESCAPES[ch] ?? `\\u${code.toString(16).padStart(4, '0')}`;
             continue;
         }
@@ -81,14 +41,6 @@ export function escapeRawControlCharsInJsonStrings(text) {
     }
     return out;
 }
-/**
- * Parse a server response body, tolerating the known #159 quirk above. Never
- * silently drops data: a byte that reaches here as a real control character
- * comes back out as the same character (via the escape → JSON.parse
- * unescape round trip) once parsed, and JSON.stringify guarantees it is
- * re-escaped correctly on the way back out through the shared `--json`
- * output seam (`lib/format.ts#json`).
- */
 export function parseServerJson(text) {
     try {
         return JSON.parse(text);

package/dist/lib/jwt.d.ts

@@ -1,8 +1 @@
-/**
- * Decode the `exp` claim from a JWT (middle segment, base64url-encoded JSON).
- * Returns null if the payload cannot be decoded or has no `exp` field.
- *
- * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
- * already-expired tokens instead of silently storing them). (#68)
- */
 export declare function decodeExp(jwt: string): number | null;

package/dist/lib/jwt.js

@@ -1,10 +1,3 @@
-/**
- * Decode the `exp` claim from a JWT (middle segment, base64url-encoded JSON).
- * Returns null if the payload cannot be decoded or has no `exp` field.
- *
- * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
- * already-expired tokens instead of silently storing them). (#68)
- */
 export function decodeExp(jwt) {
     try {
         const parts = jwt.split('.');

package/dist/lib/pinch.d.ts

@@ -1,61 +1,8 @@
-/**
- * Pinch — Trawl's voxel lobster mascot, rendered as 24-bit ANSI half-block
- * art. Distinct from Clawd's 8-bit lane: Pinch is drawn with full 24-bit
- * (`\x1b[38;2;r;g;bm` / `\x1b[48;2;r;g;bm`) color blocks, not a fixed palette.
- *
- * Each grid is packed two rows into one terminal row: the upper row's color
- * becomes the half-block's foreground, the lower row's becomes its
- * background, using the upper-half-block glyph '▀' (or '▄' when only the
- * lower half is filled). '.' cells are transparent — no color escape is
- * emitted for that half, so the terminal's own background shows through.
- *
- * The grids are the founder-approved 2D front avatar (`AVATAR_GRIDS`, rev
- * r6f) from trawl_vue `src/modules/trawl/assets/mascot/_src/pinch.model.mjs`,
- * ported VERBATIM (no cross-repo import — cli is a standalone npm package).
- * Each is 14 cols × 8 rows (the source's 9th all-'.' pad row is dropped) →
- * renders in 4 terminal rows, 14 columns wide. This is the mascot "de face":
- * antennae on top, 2-wide white eyes + navy pupils, pink cheek blush, a
- * U-smile (corners + a 2-wide dropped center), and the signature 2-WIDE
- * orange claws on the body flanks (cols 0-1 / 12-13).
- *
- * History: #133 shrank this to a 9×6 mini (1-wide claws, a single-pixel
- * mouth) — #141 reverted to this faithful 14×9 founder art after it read as
- * "trop loin du 3D".
- *
- * State parity (#135): the CLI carries all 9 canonical AVATAR_STATES with the
- * source's own names — idle · working · celebrating · thumbsup · confused ·
- * wave · heart · sleepy · shocked.
- *
- * See comes-io/trawl_cli#94, #122, #135, #141.
- */
 export type PinchState = 'idle' | 'working' | 'celebrating' | 'thumbsup' | 'confused' | 'wave' | 'heart' | 'sleepy' | 'shocked';
-/** All 9 canonical states, in the source model's AVATAR_STATES order. */
 export declare const PINCH_STATES: readonly PinchState[];
-/**
- * Render Pinch as 24-bit ANSI half-block art for the given state, plus a
- * one-line caption. Pure — never touches process.env/stdout; callers must
- * gate on `pinchEnabled()` before printing the result.
- *
- * `frame` only affects `working` (the cyan antenna-tip blip alternates every
- * frame); every other state's grid is static.
- */
 export declare function renderPinch(state: PinchState, frame?: number): string;
-/**
- * #131 — the ART lines only (no caption), optionally COMPACT: trailing and
- * leading fully-transparent grid rows are dropped so Pinch takes fewer
- * terminal lines (confused/sleepy carry an all-'.' leading row). `frame` is
- * passed through to `gridForState` — only `working` reacts to it (the cyan
- * antenna blip toggles), so the loop can pulse the tips while the body stays
- * still.
- */
 export declare function renderPinchArt(state: PinchState, opts?: {
     compact?: boolean;
     frame?: number;
 }): string;
-/**
- * True when it's safe to print Pinch art: a real color-capable interactive
- * terminal. False under NO_COLOR (https://no-color.org — presence, not
- * value, disables color output), a non-TTY stdout (piped/redirected output —
- * covers --json/--quiet/CI log capture), or TERM=dumb.
- */
 export declare function pinchEnabled(): boolean;