@flowapt/flowiq-cli 0.6.8 → 0.7.1

package/src/commands/org-flags.js

@@ -0,0 +1,151 @@
+// `flowiq org flags …` — an org's feature flags (the Settings → Profile
+// switches) from the terminal.
+//
+//   flowiq org flags show <org_id>                     what this org carries (secrets redacted)
+//   flowiq org flags list --key <path> [--all]         which orgs carry ONE flag, and its value
+//   flowiq org flags set <org_id> <key> <value> [--yes] write a registered key (type-checked server-side)
+//   flowiq org flags unset <org_id> <key> --yes         remove a key (revert to the platform default)
+//   flowiq org flags keys                               what is settable, by Settings section
+//
+// The server (api/cli/org-flags + _org-flags-registry) is the only validator:
+// only keys the Profile tab manages can be set, credentials are never shown
+// or written, dangerous keys need --yes.
+
+import { http } from "../http.js";
+import { parseFlagValue, fmtValue } from "../flag-values.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const pad = (s, n) => String(s ?? "").padEnd(n);
+
+function requireUuid(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <name>\`).`);
+    process.exit(1);
+  }
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  const b = e.body || {};
+  if (b.needs_confirm) {
+    if (b.danger) console.error(`  ⚠ ${b.danger}`);
+    if (b.before !== undefined) console.error(`  current: ${fmtValue(b.before)}`);
+    if (b.would_set !== undefined) console.error(`  would set: ${fmtValue(b.would_set)}`);
+    console.error("  Re-run with --yes to confirm.");
+  } else if (b.settable === false) {
+    console.error("  `flowiq org flags keys` lists what can be set; `flowiq org flags show <org>` still READS it.");
+  }
+  process.exit(1);
+}
+
+export async function keys(opts = {}) {
+  let resp;
+  try { resp = await http.get("org-flags", { keys: "1" }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const rows = (resp.keys || []).filter((k) => !opts.section || k.section.toLowerCase().includes(opts.section.toLowerCase()));
+  const bySection = new Map();
+  for (const k of rows) {
+    if (!bySection.has(k.section)) bySection.set(k.section, []);
+    bySection.get(k.section).push(k);
+  }
+  console.log(`Settable feature flags (${rows.length}) — the Settings → Profile switches, by section.\n`);
+  for (const [section, list] of bySection) {
+    console.log(`${section}`);
+    for (const k of list) {
+      const type = k.type === "integer" && k.min !== undefined ? `integer ${k.min}-${k.max}` : k.type;
+      console.log(`  ${pad(k.key, 46)} ${pad(type, 14)}${k.danger ? " ⚠ needs --yes" : ""}`);
+      if (k.note) console.log(`  ${pad("", 46)} ${k.note}`);
+    }
+    console.log("");
+  }
+  console.log("Wildcards (`x.*`) take one more segment, e.g. integrations_visible.instagram.");
+  console.log("Anything else on an org is readable via `flowiq org flags show` but not settable here.");
+}
+
+export async function show(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.get("org-flags", { organization_id: orgId }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  console.log(`${o.name} (${o.id})${o.inactive ? "  [INACTIVE]" : ""} — ${resp.key_count} top-level flag key(s)\n`);
+  const known = Object.entries(resp.known || {});
+  if (known.length) {
+    const bySection = new Map();
+    for (const [key, v] of known) {
+      if (!bySection.has(v.section)) bySection.set(v.section, []);
+      bySection.get(v.section).push([key, v.value]);
+    }
+    for (const [section, list] of bySection) {
+      console.log(section);
+      for (const [key, value] of list) console.log(`  ${pad(key, 46)} ${fmtValue(value, 70)}`);
+      console.log("");
+    }
+  } else {
+    console.log("(none of the registered flags are set on this org)\n");
+  }
+  if (resp.unknown_keys?.length) {
+    console.log(`Other keys on this org (readable with --json, not settable from the CLI): ${resp.unknown_keys.join(", ")}`);
+  }
+  if (resp.secret_keys?.length) {
+    console.log(`Credentials present (never shown): ${resp.secret_keys.join(", ")}`);
+  }
+  console.log("\nChange one:  flowiq org flags set <org_id> <key> <value>   (see `flowiq org flags keys`)");
+}
+
+export async function list(opts = {}) {
+  if (!opts.key) { console.error("Error: --key <path> is required (e.g. --key export_insights.enabled)."); process.exit(1); }
+  let resp;
+  try { resp = await http.get("org-flags", { list: "1", key: opts.key, all: opts.all ? "1" : undefined }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  let rows = resp.rows || [];
+  if (opts.on) rows = rows.filter((r) => r.value === true);
+  if (opts.off) rows = rows.filter((r) => r.value !== true);
+  if (opts.present) rows = rows.filter((r) => r.present);
+  if (opts.absent) rows = rows.filter((r) => !r.present);
+
+  const s = resp.summary;
+  const label = resp.registered ? ""
+    : resp.registered_parent ? `  (sub-key of \`${resp.registered_parent}\` — set it through the parent${resp.registered_parent === "export_insights" ? ", or \`flowiq insights enable\`" : ""})`
+    : "  (not a registered key — read-only)";
+  console.log(`${resp.key}${label} across ${s.orgs} org(s)${resp.include_inactive ? " incl. inactive" : ""}: ` +
+    `${s.present} present · ${s.absent} absent` + (s.true || s.false ? ` · ${s.true} true · ${s.false} false` : "") + "\n");
+  if (!rows.length) { console.log("(no orgs match the filter)"); return; }
+  const nameW = Math.min(34, Math.max(4, ...rows.map((r) => (r.name || "").length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  VALUE`);
+  for (const r of rows) {
+    console.log(`${pad((r.name || "").slice(0, nameW), nameW)}  ${pad(r.id, 36)}  ${r.present ? fmtValue(r.value, 60) : "(absent)"}${r.inactive ? "  (inactive)" : ""}`);
+  }
+  console.log(`\n${rows.length} org(s) shown`);
+}
+
+export async function set(orgId, key, value, opts = {}) {
+  requireUuid(orgId);
+  let parsed;
+  try { parsed = parseFlagValue(value); } catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "set", key, value: parsed, confirm: opts.yes === true });
+  } catch (e) { fail("Set failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — ${resp.key}`);
+  console.log(`  ${fmtValue(resp.before, 70)} → ${fmtValue(resp.after, 70)}${resp.changed ? "" : "   (no change)"}`);
+  if (resp.danger) console.log(`  ⚠ ${resp.danger}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags ${resp.before === null ? `unset ${orgId} ${resp.key} --yes` : `set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`}`);
+}
+
+export async function unset(orgId, key, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "unset", key, confirm: opts.yes === true });
+  } catch (e) { fail("Unset failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — removed ${resp.key}`);
+  console.log(`  was: ${fmtValue(resp.before, 70)}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`);
+}

package/src/commands/team-updates.js

@@ -0,0 +1,169 @@
+// `flowiq updates <verb>` — the "what changed in FlowIQ" email to the Flowapt team.
+//   status               uncovered changelog rows, last sends, who receives it
+//   uncovered            list the changelog rows no issue has covered yet
+//   draft [--out f]      write ./.flowiq/updates/<date>.json — a default issue
+//                        composed from the uncovered rows, ready to enrich
+//                        (screenshots, "for the team" notes, a CLI block)
+//   asset <file>         host an image for the email; prints the public URL
+//   preview <file>       render the issue to <file>.html (--open shows it)
+//   send <file>          --test → one copy to you (or --to a@b) without
+//                        marking anything covered; without --test the issue
+//                        goes to every super admin and needs --yes
+// The renderer, the send and the record all live server-side
+// (/cli/team-updates → the team-update-email edge fn); every send is audited.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { http } from "../http.js";
+
+const DIR = path.resolve(process.cwd(), ".flowiq", "updates");
+const TYPES = ["feature", "improvement", "fix", "ui", "agent", "cli", "infra", "db", "mcp"];
+
+function sastStamp() {
+  return new Date().toLocaleDateString("en-CA", { timeZone: "Africa/Johannesburg" }); // YYYY-MM-DD
+}
+
+async function readIssue(file) {
+  const p = path.resolve(process.cwd(), file);
+  let raw;
+  try { raw = await fs.readFile(p, "utf8"); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { console.error(`Error: ${p} is not valid JSON (${e.message})`); process.exit(1); }
+  const issue = doc.issue && typeof doc.issue === "object" ? doc.issue : doc;
+  const problems = lint(issue);
+  if (problems.length) {
+    console.error(`Error: ${p} has ${problems.length} problem(s):`);
+    for (const m of problems) console.error(`  - ${m}`);
+    process.exit(1);
+  }
+  return { issue, file: p };
+}
+
+/** The same checks the server applies, so a bad file fails here with line-level help. */
+function lint(issue) {
+  const out = [];
+  if (!issue.subject) out.push("subject is required");
+  if (!issue.title) out.push("title is required");
+  const secs = [...(issue.headlines ?? []).map((s, i) => [`headlines[${i}]`, s]), ...(issue.tools ?? []).map((s, i) => [`tools[${i}]`, s])];
+  for (const [where, s] of secs) {
+    if (!s.title) out.push(`${where}: title is required`);
+    if (s.type && !TYPES.includes(s.type)) out.push(`${where}: type '${s.type}' is not one of ${TYPES.join("|")}`);
+    if (s.image && !/^https:\/\//.test(s.image.url || "")) out.push(`${where}: image.url must be https (host it with \`flowiq updates asset\`)`);
+    if (s.what && !Array.isArray(s.what)) out.push(`${where}: what must be an array of paragraphs`);
+    if (s.team && !Array.isArray(s.team)) out.push(`${where}: team must be an array of bullets`);
+  }
+  (issue.also ?? []).forEach((a, i) => {
+    if (!a.title) out.push(`also[${i}]: title is required`);
+    if (a.type && !TYPES.includes(a.type)) out.push(`also[${i}]: type '${a.type}' is not valid`);
+  });
+  const text = JSON.stringify(issue);
+  if (/—/.test(text)) out.push("contains an em dash (—) — house style is no em dashes in anything a teammate reads");
+  return out;
+}
+
+function fmtWhen(iso) {
+  return new Date(iso).toLocaleString("en-GB", { timeZone: "Africa/Johannesburg", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" });
+}
+
+export async function status(opts) {
+  let r;
+  try { r = await http.get("team-updates"); }
+  catch (e) { console.error(`Status failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Team updates`);
+  console.log(`  uncovered:  ${r.uncovered} changelog row(s) not yet emailed${r.covered_until ? ` (covered up to ${fmtWhen(r.covered_until)} SAST)` : " (nothing has ever been sent)"}`);
+  console.log(`  recipients: ${(r.recipients ?? []).map((x) => x.email).join(", ") || "none"}`);
+  if (Array.isArray(r.recent) && r.recent.length) {
+    console.log(`  recent:`);
+    for (const s of r.recent) console.log(`    ${fmtWhen(s.created_at)}  ${s.status.padEnd(6)} ${s.source.padEnd(9)} ${String(s.subject).slice(0, 70)}  → ${s.recipients?.length ?? 0}`);
+  }
+}
+
+export async function uncovered(opts) {
+  let r;
+  try { r = await http.get("team-updates", { uncovered: 1, limit: opts?.limit ?? 60 }); }
+  catch (e) { console.error(`Failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (!r.rows?.length) { console.log("Nothing uncovered — every changelog row has been emailed."); return; }
+  console.log(`${r.rows.length} uncovered row(s)${r.since ? ` since ${fmtWhen(r.since)} SAST` : ""}:`);
+  for (const row of r.rows) console.log(`  ${fmtWhen(row.created_at)}  ${row.type.padEnd(11)} ${row.is_major ? "MAJOR " : "      "} ${row.title}${row.org_name ? `  [${row.org_name}]` : ""}`);
+}
+
+export async function draft(opts) {
+  let r;
+  try { r = await http.get("team-updates", { draft: 1, limit: opts?.limit ?? 60, since: opts?.since }); }
+  catch (e) { console.error(`Draft failed: ${e.message}`); process.exit(1); }
+  if (!r.count) { console.log("Nothing to draft — every changelog row has been emailed. Use --since <iso> to re-cover a period."); return; }
+  await fs.mkdir(DIR, { recursive: true });
+  const out = path.resolve(process.cwd(), opts?.out || path.join(DIR, `${sastStamp()}.json`));
+  const doc = {
+    _help: [
+      "This is a default issue composed from the uncovered changelog rows. Enrich it, then `flowiq updates preview` / `send`.",
+      "headlines[]: type, major, title, what[] (paragraphs), team[] (bullets: how WE use it / what to tell clients), image{url,alt,caption} (host with `flowiq updates asset`), terminal{command,output}, link{label,url}.",
+      "also[]: short rows (title, note, type). tools[]: CLI / MCP sections, same shape as headlines.",
+      "Inline markup in any text: **bold**, `code`, [label](https://…). No emoji, no em dashes.",
+    ],
+    issue: r.issue,
+  };
+  await fs.writeFile(out, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`Drafted ${r.count} row(s) → ${path.relative(process.cwd(), out)}`);
+  console.log(`  headlines ${r.issue.headlines?.length ?? 0} · also ${r.issue.also?.length ?? 0} · cli/mcp ${r.issue.tools?.length ?? 0}`);
+  console.log(`  next: enrich it, then \`flowiq updates preview ${path.relative(process.cwd(), out)} --open\``);
+}
+
+export async function asset(file, opts) {
+  const p = path.resolve(process.cwd(), file);
+  let buf;
+  try { buf = await fs.readFile(p); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  const ext = path.extname(p).toLowerCase();
+  const type = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" }[ext];
+  if (!type) { console.error(`Error: ${ext || "(no extension)"} is not an image type the email can use (png, jpg, webp, gif)`); process.exit(1); }
+  let r;
+  try { r = await http.post("team-updates", { action: "asset", name: opts?.name || path.basename(p), content_type: type, data_base64: buf.toString("base64") }); }
+  catch (e) { console.error(`Upload failed: ${e.message}`); process.exit(1); }
+  console.log(r.url);
+}
+
+export async function preview(file, opts) {
+  const { issue, file: p } = await readIssue(file);
+  let r;
+  try { r = await http.post("team-updates", { action: "preview", issue, to_name: opts?.as || "Matt" }); }
+  catch (e) { console.error(`Preview failed: ${e.message}`); process.exit(1); }
+  const out = p.replace(/\.json$/i, "") + ".html";
+  await fs.writeFile(out, r.html);
+  console.log(`Subject: ${r.subject}`);
+  console.log(`Rendered → ${path.relative(process.cwd(), out)} (${(r.html.length / 1024).toFixed(1)} KB)`);
+  if (opts?.open) spawn(process.platform === "darwin" ? "open" : "xdg-open", [out], { stdio: "ignore", detached: true }).unref();
+}
+
+export async function send(file, opts) {
+  const { issue } = await readIssue(file);
+  const to = (opts?.to || "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const test = !!opts?.test;
+  if (test && !to.length) {
+    let me;
+    try { me = await http.get("whoami"); }
+    catch (e) { console.error(`whoami failed: ${e.message}`); process.exit(1); }
+    const email = me?.user_email || me?.email || me?.userEmail;
+    if (!email) { console.error("Could not resolve your email for the test send; pass --to."); process.exit(1); }
+    to.push(email);
+  }
+  if (!test && !opts?.yes) {
+    console.error("Refusing: this sends to the whole Flowapt team and marks the changelog rows as covered. Re-run with --yes, or use --test first.");
+    process.exit(1);
+  }
+  let r;
+  try { r = await http.post("team-updates", { action: "send", issue, to: to.length ? to : undefined, test }); }
+  catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
+  const ok = (r.recipients ?? []).filter((x) => x.status === "sent");
+  const bad = (r.recipients ?? []).filter((x) => x.status !== "sent");
+  console.log(`${test ? "Test sent" : "Sent"}: "${issue.subject}"`);
+  for (const x of ok) console.log(`  ✓ ${x.to}`);
+  for (const x of bad) console.log(`  ✗ ${x.to}  ${x.error ?? x.status}`);
+  if (!test) console.log(r.covers_until ? `  covered up to ${fmtWhen(r.covers_until)} SAST · record ${r.id}` : `  NOT marked as covered (every send failed)`);
+  if (bad.length) process.exitCode = 1;
+}

package/src/flag-values.js

@@ -0,0 +1,42 @@
+// Parse the VALUE argument of `flowiq org flags set <org> <key> <value>`.
+//
+// The SERVER is the validator (api/cli/_org-flags-registry.js type-checks
+// against the registry), so this only has to turn what a human typed into the
+// most obvious JSON: `true`/`false` → booleans, a bare integer → number,
+// `[…]`/`{…}` → parsed JSON, `@file.json` → that file's JSON, `null` → null,
+// everything else → the string as typed (the server splits "a,b" for list
+// keys and coerces "true" for booleans, so a plain string is never wrong).
+
+import { readFileSync } from "node:fs";
+
+export function parseFlagValue(raw) {
+  if (raw === undefined || raw === null) throw new Error("a value is required");
+  const s = String(raw).trim();
+  if (s === "") throw new Error("value must not be empty (use `unset` to remove a key)");
+
+  if (s.startsWith("@")) {
+    const file = s.slice(1);
+    let text;
+    try { text = readFileSync(file, "utf8"); } catch (e) { throw new Error(`cannot read ${file}: ${e.message}`); }
+    try { return JSON.parse(text); } catch (e) { throw new Error(`${file} is not valid JSON: ${e.message}`); }
+  }
+  const lower = s.toLowerCase();
+  if (["true", "yes", "on"].includes(lower)) return true;
+  if (["false", "no", "off"].includes(lower)) return false;
+  if (lower === "null") return null;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (s.startsWith("[") || s.startsWith("{")) {
+    try { return JSON.parse(s); } catch (e) { throw new Error(`value looks like JSON but does not parse: ${e.message}`); }
+  }
+  return s;
+}
+
+/** Render a flag value for a table cell: short, one line, no surprises. */
+export function fmtValue(v, width = 60) {
+  if (v === undefined) return "(absent)";
+  if (v === null) return "null";
+  if (typeof v === "string") return v.length > width ? `${v.slice(0, width - 1)}…` : v;
+  if (typeof v !== "object") return String(v);
+  const s = JSON.stringify(v);
+  return s.length > width ? `${s.slice(0, width - 1)}…` : s;
+}

package/src/flag-values.test.mjs

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { parseFlagValue, fmtValue } from "./flag-values.js";
+
+test("booleans in every spelling a human types", () => {
+  for (const t of ["true", "TRUE", "yes", "on"]) assert.equal(parseFlagValue(t), true);
+  for (const f of ["false", "no", "off", "OFF"]) assert.equal(parseFlagValue(f), false);
+});
+
+test("integers become numbers, decimals stay strings (the server decides)", () => {
+  assert.equal(parseFlagValue("5"), 5);
+  assert.equal(parseFlagValue("-1"), -1);
+  assert.equal(parseFlagValue("1.5"), "1.5");
+});
+
+test("JSON arrays and objects parse; a broken one is an error, not a string", () => {
+  assert.deepEqual(parseFlagValue('["a","b"]'), ["a", "b"]);
+  assert.deepEqual(parseFlagValue('{"enabled":true}'), { enabled: true });
+  assert.throws(() => parseFlagValue("[a,b"), /does not parse/);
+});
+
+test("comma lists stay strings — the server splits them for string[] keys", () => {
+  assert.equal(parseFlagValue("summer,winter"), "summer,winter");
+});
+
+test("@file reads JSON from disk", () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "flowiq-flags-"));
+  const f = path.join(dir, "v.json");
+  writeFileSync(f, JSON.stringify({ enabled: true, schedules: [] }));
+  assert.deepEqual(parseFlagValue(`@${f}`), { enabled: true, schedules: [] });
+  assert.throws(() => parseFlagValue("@/nonexistent/x.json"), /cannot read/);
+});
+
+test("empty is refused (unset is a separate verb)", () => {
+  assert.throws(() => parseFlagValue(""), /unset/);
+  assert.throws(() => parseFlagValue("   "), /unset/);
+});
+
+test("null is explicit null", () => {
+  assert.equal(parseFlagValue("null"), null);
+});
+
+test("fmtValue keeps table cells on one line and marks absence", () => {
+  assert.equal(fmtValue(undefined), "(absent)");
+  assert.equal(fmtValue(true), "true");
+  assert.equal(fmtValue({ a: 1 }), '{"a":1}');
+  assert.equal(fmtValue("x".repeat(80), 10).length, 10);
+});

package/src/http.js

@@ -7,6 +7,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadConfig } from "./config.js";
+import { cmpVersion } from "./update-check.js";
 
 // Sent on every request as X-Flowiq-Cli-Version so the server-side audit log
 // records WHICH CLI version made a change (a stale install is a real source of
@@ -17,6 +18,42 @@ try {
   CLI_VERSION = JSON.parse(readFileSync(path.join(dir, "..", "package.json"), "utf8")).version || "unknown";
 } catch { /* version is a nice-to-have; never block a request on it */ }
 
+export const cliVersion = () => CLI_VERSION;
+
+// ── Server version contract ─────────────────────────────────────────────────
+// Every api/cli/* response carries X-Flowiq-Min-Version (the oldest client the
+// current server contract supports) and X-Flowiq-Api-Build. We record them on
+// every call, and warn ONCE per process when this install is below the minimum.
+//
+// This is the half npm cannot tell you: `npm i -g` compares against the
+// registry, which says nothing about whether the SERVER still speaks your
+// dialect. It is also instant and offline-safe — it rides on a request you were
+// making anyway, with no registry round-trip and no 24h cache to go stale.
+export const serverContract = { minVersion: null, apiBuild: null };
+let warnedBelowMinimum = false;
+
+function noteServerContract(resp) {
+  const min = resp.headers.get("x-flowiq-min-version");
+  const build = resp.headers.get("x-flowiq-api-build");
+  if (min) serverContract.minVersion = min;
+  if (build) serverContract.apiBuild = build;
+
+  if (min && CLI_VERSION !== "unknown" && cmpVersion(min, CLI_VERSION) > 0 && !warnedBelowMinimum) {
+    warnedBelowMinimum = true;
+    process.stderr.write(
+      `\n  ⬆ FLOWIQ CLI TOO OLD FOR THE SERVER — installed ${CLI_VERSION}, server requires ${min}\n` +
+      `    Run this before continuing:  npm i -g @flowapt/flowiq-cli@latest\n` +
+      `    (results from this run may be wrong or incomplete)\n\n`
+    );
+  }
+}
+
+/** True when this install is older than the server's declared minimum. */
+export function isBelowServerMinimum() {
+  const min = serverContract.minVersion;
+  return !!(min && CLI_VERSION !== "unknown" && cmpVersion(min, CLI_VERSION) > 0);
+}
+
 /**
  * Turn an error body into a STRING a human can act on.
  *
@@ -97,6 +134,7 @@ async function call(method, endpoint, { query, body } = {}) {
   }
 
   const resp = await fetch(url, init);
+  noteServerContract(resp);
   const text = await resp.text();
   let parsed, isJson = true;
   try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }

package/src/index.js

@@ -19,6 +19,9 @@ import * as hoursCmd from "./commands/hours.js";
 import * as reportCmd from "./commands/report.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
+import * as orgFlagsCmd from "./commands/org-flags.js";
+import * as insightsCmd from "./commands/insights.js";
+import * as teamUpdatesCmd from "./commands/team-updates.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
@@ -35,6 +38,7 @@ import * as guideCmd from "./commands/guide.js";
 import * as auditCmd from "./commands/audit.js";
 import * as storeApiCmd from "./commands/store-api.js";
 import { maybeNotifyUpdate } from "./update-check.js";
+import * as doctorCmd from "./commands/doctor.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
@@ -291,7 +295,7 @@ export function run(argv) {
     .action((orgId, name, opts) => templatesCmd.show(orgId, name, opts));
 
   // org (read-only org summary for the prompt-builder skill, creds stripped)
-  const org = program.command("org").description("Org info (read) + create a new organization");
+  const org = program.command("org").description("Org info (read), create a new organization, read/set its feature flags");
   org.command("list [search]")
     .description("List organizations with their UUIDs — the lookup every other command needs (filter by name/slug)")
     .option("--all", "include inactive organizations")
@@ -309,6 +313,84 @@ export function run(argv) {
     .option("--json", "print the raw JSON payload")
     .action((orgId, opts) => orgCmd.info(orgId, opts));
 
+  // org flags — organizations.feature_flags (the Settings → Profile switches).
+  // Registry-allowlisted writes, credentials never read or written, dangerous
+  // keys need --yes. `list --key` is the cross-org census that was SQL-only
+  // until 10 Sep 2026.
+  const orgFlags = org.command("flags").description("Read + set an org's feature flags (Settings → Profile switches); `list --key` = cross-org census");
+  orgFlags.command("show <organization_id>")
+    .description("Every flag on the org, by Settings section (credentials redacted)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgFlagsCmd.show(orgId, opts));
+  orgFlags.command("list")
+    .description("Cross-org census of ONE flag: which orgs carry it, and its value")
+    .requiredOption("--key <path>", "dotted flag path, e.g. export_insights.enabled or mcp_member_access.enabled")
+    .option("--all", "include inactive organizations")
+    .option("--on", "only orgs where the value is true")
+    .option("--off", "only orgs where the value is not true (false or absent)")
+    .option("--present", "only orgs that carry the key")
+    .option("--absent", "only orgs that do not carry the key")
+    .option("--json", "raw JSON")
+    .action((opts) => orgFlagsCmd.list(opts));
+  orgFlags.command("set <organization_id> <key> <value>")
+    .description("Set a registered flag (true/false, a number, JSON, or @file.json); type-checked server-side")
+    .option("--yes", "confirm a dangerous flag (the Profile tab's amber-warning switches)")
+    .option("--json", "raw JSON")
+    .action((orgId, key, value, opts) => orgFlagsCmd.set(orgId, key, value, opts));
+  orgFlags.command("unset <organization_id> <key>")
+    .description("Remove a flag key from the org (reverts to the platform default) — always needs --yes")
+    .option("--yes", "confirm")
+    .option("--json", "raw JSON")
+    .action((orgId, key, opts) => orgFlagsCmd.unset(orgId, key, opts));
+  orgFlags.command("keys")
+    .description("What is settable: every registered flag with its type, section and danger note")
+    .option("--section <name>", "filter by Settings section (substring)")
+    .option("--json", "raw JSON")
+    .action((opts) => orgFlagsCmd.keys(opts));
+
+  // insights — the Customer Insights Report (feature_flags.export_insights)
+  const collectEmail = (v, acc) => (acc || []).concat(v);
+  const insights = program.command("insights").description("Customer Insights Report: who has it, enable/disable per org, run one now");
+  insights.command("status [organization_id]")
+    .description("All orgs (or one): enabled, schedules as the scheduler reads them, recipients, own OpenAI key, last report, chats in 30d")
+    .option("--all", "include inactive organizations")
+    .option("--on", "only orgs with insights enabled")
+    .option("--off", "only orgs with insights NOT enabled")
+    .option("--min-chats <n>", "only orgs with at least n chatting contacts in the last 30 days")
+    .option("--sort <by>", "chats (default) | name | last")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.status(orgId, opts));
+  insights.command("enable <organization_id>")
+    .description("Enable the report (or update its config). Cadence flags REPLACE the schedules; none given = keep existing, else weekly Monday")
+    .option("--daily", "add a daily schedule")
+    .option("--weekly [day]", "add a weekly schedule (day: monday … sunday; default monday)")
+    .option("--monthly [day]", "add a monthly schedule (day: 1-28 or last; default last)")
+    .option("--report <type>", "standard (default) | advanced — applies to the cadence flags given")
+    .option("--store-only", "the schedules given store the report without emailing anyone")
+    .option("--recipient <email>", "recipient list (repeatable; REPLACES the existing list)", collectEmail)
+    .option("--add-recipient <email>", "add to the existing recipients (repeatable)", collectEmail)
+    .option("--remove-recipient <email>", "remove from the existing recipients (repeatable)", collectEmail)
+    .option("--dry-run", "show what would be written, write nothing")
+    .option("--force", "write even if pre-flight fails (no OpenAI key / no recipients)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.enable(orgId, opts));
+  insights.command("disable <organization_id>")
+    .description("Turn the scheduled report off (schedules + recipients are kept)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.disable(orgId, opts));
+  insights.command("run <organization_id>")
+    .description("Run one report now (DRY RUN by default — add --commit). Same path as the Profile tab's Run Now")
+    .option("--period <p>", "daily (default: last 24h) | weekly (7d) | monthly (30d)")
+    .option("--from <date>", "custom window start (YYYY-MM-DD, SAST) — with --to")
+    .option("--to <date>", "custom window end (YYYY-MM-DD, SAST) — with --from")
+    .option("--report <type>", "standard | advanced (default: the org's schedule for that period, else standard)")
+    .option("--recipient <email>", "send to these instead of the configured recipients (repeatable)", collectEmail)
+    .option("--store-only", "store the report, email nobody")
+    .option("--commit", "actually fire it")
+    .option("--force", "fire even if pre-flight fails")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.run(orgId, opts));
+
   // agent (list / create / config — config defaults to the active agent, or --agent <id>)
   const agent = program.command("agent").description("List, create, and configure an org's agents");
   agent.command("list <organization_id>")
@@ -783,6 +865,45 @@ export function run(argv) {
     .option("--out <file>", "write the JSON to a file instead of stdout")
     .action((orgId, path, opts) => storeApiCmd.wooGet(orgId, path, opts));
 
+  // updates — the "what changed in FlowIQ" email to the Flowapt team
+  const updates = program.command("updates").description("Team update email: what changed in FlowIQ, sent to every super admin (status / draft / preview / send)");
+  updates.command("status")
+    .description("uncovered changelog rows, recent sends and who receives the email")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.status(opts));
+  updates.command("uncovered")
+    .description("list the changelog rows no team update has covered yet")
+    .option("--limit <n>", "rows to list (default 60)")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.uncovered(opts));
+  updates.command("draft")
+    .description("write ./.flowiq/updates/<date>.json: a default issue composed from the uncovered rows, ready to enrich")
+    .option("--since <iso>", "compose from rows created after this time instead of the last covered point")
+    .option("--limit <n>", "rows to include (default 60)")
+    .option("--out <file>", "write the issue here instead of ./.flowiq/updates/<date>.json")
+    .action((opts) => teamUpdatesCmd.draft(opts));
+  updates.command("asset <file>")
+    .description("host an image (png/jpg/webp/gif, max 6 MB) for the email and print its public URL")
+    .option("--name <name>", "file name to store under (default: the file's own name)")
+    .action((file, opts) => teamUpdatesCmd.asset(file, opts));
+  updates.command("preview <file>")
+    .description("render the issue JSON to <file>.html exactly as it will be emailed")
+    .option("--as <first-name>", "greet this name in the preview (default Matt)")
+    .option("--open", "open the rendered HTML in the browser")
+    .action((file, opts) => teamUpdatesCmd.preview(file, opts));
+  updates.command("send <file>")
+    .description("email the issue: --test sends one copy to you (or --to) and marks nothing; without --test it goes to every super admin and needs --yes")
+    .option("--test", "send a single test copy only (to you unless --to is given); nothing is marked as covered")
+    .option("--to <emails>", "comma-separated recipients instead of the team list")
+    .option("--yes", "confirm the real send to the whole team")
+    .action((file, opts) => teamUpdatesCmd.send(file, opts));
+
+  // doctor (version + auth + server contract in one read-only command)
+  program.command("doctor")
+    .description("Check this install: version vs npm, auth, and whether the server still supports it. Exits 1 if something needs fixing")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => { process.exitCode = await doctorCmd.doctor(opts); });
+
   // guide (bundled docs — always match the installed version)
   program.command("guide")
     .description("Read the team guide (how we use this CLI); --reference for the full command reference")