@trawlme/cli 3.0.0 → 3.1.0

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/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.1.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {