@trawlme/cli 3.0.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/commands/upgrade.js

@@ -2,42 +2,16 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
 import { json } from '../lib/format.js';
+import { PKG_NAME, currentVersion, fetchLatestVersion } from '../lib/version.js';
 const execFileP = promisify(execFile);
-const PKG_NAME = '@trawlme/cli';
-/** The version currently RUNNING — read from this package's own package.json.
- * (At publish time semantic-release stamps the real version into the tarball's
- * package.json, so at runtime this is the installed version; the repo's
- * checked-in value is vestigial.) */
-function currentVersion() {
-    const here = dirname(fileURLToPath(import.meta.url)); // dist/commands
-    const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
-    return pkg.version;
-}
-/** Latest published version from the npm registry. Throws with a friendly
- * message when npm is missing or the registry is unreachable. */
-async function latestVersion() {
-    try {
-        const { stdout } = await execFileP('npm', ['view', PKG_NAME, 'version'], { timeout: 30_000 });
-        return stdout.trim();
-    }
-    catch (err) {
-        const e = err;
-        if (e.code === 'ENOENT')
-            throw new Error('npm was not found on PATH — install Node.js/npm, then run: npm install -g @trawlme/cli@latest');
-        throw new Error(`could not reach the npm registry to check for updates (${e.message})`);
-    }
-}
 export const upgrade = new Command('upgrade')
     .description('Update the trawl CLI itself to the latest published version')
     .option('--check', 'Only report whether an update is available — do not install')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
     const current = currentVersion();
-    const latest = await latestVersion();
+    const latest = await fetchLatestVersion();
     const upToDate = current === latest;
     if (upToDate) {
         if (opts.json)

package/dist/index.js

@@ -16,6 +16,7 @@ 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';
+import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -368,6 +369,23 @@ export async function runCli(argv = process.argv) {
         // Flush + close telemetry before the process exits. A `process.on('exit')`
         // handler cannot reliably run async work, so this must happen here.
         await shutdown();
+        // Passive "update available" notifier (#129) — never on a help/version
+        // query, and each half individually guarded so a notifier bug can never
+        // turn a successful command into a failure or change its exit code.
+        if (!isHelpOrVersion(argv)) {
+            try {
+                maybeNotifyUpdate();
+            }
+            catch {
+                // swallow — see updateNotifier.ts, this is already self-guarded too.
+            }
+            try {
+                scheduleUpdateCheck();
+            }
+            catch {
+                // swallow — background refresh must never affect this invocation.
+            }
+        }
     }
 }
 if (isEntryPoint(process.argv[1], import.meta.url)) {

package/dist/lib/config.d.ts

@@ -4,6 +4,11 @@ interface TrawlConfig {
     token: string;
     telemetry: boolean;
     telemetryUserId: string;
+    /** Opt-out switch for the passive "update available" notifier
+     * (src/lib/updateNotifier.ts). Optional — absent/undefined means enabled;
+     * only an explicit `false` disables it. No default entry needed since it's
+     * optional. (#129) */
+    updateNotifier?: boolean;
 }
 declare const config: Conf<TrawlConfig>;
 /**

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/dist/lib/updateCheckWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/updateCheckWorker.js

@@ -0,0 +1,30 @@
+/**
+ * Standalone worker script spawned DETACHED by scheduleUpdateCheck()
+ * (updateNotifier.ts) to refresh the update-check cache in the background —
+ * this never runs on the CLI's hot path. Invoked as
+ * `node dist/lib/updateCheckWorker.js <cachePath>`, it queries the npm
+ * registry for the latest published version, writes
+ * `{ latest, checkedAt }` to `<cachePath>`, and exits. The NEXT `trawl`
+ * invocation picks up the refreshed cache — this run never waits on it.
+ *
+ * Any failure (npm missing, registry unreachable, cache dir unwritable) exits
+ * silently (code 0) — a failed background refresh must never surface to the
+ * user; the cache simply stays stale until the next stale-check fires.
+ */
+import { execFile } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { PKG_NAME } from './version.js';
+const cachePath = process.argv[2];
+if (cachePath) {
+    execFile('npm', ['view', PKG_NAME, 'version'], { timeout: 30_000 }, (err, stdout) => {
+        if (!err) {
+            try {
+                writeFileSync(cachePath, JSON.stringify({ latest: String(stdout).trim(), checkedAt: Date.now() }));
+            }
+            catch {
+                // Best-effort — a write failure just means the next invocation retries.
+            }
+        }
+        process.exit(0);
+    });
+}

package/dist/lib/updateNotifier.d.ts

@@ -0,0 +1,20 @@
+/** The cache file lives beside the CLI's own `conf` config file — same
+ * directory, no extra config-dir resolution logic to duplicate. */
+export declare function updateCachePath(): string;
+/**
+ * Synchronous, instant — safe to call on every invocation's hot path. Prints
+ * ONE line to stderr when a cached "latest" version is a valid semver
+ * strictly greater than the running version, and every gate holds:
+ * an interactive stderr TTY, no `--json` flag, not a help/version query, and
+ * not opted out (env or config). Any error (bad cache, etc.) is swallowed —
+ * this must never throw.
+ */
+export declare function maybeNotifyUpdate(argv?: string[]): void;
+/**
+ * Non-blocking background refresh. When the cache is missing or older than
+ * CHECK_INTERVAL_MS, spawns a fully detached child (updateCheckWorker.ts)
+ * that queries npm and writes the refreshed cache, then exits — this
+ * invocation never waits on it (`.unref()`), so the refreshed cache is only
+ * ever used by the NEXT invocation. Never throws.
+ */
+export declare function scheduleUpdateCheck(): void;

package/dist/lib/updateNotifier.js

@@ -0,0 +1,150 @@
+/**
+ * Passive "update available" notifier (#129) — follows the `update-notifier`
+ * model: notify from a CACHE, refresh the cache in the BACKGROUND, never
+ * block or slow down the command it hitches a ride on.
+ *
+ * - `maybeNotifyUpdate()` is synchronous and instant — it only ever reads a
+ *   cache file that already exists on disk and prints at most one line to
+ *   stderr. It never talks to the network and never throws.
+ * - `scheduleUpdateCheck()` refreshes that cache for the NEXT invocation by
+ *   spawning a fully detached, unref'd child process
+ *   (src/lib/updateCheckWorker.ts) — this invocation never awaits it.
+ *
+ * Both are called from src/index.ts's `runCli()` finally block, after
+ * `shutdown()`, wrapped so a notifier failure can never turn a successful
+ * command into a failed one.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import config from './config.js';
+import { currentVersion } from './version.js';
+/** Refresh cadence for the background worker — a cache younger than this is
+ * left alone; older (or missing) triggers a detached refresh. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Sibling compiled worker script (dist/lib/updateCheckWorker.js next to this
+ * module's own dist/lib/updateNotifier.js) — resolved relative to THIS
+ * module so it works regardless of cwd or how the CLI was installed. */
+const WORKER_PATH = fileURLToPath(new URL('./updateCheckWorker.js', import.meta.url));
+/** The cache file lives beside the CLI's own `conf` config file — same
+ * directory, no extra config-dir resolution logic to duplicate. */
+export function updateCachePath() {
+    return join(dirname(config.path), 'update-check.json');
+}
+function readCache() {
+    try {
+        const raw = readFileSync(updateCachePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latest !== 'string' || typeof parsed.checkedAt !== 'number')
+            return undefined;
+        return { latest: parsed.latest, checkedAt: parsed.checkedAt };
+    }
+    catch {
+        // Missing file, corrupt JSON, unreadable — treat all the same: no cache.
+        return undefined;
+    }
+}
+/** Opted out via env (presence-based, mirrors NO_COLOR) or an explicit
+ * `false` config value. Absent/undefined config key means enabled. */
+function isOptedOut() {
+    if (process.env['TRAWL_NO_UPDATE_NOTIFIER'] !== undefined)
+        return true;
+    return config.get('updateNotifier') === false;
+}
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+function isValidSemver(v) {
+    return SEMVER_RE.test(v);
+}
+/** Plain MAJOR.MINOR.PATCH comparison — no prerelease/build-metadata support,
+ * consistent with this package's own version scheme (see version.ts). */
+function isGreaterSemver(a, b) {
+    if (!isValidSemver(a) || !isValidSemver(b))
+        return false;
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return true;
+        if (pa[i] < pb[i])
+            return false;
+    }
+    return false;
+}
+/** Best-effort `--json` argv scan — same "argv scan, never trust flag
+ * values" caveat as index.ts's hasJsonFlag: positional values never equal
+ * the literal `--json` string. Kept local (not imported from index.ts) so
+ * this module has no reverse dependency on the entrypoint. */
+function hasJsonFlag(argv) {
+    return argv.includes('--json');
+}
+/** Same shape as index.ts's isHelpOrVersion (bare invocation, `help`,
+ * -h/--help/-V/--version) — kept local for the same reason as hasJsonFlag
+ * above. Belt-and-suspenders: src/index.ts already skips calling this
+ * function entirely on a help/version invocation. */
+function isHelpOrVersionInvocation(argv) {
+    if (argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version'))
+        return true;
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return true;
+    if (args[0] === 'help')
+        return true;
+    return false;
+}
+/**
+ * Synchronous, instant — safe to call on every invocation's hot path. Prints
+ * ONE line to stderr when a cached "latest" version is a valid semver
+ * strictly greater than the running version, and every gate holds:
+ * an interactive stderr TTY, no `--json` flag, not a help/version query, and
+ * not opted out (env or config). Any error (bad cache, etc.) is swallowed —
+ * this must never throw.
+ */
+export function maybeNotifyUpdate(argv = process.argv) {
+    try {
+        if (!process.stderr.isTTY)
+            return;
+        if (hasJsonFlag(argv))
+            return;
+        if (isHelpOrVersionInvocation(argv))
+            return;
+        if (isOptedOut())
+            return;
+        const cache = readCache();
+        if (!cache)
+            return;
+        const current = currentVersion();
+        if (!isGreaterSemver(cache.latest, current))
+            return;
+        console.error(chalk.dim(`↑ Update available: ${current} → ${cache.latest}. Run \`trawl upgrade\`.`));
+    }
+    catch {
+        // Never let the notifier turn a successful command into a failure.
+    }
+}
+/**
+ * Non-blocking background refresh. When the cache is missing or older than
+ * CHECK_INTERVAL_MS, spawns a fully detached child (updateCheckWorker.ts)
+ * that queries npm and writes the refreshed cache, then exits — this
+ * invocation never waits on it (`.unref()`), so the refreshed cache is only
+ * ever used by the NEXT invocation. Never throws.
+ */
+export function scheduleUpdateCheck() {
+    try {
+        if (isOptedOut())
+            return;
+        const cache = readCache();
+        const isStale = !cache || Date.now() - cache.checkedAt > CHECK_INTERVAL_MS;
+        if (!isStale)
+            return;
+        const child = spawn(process.execPath, [WORKER_PATH, updateCachePath()], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        // A failed background-refresh spawn must never affect the caller.
+    }
+}

package/dist/lib/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared version plumbing — the package name + "what version am I" + "what's
+ * published" primitives, used by BOTH `trawl upgrade` (src/commands/upgrade.ts)
+ * and the passive update notifier (src/lib/updateNotifier.ts). Extracted so
+ * neither duplicates the npm-registry lookup or the package.json read (#129).
+ */
+export declare const PKG_NAME = "@trawlme/cli";
+/** The version currently RUNNING — read from this package's own package.json.
+ * (At publish time semantic-release stamps the real version into the tarball's
+ * package.json, so at runtime this is the installed version; the repo's
+ * checked-in value is vestigial.) */
+export declare function currentVersion(): string;
+/** Latest published version from the npm registry. Throws with a friendly
+ * message when npm is missing or the registry is unreachable. */
+export declare function fetchLatestVersion(): Promise<string>;

package/dist/lib/version.js

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const execFileP = promisify(execFile);
+/**
+ * Shared version plumbing — the package name + "what version am I" + "what's
+ * published" primitives, used by BOTH `trawl upgrade` (src/commands/upgrade.ts)
+ * and the passive update notifier (src/lib/updateNotifier.ts). Extracted so
+ * neither duplicates the npm-registry lookup or the package.json read (#129).
+ */
+export const PKG_NAME = '@trawlme/cli';
+/** The version currently RUNNING — read from this package's own package.json.
+ * (At publish time semantic-release stamps the real version into the tarball's
+ * package.json, so at runtime this is the installed version; the repo's
+ * checked-in value is vestigial.) */
+export function currentVersion() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/lib
+    const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}
+/** Latest published version from the npm registry. Throws with a friendly
+ * message when npm is missing or the registry is unreachable. */
+export async function fetchLatestVersion() {
+    try {
+        const { stdout } = await execFileP('npm', ['view', PKG_NAME, 'version'], { timeout: 30_000 });
+        return stdout.trim();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            throw new Error('npm was not found on PATH — install Node.js/npm, then run: npm install -g @trawlme/cli@latest');
+        throw new Error(`could not reach the npm registry to check for updates (${e.message})`);
+    }
+}

package/package.json

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