@trawlme/cli 3.5.1 → 3.6.1

package/dist/commands/scraps.js

@@ -9,6 +9,7 @@ import { classifyError, reportError, UsageError, RefusalError } from '../lib/err
 import { confirmDestructive, isInteractive } from '../lib/confirm.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
+import { maybeShowReferralTip } from '../lib/tips.js';
 /**
  * Print a usage/validation error consistently: human text to stderr, or a
  * machine envelope on stdout under --json (never both — reportError is the
@@ -738,6 +739,20 @@ export function attachRunCommand(parent, attachOpts = {}) {
             // of what the watched run actually did.
             await pollRunProgress(id, beforeRun, { json: opts.json });
         }
+        // #151 — throttled post-run referral tip. Reached only when the
+        // launch call above didn't throw (a hard failure rejects it, unwinding
+        // straight to index.ts's central catch before this line ever runs)
+        // — and, when --watch polled to a terminal state, only when
+        // pollRunProgress didn't flag a genuine run failure/timeout/poll-error
+        // via a non-zero process.exitCode (#107 review F1). See lib/tips.ts
+        // for the throttle/TTY/json/opt-out/server-flag gating itself. #153 —
+        // now async (a due tip fetches the server's userFacing flag before
+        // printing), so this must be awaited: otherwise commander's
+        // parseAsync-driven action would resolve before the tip's own
+        // await settles, racing the process's natural exit.
+        const runFailed = typeof process.exitCode === 'number' && process.exitCode !== 0;
+        if (!runFailed)
+            await maybeShowReferralTip({ json: opts.json });
     });
 }
 attachRunCommand(scraps, { hidden: true });

package/dist/lib/config.d.ts

@@ -9,6 +9,10 @@ interface TrawlConfig {
      * only an explicit `false` disables it. No default entry needed since it's
      * optional. (#129) */
     updateNotifier?: boolean;
+    /** Opt-out switch for the throttled post-run referral tip (lib/tips.ts).
+     * Same optional/absent-means-enabled shape as `updateNotifier` above. */
+    tips?: boolean;
+    referralTipShownAt: number;
 }
 declare const config: Conf<TrawlConfig>;
 /**

package/dist/lib/config.js

@@ -16,6 +16,7 @@ const config = new Conf({
         token: '',
         telemetry: true,
         telemetryUserId: '',
+        referralTipShownAt: 0,
     },
 });
 /**

package/dist/lib/tips.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 declare function isReferralTipDue(opts: {
+    json?: boolean;
+    isTTY: boolean;
+    optedOut: boolean;
+    lastShownAt: number;
+    now: number;
+}): boolean;
+/**
+ * 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 declare function maybeShowReferralTip(opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/lib/tips.js

@@ -0,0 +1,129 @@
+/**
+ * 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 500, you get 1,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;
+    if (!opts.isTTY)
+        return false;
+    if (opts.optedOut)
+        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', {
+            timeoutMs: FLAG_CHECK_TIMEOUT_MS,
+        });
+        return data?.invitations?.userFacing === true;
+    }
+    catch {
+        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;
+        const due = isReferralTipDue({
+            json: opts.json,
+            isTTY: Boolean(process.stdout.isTTY),
+            optedOut: isOptedOut(),
+            lastShownAt,
+            now: Date.now(),
+        });
+        if (!due)
+            return;
+        const userFacing = await isReferralProgramUserFacing();
+        if (!userFacing)
+            return;
+        config.set('referralTipShownAt', Date.now());
+        console.log(chalk.dim(REFERRAL_TIP_TEXT));
+    }
+    catch {
+        // silent — #151/#153: a broken tip must never break a run
+    }
+}

package/package.json

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