@flowapt/flowiq-cli 0.9.6 → 0.9.8

package/src/gaps.test.mjs

@@ -0,0 +1,48 @@
+// node --test src/gaps.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { filedVia, normaliseRef, ago } from "./commands/gaps.js";
+import { gapHint } from "./index.js";
+
+test("filedVia: a Claude Code session is marked claude, even on a TTY", () => {
+  const tty = { isTTY: true };
+  assert.equal(filedVia({ CLAUDECODE: "1" }, tty, tty), "claude");
+  assert.equal(filedVia({ CLAUDE_CODE_ENTRYPOINT: "cli" }, tty, tty), "claude");
+});
+
+test("filedVia: a person at a terminal vs a pipe or script", () => {
+  assert.equal(filedVia({}, { isTTY: true }, { isTTY: true }), "human");
+  assert.equal(filedVia({}, { isTTY: undefined }, { isTTY: true }), "script");
+  assert.equal(filedVia({}, { isTTY: true }, { isTTY: false }), "script");
+});
+
+test("normaliseRef: number, #number and uuid pass; anything else is refused", () => {
+  assert.equal(normaliseRef("42"), "42");
+  assert.equal(normaliseRef("#42"), "42");
+  assert.equal(normaliseRef(" 7 "), "7");
+  assert.equal(normaliseRef("0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b"), "0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b");
+  assert.equal(normaliseRef("abc"), null);
+  assert.equal(normaliseRef("42a"), null);
+  assert.equal(normaliseRef(""), null);
+  assert.equal(normaliseRef(undefined), null);
+});
+
+test("ago: minutes, hours, days", () => {
+  const now = Date.parse("2026-09-30T12:00:00Z");
+  assert.equal(ago("2026-09-30T11:55:00Z", now), "5m ago");
+  assert.equal(ago("2026-09-30T09:00:00Z", now), "3h ago");
+  assert.equal(ago("2026-09-26T12:00:00Z", now), "4d ago");
+  assert.equal(ago(null, now), "-");
+});
+
+test("gapHint: only for a missing command / flag, with the topic filled in", () => {
+  const argv = ["node", "flowiq", "agent", "config", "0689d0be-ba76-43d9-a0d5-f4d59c1db537", "--tool-instructions", "x"];
+  const hint = gapHint("error: unknown option '--tool-instructions'\n", argv);
+  assert.match(hint, /flowiq gaps report/);
+  assert.match(hint, /--command "agent config"/);
+  assert.match(hint, /--error "unknown option '--tool-instructions'"/);
+  assert.equal(gapHint("error: missing required argument 'organization_id'\n", argv), "");
+  assert.match(gapHint("error: unknown command 'widgets'\n", ["node", "flowiq", "widgets", "list"]), /--command "widgets list"/);
+  // an id in second place is not part of the topic
+  assert.match(gapHint("error: too many arguments\n", ["node", "flowiq", "messages", "0689d0be-ba76-43d9-a0d5-f4d59c1db537"]), /--command "messages"/);
+});

package/src/http.js

