@flowapt/flowiq-cli 0.2.8 → 0.3.0

package/README.md

@@ -552,13 +552,25 @@ Set an allowlisted set of the active agent's config fields (the prompt-builder
 flowiq agent config <organization_id>                        # show current
 flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.4-mini \
   --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
+flowiq agent config <organization_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
-`shopify_products_web_chat`), and `discount.enabled`. Anything else is rejected;
-every change is reported before → after.
+`shopify_products_web_chat`), `discount.enabled`, and the `flowiq test` contact
+(`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
+rejected; every change is reported before → after.
+
+**Test contact (`--test-contact-number` / `--test-contact-name`, v0.2.9).**
+This is the contact `flowiq test` drives the live agent through (read by
+`api/cli/agent-test.js` as `settings.test_contact_number`). ⚠ **Use a clearly
+FAKE number.** Whatever you set becomes the `whatsapp_id` the test harness looks
+up or creates in the org — point it at a real customer's number and your tests
+route through *their* contact record and force `bot_status=true` on it. If that
+number already maps to an existing contact, the command prints a `⚠` warning
+naming it. Pass `--test-contact-number ""` (empty) to clear the override — the
+harness then falls back to a synthetic per-agent `test_<agent_id>` contact.
 
 ### Agent updates — `flowiq agent-updates pull|list|resolve` (alias `au`)
 
@@ -633,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. |
 
@@ -648,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.
@@ -75,6 +81,7 @@ you have installed.
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
+| Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.8",
+  "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/commands/agent-config.js

@@ -41,6 +41,8 @@ export async function config(orgId, opts = {}) {
   const settings = {};
   if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
   if (opts.model !== undefined) settings.model = opts.model;
+  if (opts.testContactNumber !== undefined) settings.test_contact_number = opts.testContactNumber;
+  if (opts.testContactName !== undefined) settings.test_contact_name = opts.testContactName;
   if (Object.keys(settings).length) body.settings = settings;
   if (opts.rename !== undefined) body.name = opts.rename;
   if (opts.discount !== undefined) body.discount_enabled = parseBool(opts.discount, "--discount");
@@ -73,7 +75,7 @@ export async function config(orgId, opts = {}) {
     }
     console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
     printSnapshot("current", resp.current);
-    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount to change)");
+    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount / --test-contact-number / --test-contact-name to change)");
     return;
   }
 
@@ -93,4 +95,5 @@ export async function config(orgId, opts = {}) {
     const a = resp.after?.[k];
     console.log(`    ${k.padEnd(30)} ${b === null || b === undefined ? "(unset)" : b} → ${a === null || a === undefined ? "(unset)" : a}`);
   }
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
 }

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")
@@ -227,6 +231,8 @@ export function run(argv) {
     .option("--rename <name>", "rename the agent")
     .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat", agentConfigCmd.collectTool, [])
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
+    .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
+    .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
   // agent-updates (pending client change-requests + chat context; pull + resolve)

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