@trawlme/cli 3.11.0 → 3.12.1

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;

package/dist/lib/pinch.js

@@ -1,46 +1,12 @@
-/**
- * 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.
- */
-/** Grid-char → RGB, ported from AVCOLORS (pinch.model.mjs, rev r6f). 'C'
- * (cyan) is the `working` thinking-blip — not present in any static grid,
- * injected per-frame on the antenna tips. */
 const PALETTE = {
-    B: [0x29, 0x79, 0xff], // blue — shell
-    O: [0xfb, 0x92, 0x3c], // orange — antennae / claws
-    W: [0xff, 0xff, 0xff], // white — eye whites
-    K: [0x12, 0x30, 0x33], // navy — pupils / mouth / blush-adjacent mouth corner
-    P: [0xf4, 0x72, 0xb6], // pink — blush / heart-eyes
-    C: [0x06, 0xb6, 0xd4], // cyan — `working` thinking-blip on the antenna tips
+    B: [0x29, 0x79, 0xff],
+    O: [0xfb, 0x92, 0x3c],
+    W: [0xff, 0xff, 0xff],
+    K: [0x12, 0x30, 0x33],
+    P: [0xf4, 0x72, 0xb6],
+    C: [0x06, 0xb6, 0xd4],
 };
 const TRANSPARENT = '.';
-/** All 9 canonical states, in the source model's AVATAR_STATES order. */
 export const PINCH_STATES = [
     'idle',
     'working',
@@ -52,21 +18,6 @@ export const PINCH_STATES = [
     'sleepy',
     'shocked',
 ];
-/**
- * The founder 2D front avatar grids (`AVATAR_GRIDS`, pinch.model.mjs rev
- * r6f), ported VERBATIM — rows 0-7 of each 9-row grid (the trailing all-'.'
- * pad row 8 is dropped; it only exists to square the SVG canvas). 14 cols,
- * 8 rows → 4 terminal lines. Layout:
- *   rows 0-1  antennae (2 orange, drooped/spread for confused & sleepy)
- *   row  2    head top      (+ claw at cols 0-1/12-13 when RAISED)
- *   rows 3-4  eyes: 2-wide W whites (row 3) + K pupils (row 4)
- *   row  5    head mid
- *   rows 6-7  mouth + blush + the 2-WIDE claws on the flanks
- * The claws are 2×2 O blocks OUTSIDE the body silhouette (cols 0-1 / 12-13),
- * raised to rows 3-4 for celebrating / shocked (and the right claw for
- * wave / thumbsup). The smile is a U: corners K on row 6, a 2-wide center
- * KK on row 7.
- */
 const GRIDS = {
     idle: [
         '....O....O....',
@@ -78,8 +29,6 @@ const GRIDS = {
         'OOBBPKBBKPBBOO',
         'OOBBBBKKBBBBOO',
     ],
-    // idle pose + the cyan thinking-blip on the antenna tips (frame-toggled in
-    // `gridForState`) — the only animated static state.
     working: [
         '....O....O....',
         '....O....O....',
@@ -90,7 +39,6 @@ const GRIDS = {
         'OOBBPKBBKPBBOO',
         'OOBBBBKKBBBBOO',
     ],
-    // both claws raised to rows 3-4 + a big open mouth (rows 6-7).
     celebrating: [
         '....O....O....',
         '....O....O....',
@@ -101,8 +49,6 @@ const GRIDS = {
         '..BBPKKKKPBB..',
         '..BBBKKKKBBB..',
     ],
-    // right claw raised (rows 3-4) + a thumb pixel poking up (row 2, col 12);
-    // left claw resting on the flank (rows 6-7).
     thumbsup: [
         '....O....O....',
         '....O....O....',
@@ -113,8 +59,6 @@ const GRIDS = {
         'OOBBPKBBKPBB..',
         'OOBBBBKKBBBB..',
     ],
-    // antennae drooped + spread (row 1, cols 3 & 10), flat mouth (blush only, no
-    // smile K on row 6), claws resting. A '?' is appended by `renderPinch`.
     confused: [
         '..............',
         '...O......O...',
@@ -125,7 +69,6 @@ const GRIDS = {
         'OOBBPBBBBPBBOO',
         'OOBBBBKKBBBBOO',
     ],
-    // right claw raised (rows 3-4), left claw resting; base face.
     wave: [
         '....O....O....',
         '....O....O....',
@@ -136,8 +79,6 @@ const GRIDS = {
         'OOBBPKBBKPBB..',
         'OOBBBBKKBBBB..',
     ],
-    // pink heart-eyes (P fills both eye blocks, rows 3-4), claws resting, normal
-    // smile.
     heart: [
         '....O....O....',
         '....O....O....',
@@ -148,8 +89,6 @@ const GRIDS = {
         'OOBBPKBBKPBBOO',
         'OOBBBBKKBBBBOO',
     ],
-    // closed eyes (flat K line on row 4, no white), antennae drooped + spread,
-    // flat mouth, claws resting — like confused but eyes shut and no '?'.
     sleepy: [
         '..............',
         '...O......O...',
@@ -160,9 +99,6 @@ const GRIDS = {
         'OOBBPBBBBPBBOO',
         'OOBBBBKKBBBBOO',
     ],
-    // pupils up a row (row 3 carries K, row 4 all white), both claws raised
-    // (rows 3-4), a small round mouth (row 6 only) — startled, not the wide
-    // celebrating grin.
     shocked: [
         '....O....O....',
         '....O....O....',
@@ -185,19 +121,13 @@ const CAPTIONS = {
     sleepy: 'Pinch is sleepy…',
     shocked: 'Pinch is shocked!',
 };
-/** Antenna-tip cells (grid row 0) for the `working` cyan blip: cols 4 & 9. */
 const ANTENNA_TIP_COLS = [4, 9];
-/** Replace the chars at `indices` in `row` with `ch` — never mutates `row`. */
 function setCells(row, indices, ch) {
     const chars = row.split('');
     for (const i of indices)
         chars[i] = ch;
     return chars.join('');
 }
-/** Look up the grid for `state`. `frame` only affects `working`: on even
- * frames its antenna tips blip cyan (the thinking indicator), on odd frames
- * they stay orange — a 2-frame pulse with no layout shift. Every other
- * state's grid is static and ignores `frame`. */
 function gridForState(state, frame) {
     if (state === 'working' && frame % 2 === 0) {
         const rows = [...GRIDS.working];
@@ -209,29 +139,17 @@ function gridForState(state, frame) {
 const RESET = '\x1b[0m';
 const fgCode = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
 const bgCode = ([r, g, b]) => `\x1b[48;2;${r};${g};${b}m`;
-/**
- * One terminal column: combine an upper (fg-half) + lower (bg-half) grid
- * cell into a single half-block character. Either half may be transparent
- * independently — no bg/fg escape is emitted for a transparent half, so the
- * terminal's own background/foreground shows through it.
- */
 function renderCell(upper, lower) {
     const upperColor = upper === TRANSPARENT ? null : PALETTE[upper];
     const lowerColor = lower === TRANSPARENT ? null : PALETTE[lower];
     if (!upperColor && !lowerColor)
         return ' ';
-    // Lower half transparent — draw the upper half-block with fg only, no bg
-    // (the glyph's own unpainted lower half already shows the terminal bg).
     if (!lowerColor)
         return `${fgCode(upperColor)}▀${RESET}`;
-    // Upper half transparent — draw the LOWER half-block glyph instead, with
-    // fg set to the lower color and no bg, so the painted half is the bottom.
     if (!upperColor)
         return `${fgCode(lowerColor)}▄${RESET}`;
     return `${fgCode(upperColor)}${bgCode(lowerColor)}▀${RESET}`;
 }
-/** Pack a grid into terminal lines, 2 grid rows per line (upper=fg, lower=bg).
- * The 14×8 founder grid is 8 rows → 4 lines. */
 function renderGrid(rows) {
     const lines = [];
     for (let i = 0; i < rows.length; i += 2) {
@@ -245,32 +163,14 @@ function renderGrid(rows) {
     }
     return lines;
 }
-/**
- * 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 function renderPinch(state, frame = 0) {
     const grid = gridForState(state, frame);
     const lines = renderGrid(grid);
     if (state === 'confused') {
-        // "beside the art" — a bold '?' to the right of the eye row. The eyes are
-        // grid rows 2-3 (head-top + eye-whites), which pack into terminal line 1.
         lines[1] = `${lines[1]}  \x1b[1m?${RESET}`;
     }
     return [...lines, CAPTIONS[state]].join('\n');
 }
-/**
- * #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 function renderPinchArt(state, opts = {}) {
     let grid = gridForState(state, opts.frame ?? 0);
     if (opts.compact) {
@@ -288,12 +188,6 @@ export function renderPinchArt(state, opts = {}) {
         lines[1] = `${lines[1]}  \x1b[1m?${RESET}`;
     return lines.join('\n');
 }
-/**
- * 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 function pinchEnabled() {
     if (process.env['NO_COLOR'] !== undefined)
         return false;

package/dist/lib/pinchAnimation.d.ts

@@ -1,20 +1,4 @@
 export interface PinchAnimation {
-    /** Stop the loop and erase the whole animation block, leaving the cursor at
-     * its top-left so the caller prints its result on a clean line. Idempotent. */
     stop(): void;
 }
-/**
- * #131 / #139 — show Pinch IN PLACE on STDERR while a long operation runs (the
- * `create` wizard, `--watch`). Pinch stays a STILL `working` sprite; the ONLY
- * animation is the cyan antenna-tip blip pulsing on/off every {@link FRAME_MS}
- * (frame 0 = cyan, frame 1 = orange). The body — mouth, claws, eyes — never
- * moves (the old loop cycled whole poses, which flickered "in every
- * direction"). Redrawn via ANSI cursor moves; `stop()` clears the block.
- *
- * Contract: the CALLER must have already checked `pinchEnabled()` (TTY /
- * !NO_COLOR) and that the command is NOT `--json` — this writes only to
- * STDERR, so stdout stays pure regardless, but the animation is human-only.
- * The interval is `unref()`'d so it can never keep the process alive on its
- * own.
- */
 export declare function startPinchAnimation(statusText: string): PinchAnimation;

package/dist/lib/pinchAnimation.js

@@ -1,32 +1,13 @@
 import chalk from 'chalk';
 import { renderPinchArt } from './pinch.js';
-/** Frame cadence — a calm, ~2/second pulse. The only thing that moves is the
- * cyan antenna blip, so this is intentionally slow: a fast rate on a 2-pixel
- * color change reads as a nervous flicker. */
 const FRAME_MS = 600;
-/**
- * #131 / #139 — show Pinch IN PLACE on STDERR while a long operation runs (the
- * `create` wizard, `--watch`). Pinch stays a STILL `working` sprite; the ONLY
- * animation is the cyan antenna-tip blip pulsing on/off every {@link FRAME_MS}
- * (frame 0 = cyan, frame 1 = orange). The body — mouth, claws, eyes — never
- * moves (the old loop cycled whole poses, which flickered "in every
- * direction"). Redrawn via ANSI cursor moves; `stop()` clears the block.
- *
- * Contract: the CALLER must have already checked `pinchEnabled()` (TTY /
- * !NO_COLOR) and that the command is NOT `--json` — this writes only to
- * STDERR, so stdout stays pure regardless, but the animation is human-only.
- * The interval is `unref()`'d so it can never keep the process alive on its
- * own.
- */
 export function startPinchAnimation(statusText) {
-    // Two frames of the SAME `working` sprite — identical geometry, the antenna
-    // tips just toggle cyan↔orange. Nothing else changes between frames.
     const frames = [
-        renderPinchArt('working', { compact: true, frame: 0 }), // cyan tips
-        renderPinchArt('working', { compact: true, frame: 1 }), // orange tips
+        renderPinchArt('working', { compact: true, frame: 0 }),
+        renderPinchArt('working', { compact: true, frame: 1 }),
     ];
     const artHeight = frames[0].split('\n').length;
-    const totalHeight = artHeight + 1; // + the status line below the art
+    const totalHeight = artHeight + 1;
     const out = process.stderr;
     let i = 0;
     const block = (frame) => `${frame}\n${chalk.dim(statusText)}\n`;
@@ -34,13 +15,11 @@ export function startPinchAnimation(statusText) {
         if (n > 0)
             out.write(`\x1b[${n}A`);
     };
-    // Redraw a frame over the previous one — clear each line to EOL first so a
-    // narrower frame can't leave trailing pixels from a wider one.
     const redraw = (frame) => {
         const lines = `${frame}\n${chalk.dim(statusText)}`.split('\n');
         out.write(lines.map((l) => `\x1b[2K${l}`).join('\n') + '\n');
     };
-    out.write('\x1b[?25l'); // hide cursor for a flicker-free redraw
+    out.write('\x1b[?25l');
     out.write(block(frames[0]));
     const timer = setInterval(() => {
         i += 1;
@@ -56,11 +35,11 @@ export function startPinchAnimation(statusText) {
                 return;
             stopped = true;
             clearInterval(timer);
-            cursorUp(totalHeight); // back to the top of the block
+            cursorUp(totalHeight);
             for (let l = 0; l < totalHeight; l++)
-                out.write('\x1b[2K\n'); // erase each line
-            cursorUp(totalHeight); // back to top so the caller's next print lands here
-            out.write('\x1b[?25h'); // restore the cursor
+                out.write('\x1b[2K\n');
+            cursorUp(totalHeight);
+            out.write('\x1b[?25h');
         },
     };
 }

package/dist/lib/posthog.d.ts

@@ -1,14 +1,5 @@
 export declare const initPostHog: () => void;
-/**
- * Register the complete set of valid "<parent> <name>" telemetry tokens,
- * derived from the actual commander command tree (see resolveCommandName /
- * collectCommandNames in src/index.ts). captureCommand refuses any command
- * string outside this set — defense in depth so free-form user input (argv
- * operands, flag values) can never reach PostHog as the event name, even if a
- * future change accidentally reintroduces argv-derived naming.
- */
 export declare const registerAllowedCommands: (names: readonly string[]) => void;
 export declare const captureCommand: (command: string, props?: Record<string, unknown>) => void;
 export declare const shutdown: () => Promise<void>;
-/** Reset singleton state — for testing only */
 export declare const _resetForTesting: () => void;

package/dist/lib/posthog.js

@@ -6,28 +6,17 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import config from './config.js';
-// public-by-design — cf memory feedback_public_keys_in_config.md
 const POSTHOG_KEY = 'phc_pGgSLivbq8rDZzXC9trWWJG7sBjNghXeTJjETzBcnEDv';
 const POSTHOG_HOST = 'https://eu.i.posthog.com';
-// Fail fast: a firewalled/offline endpoint must never add tens of seconds of
-// trailing latency to a CLI command. Library defaults are requestTimeout 10s x
-// 3 retries at a 3s delay (~40s+ worst case per call), and a 30s shutdown
-// ceiling on top of that — cap all three low.
 const REQUEST_TIMEOUT_MS = 3000;
 const FETCH_RETRY_COUNT = 1;
 const FETCH_RETRY_DELAY_MS = 250;
-// A touch above one request + one retry, so the shutdown-time flush has room
-// to complete normally without inheriting the library's 30s default ceiling.
 const SHUTDOWN_TIMEOUT_MS = 8000;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 let client = null;
 let distinctId = null;
 let allowedCommands = new Set();
-/**
- * Cross-vendor opt-out (https://consoledonottrack.com) on top of the existing
- * config/env gates. Any one of these disables telemetry entirely.
- */
 function isTelemetryDisabled() {
     return (config.get('telemetry') === false ||
         process.env['TRAWL_TELEMETRY'] === '0' ||
@@ -39,7 +28,6 @@ export const initPostHog = () => {
     const isFirstRun = !config.get('telemetryUserId');
     if (isFirstRun) {
         config.set('telemetryUserId', `cli_${crypto.randomUUID()}`);
-        // One-time disclosure — telemetry is on by default and otherwise silent.
         console.error(chalk.dim('ℹ Trawl CLI collects anonymous usage telemetry (no credentials or command arguments). ' +
             'Opt out: trawl telemetry off, TRAWL_TELEMETRY=0, or DO_NOT_TRACK=1.'));
     }
@@ -53,14 +41,6 @@ export const initPostHog = () => {
         fetchRetryDelay: FETCH_RETRY_DELAY_MS,
     });
 };
-/**
- * Register the complete set of valid "<parent> <name>" telemetry tokens,
- * derived from the actual commander command tree (see resolveCommandName /
- * collectCommandNames in src/index.ts). captureCommand refuses any command
- * string outside this set — defense in depth so free-form user input (argv
- * operands, flag values) can never reach PostHog as the event name, even if a
- * future change accidentally reintroduces argv-derived naming.
- */
 export const registerAllowedCommands = (names) => {
     allowedCommands = new Set(names);
 };
@@ -83,12 +63,9 @@ export const captureCommand = (command, props = {}) => {
     });
 };
 export const shutdown = async () => {
-    // Explicit ceiling — client.shutdown() otherwise defaults to a 30s internal
-    // race, which would undercut the whole point of capping request/retry time.
     if (client)
         await client.shutdown(SHUTDOWN_TIMEOUT_MS);
 };
-/** Reset singleton state — for testing only */
 export const _resetForTesting = () => {
     client = null;
     distinctId = null;

package/dist/lib/prompt.js

@@ -12,27 +12,19 @@ export async function promptPassword(prompt) {
                 process.stdin.removeListener('data', onData);
             };
             const onData = (chunk) => {
-                // A stdin chunk is NOT a single keystroke. Terminals deliver a paste as
-                // one chunk (Windows Terminal always chunk-pastes), and a paste that
-                // ends in a newline embeds a literal \r mid-chunk. Iterate per code
-                // point so an embedded Enter finalizes the password instead of being
-                // appended to it and hanging for a second Enter. (#73)
                 for (const char of chunk) {
                     if (char === '\r' || char === '\n') {
                         restore();
                         process.stderr.write('\n');
                         resolve(password);
-                        return; // ignore anything after the first terminator
+                        return;
                     }
                     if (char === '') {
-                        // Ctrl+C: restore the terminal and terminate the line before
-                        // exiting so the shell prompt isn't left mid-line. 130 = 128+SIGINT.
                         restore();
                         process.stderr.write('\n');
                         process.exit(130);
                     }
                     if (char === '' || char === '\b') {
-                        // Backspace
                         password = password.slice(0, -1);
                     }
                     else {
@@ -43,17 +35,6 @@ export async function promptPassword(prompt) {
             process.stdin.on('data', onData);
         }
         else {
-            // Non-TTY fallback (e.g. piped input in CI). If stdin closes (EOF)
-            // before an answer arrives — e.g. `trawl login < /dev/null` — the
-            // `question` callback never fires; without a `close` handler the
-            // promise hangs forever and the process exits 0 without logging in.
-            // Reject loudly instead. (#68)
-            //
-            // No `output` is wired to the interface: readline echoes typed input
-            // whenever its output is a TTY, so `trawl login < creds` run from a real
-            // terminal would print the password. Omitting output (and terminal:false)
-            // guarantees the secret is never echoed. The prompt itself was already
-            // written to stderr above. (#73)
             import('readline').then(({ createInterface }) => {
                 const rl = createInterface({ input: process.stdin, terminal: false });
                 let answered = false;

package/dist/lib/secure-transport.d.ts

@@ -0,0 +1 @@
+export declare function assertSecureTransport(apiUrl: string): string | null;

package/dist/lib/secure-transport.js

@@ -0,0 +1,15 @@
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost']);
+export function assertSecureTransport(apiUrl) {
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol === 'https:')
+        return null;
+    if (LOOPBACK_HOSTS.has(url.hostname.toLowerCase()))
+        return null;
+    return `The configured API URL (${url.origin}) is not https: — a captured/uploaded browser session is a bearer-equivalent secret and this command refuses to send it in cleartext. An https:// API URL is accepted (trawl login --url https://…); so is any URL on 127.0.0.1, ::1, or localhost, for local testing.`;
+}