@@ -70,7 +70,7 @@ export function isBelowServerMinimum() {
  * serialised — and always name the HTTP status, since a 504 tells you "retry or
  * narrow it" while a 400 never will.
  */
-export function describeError(parsed, method, endpoint, status) {
+export function describeError(parsed, method, endpoint, status, { json = true } = {}) {
   const pick = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
   const nested = (v) => {
     if (!v || typeof v !== "object") return null;
@@ -95,12 +95,27 @@ export function describeError(parsed, method, endpoint, status) {
   if (!detail) return where;
 
   // A timeout is transient and the remedy is specific, so say so rather than
-  // leaving the reader to work out whether they hit a hard limit.
-  const timedOut = status === 504 || /TIMEOUT|timed out/i.test(detail);
-  return timedOut
-    ? `${detail} [${where}] — this is a TIMEOUT, not a limit: retry, or narrow the request ` +
-      `(fewer pages via --max-pages, a smaller --q limit, or a tighter filter).`
-    : `${detail} [${where}]`;
+  // leaving the reader to work out whether they hit a hard limit. Only a JSON
+  // body is scanned for the word: an HTML page (a Vercel challenge) carries
+  // "timeout" in its inline script and is not one.
+  const timedOut = status === 504 || (json && /TIMEOUT|timed out/i.test(detail));
+  if (!timedOut) return `${detail} [${where}]`;
+  // A write can finish on the server after the proxy gave up, so "retry" is the
+  // wrong first move there (a template created twice, a send fired twice).
+  if (method !== "GET" && endpoint !== "store-api") {
+    return `${detail} [${where}] — this is a TIMEOUT: the server may still have finished the write. ` +
+      `Check the result (the command's list / status / pull verb, or flowiq audit) before retrying.`;
+  }
+  return `${detail} [${where}] — this is a TIMEOUT, not a limit: retry, or narrow the request ` +
+    `(fewer pages via --max-pages, a smaller --q limit, or a tighter filter).`;
+}
+
+/** Vercel's bot protection answers with an HTML challenge page (403/429),
+ *  before the request ever reaches our API. It is about this network, not the key. */
+export function isVercelChallenge(status, headers, text) {
+  const mitigated = headers?.get?.("x-vercel-mitigated") || "";
+  if (/challenge/i.test(mitigated)) return true;
+  return (status === 403 || status === 429) && /Vercel Security Checkpoint|vercel-challenge|_vercel\/challenge/i.test(text || "");
 }
 
 async function call(method, endpoint, { query, body } = {}) {
@@ -138,8 +153,19 @@ async function call(method, endpoint, { query, body } = {}) {
   const text = await resp.text();
   let parsed, isJson = true;
   try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }
+  if (!resp.ok && isVercelChallenge(resp.status, resp.headers, text)) {
+    const err = new Error(
+      `Vercel is challenging this network (bot protection) [${method} ${endpoint} → HTTP ${resp.status}]. ` +
+      `This is not your key and the request never reached the API: wait a few minutes, or try another ` +
+      `network (a phone hotspot), then retry.`
+    );
+    err.status = resp.status;
+    err.code = "EVERCELCHALLENGE";
+    err.body = parsed;
+    throw err;
+  }
   if (!resp.ok) {
-    const err = new Error(describeError(parsed, method, endpoint, resp.status));
+    const err = new Error(describeError(parsed, method, endpoint, resp.status, { json: isJson }));
     err.status = resp.status;
     err.body = parsed;
     throw err;

package/src/index.js

@@ -27,6 +27,7 @@ import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as plansCmd from "./commands/plans.js";
+import * as gapsCmd from "./commands/gaps.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
@@ -48,6 +49,19 @@ import * as doctorCmd from "./commands/doctor.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
 
+/** The one-line "file it" hint appended to a missing-command / missing-flag error. */
+export function gapHint(errorText, argv = []) {
+  if (!/unknown option|unknown command|too many arguments/i.test(String(errorText))) return "";
+  const args = argv.slice(2).filter((a) => !a.startsWith("-"));
+  // "agent config", "bc send", "org flags": a verb-shaped second word belongs to the topic.
+  const topic = (args[1] && /^[a-z][a-z-]*$/.test(args[1]) ? args.slice(0, 2) : args.slice(0, 1)).join(" ") || "<topic>";
+  const firstLine = String(errorText).split("\n")[0].replace(/^error:\s*/i, "").replace(/"/g, "'").trim();
+  return (
+    `  → If the CLI should be able to do this, file it so it gets built:\n` +
+    `    flowiq gaps report "<what you needed>" --command "${topic}" --error "${firstLine}"\n`
+  );
+}
+
 export function run(argv) {
   // Non-blocking "you're behind" hint (stderr; cached; detached refresh).
   maybeNotifyUpdate(pkg.version);
@@ -56,7 +70,12 @@ export function run(argv) {
   program
     .name("flowiq")
     .description("FlowIQ staff CLI — round-trip agent prompts, webhooks, and more, without service-role credentials.")
-    .version(pkg.version);
+    .version(pkg.version)
+    // Set before any subcommand exists so every subcommand inherits it. When a
+    // command or flag does not exist, that is usually a gap: say how to file it,
+    // so a teammate (or their Claude session) records it instead of quietly
+    // falling back to SQL.
+    .configureOutput({ outputError: (str, write) => write(str + gapHint(str, argv)) });
 
   // auth
   const auth = program.command("auth").description("Manage CLI authentication");
@@ -77,6 +96,7 @@ export function run(argv) {
   prompts.command("pull <organization_id>")
     .description("Fetch an agent's prompt_sections into a local JSON file (default: active agent)")
     .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .option("--out <file>", "write the JSON here instead of .flowiq/prompts/<slug>.json")
     .action((orgId, opts) => promptsCmd.pull(orgId, opts));
   prompts.command("history <organization_id>")
     .description("Every recorded prompt push (who / when / size) — the version list for `restore`")
@@ -362,8 +382,10 @@ export function run(argv) {
     .requiredOption("--request-file <path>", "JSON file with template_request (+ optional template_data/media_header/cards_media)")
     .action((orgId, opts) => templatesCmd.create(orgId, opts));
   templates.command("status <organization_id>")
-    .description("List the org's template rows (name + status) to poll Meta approval")
+    .description("Template status: FlowIQ's record by default, or straight from Meta with --live (incl. rejection reasons)")
     .option("--name <substr>", "filter by template name substring")
+    .option("--live", "read Meta directly (one cheap call with --name; no snapshot file written)")
+    .option("--watch", "with --live: re-check every 15 s until every match is decided (max 15 min)")
     .action((orgId, opts) => templatesCmd.status(orgId, opts));
   templates.command("show <organization_id> <name>")
     .description("Render ONE template row in full — including a DRAFT, which `pull` cannot see (drafts never reach Meta)")
@@ -495,12 +517,27 @@ export function run(argv) {
     .option("--model <model>", "settings.model (e.g. gpt-6-luna, the house default)")
     .option("--reasoning-effort <level>", "settings.reasoning_effort — low|medium|high|xhigh|max (\"\" clears it; max = GPT-6 and Claude only); pairs with reasoning models (e.g. gpt-6-luna + high, gpt-6-luna + high, claude-sonnet-5 + medium)")
     .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/ticket_tool_status/product_lookup/email_request_tool/collapse_product_variants", agentConfigCmd.collectTool, [])
+    .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/ticket_tool_status/product_lookup/email_request_tool/collapse_product_variants/silent_option", 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)")
     .option("--disable-base-tool <name>", "hide a disableable built-in tool from this agent (repeatable)", agentConfigCmd.collectToolName, [])
     .option("--enable-base-tool <name>", "restore a previously disabled built-in tool (repeatable)", agentConfigCmd.collectToolName, [])
+    .option("--tool-instruction <tool=text>", "settings.tool_instructions: text APPENDED to that tool's description (repeatable; text or @file; \"tool=\" removes it)", agentConfigCmd.collectTool, [])
+    .option("--shorten-links <channel=on|off|default>", "per-channel link shortening (repeatable): whatsapp/web/messenger/instagram/tiktok/email/call; default = on for whatsapp only", agentConfigCmd.collectTool, [])
+    .option("--email-from-name <name>", "settings.email_from_name: the From display name on agent emails (\"\" clears)")
+    .option("--email-signature-name <name>", "settings.email_signature_name: name printed in the email signature (\"\" clears → agent name)")
+    .option("--email-signature-title <title>", "settings.email_signature_title: title line under the signature name (\"\" clears)")
+    .option("--email-request-to <addresses>", "settings.email_request.to: comma-separated recipients for email_request_to_team (\"\" clears)")
+    .option("--email-request-subject-prefix <text>", "settings.email_request.subject_prefix (\"\" clears)")
+    .option("--send-success-rule <when=text>", "send_message_success_instructions rule, one per condition: media/image/video/document/audio/text/always (repeatable; text or @file; \"when=\" removes it)", agentConfigCmd.collectTool, [])
+    .option("--send-success [bool]", "send_message_success_instructions.enabled (true if bare)")
+    .option("--after-escalation <text>", "human_notify.success_instructions: the NEXT STEP appended to the handover tool's reply (text or @file; \"\" clears)")
+    .option("--knowledge <pairs>", "knowledge_config: enabled=true,match_count=8,min_similarity=0.3 (\"default\" clears a key)")
+    .option("--human-notify <json>", "merge keys into human_notify (JSON or @file.json; null deletes a key; unknown keys refused)")
+    .option("--order-notify <json>", "merge keys into order_notify (JSON or @file.json; null deletes a key; unknown keys refused)")
+    .option("--full", "show long values in full (show mode and the before/after diff)")
+    .option("--json", "show mode: print the raw response as JSON")
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
   // agent-updates (pending client change-requests + chat context; pull + resolve)
@@ -544,11 +581,11 @@ export function run(argv) {
     .description("List local agent-updates snapshots")
     .action(() => agentUpdatesCmd.list());
   au.command("resolve <update_id>")
-    .description("Flip a client-raised ticket to resolved/declined + write the client-facing note (the client reads \"FlowIQ: <note>\")")
+    .description("Flip a client-raised ticket to resolved/declined (or back to in_progress) + write the client-facing note (the client reads \"FlowIQ: <note>\")")
     .option("--note <text>", "client-facing note (required when resolving)")
     .option("--internal <text>", "staff-only note (never shown to the client)")
     .option("--image <url>", "client-facing response image URL")
-    .option("--status <status>", "resolved (default) | declined", "resolved")
+    .option("--status <status>", "resolved (default) | declined | in_progress (open, fix not yet proven; note optional)", "resolved")
     .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
     .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
@@ -579,6 +616,60 @@ export function run(argv) {
     .option("--commit", "apply the change (default is a dry run)")
     .action((planId, opts) => plansCmd.status(planId, opts));
 
+  // gaps (CLI gap reports + feature requests, filed by anyone incl. a Claude session)
+  const gaps = program.command("gaps")
+    .alias("requests")
+    .description("Found something the CLI can't do (or does wrong)? `report` it; `list` what is asked for; `hit` one that bit you too");
+  gaps.command("report <title...>")
+    .description("File a gap / bug / idea (one-line title). Refused with the matching number if it is already on the list")
+    .option("--command <topic>", "the flowiq command it concerns, e.g. \"agent config\" or \"bc send\" (none yet? name the one you expected)")
+    .option("--kind <kind>", "gap (default: the CLI cannot do it) | bug (it does it wrong) | idea (it should)")
+    .option("--detail <text>", "what you were trying to do and what should happen")
+    .option("--detail-file <path>", "read --detail from a file")
+    .option("--error <text>", "the exact error the CLI printed, verbatim")
+    .option("--workaround <text>", "what you did instead (SQL, the dashboard, a script…)")
+    .option("--org <uuid>", "the org you were working on, for context")
+    .option("--priority <p>", "low | normal (default) | high — high = it blocked the job")
+    .option("--new", "file it even though a similar open request exists")
+    .option("--dry-run", "only show similar requests; file nothing")
+    .option("--json", "print the raw response")
+    .action((titleWords, opts) => gapsCmd.report(titleWords, opts));
+  gaps.command("list")
+    .description("Requests, most-hit first (default: open = open, planned, in_progress)")
+    .option("--status <list>", "open (default) | all | open | planned | in_progress | done | declined | duplicate (comma-separated allowed)")
+    .option("--command <topic>", "only requests about this command (contains)")
+    .option("--kind <kind>", "gap | bug | idea")
+    .option("--search <text>", "title / detail / error contains this text")
+    .option("--mine", "only requests you filed")
+    .option("--sort <how>", "hits (default) | new | old | touched")
+    .option("--limit <n>", "max rows (default 100, max 500)")
+    .option("--json", "print the raw response")
+    .action((opts) => gapsCmd.list(opts));
+  gaps.command("show <number>")
+    .description("One request in full: detail, verbatim error, every hit, note and status change")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.show(ref, opts));
+  gaps.command("hit <number>")
+    .description("It bit you too: +1 with what you were doing (the most-hit requests get built first)")
+    .option("--note <text>", "what you were doing when you hit it")
+    .option("--error <text>", "the exact error, if it differs")
+    .option("--org <uuid>", "the org you were working on")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.hit(ref, opts));
+  gaps.command("note <number> <text...>")
+    .description("Add context to a request without counting a hit")
+    .option("--json", "print the raw response")
+    .action((ref, textWords, opts) => gapsCmd.note(ref, textWords, opts));
+  gaps.command("status <number>")
+    .description("Maintainers: planned | in_progress | done | declined | duplicate. Closing emails everyone who reported or hit it")
+    .requiredOption("--to <status>", "open | planned | in_progress | done | declined | duplicate")
+    .option("--note <text>", "what shipped / why not (required for done + declined; the people who asked read it)")
+    .option("--version <x.y.z>", "the CLI version the fix shipped in (done)")
+    .option("--of <number>", "with --to duplicate: the request this one duplicates (hits move across)")
+    .option("--no-notify", "close without emailing the people who asked")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.status(ref, opts));
+
   // audit (who did what, when — with the full before/after content)
   const audit = program.command("audit")
     .description("Staff-CLI audit trail: who changed what, when — with full before/after content")
@@ -589,9 +680,10 @@ export function run(argv) {
     .option("--agent <id>", "scope to one agent")
     .option("--target <id>", "scope to one target (task id, tool name, tag, broadcast id)")
     .option("--user <substr>", "filter by staff email (substring)")
-    .option("--since <date>", "YYYY-MM-DD or ISO")
-    .option("--until <date>", "YYYY-MM-DD or ISO")
-    .option("--limit <n>", "max entries (default 50, max 200)")
+    .option("--since <when>", "YYYY-MM-DD (SAST day start), ISO, or a window: 14d / 12h / 2w")
+    .option("--until <when>", "YYYY-MM-DD, ISO, or a window: 14d / 12h / 2w")
+    .option("--before <created_at>", "page back: only entries older than this (the listing prints the value to use)")
+    .option("--limit <n>", "max entries (default 50, max 200; above 200 is clamped and the total is shown)")
     .option("--json", "raw JSON")
     .action((orgId, opts) => auditCmd.list(orgId, opts));
   audit.command("show <audit_id>")
@@ -622,11 +714,13 @@ export function run(argv) {
     .option("--image <url>", "attach a publicly-fetchable image URL (text is the caption)")
     .option("--timeout <ms>", "per-turn HTTP timeout (default 120000)")
     .option("--json", "print raw JSON instead of the transcript")
+    .option("--force", "go ahead even though the test contact had real (non-web) messages in the last 6 h")
     .action((orgId, message, opts) => testCmd.send(orgId, message, opts));
   test.command("scenario <organization_id> <file>")
     .description("Run a scenario pack (JSON: {scenarios:[{id,title,turns:[{text,expect?,expectNot?}]}]})")
     .option("--agent <id>", "test a specific agent")
     .option("--no-clear-between", "do NOT clear between scenarios (one long thread)")
+    .option("--force", "go ahead even though the test contact had real (non-web) messages in the last 6 h")
     .option("--sender <name>", "senderName")
     .option("--timeout <ms>", "per-turn HTTP timeout (default 120000)")
     .option("--json", "print raw JSON results")
@@ -635,6 +729,7 @@ export function run(argv) {
     .description("Run the bundled generic smoke pack")
     .option("--agent <id>", "test a specific agent")
     .option("--no-clear-between", "do NOT clear between scenarios")
+    .option("--force", "go ahead even though the test contact had real (non-web) messages in the last 6 h")
     .option("--sender <name>", "senderName")
     .option("--timeout <ms>", "per-turn HTTP timeout")
     .option("--json", "print raw JSON results")
@@ -642,6 +737,7 @@ export function run(argv) {
   test.command("clear <organization_id>")
     .description("Clear the test conversation (hide history via memory_cutoff)")
     .option("--agent <id>", "target a specific agent's test contact")
+    .option("--force", "go ahead even though the test contact had real (non-web) messages in the last 6 h")
     .action((orgId, opts) => testCmd.clear(orgId, opts));
   test.command("stress <organization_id> [pack]")
     .description("Run an adversarial pack in parallel, one isolated contact per scenario (phase 2)")
@@ -797,10 +893,11 @@ export function run(argv) {
     .option("--limit <n>", "how many to show (default 25, max 200)")
     .option("--template <substr>", "filter: template_name contains this (case-insensitive)")
     .option("--since <date>", "filter: created on/after this date, e.g. 2026-07-01")
+    .option("--min-recipients <n>", "filter: only sends to at least N recipients (2 hides welcomes and cart reminders)")
     .option("--json", "raw JSON")
     .action((orgId, opts) => broadcastCmd.listRemote(orgId, opts));
   broadcast.command("status <organization_id> <broadcast_id>")
-    .description("Live delivery counts (read/delivered/sent/failed) for a broadcast by its broadcastId — e.g. from a --python fire-and-forget send")
+    .description("Live delivery counts (read/delivered/sent/failed) for a broadcast by its broadcastId, plus what it sent (slot values, button code and the link's destination)")
     .option("--failures", "also list each FAILED recipient + the Meta error reason (makes a python send auditable)")
     .option("--limit <n>", "with --failures: how many failed rows to print", "40")
     .option("--json", "raw JSON")
@@ -878,6 +975,7 @@ export function run(argv) {
     .option("--content <value>", "utm_content, the per-link tag (e.g. ViewMore); defaults to the campaign")
     .option("--date <value>", "send date for the campaign tag when it is not today: 9Sep | 2026-09-24 | 24/9/2026")
     .option("--raw-campaign", "use --campaign exactly as typed, bypassing the Date_Campaign normalisation")
+    .option("--new-campaign", "confirm the tag is a NEW campaign even though a differently spelled one with the same name already runs")
     .option("--domain <host>", "short domain: chatcart.io (default) | linklnk.io | yapi.store")
     .option("--commit", "actually mint the links (omit = dry-run preview)")
     .option("--json", "raw JSON output")