@flowapt/flowiq-cli 0.9.6 → 0.9.8

package/src/commands/gaps.js

@@ -0,0 +1,346 @@
+// `flowiq gaps report|list|show|hit|note|status` — CLI gap reports and feature
+// requests (alias `flowiq requests`), via /cli/gaps.
+//   report  file one: something the CLI cannot do, does wrong, or should do
+//   list    open requests, most-hit first (every status with --status all)
+//   show    one request in full, with every hit, note and status change
+//   hit     "this bit me too": +1 with what you were doing (the ranking signal)
+//   note    add context without counting a hit
+//   status  planned / in_progress / done / declined / duplicate (maintainers;
+//           closing emails everyone who reported or hit it)
+// Anyone with a staff key can report, hit and note — including a Claude
+// session driving the CLI, which is marked `claude` automatically.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const KINDS = ["gap", "idea", "bug"];
+const STATUSES = ["open", "planned", "in_progress", "done", "declined", "duplicate"];
+const STATUS_ORDER = ["in_progress", "planned", "open", "done", "declined", "duplicate"];
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** Who is typing: a Claude session, a script/pipe, or a person at a terminal. */
+export function filedVia(env = process.env, stdin = process.stdin, stdout = process.stdout) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) return "claude";
+  if (!stdin?.isTTY || !stdout?.isTTY) return "script";
+  return "human";
+}
+
+/** "42", "#42" or a UUID; anything else is refused before a request is made. */
+export function normaliseRef(ref) {
+  const raw = String(ref ?? "").trim().replace(/^#/, "");
+  if (/^\d{1,12}$/.test(raw)) return raw;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) return raw;
+  return null;
+}
+
+function sastParts(ts) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(ts));
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+function fmtTs(ts) {
+  if (!ts) return "-";
+  const p = sastParts(ts);
+  const hour = p.hour === "24" ? "00" : p.hour;
+  return `${Number(p.day)} ${MONTHS[Number(p.month) - 1]} ${p.year} ${hour}:${p.minute}`;
+}
+
+export function ago(ts, now = Date.now()) {
+  if (!ts) return "-";
+  const mins = Math.max(0, Math.round((now - new Date(ts).getTime()) / 60000));
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.round(mins / 60);
+  if (hrs < 48) return `${hrs}h ago`;
+  return `${Math.round(hrs / 24)}d ago`;
+}
+
+function who(email) {
+  if (!email) return "?";
+  return String(email).split("@")[0];
+}
+
+function indent(text, pad = "    ") {
+  return String(text ?? "").trim().split("\n").map((l) => `${pad}${l}`).join("\n");
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  if (e.body?.error && !String(e.message).includes(e.body.error)) console.error(`  ${e.body.error}`);
+  process.exit(1);
+}
+
+function requireRef(ref) {
+  const r = normaliseRef(ref);
+  if (!r) {
+    console.error(`Error: "${ref}" is not a request number (e.g. 42 or #42). Find it with \`flowiq gaps list\`.`);
+    process.exit(1);
+  }
+  return r;
+}
+
+function printSimilar(similar, heading) {
+  if (!similar?.length) return;
+  console.log(heading);
+  for (const s of similar) {
+    const shipped = s.status === "done" && s.resolved_version ? ` in ${s.resolved_version}` : "";
+    console.log(`  #${s.number}  ${s.title}  [${s.status}${shipped} · ${s.hit_count} hit(s) · match ${s.score}]`);
+  }
+}
+
+// ── report ──────────────────────────────────────────────────────────────────
+export async function report(titleWords, opts = {}) {
+  const title = (Array.isArray(titleWords) ? titleWords.join(" ") : String(titleWords || "")).trim();
+  if (title.length < 3) {
+    console.error('Error: give a one-line title, e.g. flowiq gaps report "agent config cannot set tool_instructions" --command "agent config"');
+    process.exit(1);
+  }
+  const kind = String(opts.kind || "gap").toLowerCase();
+  if (!KINDS.includes(kind)) {
+    console.error(`Error: --kind must be ${KINDS.join(" | ")} (gap = the CLI cannot do it, bug = it does it wrong, idea = it should).`);
+    process.exit(1);
+  }
+  let detail = opts.detail ?? null;
+  if (opts.detailFile) {
+    try {
+      detail = await fs.readFile(path.resolve(process.cwd(), opts.detailFile), "utf8");
+    } catch (e) {
+      console.error(`Error: cannot read --detail-file ${opts.detailFile}: ${e.message}`);
+      process.exit(1);
+    }
+  }
+
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "report",
+      title,
+      kind,
+      command: opts.command ?? null,
+      detail,
+      error_text: opts.error ?? null,
+      workaround: opts.workaround ?? null,
+      priority: opts.priority ?? "normal",
+      organization_id: opts.org ?? null,
+      filed_via: filedVia(),
+      force_new: Boolean(opts.new),
+      dry_run: Boolean(opts.dryRun),
+    });
+  } catch (e) {
+    if (e.status === 409) {
+      console.error(e.body?.error || e.message);
+      printSimilar(e.body?.similar, "\nAlready on the list:");
+      process.exit(1);
+    }
+    fail("Report failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  if (resp.dry_run) {
+    console.log(`DRY RUN · nothing filed · "${title}"`);
+    if (!resp.similar?.length) console.log("  No similar requests on the list. File it by re-running without --dry-run.");
+    printSimilar(resp.similar, "Similar requests:");
+    if (resp.would_block) console.log("\nA real report would be held as a duplicate: hit the matching one, or pass --new if it is different.");
+    return;
+  }
+  const r = resp.request;
+  console.log(`Filed #${r.number} (${r.kind}${r.command ? ` · flowiq ${r.command}` : ""}): ${r.title}`);
+  console.log(`  by ${r.reporter_email ?? "?"} via ${r.filed_via}${r.organization_name ? ` · org ${r.organization_name}` : ""}`);
+  printSimilar(resp.similar, "\nPossibly related:");
+  console.log(`\nTrack it: flowiq gaps show ${r.number}   ·   hit it again next time: flowiq gaps hit ${r.number} --note "…"`);
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+export async function list(opts = {}) {
+  const query = {};
+  if (opts.status) query.status = opts.status;
+  if (opts.command) query.command = opts.command;
+  if (opts.kind) query.kind = opts.kind;
+  if (opts.mine) query.mine = "1";
+  if (opts.search) query.search = opts.search;
+  if (opts.sort) query.sort = opts.sort;
+  if (opts.limit != null) query.limit = String(opts.limit);
+
+  let resp;
+  try {
+    resp = await http.get("gaps", query);
+  } catch (e) {
+    fail("List failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const totals = STATUS_ORDER.filter((s) => resp.counts?.[s]).map((s) => `${s} ${resp.counts[s]}`).join(" · ");
+  console.log(`CLI requests · status ${resp.status_filter} · ${resp.total} shown · every status: ${totals || "none yet"}`);
+  const rows = resp.requests || [];
+  if (!rows.length) {
+    console.log("  (nothing matches)");
+    console.log('\nFile one: flowiq gaps report "<what the CLI cannot do>" --command "<topic>"');
+    return;
+  }
+  for (const r of rows) {
+    const cmd = r.command ? `[${r.command}] ` : "";
+    const shipped = r.status === "done" && r.resolved_version ? ` ${r.resolved_version}` : "";
+    console.log(`\n#${r.number}  ${r.kind.padEnd(4)} ×${r.hit_count}  ${cmd}${r.title}`);
+    const bits = [
+      `${r.status}${shipped}`,
+      r.priority !== "normal" ? `${r.priority} priority` : null,
+      `by ${who(r.reporter_email)}${r.filed_via === "claude" ? " (Claude)" : ""} ${ago(r.created_at)}`,
+      r.hit_count > 1 ? `last hit ${ago(r.last_hit_at)}` : null,
+      r.organization_name ? `org ${r.organization_name}` : null,
+    ].filter(Boolean);
+    console.log(`    ${bits.join(" · ")}`);
+  }
+  if (resp.truncated) console.log(`\n⚠ the limit (${resp.limit}) was reached: pass --limit, or narrow with --status / --command / --search.`);
+  console.log("\nOne in full: flowiq gaps show <number>   ·   same problem? flowiq gaps hit <number> --note \"…\"");
+}
+
+// ── show ────────────────────────────────────────────────────────────────────
+export async function show(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  let resp;
+  try {
+    resp = await http.get("gaps", { ref: r0 });
+  } catch (e) {
+    fail("Show failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`#${r.number}  ${r.title}`);
+  console.log(`  kind:      ${r.kind}${r.command ? ` · flowiq ${r.command}` : ""} · priority ${r.priority}`);
+  console.log(`  status:    ${r.status}${r.resolved_version ? ` (${r.resolved_version})` : ""}${resp.duplicate_of ? ` of #${resp.duplicate_of.number} "${resp.duplicate_of.title}"` : ""}`);
+  console.log(`  hits:      ${r.hit_count} · last ${fmtTs(r.last_hit_at)} SAST`);
+  console.log(`  filed:     ${fmtTs(r.created_at)} SAST by ${r.reporter_email ?? "?"} via ${r.filed_via ?? "?"}${r.cli_version ? ` (CLI ${r.cli_version})` : ""}`);
+  if (r.organization_name) console.log(`  org:       ${r.organization_name}`);
+  if (r.resolved_at) console.log(`  closed:    ${fmtTs(r.resolved_at)} SAST by ${r.resolved_by_email ?? "?"}`);
+  console.log(`  id:        ${r.id}`);
+  if (r.detail) console.log(`\nDetail\n${indent(r.detail, "  ")}`);
+  if (r.error_text) console.log(`\nError (verbatim)\n${indent(r.error_text, "  ")}`);
+  if (r.workaround) console.log(`\nWorkaround used\n${indent(r.workaround, "  ")}`);
+  if (r.resolution_note) console.log(`\nResolution\n${indent(r.resolution_note, "  ")}`);
+
+  const events = resp.events || [];
+  if (events.length) {
+    console.log(`\nHistory (${events.length})`);
+    for (const e of events) {
+      const head = e.kind === "status"
+        ? `status ${e.from_status} → ${e.to_status}`
+        : e.kind === "hit" ? "hit again" : "note";
+      const org = e.organization_name ? ` · ${e.organization_name}` : "";
+      console.log(`  ${fmtTs(e.created_at)}  ${who(e.user_email)}${e.filed_via === "claude" ? " (Claude)" : ""}: ${head}${org}`);
+      if (e.body) console.log(indent(e.body, "      "));
+      if (e.error_text) console.log(indent(`error: ${e.error_text}`, "      "));
+    }
+  }
+  console.log(`\nSame problem? flowiq gaps hit ${r.number} --note "what you were doing"`);
+  console.log(`Maintainers (${(resp.editors || []).join(", ")}): flowiq gaps status ${r.number} --to done --version <x.y.z> --note "…"`);
+}
+
+// ── hit ─────────────────────────────────────────────────────────────────────
+export async function hit(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "hit",
+      ref: r0,
+      note: opts.note ?? null,
+      error_text: opts.error ?? null,
+      organization_id: opts.org ?? null,
+      filed_via: filedVia(),
+    });
+  } catch (e) {
+    fail("Hit failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`+1 on #${r.number} (${resp.hit_count} hits): ${r.title}`);
+  if (r.status === "done") {
+    console.log(`  ⚠ this is marked DONE${r.resolved_version ? ` in ${r.resolved_version}` : ""}. Update first (npm i -g @flowapt/flowiq-cli@latest); if it still fails, say so with: flowiq gaps note ${r.number} "still fails on <version>: …"`);
+  } else if (r.status !== "open") {
+    console.log(`  status: ${r.status}`);
+  }
+}
+
+// ── note ────────────────────────────────────────────────────────────────────
+export async function note(ref, textWords, opts = {}) {
+  const r0 = requireRef(ref);
+  const text = (Array.isArray(textWords) ? textWords.join(" ") : String(textWords || "")).trim();
+  if (!text) {
+    console.error("Error: give the note text, e.g. flowiq gaps note 42 \"also happens with --agent\"");
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("gaps", { action: "note", ref: r0, body: text });
+  } catch (e) {
+    fail("Note failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  console.log(`Noted on #${resp.request.number}: ${resp.request.title}`);
+}
+
+// ── status ──────────────────────────────────────────────────────────────────
+export async function status(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  const to = String(opts.to || "").toLowerCase();
+  if (!STATUSES.includes(to)) {
+    console.error(`Error: --to must be one of ${STATUSES.join(" | ")} (got "${opts.to ?? ""}").`);
+    process.exit(1);
+  }
+  if (["done", "declined"].includes(to) && !(opts.note && opts.note.trim())) {
+    console.error(`Error: --note is required for ${to}. The people who asked get it by email: what shipped, or why not.`);
+    process.exit(1);
+  }
+  let dupRef = null;
+  if (to === "duplicate") {
+    dupRef = normaliseRef(opts.of);
+    if (!dupRef) {
+      console.error("Error: --to duplicate needs --of <number>: the request this one duplicates.");
+      process.exit(1);
+    }
+  }
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "status",
+      ref: r0,
+      status: to,
+      note: opts.note ?? null,
+      version: opts.version ?? null,
+      duplicate_of: dupRef,
+      notify: opts.notify !== false,
+    });
+  } catch (e) {
+    fail("Status change failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`#${r.number} ${resp.previous_status} → ${r.status}${r.resolved_version ? ` (${r.resolved_version})` : ""}: ${r.title}`);
+  if (resp.duplicate_of) console.log(`  merged into #${resp.duplicate_of.number} "${resp.duplicate_of.title}" (hits carried over)`);
+  const n = resp.notified || {};
+  if (n.skipped) return;
+  if (n.sent?.length) console.log(`  emailed: ${n.sent.join(", ")}`);
+  else console.log("  nobody else to email (you were the only reporter)");
+  for (const f of n.failed || []) console.log(`  ⚠ email to ${f.to} failed: ${f.error}`);
+}

package/src/commands/keywords.js

@@ -37,6 +37,32 @@ async function resolvePushPath(identifier) {
   throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
 }
 
+const sastDay = (iso) => {
+  try { return new Date(iso).toLocaleString("sv-SE", { timeZone: "Africa/Johannesburg" }).slice(0, 16); }
+  catch { return String(iso).slice(0, 16); }
+};
+
+// The keyword-scheduler cron (every 30 min) flips `active` on at start_date and
+// off at end_date; the runtime itself reads `active` only. So an ACTIVE row with
+// a future start is answering already, and an active row past its end has not
+// been switched off yet.
+export function scheduleLabel(k, now = Date.now()) {
+  const start = k.start_date ? Date.parse(k.start_date) : null;
+  const end = k.end_date ? Date.parse(k.end_date) : null;
+  const parts = [];
+  if (start && start > now) {
+    parts.push(k.active === false
+      ? ` · starts ${sastDay(k.start_date)} SAST`
+      : ` · ⚠ LIVE BEFORE ITS START (${sastDay(k.start_date)} SAST): active, so it answers now`);
+  }
+  if (end) {
+    parts.push(end <= now && k.active !== false
+      ? ` · ⚠ PAST ITS END (${sastDay(k.end_date)} SAST) but still active`
+      : ` · ends ${sastDay(k.end_date)}${end > now ? " SAST" : ""}`);
+  }
+  return parts.join("");
+}
+
 export async function pull(orgId) {
   if (!UUID_RE.test(orgId)) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);
@@ -59,9 +85,24 @@ export async function pull(orgId) {
   console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
   console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
   console.log(`  keywords:  ${resp.keyword_count}`);
-  for (const k of resp.keywords || []) {
+  // Active rows first, in the order the runtime tries them (first match wins),
+  // then the inactive ones.
+  const all = resp.keywords || [];
+  const order = resp.runtime_order || [];
+  const byId = new Map(all.map((k) => [k.id, k]));
+  const listed = [
+    ...order.map((id) => byId.get(id)).filter(Boolean),
+    ...all.filter((k) => !order.includes(k.id)),
+  ];
+  if (order.length) console.log(`  (active rows in runtime order: the first matching row answers)`);
+  for (const k of listed) {
     const acts = (k.keyword_actions || []).length;
-    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${k.end_date ? ` · ends ${k.end_date.slice(0, 10)}` : ""}`);
+    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${scheduleLabel(k)}`);
+  }
+  for (const c of resp.collisions || []) {
+    console.log("");
+    console.log(`  ⚠ TRIGGER COLLISION: ${c.triggers.map((t) => `"${t}"`).join(", ")} matches both "${c.winner.type}" and "${c.shadowed.type}".`);
+    console.log(`    ${c.note}.`);
   }
   if (resp.has_attribute_actions) {
     console.log("");

package/src/commands/links.js

@@ -115,6 +115,7 @@ export async function shorten(orgId, opts = {}) {
       content,
       domain: opts.domain,
       dry_run: dryRun,
+      confirm_new_campaign: !!opts.newCampaign,
     });
   } catch (e) {
     console.error(`Shorten failed: ${e.message}`);
@@ -128,6 +129,13 @@ export async function shorten(orgId, opts = {}) {
     : "no UTM tags (plain short link)";
   console.log(`${resp.organization_name} · ${resp.domain}`);
   console.log(`${utm}\n`);
+  if (resp.campaign_conflicts?.length) {
+    const c = resp.campaign_conflicts[0];
+    console.log(`⚠ CAMPAIGN FORK: this org already runs ${resp.campaign_conflicts.map((x) => `"${x.campaign}" (${x.links} link${x.links === 1 ? "" : "s"})`).join(", ")},`);
+    console.log(`  the same campaign as "${resp.utm?.campaign}" spelled differently. The Broadcasts tab would show two rows.`);
+    console.log(`  Reuse it: --campaign ${c.campaign} --raw-campaign    or confirm a separate campaign: --new-campaign`);
+    console.log("");
+  }
 
   for (const r of resp.results) {
     const label = {

package/src/commands/prompts.js

@@ -5,6 +5,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { http } from "../http.js";
 import { fmtSast } from "./audit.js";
 
@@ -54,15 +55,16 @@ export async function pull(orgId, opts = {}) {
     process.exit(1);
   }
 
-  await fs.mkdir(PROMPTS_DIR, { recursive: true });
   // Non-active agents get an agent-suffixed filename so pulling multiple agents
   // from the same org doesn't clobber each other's working copy. The active
-  // agent keeps the plain <org>.json name (backwards-compatible).
+  // agent keeps the plain <org>.json name (backwards-compatible). --out writes
+  // anywhere else (a scratch copy that leaves the working file alone).
   const orgSlug = slugify(resp.organization_name, resp.organization_id);
   const slug = resp.is_active === false
     ? `${orgSlug}-${slugify(resp.agent_name, resp.agent_id.slice(0, 8))}`
     : orgSlug;
-  const filePath = path.join(PROMPTS_DIR, `${slug}.json`);
+  const filePath = opts.out ? path.resolve(opts.out) : path.join(PROMPTS_DIR, `${slug}.json`);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
   const overwriting = await fileExists(filePath);
   await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
 
@@ -82,6 +84,18 @@ export async function pull(orgId, opts = {}) {
   }
 }
 
+/** Give every section without an id a fresh uuid. Returns the titles it touched. */
+export function mintSectionIds(sections) {
+  const touched = [];
+  for (const sec of sections) {
+    if (sec && typeof sec === "object" && (typeof sec.id !== "string" || !sec.id.trim())) {
+      sec.id = randomUUID();
+      touched.push(sec.title || "(untitled)");
+    }
+  }
+  return touched;
+}
+
 export async function push(identifier) {
   let filePath;
   try {
@@ -107,6 +121,14 @@ export async function push(identifier) {
     process.exit(1);
   }
 
+  // A section added by hand has no id yet. Mint one and write it back to the
+  // file BEFORE pushing, so a later pull or push keeps the same id.
+  const minted = mintSectionIds(data.prompt_sections);
+  if (minted.length) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    console.log(`Added an id to ${minted.length} new section(s) in ${filePath}: ${minted.map((t) => `"${t}"`).join(", ")}`);
+  }
+
   let resp;
   try {
     resp = await http.post("prompts", {

package/src/commands/store-api.js

@@ -265,6 +265,45 @@ async function rawGet(orgId, path, query, { label } = {}) {
   return resp.data;
 }
 
+// Shopify's own product search (title, SKU, vendor, tags…), so a partial title
+// on a 3,594-product catalogue is found without scanning pages. Anything
+// Shopify's search syntax takes works here too: "sku:75461", "handle:foo".
+const STOCK_SEARCH_GQL = `query StockSearch($q: String!) {
+  products(first: 50, query: $q) {
+    edges { node {
+      legacyResourceId title status
+      variants(first: 100) { edges { node {
+        legacyResourceId title sku price inventoryPolicy inventoryQuantity
+        inventoryItem { legacyResourceId }
+      } } }
+    } }
+  }
+}`;
+
+async function searchProducts(orgId, search) {
+  console.error(`  $ flowiq shopify gql <org> --query '${STOCK_SEARCH_GQL.replace(/\s+/g, " ")}' --var q=${JSON.stringify(search)}    # Shopify product search`);
+  const resp = await http.post("store-api", {
+    platform: "shopify", organization_id: orgId, mode: "graphql",
+    graphql: { query: STOCK_SEARCH_GQL, variables: { q: search } },
+  });
+  if (resp.graphql_errors?.length) throw new Error(`Shopify search failed: ${resp.graphql_errors.map((e) => e.message).join("; ")}`);
+  // Map to the REST shape the rest of the recipe reads.
+  return (resp.data?.products?.edges || []).map(({ node: p }) => ({
+    id: Number(p.legacyResourceId),
+    title: p.title,
+    status: String(p.status || "").toLowerCase(),
+    variants: (p.variants?.edges || []).map(({ node: v }) => ({
+      id: Number(v.legacyResourceId),
+      title: v.title,
+      sku: v.sku,
+      price: v.price,
+      inventory_policy: String(v.inventoryPolicy || "").toLowerCase(),
+      inventory_quantity: v.inventoryQuantity,
+      inventory_item_id: v.inventoryItem?.legacyResourceId ? Number(v.inventoryItem.legacyResourceId) : null,
+    })),
+  }));
+}
+
 export async function shopifyStock(orgId, search, opts = {}) {
   requireOrg(orgId);
   if (!search || !String(search).trim()) {
@@ -278,17 +317,22 @@ export async function shopifyStock(orgId, search, opts = {}) {
     const p = await rawGet(orgId, "products.json", { title: search, limit: 50 }, { label: "find the product" });
     products = (p?.products || []).filter((x) =>
       String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+    let fromSearch = false;
     if (!products.length) {
-      const all = await rawGet(orgId, "products.json", { limit: 250, fields: "id,title,variants,status" },
-        { label: "no title match — scanning the catalogue" });
-      products = (all?.products || []).filter((x) =>
-        String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+      // No exact title: ask Shopify's search, then keep the titles holding every
+      // word of the search (or, when none do, what Shopify ranked closest).
+      const found = await searchProducts(orgId, String(search));
+      const words = String(search).toLowerCase().split(/\s+/).filter((w) => w && !w.includes(":"));
+      const strict = found.filter((x) => words.every((w) => String(x.title).toLowerCase().includes(w)));
+      products = strict.length ? strict : found;
+      fromSearch = products.length > 0 && !strict.length && words.length > 0;
     }
     if (!products.length) {
-      console.error(`\nNothing matched "${search}". This searches product TITLES only — ` +
-        `the passthrough can query anything else Shopify exposes.`);
+      console.error(`\nShopify's product search found nothing for "${search}" (it searches the whole catalogue: ` +
+        `title, SKU, vendor, tags). Try fewer words, or "sku:<sku>" / "handle:<handle>".`);
       process.exit(1);
     }
+    if (fromSearch) console.error(`  (no title holds every word of "${search}"; showing Shopify's closest matches)`);
     const itemIds = products.flatMap((x) => (x.variants || []).map((v) => v.inventory_item_id)).filter(Boolean);
     // 2. inventory_item_id → per-location levels   3. location_id → names
     levels = itemIds.length
@@ -335,6 +379,9 @@ export async function shopifyStock(orgId, search, opts = {}) {
   }
   console.error("");
   console.log(renderTable(rows) ?? "(no variants)");
+  if (products.flatMap((x) => x.variants || []).length > 50) {
+    console.error(`\n⚠ per-location levels cover the first 50 variants only; narrow the search for the rest.`);
+  }
   console.error(`\n${products.length} product(s) · ${rows.length} variant(s). ` +
     `"not tracked" means Shopify holds no inventory record at that location — it is not a zero.`);
 }

package/src/commands/templates.js

@@ -91,6 +91,10 @@ export async function create(orgId, opts = {}) {
   } catch (e) {
     console.error(`Create failed: ${e.message}`);
     if (e.body) console.error(JSON.stringify(e.body, null, 2));
+    if (e.status === 504 || /TIMEOUT/i.test(e.message)) {
+      console.error(`\n⚠ The template may already be created at Meta (the upload can outlive the proxy). Do NOT retry yet; check first:`);
+      console.error(`  flowiq templates status ${organizationId} --live --name ${templateRequest.name}`);
+    }
     process.exit(1);
   }
 
@@ -103,6 +107,8 @@ export async function status(orgId, opts = {}) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);
     process.exit(1);
   }
+  if (opts.watch && !opts.live) opts.live = true;
+  if (opts.live) return liveStatus(orgId, opts);
   let resp;
   try {
     resp = await http.get("meta-templates", { organization_id: orgId, name: opts.name });
@@ -112,18 +118,55 @@ export async function status(orgId, opts = {}) {
   }
   const rows = resp.templates || [];
   if (!rows.length) {
-    console.log(opts.name ? `(no templates matching "${opts.name}")` : "(no templates on record for this org)");
+    // An empty FlowIQ table is not "no templates": templates made in Meta's
+    // own tools, or on a swapped WABA, exist only at Meta (Health Matrix, 22 Sep).
+    console.log(opts.name
+      ? `No template matching "${opts.name}" is recorded in FlowIQ. Meta may still hold one: flowiq templates status ${orgId} --live --name ${opts.name}`
+      : `No templates are recorded in FlowIQ for this org. Meta may still hold some: flowiq templates status ${orgId} --live (or templates pull ${orgId}).`);
     return;
   }
-  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""}:`);
+  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""} recorded in FlowIQ:`);
   for (const t of rows) {
     const name = t.template_name || t.name || "(unnamed)";
-    const st = t.status || "(no status)";
+    // meta_status is what Meta's status webhook last reported; `status` is often
+    // left at its submit-time value.
+    const st = t.meta_status || t.status || "(no status)";
     const cat = t.category ? ` [${t.category}]` : "";
     console.log(`  ${name.padEnd(40)} ${String(st).padEnd(16)}${cat}`);
   }
-  console.log("\nNote: status is captured at submit time (older rows may be null). For the live");
-  console.log("Meta-side status + rejection reasons, run `templates pull <org_id>`.");
+  console.log(`\nThis is FlowIQ's record (Meta's webhook keeps it current). Straight from Meta, with rejection reasons:`);
+  console.log(`  flowiq templates status ${orgId} --live${opts.name ? ` --name ${opts.name}` : ""} [--watch]`);
+}
+
+const TERMINAL = new Set(["APPROVED", "REJECTED", "DISABLED", "PAUSED", "DELETED", "LIMIT_EXCEEDED"]);
+
+async function liveStatus(orgId, opts) {
+  const intervalMs = 15000, maxMs = 15 * 60 * 1000, started = Date.now();
+  for (;;) {
+    let resp;
+    try {
+      resp = await http.get("templates", { organization_id: orgId, name: opts.name });
+    } catch (e) {
+      console.error(`Live status failed: ${e.message}`);
+      process.exit(1);
+    }
+    const rows = resp.templates || [];
+    const stamp = new Date().toLocaleTimeString("en-GB", { timeZone: "Africa/Johannesburg" });
+    if (!rows.length) {
+      console.log(`${stamp}  Meta holds no template${opts.name ? ` matching "${opts.name}"` : "s"} on ${resp.organization_name}'s WABA.`);
+    } else {
+      console.log(`${stamp}  ${rows.length} template${rows.length === 1 ? "" : "s"} at Meta (${resp.organization_name})${opts.name ? ` matching "${opts.name}"` : ""}:`);
+      for (const t of rows) {
+        const moved = t.previous_category && t.previous_category !== t.category ? ` (was ${t.previous_category})` : "";
+        const why = t.rejected_reason && t.rejected_reason !== "NONE" ? `  reason: ${t.rejected_reason}` : "";
+        console.log(`  ${String(t.name).padEnd(40)} ${String(t.status).padEnd(16)} [${t.category}${moved}] ${t.language}${t.parameter_format ? ` · ${t.parameter_format}` : ""}${why}`);
+      }
+    }
+    const pending = rows.filter((t) => !TERMINAL.has(String(t.status)));
+    if (!opts.watch || (rows.length && !pending.length)) return;
+    if (Date.now() - started > maxMs) { console.log(`Still not decided after 15 min; stopped watching.`); return; }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
 }
 
 export async function list() {