@flowapt/flowiq-cli 0.2.9 → 0.3.0

package/README.md

@@ -645,6 +645,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 +661,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "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/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")

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));
+}