@trawlme/cli 2.2.0 → 2.4.0

package/README.md

@@ -54,7 +54,7 @@ trawl ping [--json]                            Health/version handshake against
 
 > **No breaking change:** every verb above is also still reachable under its pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`, `trawl scraps run <id>`) — kept as a hidden alias so scripts written before the surface reorg keep working. `trawl --help` only shows the top-level form above; `trawl scraps --help` only shows the remaining scrap-management commands below.
 
-`create`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl create` runs the AI wizard server-side (`POST /api/ai/wizard`): generate scrap code from `--prompt` via LLM, persist the scrap, trigger its FIRST run, and auto-fix on failure (default on — `--no-autofix` disables it, sending `autoFix:false`). `success` is an honest outcome of that first run, not "did the HTTP call succeed" — a failed first run is still a 200 response (the scrap was still created; auto-fix, when enabled, retries in the background), and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. The call legitimately takes 30–250s+ server-side (AI generation + a real run), same long-run timeout as `run`/`data --fresh`/`trigger --wait` below. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
+`create`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl create` runs the AI wizard server-side (`POST /api/ai/wizard`): generate scrap code from `--prompt` via LLM, persist the scrap, trigger its FIRST run, and auto-fix on failure (default on — `--no-autofix` disables it, sending `autoFix:false`). On a successful first run (human mode) it prints a small **data sample** (item count + first-item fields + one truncated value) as proof of value — best-effort, silent if the sample can't be fetched — and points `Next step` at `trawl data <id>` (the data), with `trawl get <id>` as the secondary detail view. `--json` skips the sample fetch and prints the raw wizard payload verbatim. `success` is an honest outcome of that first run, not "did the HTTP call succeed" — a failed first run is still a 200 response (the scrap was still created; auto-fix, when enabled, retries in the background), and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. The call legitimately takes 30–250s+ server-side (AI generation + a real run), same long-run timeout as `run`/`data --fresh`/`trigger --wait` below. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
 
 > **`create` is NOT idempotent, and every wizard-created scrap runs on a DAILY cron by default.** A client-side timeout (exit `5`, a `NetworkError`) does not mean the wizard failed server-side — scrap creation + the first run keep going after the CLI gives up waiting, so the scrap may already exist. Run `trawl list` and look for a matching URL/title **before** retrying — a blind retry creates a DUPLICATE scrap and burns AI-generation quota a second time for the same goal. Separately, the scrap the wizard creates is scheduled to re-run every day at 07:00 UTC (`cron: "0 7 * * *"`, hardcoded server-side, unrelated to `--no-autofix`) — each of those recurring runs consumes execute quota like any other run. Review the generated scrap, then change or disable the schedule with `trawl update <id> --cron <expr>` (or `--no-cron` to disable it). Because the call can legitimately run 250s+, also confirm `TRAWL_TIMEOUT` isn't set to something tighter than `create` needs — the env var always wins over `create`'s own 300s default (see [Environment variables](#environment-variables)), so a value set for another purpose (e.g. a tight CI smoke-test budget) silently clamps `create` too; unset it or raise it before running `create`.
 

package/dist/commands/create.js

@@ -5,6 +5,7 @@ import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
 import { json } from '../lib/format.js';
 import { requireUrl, requireString } from '../lib/validate.js';
 import { UsageError } from '../lib/errors.js';
+import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /** Best-effort, honest first-run summary — never claims a background retry
  * happened when auto-fix was disabled for this call, and never claims a
  * scrap was persisted when the response carries none (#114-F3 — a hard
@@ -50,6 +51,41 @@ function scheduleLabel(scrap) {
     }
     return 'scheduled daily by default';
 }
+/**
+ * #121 — onboarding principle: a successful `create` should SHOW the value,
+ * not just an id. Best-effort fetch of the first run's persisted data (the
+ * same read-only, no-quota path `trawl data <id>` uses:
+ * `GET /api/historys/:historyId` → a JSON string `{ data: [...] }`) and print
+ * a small proof-of-value sample (count + first-item keys + one truncated
+ * value line — never a full dump; that's what `trawl data --json` is for).
+ * ANY failure (network, parse, no data) is swallowed silently — the sample is
+ * a bonus, it must never turn a successful create into a failure or noise.
+ */
+async function printDataSample(historyId) {
+    try {
+        const detail = await api.get(`/api/historys/${historyId}`);
+        if (typeof detail?.data !== 'string' || !detail.data)
+            return;
+        const items = JSON.parse(detail.data)?.data;
+        if (!Array.isArray(items) || items.length === 0)
+            return;
+        console.log(chalk.dim(`  Sample:     `) + `${items.length} item${items.length === 1 ? '' : 's'}`);
+        const first = items[0];
+        if (first && typeof first === 'object') {
+            const keys = Object.keys(first);
+            console.log(chalk.dim(`  Fields:     `) + keys.join(', '));
+            const firstKey = keys[0];
+            if (firstKey) {
+                const raw = String(first[firstKey] ?? '');
+                const val = raw.length > 60 ? `${raw.slice(0, 60)}…` : raw;
+                console.log(chalk.dim(`  ${firstKey.slice(0, 10).padEnd(10)}: `) + val);
+            }
+        }
+    }
+    catch {
+        // best-effort — a missing sample never fails or noises up a good create
+    }
+}
 export const create = new Command('create')
     .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated)')
     .argument('[url]', 'Target public URL (http/https)')
@@ -94,6 +130,14 @@ export const create = new Command('create')
         data = await call();
     }
     else {
+        // #122 — Pinch shows up front, working, while the server-side wizard
+        // runs (legitimately 30-250s+, see LONG_RUN_TIMEOUT_MS above). Belt-
+        // and-suspenders `!opts.json` alongside pinchEnabled(): we're already
+        // inside the non-`--json` branch, but the check is kept explicit here
+        // too so stdout purity under `--json` (#106-F2/#121) never depends on
+        // this code staying inside that branch.
+        if (!opts.json && pinchEnabled())
+            console.log(renderPinch('thinking'));
         try {
             data = await spin(call, {
                 text: `Creating a scrap from ${url}…`,
@@ -137,8 +181,15 @@ export const create = new Command('create')
         console.log(chalk.dim(`  First run:  `) + firstRunLabel(data, autoFixEnabled));
         if (schedule)
             console.log(chalk.dim(`  Schedule:   `) + schedule);
-        if (scrapId)
-            console.log(chalk.dim(`  Next step:  `) + `trawl get ${scrapId}`);
+        // #121 — on a successful first run, prove the value: show a small data
+        // sample (best-effort, silent on failure) before the next-step hint.
+        if (data.success && data.historyId)
+            await printDataSample(data.historyId);
+        // #121 — the natural next command is the DATA, not the metadata: point
+        // at `trawl data` primarily, keep `trawl get` as the secondary detail view.
+        if (scrapId) {
+            console.log(chalk.dim(`  Next step:  `) + `trawl data ${scrapId}` + chalk.dim(`  (details: trawl get ${scrapId})`));
+        }
         // #114-F3 — only claim a background retry is happening when a scrap
         // actually exists to retry (never fabricate progress that isn't real);
         // `firstRunLabel` above already covers the !scrap / autofix-disabled
@@ -150,6 +201,13 @@ export const create = new Command('create')
             console.log(chalk.yellow(`  Note:       `) +
                 `Auto-fix is retrying in the background — do NOT re-run create; poll ${pollTarget}.`);
         }
+        // #122 — Pinch reacts to the HONEST first-run outcome (same signal the
+        // ✓/✗ line above already renders): celebrates a real success, looks
+        // confused on a genuine failure. Belt-and-suspenders `!opts.json`
+        // alongside pinchEnabled() — see the 'thinking' print above for why.
+        if (!opts.json && pinchEnabled()) {
+            console.log(data.success ? renderPinch('celebrating') : renderPinch('confused'));
+        }
     }
     // Honest exit code alongside the honest payload — a --json caller gets
     // the raw body regardless (never wrapped/altered), but a script checking

package/dist/lib/pinch.d.ts

@@ -3,15 +3,21 @@
  * 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.
+ * The 14×9 cube-grid 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, 14 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.
+ * Grids + palette are mirrored from trawl_vue
+ * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
+ * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
+ * package). Claws are 2×2 'O' blocks at cols 0-1 / 12-13, fully outside the
+ * body silhouette (on the sides), per r6f.
+ *
+ * See comes-io/trawl_cli#94, comes-io/trawl_cli#122.
  */
 export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
 /**
@@ -19,8 +25,8 @@ export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
  * 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.
+ * `frame` is accepted for signature stability but currently unused — every
+ * state's grid is static (see `gridForState`).
  */
 export declare function renderPinch(state: PinchState, frame?: number): string;
 /**

package/dist/lib/pinch.js

@@ -3,76 +3,98 @@
  * 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.
+ * The 14×9 cube-grid 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, 14 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.
+ * Grids + palette are mirrored from trawl_vue
+ * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
+ * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
+ * package). Claws are 2×2 'O' blocks at cols 0-1 / 12-13, fully outside the
+ * body silhouette (on the sides), per r6f.
+ *
+ * See comes-io/trawl_cli#94, comes-io/trawl_cli#122.
  */
-/** Grid-char → RGB. 'C' (cyan) is a "thinking" blip, not present in BASE_GRID. */
+/** Grid-char → RGB, ported from AVCOLORS (pinch.model.mjs, rev r6f). */
 const PALETTE = {
-    B: [0x3b, 0x82, 0xf6], // blue — shell
-    O: [0xee, 0x90, 0x18], // orange — antennae / claws
+    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
-    P: [0xf9, 0xa8, 0xd4], // pink — claw tips
-    C: [0x08, 0x91, 0xb2], // cyan — thinking-spinner antenna blip
+    K: [0x12, 0x30, 0x33], // navy — pupils / mouth / blush-adjacent mouth corner
+    P: [0xf4, 0x72, 0xb6], // pink — blush
 };
 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',
-];
+/**
+ * Explicit per-state 14×9 grids, ported verbatim from trawl_vue's
+ * AVATAR_GRIDS (pinch.model.mjs, rev r6f) — no derivation/mutation from a
+ * shared base, so each state stays a straight, auditable copy of its source
+ * grid. CLI state → source grid: wave→wave, thinking→working (a.k.a.
+ * AVGRID/idle), celebrating→celebrating, confused→confused.
+ */
+const GRIDS = {
+    wave: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWBOO',
+        '..BWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBB..',
+        'OOBBBBKKBBBB..',
+        '..............',
+    ],
+    // 'thinking' maps to the source's 'working' grid (identical to 'idle').
+    // The frame param is accepted for signature compatibility but ignored — a
+    // static working frame rather than an animated blip (#122, simplified;
+    // the source has no per-frame "thinking" animation to port).
+    thinking: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBBOO',
+        'OOBBBBKKBBBBOO',
+        '..............',
+    ],
+    celebrating: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        'OOBWWBBBBWWBOO',
+        'OOBWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        '..BBPKKKKPBB..',
+        '..BBBKKKKBBB..',
+        '..............',
+    ],
+    confused: [
+        '..............',
+        '...O......O...',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPBBBBPBBOO',
+        'OOBBBBKKBBBBOO',
+        '..............',
+    ],
+};
 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;
-    }
+/** Look up the grid for `state`. `frame` is accepted (signature stability
+ * for `renderPinch`) but unused — every current state's grid is static. */
+function gridForState(state, _frame) {
+    return GRIDS[state];
 }
 const RESET = '\x1b[0m';
 const fgCode = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
@@ -117,15 +139,17 @@ function renderGrid(rows) {
  * 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.
+ * `frame` is accepted for signature stability but currently unused — every
+ * state's grid is static (see `gridForState`).
  */
 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).
+        // 4-5 pack into terminal line index 2, unchanged by the r6f grid — the
+        // antenna/shell/eye/claw row layout stayed the same, only width + claw
+        // placement changed).
         lines[2] = `${lines[2]}  \x1b[1m?${RESET}`;
     }
     return [...lines, CAPTIONS[state]].join('\n');

package/package.json

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