@trawlme/cli 3.6.0 → 3.6.1

package/dist/commands/scraps.js

@@ -745,10 +745,14 @@ export function attachRunCommand(parent, attachOpts = {}) {
         // — 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 gating itself.
+        // 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)
-            maybeShowReferralTip({ json: opts.json });
+            await maybeShowReferralTip({ json: opts.json });
     });
 }
 attachRunCommand(scraps, { hidden: true });

package/dist/lib/tips.d.ts

@@ -2,7 +2,11 @@
  * 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.
+ * 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;
@@ -15,16 +19,30 @@ export declare function isReferralTipDue(opts: {
  * 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).
+ * 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 — 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
+ * 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 failure (corrupt config file,
- * disk error, …) is swallowed silently — a broken tip must never break a
- * run.
+ * 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;
-}): void;
+}): Promise<void>;

package/dist/lib/tips.js

@@ -1,13 +1,23 @@
 /**
  * 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: synchronous, instant, self-guarded so a
- * broken tip can never turn a successful command into a failed one.
+ * 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
@@ -23,7 +33,11 @@ function isOptedOut() {
  * 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.
+ * 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)
@@ -34,21 +48,64 @@ 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', {
+            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).
+ * 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 — 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
+ * 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 failure (corrupt config file,
- * disk error, …) is swallowed silently — a broken tip must never break a
- * run.
+ * 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 function maybeShowReferralTip(opts = {}) {
+export async function maybeShowReferralTip(opts = {}) {
     try {
         const lastShownAt = config.get('referralTipShownAt') || 0;
         const due = isReferralTipDue({
@@ -60,10 +117,13 @@ export function maybeShowReferralTip(opts = {}) {
         });
         if (!due)
             return;
-        console.log(chalk.dim(REFERRAL_TIP_TEXT));
+        const userFacing = await isReferralProgramUserFacing();
+        if (!userFacing)
+            return;
         config.set('referralTipShownAt', Date.now());
+        console.log(chalk.dim(REFERRAL_TIP_TEXT));
     }
     catch {
-        // silent — #151: a broken tip must never break a run
+        // silent — #151/#153: a broken tip must never break a run
     }
 }

package/package.json

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