@trawlme/cli 3.12.0 → 3.12.2

package/dist/lib/tips.js

@@ -1,44 +1,14 @@
-/**
- * Throttled post-run referral tip (#151) — after a successful `trawl run`,
- * occasionally invite the user to refer a builder. Mirrors
- * lib/updateNotifier.ts's shape: self-guarded so a broken tip can never turn
- * a successful command into a failed one. Async since #153 — printing is
- * additionally gated on a server-side flag fetch (see
- * isReferralProgramUserFacing below).
- */
 import chalk from 'chalk';
 import config from './config.js';
 import { api } from './api.js';
-/** Max once per 7 days. */
 const TIP_THROTTLE_MS = 7 * 24 * 60 * 60 * 1000;
-/**
- * #153 — checked only once the 7-day throttle window is already open
- * (isReferralTipDue === true), so a run that isn't due for the tip anyway
- * never pays a network round-trip. ≤2s so a slow/dead server can never
- * perceptibly slow a run down.
- */
 const FLAG_CHECK_TIMEOUT_MS = 2_000;
 const REFERRAL_TIP_TEXT = 'Invite a builder — they get 1,500, you get 3,000 compute → trawl.me → account → Referrals';
-/**
- * Opted out via env (presence-based, mirrors NO_COLOR / the update
- * notifier's TRAWL_NO_UPDATE_NOTIFIER — see lib/updateNotifier.ts) or an
- * explicit `false` config value. Absent/undefined config key means enabled.
- */
 function isOptedOut() {
     if (process.env['TRAWL_NO_TIPS'] !== undefined)
         return true;
     return config.get('tips') === false;
 }
-/**
- * Pure gate: true when the tip should print. Every external signal (json
- * flag, TTY-ness, opt-out, persisted timestamp, current time) is a
- * parameter rather than read internally, so this is trivially testable
- * without mocking process.env/stdout/Date/config. Does NOT cover the
- * server-side `invitations.userFacing` flag (#153) — that check requires a
- * network round-trip, so it's kept out of this pure/sync gate and only
- * consulted once this gate is already true (see
- * isReferralProgramUserFacing + maybeShowReferralTip below).
- */
 export function isReferralTipDue(opts) {
     if (opts.json)
         return false;
@@ -48,24 +18,6 @@ export function isReferralTipDue(opts) {
         return false;
     return opts.now - opts.lastShownAt >= TIP_THROTTLE_MS;
 }
-/**
- * Server-side kill switch (#153) — the web nudge and the digest email
- * footer both gate on the same `invitations.userFacing` flag (trawl_node
- * modules/auth/controllers/auth.controller.js `getConfig`,
- * config/defaults/*.config.js), so if it's ever flipped off for abuse
- * mitigation the CLI must stop promising a referral program that isn't
- * actually reachable. `api.publicGet` resolves the request's base URL the
- * exact same way every other CLI API call does (getApiUrl() in
- * lib/config.ts — TRAWL_API_URL env > stored `trawl login --url` >
- * default) and never requires a token, matching this endpoint's public/
- * unauthenticated contract (mirrors `trawl ping`'s use of the same
- * helper for GET /api/health).
- *
- * ANY failure — network error, timeout (FLAG_CHECK_TIMEOUT_MS), or a
- * malformed/unexpected response shape — is indistinguishable from "flag
- * off" here: resolves to false, never throws, never retries. A slow or
- * broken server must never slow down or break a run.
- */
 async function isReferralProgramUserFacing() {
     try {
         const data = await api.publicGet('/api/auth/config', {
@@ -77,34 +29,6 @@ async function isReferralProgramUserFacing() {
         return false;
     }
 }
-/**
- * Best-effort: print one subtle line inviting the user to refer a builder,
- * throttled to once per 7 days via a timestamp persisted in the CLI's
- * existing Conf-backed config store (lib/config.ts — same store as
- * apiUrl/token/telemetry/updateNotifier), AND gated on the server's
- * `invitations.userFacing` flag (#153) once that throttle window is open.
- *
- * This only gates on throttle/TTY/`--json`/opt-out/server-flag — it does
- * NOT know whether the underlying command actually succeeded. Callers must
- * only invoke it on a genuine success (see commands/scraps.ts `run <id>`'s
- * action, which also checks pollRunProgress's exit code under `--watch`
- * before calling this). Any state read/write/network failure (corrupt
- * config file, disk error, unreachable server, …) is swallowed silently —
- * a broken tip must never break a run.
- *
- * #153 — the timestamp is now persisted BEFORE the print (#151 originally
- * had it after). Two overlapping calls that both read `due=true` before
- * either has persisted can still both decide to print (a file-based config
- * store can't fully arbitrate that without a lock this feature doesn't
- * warrant) — but persist-before-print closes the narrower, guaranteed-
- * recurring failure mode: previously, if the print succeeded but the
- * subsequent config.set failed (or simply hadn't landed yet when a second
- * call read the same stale timestamp), the tip could print again on every
- * later run forever, since the "already shown" state never advanced. With
- * persist first, a lost race collapses to "tip skipped this time, timestamp
- * still unset, next due window free to retry" — never a guaranteed
- * repeat print.
- */
 export async function maybeShowReferralTip(opts = {}) {
     try {
         const lastShownAt = config.get('referralTipShownAt') || 0;
@@ -124,6 +48,5 @@ export async function maybeShowReferralTip(opts = {}) {
         console.log(chalk.dim(REFERRAL_TIP_TEXT));
     }
     catch {
-        // silent — #151/#153: a broken tip must never break a run
     }
 }

package/dist/lib/updateCheckWorker.js

@@ -1,16 +1,3 @@
-/**
- * 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';
@@ -22,7 +9,6 @@ if (cachePath) {
                 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

@@ -1,20 +1,3 @@
-/** 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

@@ -1,19 +1,3 @@
-/**
- * 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';
@@ -21,15 +5,8 @@ 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');
 }
@@ -42,12 +19,9 @@ function readCache() {
         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;
@@ -57,8 +31,6 @@ 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;
@@ -72,17 +44,9 @@ function isGreaterSemver(a, b) {
     }
     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;
@@ -93,14 +57,6 @@ function isHelpOrVersionInvocation(argv) {
         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)
@@ -120,16 +76,8 @@ export function maybeNotifyUpdate(argv = process.argv) {
         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())
@@ -145,6 +93,5 @@ export function scheduleUpdateCheck() {
         child.unref();
     }
     catch {
-        // A failed background-refresh spawn must never affect the caller.
     }
 }

package/dist/lib/validate.d.ts

@@ -2,12 +2,4 @@ export declare function validateObjectId(id: string): void;
 export declare function requireString(value: unknown, name: string): string;
 export declare function requireUrl(value: unknown, name: string): string;
 export declare function requireJwt(value: unknown, name: string): string;
-/**
- * Like requireJwt, but also rejects a JWT whose `exp` claim has already
- * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
- * not print "✓ Logged in" for a token that can't actually authenticate.
- * A JWT with an undecodable/opaque payload is let through (we can't prove
- * it's expired), mirroring `trawl token`'s advisory-only handling of the
- * same case. (#68)
- */
 export declare function requireFreshJwt(value: unknown, name: string): string;

package/dist/lib/validate.js

@@ -33,14 +33,6 @@ export function requireJwt(value, name) {
     }
     return str;
 }
-/**
- * Like requireJwt, but also rejects a JWT whose `exp` claim has already
- * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
- * not print "✓ Logged in" for a token that can't actually authenticate.
- * A JWT with an undecodable/opaque payload is let through (we can't prove
- * it's expired), mirroring `trawl token`'s advisory-only handling of the
- * same case. (#68)
- */
 export function requireFreshJwt(value, name) {
     const jwt = requireJwt(value, name);
     const exp = decodeExp(jwt);

package/dist/lib/version.d.ts

@@ -1,15 +1,3 @@
-/**
- * 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

@@ -4,24 +4,12 @@ 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 here = dirname(fileURLToPath(import.meta.url));
     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 });

package/docs/agent-quickstart.md

@@ -43,14 +43,14 @@ underlying `html-snapshot` route is JWT-only even though the scrap lookup it
 starts from isn't) — nor the standalone SSE **command** `scraps watch`.
 Those, plus `whoami`, stay JWT-only. `scraps account status`, `scraps
 doctor`, and `scraps autofix` are the exceptions inside that same
-management-tier group: all three only ever read routes trawl_node opened to
+management-tier group: all three only ever read routes the API opened to
 keys (`GET /api/scraps/:id`, `GET /api/historys/:hid`, `GET
 /api/scraps/:id/activities`), so all three work fine under a key. (`scraps
 watch` is a separate command, not the same thing as the `--watch` polling
 flag on `run`/`trigger` below, which works fine under a key — do not
 conflate the two.)
 
-This list mirrors trawl_node's route wiring as of this writing, not a
+This list mirrors the server's route wiring as of this writing, not a
 permanent contract — a route's auth mode can change on either side without
 this doc catching up same-day. Don't trust the list blind for a command not
 named above: the reliable check is the real `--json` envelope, every time —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "3.12.0",
+  "version": "3.12.2",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "url": "https://github.com/comes-io/trawl_cli/issues"
   },
   "dependencies": {
-    "@trawlme/skills": "1.3.4",
+    "@trawlme/skills": "1.4.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "conf": "^15.1.0",