@flowapt/flowiq-cli 0.2.9 → 0.3.1

package/README.md

@@ -230,6 +230,14 @@ throttle *and* your brake. Tags only; the send is `broadcast send --tag` (one
 batch at a time) or the dashboard broadcaster.
 
 ```bash
+# Broadcast list → N even TAGGED COHORTS in ONE command (v0.3.1 — no id file, no DB access):
+flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3 --seed 42
+# every broadcast-opted-in contact (minus archived/blocked), shuffled into 3
+# BALANCED cohorts → bcast-batch-01/02/03. --from-attribute also takes
+# all_contacts | allow_broadcast_false | no_broadcast_permission (same selector
+# as `tag attributes --filter`). --split N (2..100) replaces --batch-size;
+# --seed makes the shuffle reproducible, --ordered keeps server order (no shuffle).
+
 # Cohort by ORDER-COUNT CRITERIA (v0.2.6 — server-resolved, no id file needed):
 flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d
 # "everyone with 2+ orders in the last 60 days" — counted from the captured
@@ -252,11 +260,19 @@ flowiq seg list  <org_id> --prefix repeat-60d   # VERIFY: tag → count
 flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own tags only)
 ```
 
-- **Two cohort sources:** `--min-orders [--window]` resolves the cohort
-  server-side (the windowed order count the app's Advanced Tagging UI cannot
-  express — its Min Orders filter is lifetime-only), or pass explicit
-  **contact UUIDs** (a snapshot JSON's `contact_ids[]` or a plain file) for
-  SQL-derived / bespoke cohorts.
+- **Cohort sources:** `--from-attribute <filter>` (a broadcast-permission
+  audience — `all_contacts` / `allow_broadcast_true` / `allow_broadcast_false`
+  / `no_broadcast_permission`, resolved server-side past the 1000-row cap);
+  `--min-orders [--window]` (the windowed order count the app's Advanced Tagging
+  UI cannot express — its Min Orders filter is lifetime-only); `--bought`
+  (product line-items); or explicit **contact UUIDs** (a snapshot JSON's
+  `contact_ids[]` or a plain file). Exactly one per plan.
+- **`--split N` = exactly N even cohorts** (2..100), an alternative to
+  `--batch-size` fixed chunks. It **shuffles by default** so the cohorts are
+  balanced (not skewed by contact age / signup order); `--seed S` makes the
+  shuffle reproducible, `--ordered` keeps server order. `--from-attribute
+  allow_broadcast_true --split 3` is the "whole broadcast list → 3 balanced
+  tagged cohorts" one-liner — no id file, no database access.
 - Apply is **append-only** — it never touches a contact's other tags, names,
   or anything else, and never double-adds.
 - Point-in-time warning: the plan snapshots the cohort at plan time; re-run
@@ -645,6 +661,7 @@ version you have installed.
 |---|---|---|
 | `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (local dev, staging). |
 | `FLOWIQ_TOKEN` | (saved in `~/.config/flowiq/auth.json`) | Override the auth token, useful for CI. |
+| `FLOWIQ_NO_UPDATE_CHECK` | (unset) | Set to `1` to silence the "you're behind" update hint (also honours `NO_UPDATE_NOTIFIER=1` and any `CI` env). |
 | `FLOWMOD_EVO_DB_URL` | (none) | Full `postgres://` URL for `groups` (Evolution DB). Required for `groups`. |
 | `FLOWMOD_DB_HOST/PORT/USER/PASS/NAME` | (none) | Alternative to `FLOWMOD_EVO_DB_URL` — assembled into a connection string. |
 
@@ -660,6 +677,18 @@ flowiq --version
 Your saved token in `~/.config/flowiq/auth.json` is preserved across
 upgrades.
 
+**You'll be told when you're behind.** The CLI checks npm about once a day (in a
+detached background process — it never slows a command) and prints a one-line
+hint to stderr on your next run when a newer version exists:
+
+```
+  ⬆ flowiq 0.3.1 is available (you're on 0.3.0)
+    update:  npm i -g @flowapt/flowiq-cli
+```
+
+It's stderr-only (never corrupts piped or `--json` output) and shows only in an
+interactive terminal. Silence it with `FLOWIQ_NO_UPDATE_CHECK=1`.
+
 ## License
 
 UNLICENSED. Internal staff tool — install requires a valid `fiq_staff_…`

package/TEAM-GUIDE.md

@@ -38,6 +38,12 @@ This guide travels with the CLI — read it any time with `flowiq guide`
 (`--reference` for the full command reference). It always matches the version
 you have installed.
 
+**Keep it current.** The CLI checks npm about once a day and, on your next run,
+prints a one-line hint when you're behind (e.g. `⬆ flowiq 0.3.1 is available…`).
+When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also means
+`flowiq guide` shows you stale instructions. (Silence it with
+`FLOWIQ_NO_UPDATE_CHECK=1` if you must.)
+
 > **Approving someone else's login:** when a teammate runs `auth login`, they
 > read you their code (or you open the link they send). On `/cli-auth`, check
 > the code AND the device name match what they told you, then Approve.
@@ -81,6 +87,7 @@ you have installed.
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
 | Advanced Tagging in the terminal (one named tag on a matched set) | `flowiq tag field\|cohort\|segment\|attributes\|messages <org_id> …` (dry-run) → add `--tag <name> --commit` |
 | List / remove tags | `flowiq tag list <org_id>` · `flowiq tag remove <org_id> <tag> --confirm` |
+| Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/segments.js

@@ -39,6 +39,27 @@ function slugify(name, fallback) {
   return s || fallback;
 }
 
+/** Deterministic PRNG (mulberry32) so `--seed` gives a reproducible shuffle. */
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0; a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Fisher–Yates shuffle in place. Pass a numeric seed for reproducibility, else Math.random. */
+function shuffle(arr, seed) {
+  const rng = seed !== undefined && seed !== null && String(seed).length ? mulberry32(Number(seed) >>> 0) : Math.random;
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
 async function fileExists(p) {
   try { await fs.access(p); return true; } catch { return false; }
 }
@@ -98,26 +119,45 @@ export async function plan(orgId, opts = {}) {
     console.error(`Error: --tag-prefix must be slug-safe lowercase ([a-z0-9-], got "${prefix}").`);
     process.exit(1);
   }
+  const splitMode = opts.split !== undefined;
   const batchSize = Number(opts.batchSize ?? 75);
-  if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
-  if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
+  if (!splitMode) {
+    if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
+    if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
+  }
+  let splitN = 0;
+  if (splitMode) {
+    splitN = Number(opts.split);
+    if (!Number.isInteger(splitN) || splitN < 2 || splitN > 100) { console.error("Error: --split must be an integer 2..100."); process.exit(1); }
+    if (opts.seed !== undefined && !Number.isFinite(Number(opts.seed))) { console.error("Error: --seed must be a number."); process.exit(1); }
+  }
 
-  // Cohort source: a server-resolved criterion (--min-orders OR --bought,
-  // both with an optional --window) OR an explicit id list (--from-segment /
-  // --ids-file).
+  // Cohort source: a server-resolved criterion (--from-attribute / --min-orders
+  // / --bought) OR an explicit id list (--from-segment / --ids-file). Exactly one.
   const orderMode = opts.minOrders !== undefined;
   const productMode = opts.bought !== undefined;
-  const criteriaMode = orderMode || productMode;
-  if (orderMode && productMode) {
-    console.error("Error: use either --min-orders or --bought, not both."); process.exit(1);
+  const attributeMode = opts.fromAttribute !== undefined;
+  const criteriaMode = orderMode || productMode || attributeMode;
+  const sourceCount = [orderMode, productMode, attributeMode, !!opts.fromSegment, !!opts.idsFile].filter(Boolean).length;
+  if (sourceCount === 0) {
+    console.error("Error: a cohort source is required — one of --from-attribute / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
   }
-  if (criteriaMode && (opts.fromSegment || opts.idsFile)) {
-    console.error("Error: --min-orders / --bought cannot be combined with --from-segment / --ids-file."); process.exit(1);
+  if (sourceCount > 1) {
+    console.error("Error: pick exactly ONE cohort source (--from-attribute / --min-orders / --bought / --from-segment / --ids-file)."); process.exit(1);
   }
 
   let cohort;
   let cohortSpec = null;
   if (criteriaMode) {
+    if (attributeMode) {
+      const ATTR = ["all_contacts", "allow_broadcast_true", "allow_broadcast_false", "no_broadcast_permission"];
+      const attribute = String(opts.fromAttribute).trim();
+      if (!ATTR.includes(attribute)) {
+        console.error(`Error: --from-attribute must be one of: ${ATTR.join(", ")}`); process.exit(1);
+      }
+      cohortSpec = { attribute };
+      cohort = { ids: [], badUuids: [], sourceMeta: { type: "attribute_cohort", attribute } };
+    } else {
     let windowDays = null;
     if (opts.window) {
       try { windowDays = parseWindowDays(opts.window); }
@@ -140,6 +180,7 @@ export async function plan(orgId, opts = {}) {
       cohortSpec = { min_orders: minOrders, window_days: windowDays, platform: opts.platform || "auto" };
       cohort = { ids: [], badUuids: [], sourceMeta: { type: "order_cohort", ...cohortSpec } };
     }
+    }
   } else {
     try { cohort = await readCohort(opts, orgId); }
     catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
@@ -160,23 +201,54 @@ export async function plan(orgId, opts = {}) {
     process.exit(1);
   }
   if (resp.cohort) {
-    const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
-    if (resp.cohort.kind === "product") {
-      const verb = resp.cohort.min_purchases > 1 ? `bought ${resp.cohort.min_purchases}+ times` : "bought";
-      const join = resp.cohort.match === "all" ? "ALL of" : "any of";
-      console.log(`Cohort: ${verb} ${join} [${resp.cohort.product_terms.join(", ")}] ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from order line-items).`);
+    if (resp.cohort.kind === "attribute") {
+      const label = {
+        all_contacts: "all contacts",
+        allow_broadcast_true: "broadcast-opted-in contacts",
+        allow_broadcast_false: "broadcast-opted-OUT contacts",
+        no_broadcast_permission: "contacts with no broadcast permission set",
+      }[resp.cohort.attribute] || resp.cohort.attribute;
+      console.log(`Cohort: ${label} → ${resp.cohort.resolved_count} contact(s) (server-resolved).`);
     } else {
-      console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+      const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
+      if (resp.cohort.kind === "product") {
+        const verb = resp.cohort.min_purchases > 1 ? `bought ${resp.cohort.min_purchases}+ times` : "bought";
+        const join = resp.cohort.match === "all" ? "ALL of" : "any of";
+        console.log(`Cohort: ${verb} ${join} [${resp.cohort.product_terms.join(", ")}] ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from order line-items).`);
+      } else {
+        console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+      }
     }
     cohort.sourceMeta.resolved_count = resp.cohort.resolved_count;
   }
   if (!resp.safe_count) { console.error("Nothing to tag — 0 safe contacts after exclusions (V-13)."); process.exit(1); }
+  if (splitMode && splitN > resp.safe_count) {
+    console.error(`Error: --split ${splitN} but only ${resp.safe_count} safe contact(s) — can't make that many cohorts.`); process.exit(1);
+  }
 
-  // Slice safe_ids into contiguous batches (client-side, per the spec split).
+  // --split makes exactly N EVEN cohorts and shuffles by default so the groups
+  // are balanced (not skewed by contact age / id order); --ordered keeps server
+  // order; --seed makes the shuffle reproducible. Without --split, slice into
+  // contiguous --batch-size chunks (the original behaviour).
   const batches = [];
-  for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
-    const nn = String(batches.length + 1).padStart(2, "0");
-    batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+  if (splitMode) {
+    const ids = opts.ordered ? resp.safe_ids.slice() : shuffle(resp.safe_ids.slice(), opts.seed);
+    const total = ids.length;
+    const base = Math.floor(total / splitN);
+    const rem = total % splitN;
+    let idx = 0;
+    for (let g = 0; g < splitN; g++) {
+      const size = base + (g < rem ? 1 : 0);
+      const nn = String(g + 1).padStart(2, "0");
+      batches.push({ tag: `${prefix}-batch-${nn}`, count: size, contact_ids: ids.slice(idx, idx + size) });
+      idx += size;
+    }
+    if (batches[0].count > 500) console.log(`⚠ each cohort is ~${batches[0].count} contacts — a single-cohort send is large (Meta tier risk); pace the sends.`);
+  } else {
+    for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
+      const nn = String(batches.length + 1).padStart(2, "0");
+      batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+    }
   }
 
   const slug = slugify(opts.segment || prefix, prefix);
@@ -186,7 +258,8 @@ export async function plan(orgId, opts = {}) {
     organization_id: resp.organization_id,
     organization_slug: slugify(resp.organization_name, resp.organization_id.slice(0, 8)),
     tag_prefix: prefix,
-    batch_size: batchSize,
+    batch_size: splitMode ? null : batchSize,
+    split: splitMode ? { cohorts: splitN, shuffled: !opts.ordered, seed: opts.seed ?? null } : null,
     created_at: new Date().toISOString(),
     source: cohort.sourceMeta,
     exclusions: {
@@ -206,7 +279,12 @@ export async function plan(orgId, opts = {}) {
   console.log(`Wrote ${planPath(slug)}`);
   console.log(`  org:      ${resp.organization_name}`);
   console.log(`  input:    ${resp.input_count} · safe: ${resp.safe_count} · excluded: ${ex.not_allow_broadcast + ex.archived + ex.blocked} (allow_broadcast ${ex.not_allow_broadcast}, archived ${ex.archived}, blocked ${ex.blocked}) · not_found ${ex.not_found_in_org} · dupes ${ex.duplicate_in_input}`);
-  console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  if (splitMode) {
+    const how = opts.ordered ? "ordered" : (opts.seed != null ? `shuffled, seed ${opts.seed}` : "shuffled");
+    console.log(`  cohorts:  ${batches.length} even (${how}) — sizes ${batches.map((b) => b.count).join(" / ")}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  } else {
+    console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  }
   if (cohort.sourceMeta.generated_at) {
     console.log(`  ⚠ tagging point-in-time ids from ${cohort.sourceMeta.generated_at} — re-derive the cohort SQL if freshness matters.`);
   }

package/src/config.js

@@ -13,7 +13,7 @@ import os from "node:os";
 
 const DEFAULT_API_URL = "https://api.flowiq.live";
 
-function configDir() {
+export function configDir() {
   // Honour XDG_CONFIG_HOME if set; else ~/.config (Linux/Mac default).
   const xdg = process.env.XDG_CONFIG_HOME;
   const base = xdg && xdg.trim() ? xdg : path.join(os.homedir(), ".config");

package/src/index.js

@@ -29,6 +29,7 @@ import * as segmentsCmd from "./commands/segments.js";
 import * as tagCmd from "./commands/tag.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
+import { maybeNotifyUpdate } from "./update-check.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -37,6 +38,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
 
 export function run(argv) {
+  // Non-blocking "you're behind" hint (stderr; cached; detached refresh).
+  maybeNotifyUpdate(pkg.version);
+
   const program = new Command();
   program
     .name("flowiq")
@@ -412,10 +416,11 @@ export function run(argv) {
     .alias("seg")
     .description("Slice a contact cohort into fixed-size batch tags and bulk-apply them (broadcast batching)");
   segments.command("plan <organization_id>")
-    .description("Resolve a cohort (id list, order-count, or product-purchase criteria), apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .description("Resolve a cohort (id list, order-count, product-purchase, or broadcast-attribute), apply broadcast-safety exclusions, slice into fixed-size OR N even batch tags, write the plan (no DB write)")
     .requiredOption("--tag-prefix <name>", "campaign tag stem; batches become <prefix>-batch-NN")
     .option("--from-segment <path>", "a segments snapshot JSON (uses its contact_ids[])")
     .option("--ids-file <path>", "a plain newline/CSV file of contact UUIDs")
+    .option("--from-attribute <filter>", "SERVER-RESOLVED cohort: every contact matching a broadcast-permission filter (all_contacts | allow_broadcast_true | allow_broadcast_false | no_broadcast_permission)")
     .option("--min-orders <n>", "SERVER-RESOLVED cohort: contacts with ≥ n captured orders (instead of an id file)")
     .option("--bought <terms>", "SERVER-RESOLVED cohort: contacts who bought these product(s) (comma-separated name substrings) from real order line-items")
     .option("--match <mode>", "with --bought: any (bought any listed product) | all (bought every one)", "any")
@@ -423,6 +428,9 @@ export function run(argv) {
     .option("--window <span>", "with --min-orders/--bought: only count orders in this window, e.g. 60d / 8w / 3m (omit = all captured history)")
     .option("--platform <p>", "with --min-orders/--bought: auto | shopify | woo", "auto")
     .option("--batch-size <n>", "contacts per batch tag", "75")
+    .option("--split <n>", "split the safe cohort into exactly N even cohorts (alternative to --batch-size; shuffles by default for balanced groups)")
+    .option("--seed <n>", "with --split: reproducible shuffle seed (omit = random each run)")
+    .option("--ordered", "with --split: keep server order instead of shuffling (deterministic, but skews groups by contact age)")
     .option("--segment <name>", "plan file slug (default: the tag prefix)")
     .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
     .action((orgId, opts) => segmentsCmd.plan(orgId, opts));

package/src/update-check.js

@@ -0,0 +1,132 @@
+// Best-effort "you're behind" nudge for the flowiq CLI.
+//
+// On startup we print a one-line update hint to STDERR (never stdout — so it
+// can never corrupt piped / --json output) when the installed version is older
+// than the latest published on npm.
+//
+// The nudge is driven by a CACHED value read SYNCHRONOUSLY — zero network on the
+// hot path, so no command is ever slowed. The cache is refreshed at most once a
+// day by a DETACHED, unref'd child process, so even `flowiq --version` returns
+// instantly (the parent never waits on the registry). The hint therefore
+// appears on the NEXT run after a new release — exactly how npm / update-notifier
+// behave.
+//
+// Fully fail-silent: offline, registry down, malformed cache → no output, no
+// crash, never blocks. Opt out with FLOWIQ_NO_UPDATE_CHECK=1 (also honours
+// NO_UPDATE_NOTIFIER=1 and any CI env).
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { configDir } from "./config.js";
+
+const PKG = "@flowapt/flowiq-cli";
+const REGISTRY = "https://registry.npmjs.org/@flowapt%2Fflowiq-cli/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // refresh the cache at most once/day
+const FETCH_TIMEOUT_MS = 2000;
+
+function cacheFile() {
+  return path.join(configDir(), "update-check.json");
+}
+
+function disabled() {
+  return (
+    process.env.FLOWIQ_NO_UPDATE_CHECK === "1" ||
+    process.env.NO_UPDATE_NOTIFIER === "1" ||
+    !!process.env.CI
+  );
+}
+
+// Compare dotted numeric versions (ignoring any -prerelease). a>b → 1, a<b → -1, = → 0.
+export function cmpVersion(a, b) {
+  const parse = (v) => String(v).split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function readCacheSync() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(obj) {
+  try {
+    await fsp.mkdir(configDir(), { recursive: true, mode: 0o700 });
+    await fsp.writeFile(cacheFile(), JSON.stringify(obj) + "\n", "utf8");
+  } catch {
+    /* best-effort — a failed cache write just means we re-check next run */
+  }
+}
+
+// Hit the npm registry for dist-tags.latest and cache it. Runs ONLY in the
+// detached child (never on the hot path). Backs off for the day even on failure
+// so an offline machine doesn't spawn a refresher on every invocation.
+async function refreshLatest(prevLatest) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY, { signal: ctrl.signal, headers: { Accept: "application/json" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    await writeCache({ checked_at: Date.now(), latest: body?.version || prevLatest || null });
+  } catch {
+    await writeCache({ checked_at: Date.now(), latest: prevLatest || null });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Print the nudge (from cache, synchronously) and, if the cache is stale, spawn
+// a detached child to refresh it for the NEXT run. Never throws, never blocks.
+export function maybeNotifyUpdate(currentVersion) {
+  try {
+    if (disabled()) return;
+    const cache = readCacheSync();
+    const latest = cache?.latest;
+
+    if (latest && process.stderr.isTTY && cmpVersion(latest, currentVersion) > 0) {
+      process.stderr.write(
+        `\n  ⬆ flowiq ${latest} is available (you're on ${currentVersion})\n` +
+        `    update:  npm i -g ${PKG}\n\n`
+      );
+    }
+
+    const stale = !cache || (Date.now() - (cache.checked_at || 0)) > CHECK_INTERVAL_MS;
+    if (stale) {
+      try {
+        const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "--refresh"], {
+          detached: true,
+          stdio: "ignore",
+          windowsHide: true,
+        });
+        child.unref();
+      } catch {
+        /* if we can't spawn, we simply try again next run */
+      }
+    }
+  } catch {
+    /* fully silent — an update hint must never be the reason a command fails */
+  }
+}
+
+// When this module is executed directly as `node update-check.js --refresh`
+// (the detached child spawned above), do the network refresh and exit. Guarded
+// so importing the module for maybeNotifyUpdate never triggers it.
+const invokedDirectly =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) &&
+  process.argv.includes("--refresh");
+if (invokedDirectly) {
+  const cache = readCacheSync();
+  refreshLatest(cache?.latest).finally(() => process.exit(0));
+}