@trawlme/cli 3.1.0 → 3.2.0

package/dist/commands/create.js

@@ -6,6 +6,7 @@ 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';
+import { startPinchAnimation } from '../lib/pinchAnimation.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
@@ -130,24 +131,25 @@ 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'));
+        // #122/#131 — while the server-side wizard runs (legitimately 30-250s+,
+        // see LONG_RUN_TIMEOUT_MS above) Pinch ANIMATES in place (claw-wiggle)
+        // on a color-capable TTY; otherwise the ora spinner (which itself
+        // no-ops under a non-TTY, so piped human output stays clean). Both
+        // write to stderr only — stdout purity under `--json` is guaranteed by
+        // the `opts.json` branch above, never by this code.
+        const anim = pinchEnabled() ? startPinchAnimation(`Creating a scrap from ${url}…`) : null;
         try {
-            data = await spin(call, {
-                text: `Creating a scrap from ${url}…`,
-                // No verdict symbol here (#106-F3) — ora's success only means "the
-                // HTTP call didn't throw", not "the first run succeeded". The real
-                // outcome renders below via the icon + the First run: line.
-                successText: 'Request complete',
-            });
+            data = anim
+                ? await call()
+                : await spin(call, {
+                    // No verdict symbol (#106-F3) — ora's success only means "the
+                    // HTTP call didn't throw", not "the first run succeeded".
+                    text: `Creating a scrap from ${url}…`,
+                    successText: 'Request complete',
+                });
         }
         catch (err) {
+            anim?.stop();
             // #114-F1 — a client-side timeout (NetworkError, "timed out after
             // …ms" per api.ts's safeFetch) does NOT mean the wizard failed
             // server-side: the scrap creation + first run keep going on the
@@ -165,6 +167,9 @@ export const create = new Command('create')
             // stays intact (this stays a NetworkError -> exit 5, same as before).
             throw err;
         }
+        // Success — stop + erase the animation so the result prints on a clean
+        // line (the celebrating/confused frame below is the one-shot outcome).
+        anim?.stop();
     }
     if (opts.json) {
         json(data);

package/dist/lib/pinch.d.ts

@@ -29,6 +29,23 @@ export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
  * state's grid is static (see `gridForState`).
  */
 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 (the r6f grids carry an all-'.' bottom row + blank-ish
+ * antenna padding). Used by the animation loop, where a caption + full
+ * height would be too heavy for a frame redrawn every ~380ms.
+ */
+export declare function renderPinchArt(state: PinchState, opts?: {
+    compact?: boolean;
+}): string;
+/**
+ * #131 — frame sequence for the "working" animation shown during long waits
+ * (the `create` wizard, `--watch`). Reuses the existing r6f state grids: the
+ * claws pump up (wave → celebrating) and back down, reading as Pinch busily
+ * waving while it works. No new art — just an order over the grids we have.
+ */
+export declare const WORKING_FRAMES: readonly PinchState[];
 /**
  * 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

package/dist/lib/pinch.js

@@ -154,6 +154,37 @@ export function renderPinch(state, frame = 0) {
     }
     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 (the r6f grids carry an all-'.' bottom row + blank-ish
+ * antenna padding). Used by the animation loop, where a caption + full
+ * height would be too heavy for a frame redrawn every ~380ms.
+ */
+export function renderPinchArt(state, opts = {}) {
+    let grid = gridForState(state, 0);
+    if (opts.compact) {
+        const blank = (row) => [...row].every((c) => c === TRANSPARENT);
+        let start = 0;
+        let end = grid.length;
+        while (end > start && blank(grid[end - 1]))
+            end--;
+        while (start < end && blank(grid[start]))
+            start++;
+        grid = grid.slice(start, end);
+    }
+    const lines = renderGrid(grid);
+    if (state === 'confused')
+        lines[2] = `${lines[2]}  \x1b[1m?${RESET}`;
+    return lines.join('\n');
+}
+/**
+ * #131 — frame sequence for the "working" animation shown during long waits
+ * (the `create` wizard, `--watch`). Reuses the existing r6f state grids: the
+ * claws pump up (wave → celebrating) and back down, reading as Pinch busily
+ * waving while it works. No new art — just an order over the grids we have.
+ */
+export const WORKING_FRAMES = ['thinking', 'wave', 'celebrating', 'wave'];
 /**
  * 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

package/dist/lib/pinchAnimation.d.ts

@@ -0,0 +1,17 @@
+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 — animate Pinch (a claw-wiggle over the r6f grids) IN PLACE on STDERR
+ * while a long operation runs (the `create` wizard, `--watch`). The frame is
+ * redrawn every {@link FRAME_MS} via ANSI cursor moves; `stop()` clears it.
+ *
+ * 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

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import { renderPinchArt, WORKING_FRAMES } from './pinch.js';
+/** Frame cadence — slow enough to read as a wave, fast enough to feel alive. */
+const FRAME_MS = 380;
+/**
+ * #131 — animate Pinch (a claw-wiggle over the r6f grids) IN PLACE on STDERR
+ * while a long operation runs (the `create` wizard, `--watch`). The frame is
+ * redrawn every {@link FRAME_MS} via ANSI cursor moves; `stop()` clears it.
+ *
+ * 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) {
+    const frames = WORKING_FRAMES.map((s) => renderPinchArt(s, { compact: true }));
+    const artHeight = frames[0].split('\n').length;
+    const totalHeight = artHeight + 1; // + the status line below the art
+    const out = process.stderr;
+    let i = 0;
+    const block = (frame) => `${frame}\n${chalk.dim(statusText)}\n`;
+    const cursorUp = (n) => {
+        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(block(frames[0]));
+    const timer = setInterval(() => {
+        i += 1;
+        cursorUp(totalHeight);
+        redraw(frames[i % frames.length]);
+    }, FRAME_MS);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            cursorUp(totalHeight); // back to the top of the block
+            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
+        },
+    };
+}

package/package.json

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