@trawlme/cli 1.18.7 → 1.19.1

package/README.md

@@ -83,7 +83,7 @@ trawl scraps account session set <id> -c <file>
 
 ### Claude Code skills
 
-The CLI bundles a Claude Code skill that teaches Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
+The CLI bundles 5 Claude Code skills that teach Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
 
 ```
 trawl skills list                                     List bundled skills and install status

package/dist/commands/scraps.js

@@ -7,6 +7,7 @@ import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
 import { classifyError, reportError, UsageError } from '../lib/errors.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
+import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /**
  * Print a usage/validation error consistently: human text to stderr, or a
  * machine envelope on stdout under --json (never both — reportError is the
@@ -242,6 +243,14 @@ export async function pollRunProgress(id, before, opts = {}) {
         if (last.status !== null) {
             const outcome = last.statusDetail ?? (last.status ? 'success' : 'failure');
             console.log(chalk.dim(`Run finished: ${outcome}`));
+            // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
+            // `status === true` success definition (regardless of statusDetail),
+            // never for a failed/regression run. Neither `run --watch` nor
+            // `trigger --watch` (the only two callers) has a --json flag, so this
+            // is always safe to print. Guarded by pinchEnabled() (NO_COLOR/non-TTY).
+            if (last.status === true && pinchEnabled()) {
+                console.log(renderPinch('celebrating'));
+            }
             return;
         }
     }

package/dist/index.d.ts

@@ -24,7 +24,18 @@ export declare function resolveCommandName(actionCommand: Command | undefined):
  */
 export declare function collectCommandNames(root: Command): string[];
 export declare function createProgram(): Command;
-/** True when this module is the process entrypoint (not merely imported by a test). */
+/**
+ * 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
@@ -36,6 +47,15 @@ export declare function isEntryPoint(argv1: string | undefined, moduleUrl: strin
  * 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;
 /** 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

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from 'commander';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
@@ -11,6 +11,7 @@ import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
 import { classifyError, reportError } from './lib/errors.js';
+import { renderPinch, pinchEnabled } from './lib/pinch.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -73,9 +74,27 @@ export function createProgram() {
     program.addCommand(token);
     return program;
 }
-/** True when this module is the process entrypoint (not merely imported by a test). */
+/**
+ * True when this module is the process entrypoint (not merely imported by a test).
+ *
+ * npm installs the global bin as a SYMLINK (`bin/trawl` -> `dist/index.js`). For an
+ * ESM entrypoint Node realpaths the module URL (`import.meta.url` = the real
+ * `dist/index.js`) but leaves `process.argv[1]` as the symlink path — so a raw
+ * `moduleUrl === pathToFileURL(argv1).href` compare is FALSE for the normal global
+ * invocation, the guard never fires, and `runCli()` never runs (silent no-op, #103).
+ * Canonicalise both sides with `realpathSync` before comparing. A genuine entrypoint
+ * was just loaded by Node, so both realpath calls resolve; the catch only trips for a
+ * non-file module URL (exotic loaders) — correctly "not the entrypoint".
+ */
 export function isEntryPoint(argv1, moduleUrl) {
-    return argv1 !== undefined && moduleUrl === pathToFileURL(argv1).href;
+    if (argv1 === undefined)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argv1);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * True when the invocation is a pure `--help`/`--version` query, a bare
@@ -96,6 +115,17 @@ export function isHelpOrVersion(argv) {
         return true;
     return false;
 }
+/**
+ * True for a bare `trawl` invocation — no subcommand, no flags at all. This
+ * is the CLI's "first thing a new user sees" moment (commander prints its
+ * own top-level help right after), distinct from `isHelpOrVersion` which is
+ * intentionally broader (also matches `--help`/`--version`/`trawl help`
+ * anywhere in argv) — the Pinch wave banner (#94) only wants the narrowest
+ * case so it never shows up ahead of e.g. `trawl scraps --help`.
+ */
+export function isBareInvocation(argv) {
+    return argv.slice(2).length === 0;
+}
 /** 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
@@ -171,6 +201,12 @@ export function bestEffortCommandName(argv, allowedNames) {
 export async function runCli(argv = process.argv) {
     if (!isHelpOrVersion(argv))
         autoUpdateInstalledSkills();
+    // Pinch wave banner (#94) — bare `trawl` only, guarded so it never shows
+    // under NO_COLOR/non-TTY/piped output (pinchEnabled() covers all three).
+    if (isBareInvocation(argv) && pinchEnabled()) {
+        console.log(renderPinch('wave'));
+        console.log();
+    }
     initPostHog();
     const program = createProgram();
     // Must run before parseAsync — installs on every node in the tree,
@@ -270,6 +306,12 @@ export async function runCli(argv = process.argv) {
             // (stderr), never both; `quiet` skips the human line when the raw
             // stack was already dumped above under --debug.
             process.exitCode = reportError(err, { json: wantsJson, quiet: isDebug });
+            // Pinch confused frame (#94) — never under --json (stdout must stay
+            // pure JSON) and guarded by pinchEnabled() (NO_COLOR/non-TTY/piped).
+            // Printed to stderr, alongside reportError's own human line above.
+            if (!wantsJson && pinchEnabled()) {
+                console.error(renderPinch('confused'));
+            }
         }
     }
     finally {

package/dist/lib/pinch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ *
+ * The 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) is packed two
+ * grid 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). A
+ * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
+ * are transparent — no color escape is emitted for that half, so the
+ * terminal's own background shows through.
+ *
+ * See comes-io/trawl_cli#94.
+ */
+export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
+/**
+ * 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 'thinking' (2-frame spinner alternation); every other
+ * state ignores it.
+ */
+export declare function renderPinch(state: PinchState, 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

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ *
+ * The 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) is packed two
+ * grid 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). A
+ * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
+ * are transparent — no color escape is emitted for that half, so the
+ * terminal's own background shows through.
+ *
+ * See comes-io/trawl_cli#94.
+ */
+/** Grid-char → RGB. 'C' (cyan) is a "thinking" blip, not present in BASE_GRID. */
+const PALETTE = {
+    B: [0x3b, 0x82, 0xf6], // blue — shell
+    O: [0xee, 0x90, 0x18], // orange — antennae / claws
+    W: [0xff, 0xff, 0xff], // white — eye whites
+    K: [0x12, 0x30, 0x33], // navy — pupils / mouth
+    P: [0xf9, 0xa8, 0xd4], // pink — claw tips
+    C: [0x08, 0x91, 0xb2], // cyan — thinking-spinner antenna blip
+};
+const TRANSPARENT = '.';
+/** Base 12×9 grid — Pinch waving (also the 'wave' state, unmodified). */
+const BASE_GRID = [
+    '...O....O...',
+    '...O....O...',
+    '.BBBBBBBBBB.',
+    '.BWWBBBBWWB.',
+    '.BWKBBBBKWB.',
+    '.PBBBBBBBBP.',
+    '.BBBKBBKBBB.',
+    '.BBBBKKBBBB.',
+    'OO........OO',
+];
+const CAPTIONS = {
+    wave: 'Pinch says hi.',
+    thinking: 'Pinch is thinking…',
+    celebrating: 'Pinch is celebrating!',
+    confused: 'Pinch looks confused.',
+};
+/** 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('');
+}
+/** Derive the per-state grid from BASE_GRID (which is never mutated). */
+function gridForState(state, frame) {
+    const rows = [...BASE_GRID];
+    switch (state) {
+        case 'thinking':
+            // Odd frames: both antenna tips (row 0, cols 3 & 8) blip cyan — a
+            // 2-frame spinner alternation with no layout shift.
+            if (frame % 2 === 1) {
+                rows[0] = setCells(rows[0], [3, 8], 'C');
+            }
+            return rows;
+        case 'celebrating':
+            // Fists up: the row-8 corner claws move up to row 7's corners; row 8's
+            // corners go transparent (arms raised, no longer at the sides).
+            rows[7] = setCells(rows[7], [0, 11], 'O');
+            rows[8] = setCells(rows[8], [0, 1, 10, 11], TRANSPARENT);
+            return rows;
+        case 'confused':
+            // Pupils removed (row 4, cols 3 & 8) — blank white eyes.
+            rows[4] = setCells(rows[4], [3, 8], 'W');
+            return rows;
+        case 'wave':
+        default:
+            return rows;
+    }
+}
+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 9-row grid into 5 terminal lines (rows 0-1, 2-3, 4-5, 6-7, 8-blank). */
+function renderGrid(rows) {
+    const lines = [];
+    for (let i = 0; i < rows.length; i += 2) {
+        const upperRow = rows[i];
+        const lowerRow = rows[i + 1] ?? TRANSPARENT.repeat(upperRow.length);
+        let line = '';
+        for (let c = 0; c < upperRow.length; c++) {
+            line += renderCell(upperRow[c], lowerRow[c]);
+        }
+        lines.push(line);
+    }
+    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 'thinking' (2-frame spinner alternation); every other
+ * state ignores it.
+ */
+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 (grid rows
+        // 4-5 pack into terminal line index 2).
+        lines[2] = `${lines[2]}  \x1b[1m?${RESET}`;
+    }
+    return [...lines, CAPTIONS[state]].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;
+    if (!process.stdout.isTTY)
+        return false;
+    if (process.env['TERM'] === 'dumb')
+        return false;
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.18.7",
+  "version": "1.19.1",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {