@flowapt/flowiq-cli 0.1.5 → 0.1.7

package/src/commands/groups.js

@@ -0,0 +1,329 @@
+// `flowiq groups list|pull` — read WhatsApp GROUP chat history out of the
+// FlowMod Evolution Postgres (app.flowmod.ai:5555), mirroring `messages pull`.
+//
+// This is the only CLI command that talks to a database directly instead of
+// going through api.flowiq.live/cli/* — the Evolution DB is a separate Postgres
+// (NOT Supabase, NOT a service-role key). To keep this published npm package
+// secret-free, the connection string comes from the environment, never source:
+//
+//   FLOWMOD_EVO_DB_URL=postgres://user:pass@app.flowmod.ai:5555/flowiq-db
+//     — or the five vars the flowmod-copilot edge fn already uses —
+//   FLOWMOD_DB_HOST / FLOWMOD_DB_PORT / FLOWMOD_DB_USER / FLOWMOD_DB_PASS / FLOWMOD_DB_NAME
+//
+// Read-only: there is no `push` — group history is a system of record.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const OUT_DIR = path.resolve(process.cwd(), ".flowiq", "groups");
+const DEFAULT_INSTANCE = "flowapt";
+const DEFAULT_LAST_MS = 48 * 3600 * 1000; // 48h
+const DEFAULT_LIMIT = 1000;
+
+// ---------- credential resolution (env only — no baked secret) ----------
+function evoConnString() {
+  const url = process.env.FLOWMOD_EVO_DB_URL?.trim();
+  if (url) return url;
+  const host = process.env.FLOWMOD_DB_HOST?.trim();
+  const user = process.env.FLOWMOD_DB_USER?.trim();
+  const pass = process.env.FLOWMOD_DB_PASS;
+  const name = process.env.FLOWMOD_DB_NAME?.trim();
+  if (host && user && pass != null && name) {
+    const port = process.env.FLOWMOD_DB_PORT?.trim() || "5555";
+    return `postgres://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@${host}:${port}/${name}`;
+  }
+  return null;
+}
+
+async function connect() {
+  const conn = evoConnString();
+  if (!conn) {
+    console.error(
+      "Error: no Evolution DB connection configured.\n" +
+        "Set FLOWMOD_EVO_DB_URL (a full postgres:// URL) in your shell env,\n" +
+        "or the five FLOWMOD_DB_HOST/PORT/USER/PASS/NAME vars.\n" +
+        "Creds are in ~/.claude/context/external-services.md (FlowMod Evolution section)."
+    );
+    process.exit(1);
+  }
+  let Client;
+  try {
+    const mod = await import("pg");
+    Client = (mod.default ?? mod).Client;
+  } catch {
+    console.error("Error: the `pg` package is not installed. Run `npm install` in the cli/ folder.");
+    process.exit(1);
+  }
+  const client = new Client({ connectionString: conn, ssl: false });
+  try {
+    await client.connect();
+  } catch (e) {
+    console.error(`Could not connect to the Evolution DB: ${e.message}`);
+    process.exit(1);
+  }
+  return client;
+}
+
+// ---------- helpers ----------
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+// "48h" | "7d" | "90m" | "2w" -> milliseconds (null if unparseable)
+function parseLast(s) {
+  const m = /^(\d+)\s*(m|h|d|w)$/i.exec(String(s).trim());
+  if (!m) return null;
+  const n = Number(m[1]);
+  const mult = { m: 60e3, h: 3600e3, d: 86400e3, w: 604800e3 }[m[2].toLowerCase()];
+  return n * mult;
+}
+
+// "YYYY-MM-DD" | "YYYY-MM-DD HH:MM[:SS]" interpreted as SAST -> unix seconds
+function sastToUnix(s) {
+  const m = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}:\d{2}(?::\d{2})?))?$/.exec(String(s).trim());
+  if (!m) return null;
+  let time = m[2] || "00:00";
+  if (time.length === 5) time += ":00";
+  const d = new Date(`${m[1]}T${time}+02:00`);
+  return Number.isNaN(d.getTime()) ? null : Math.floor(d.getTime() / 1000);
+}
+
+// unix seconds -> "YYYY-MM-DD HH:MM" in SAST (full=false drops the year/date prefix into MM-DD)
+function fmtSast(unix, full = true) {
+  const d = new Date(unix * 1000);
+  const p = new Intl.DateTimeFormat("en-ZA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(d).reduce((a, x) => ((a[x.type] = x.value), a), {});
+  return full
+    ? `${p.year}-${p.month}-${p.day} ${p.hour}:${p.minute}`
+    : `${p.month}-${p.day} ${p.hour}:${p.minute}`;
+}
+
+// Pull a human-readable body out of Evolution's `message` jsonb.
+function extractText(m) {
+  if (!m || typeof m !== "object") return null;
+  if (m.conversation) return m.conversation;
+  if (m.extendedTextMessage?.text) return m.extendedTextMessage.text;
+  if (m.imageMessage) return m.imageMessage.caption ? `[image] ${m.imageMessage.caption}` : "[image]";
+  if (m.videoMessage) return m.videoMessage.caption ? `[video] ${m.videoMessage.caption}` : "[video]";
+  if (m.audioMessage) return m.audioMessage.ptt ? "[voice note]" : "[audio]";
+  if (m.documentMessage) return `[document] ${m.documentMessage.fileName || ""}`.trim();
+  if (m.documentWithCaptionMessage?.message?.documentMessage)
+    return `[document] ${m.documentWithCaptionMessage.message.documentMessage.fileName || ""}`.trim();
+  if (m.stickerMessage) return "[sticker]";
+  if (m.locationMessage) return "[location]";
+  if (m.contactMessage || m.contactsArrayMessage) return "[contact card]";
+  if (m.reactionMessage) return `[reaction ${m.reactionMessage.text || ""}]`.trim();
+  if (m.pollCreationMessage || m.pollCreationMessageV3)
+    return `[poll] ${(m.pollCreationMessage || m.pollCreationMessageV3).name || ""}`.trim();
+  if (m.protocolMessage) return null; // system/internal — skip
+  return null;
+}
+
+async function resolveInstanceId(client, instanceName) {
+  const r = await client.query('SELECT id, "profileName" FROM "Instance" WHERE name = $1', [instanceName]);
+  if (!r.rows.length) {
+    const all = await client.query('SELECT name FROM "Instance" ORDER BY name');
+    console.error(
+      `Error: no Evolution instance named "${instanceName}". Available: ${all.rows.map((x) => x.name).join(", ")}`
+    );
+    process.exit(1);
+  }
+  return r.rows[0];
+}
+
+// ---------- groups list ----------
+export async function list(opts = {}) {
+  const instanceName = opts.instance || DEFAULT_INSTANCE;
+  const client = await connect();
+  try {
+    const inst = await resolveInstanceId(client, instanceName);
+    const r = await client.query(
+      `SELECT ch.name,
+              ch."remoteJid" AS jid,
+              (SELECT count(DISTINCT m.key->>'id') FROM "Message" m
+                 WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = ch."remoteJid") AS msgs,
+              (SELECT max((m."messageTimestamp")::bigint) FROM "Message" m
+                 WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = ch."remoteJid") AS last_ts
+         FROM "Chat" ch
+        WHERE ch."instanceId" = $1 AND ch."remoteJid" LIKE '%@g.us'
+        ORDER BY last_ts DESC NULLS LAST`,
+      [inst.id]
+    );
+    console.log(`Instance "${instanceName}" (${inst.profileName ?? "?"}) — ${r.rows.length} group chats\n`);
+    const rows = r.rows.map((x) => ({
+      group: x.name || "(no name)",
+      msgs: Number(x.msgs || 0),
+      last: x.last_ts ? fmtSast(Number(x.last_ts)) : "—",
+      jid: x.jid,
+    }));
+    const wName = Math.min(48, Math.max(...rows.map((x) => x.group.length), 5));
+    for (const x of rows) {
+      console.log(
+        `  ${x.group.padEnd(wName)}  ${String(x.msgs).padStart(5)} msgs   last ${x.last.padEnd(16)}  ${x.jid}`
+      );
+    }
+  } finally {
+    await client.end();
+  }
+}
+
+// ---------- groups pull ----------
+export async function pull(nameOrJid, opts = {}) {
+  const instanceName = opts.instance || DEFAULT_INSTANCE;
+  const limit = Math.max(1, Math.min(Number(opts.limit) || DEFAULT_LIMIT, 5000));
+
+  // window
+  let untilUnix = Math.floor(Date.now() / 1000);
+  let sinceUnix;
+  if (opts.until) {
+    const u = sastToUnix(opts.until);
+    if (u == null) { console.error(`Error: --until "${opts.until}" is not a valid date (use YYYY-MM-DD or "YYYY-MM-DD HH:MM").`); process.exit(1); }
+    untilUnix = u;
+  }
+  if (opts.since) {
+    const s = sastToUnix(opts.since);
+    if (s == null) { console.error(`Error: --since "${opts.since}" is not a valid date (use YYYY-MM-DD or "YYYY-MM-DD HH:MM").`); process.exit(1); }
+    sinceUnix = s;
+  } else {
+    const lastMs = opts.last ? parseLast(opts.last) : DEFAULT_LAST_MS;
+    if (lastMs == null) { console.error(`Error: --last "${opts.last}" is not valid (use e.g. 48h, 7d, 2w, 90m).`); process.exit(1); }
+    sinceUnix = untilUnix - Math.floor(lastMs / 1000);
+  }
+  if (sinceUnix > untilUnix) { console.error("Error: --since is after --until."); process.exit(1); }
+
+  const client = await connect();
+  try {
+    const inst = await resolveInstanceId(client, instanceName);
+
+    // resolve the group: exact JID, else exact name (case-insensitive), else contains
+    const groups = await client.query(
+      `SELECT ch."remoteJid" AS jid, ch.name FROM "Chat" ch
+        WHERE ch."instanceId" = $1 AND ch."remoteJid" LIKE '%@g.us'`,
+      [inst.id]
+    );
+    let match;
+    const arg = String(nameOrJid).trim();
+    if (/@g\.us$/.test(arg)) {
+      match = groups.rows.find((g) => g.jid === arg);
+    } else {
+      const lc = arg.toLowerCase();
+      const exact = groups.rows.filter((g) => (g.name || "").toLowerCase() === lc);
+      const contains = groups.rows.filter((g) => (g.name || "").toLowerCase().includes(lc));
+      const hits = exact.length ? exact : contains;
+      if (hits.length > 1) {
+        console.error(`"${arg}" matches ${hits.length} groups — be more specific or pass the JID:`);
+        for (const g of hits) console.error(`  ${g.name}  ${g.jid}`);
+        process.exit(1);
+      }
+      match = hits[0];
+    }
+    if (!match) {
+      console.error(`Error: no group matching "${arg}" on instance "${instanceName}". Try \`flowiq groups list --instance ${instanceName}\`.`);
+      process.exit(1);
+    }
+
+    // pull deduped messages in window
+    const r = await client.query(
+      `SELECT DISTINCT ON (m.key->>'id')
+              m.key->>'id'      AS mid,
+              m."pushName"      AS push_name,
+              m."participant"   AS participant,
+              m."messageType"   AS message_type,
+              m.message         AS message,
+              (m."messageTimestamp")::bigint AS ts,
+              m.key->>'fromMe'  AS from_me
+         FROM "Message" m
+        WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = $2
+          AND (m."messageTimestamp")::bigint >= $3
+          AND (m."messageTimestamp")::bigint <= $4
+        ORDER BY m.key->>'id', m."messageTimestamp" DESC`,
+      [inst.id, match.jid, sinceUnix, untilUnix]
+    );
+
+    let rows = r.rows
+      .map((x) => {
+        const fromMe = x.from_me === "true" || x.from_me === true;
+        return {
+          ts: Number(x.ts),
+          ts_sast: fmtSast(Number(x.ts)),
+          sender: fromMe ? (inst.profileName || "Flowapt") : (x.push_name || "(unknown)"),
+          from_me: fromMe,
+          participant: x.participant || null,
+          type: x.message_type,
+          text: extractText(x.message),
+        };
+      })
+      .sort((a, b) => a.ts - b.ts);
+
+    const totalInWindow = rows.length;
+    let truncated = 0;
+    if (rows.length > limit) {
+      truncated = rows.length - limit;
+      rows = rows.slice(rows.length - limit); // keep the most recent `limit`
+    }
+
+    // participants
+    const participants = {};
+    for (const m of rows) if (!m.from_me) participants[m.sender] = (participants[m.sender] || 0) + 1;
+
+    const payload = {
+      instance: instanceName,
+      group_name: match.name,
+      group_jid: match.jid,
+      window: { since_sast: fmtSast(sinceUnix), until_sast: fmtSast(untilUnix) },
+      pulled_at_sast: fmtSast(Math.floor(Date.now() / 1000)),
+      message_count: rows.length,
+      messages_in_window: totalInWindow,
+      truncated_older: truncated,
+      participant_counts: participants,
+      messages: rows.map(({ ts, ts_sast, sender, from_me, type, text }) => ({ ts_sast, sender, from_me, type, text })),
+    };
+
+    await fs.mkdir(OUT_DIR, { recursive: true });
+    const slug = `${slugify(instanceName, "inst")}-${slugify(match.name, match.jid.split("@")[0])}`;
+    const filePath = path.join(OUT_DIR, `${slug}.json`);
+    const overwriting = await fileExists(filePath);
+    await fs.writeFile(filePath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+
+    if (opts.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+    console.log(`  group:        ${match.name}  (${match.jid})`);
+    console.log(`  instance:     ${instanceName} (${inst.profileName ?? "?"})`);
+    console.log(`  window:       ${payload.window.since_sast} → ${payload.window.until_sast} SAST`);
+    console.log(`  messages:     ${rows.length}${truncated ? ` (of ${totalInWindow} in window — ${truncated} older dropped by --limit ${limit})` : ""}`);
+    console.log(`  participants: ${Object.keys(participants).length}`);
+
+    if (!rows.length) {
+      console.log("\n  (no messages in this window)");
+      return;
+    }
+
+    if (rows.length > 400) {
+      console.log(`\n  Timeline has ${rows.length} messages — full text is in the JSON file above.`);
+      return;
+    }
+    console.log("");
+    for (const m of rows) {
+      const t = fmtSast(m.ts, false);
+      console.log(`  [${t}] ${m.sender}: ${m.text ?? `(${m.type} — no readable text)`}`);
+    }
+  } finally {
+    await client.end();
+  }
+}

package/src/commands/org.js

@@ -0,0 +1,33 @@
+// `flowiq org info <organization_id>` — read-only org summary (platform detect
+// + active agent) for the prompt-builder skill's Step 0. Raw store/Meta creds
+// are stripped server-side; this only prints derived booleans + public urls.
+
+import { http } from "../http.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;
+
+export async function info(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("org", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  console.log(`${resp.name} (${resp.id})`);
+  console.log(`  platform:      ${resp.platform || "(neither shopify nor woo)"}${resp.ip_whitelist ? " [ip_whitelist]" : ""}`);
+  if (resp.shopify_domain) console.log(`  shopify:       ${resp.shopify_domain}`);
+  if (resp.woo_store_url) console.log(`  woo store:     ${resp.woo_store_url}`);
+  console.log(`  provider:      ${resp.provider || "(unset → meta)"}`);
+  console.log(`  active agent:  ${resp.active_whatsapp_agent || "(NONE — set one before building a prompt)"}`);
+}

package/src/commands/pinboard.js

@@ -0,0 +1,174 @@
+// `flowiq pinboard pull <task_id>` / `push <slug>` / `list` / `list-remote [status]`.
+// Round-trips a single Pin Board task (flowapt_tasks row) via /cli/pinboard.
+// No DB credentials on disk — all work happens server-side.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const PIN_DIR = path.resolve(process.cwd(), ".flowiq", "pinboard");
+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 VALID_STATUS = ["open", "in_progress", "done"];
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return (s || fallback).slice(0, 60);
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function resolvePushPath(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) {
+    candidates.push(identifier);
+  } else if (identifier.includes("/") || identifier.includes("\\")) {
+    candidates.push(path.resolve(identifier));
+  } else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(PIN_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) {
+    if (await fileExists(c)) return c;
+  }
+  throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+export async function pull(taskId) {
+  if (!UUID_RE.test(taskId)) {
+    console.error(`Error: "${taskId}" is not a valid task UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("pinboard", { task_id: taskId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(PIN_DIR, { recursive: true });
+  const slug = slugify(resp.name, resp.id);
+  const filePath = path.join(PIN_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const orgs = resp.organizations_resolved || [];
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  name:      ${resp.name}`);
+  console.log(`  status:    ${resp.status} / ${resp.urgency}`);
+  console.log(`  due:       ${resp.preferred_due_date || "(none)"}`);
+  console.log(`  orgs:      ${(resp.organizations || []).length}${orgs.length ? " (" + orgs.map((o) => o.name || o.id.slice(0, 8)).join(", ") + ")" : ""}`);
+  console.log(`  media:     ${(resp.media || []).length}`);
+  console.log(`  messages:  ${(resp.messages || []).length}`);
+  console.log(`  created:   ${resp.created_by} @ ${resp.created_at}`);
+}
+
+export async function push(identifier) {
+  let filePath;
+  try {
+    filePath = await resolvePushPath(identifier);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const raw = await fs.readFile(filePath, "utf8");
+  let data;
+  try { data = JSON.parse(raw); }
+  catch (e) {
+    console.error(`Invalid JSON in ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+  if (!data.id || !UUID_RE.test(data.id)) {
+    console.error(`${filePath}: id missing or invalid`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("pinboard", {
+      id: data.id,
+      name: data.name,
+      description: data.description ?? null,
+      status: data.status,
+      urgency: data.urgency,
+      preferred_due_date: data.preferred_due_date ?? null,
+      organizations: data.organizations ?? [],
+      media: data.media ?? [],
+      messages: data.messages ?? [],
+      created_by: data.created_by,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Pushed ${filePath}`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  name:      ${resp.name}`);
+  console.log(`  status:    ${resp.status} / ${resp.urgency}`);
+  console.log(`  due:       ${resp.preferred_due_date || "(none)"}`);
+  console.log(`  orgs:      ${resp.orgs}`);
+  console.log(`  media:     ${resp.media}`);
+  console.log(`  messages:  ${resp.messages}`);
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(PIN_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local task files; run `pinboard pull <task_id>`, or `pinboard list-remote` to see ids)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local task files; run `pinboard pull <task_id>`, or `pinboard list-remote` to see ids)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(PIN_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  id:       ${d.id || "?"}`);
+      console.log(`  name:     ${d.name || "(unknown)"}`);
+      console.log(`  status:   ${d.status || "?"} / ${d.urgency || "?"}`);
+      console.log(`  msgs:     ${Array.isArray(d.messages) ? d.messages.length : "?"}`);
+      console.log(`  pulled:   ${d.pulled_at || "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}
+
+export async function listRemote(statusFilter) {
+  if (statusFilter && !VALID_STATUS.includes(statusFilter)) {
+    console.error(`Invalid status filter "${statusFilter}". Use one of ${VALID_STATUS.join(" | ")}.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("pinboard", { list: "1", status: statusFilter });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+  const tasks = resp.tasks || [];
+  if (!tasks.length) {
+    console.log(statusFilter ? `(no tasks with status=${statusFilter})` : "(no tasks in flowapt_tasks)");
+    return;
+  }
+  console.log(`Found ${tasks.length} task${tasks.length === 1 ? "" : "s"}${statusFilter ? ` (status=${statusFilter})` : ""}:\n`);
+  for (const t of tasks) {
+    const updated = t.updated_at ? new Date(t.updated_at).toISOString().replace("T", " ").slice(0, 16) : "?";
+    console.log(`  ${t.id}  [${String(t.status).padEnd(11)}] [${String(t.urgency).padEnd(8)}]  ${updated}  ${t.created_by} — ${t.name}`);
+  }
+}

package/src/commands/templates.js

@@ -0,0 +1,156 @@
+// `flowiq templates pull <org_id>` / `list` — read WhatsApp templates from Meta.
+// `flowiq templates create <org> --request-file f.json` / `status` — §12 (create).
+// Pull is read-only via /cli/templates; create proxies /cli/meta-templates.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const TPL_DIR = path.resolve(process.cwd(), ".flowiq", "templates");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+export async function pull(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("templates", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(TPL_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(TPL_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  waba:      ${resp.waba_id}`);
+  if (resp.meta_phone_number) console.log(`  phone:     ${resp.meta_phone_number}`);
+  console.log(`  templates: ${resp.template_count}`);
+  console.log(`  status:    ${JSON.stringify(resp.summary?.byStatus || {})}`);
+  console.log(`  category:  ${JSON.stringify(resp.summary?.byCategory || {})}`);
+  console.log(`  language:  ${JSON.stringify(resp.summary?.byLanguage || {})}`);
+}
+
+export async function create(orgId, opts = {}) {
+  if (!opts.requestFile) {
+    console.error("Error: --request-file <path> is required (JSON with template_request, optional template_data/media_header/cards_media).");
+    process.exit(1);
+  }
+  let filePath = opts.requestFile;
+  if (!path.isAbsolute(filePath)) filePath = path.resolve(filePath);
+  let data;
+  try {
+    data = JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (e) {
+    console.error(`Cannot read request file ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+
+  // The file may be the full edge-fn body, or just the inner template_request.
+  const organizationId = orgId || data.organization_id;
+  if (!organizationId || !UUID_RE.test(organizationId)) {
+    console.error("Error: organization_id missing/invalid (pass <org_id> or include it in the request file).");
+    process.exit(1);
+  }
+  const templateRequest = data.template_request || (data.name ? data : null);
+  if (!templateRequest) {
+    console.error("Error: request file must contain a `template_request` object (or be one, with a `name`).");
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("meta-templates", {
+      organization_id: organizationId,
+      template_request: templateRequest,
+      template_data: data.template_data,
+      media_header: data.media_header,
+      cards_media: data.cards_media,
+    });
+  } catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    if (e.body) console.error(JSON.stringify(e.body, null, 2));
+    process.exit(1);
+  }
+
+  console.log(`Submitted template "${templateRequest.name}" for org ${organizationId}`);
+  console.log(JSON.stringify(resp, null, 2));
+}
+
+export async function status(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("meta-templates", { organization_id: orgId, name: opts.name });
+  } catch (e) {
+    console.error(`Status lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  const rows = resp.templates || [];
+  if (!rows.length) {
+    console.log(opts.name ? `(no templates matching "${opts.name}")` : "(no templates on record for this org)");
+    return;
+  }
+  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""}:`);
+  for (const t of rows) {
+    const name = t.template_name || t.name || "(unnamed)";
+    const st = 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>`.");
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(TPL_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local template files; run `templates pull <org_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local template files; run `templates pull <org_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(TPL_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  org:       ${d.organization_name ?? "(unknown)"} (${d.organization_id ?? "?"})`);
+      console.log(`  waba:      ${d.waba_id ?? "?"}`);
+      console.log(`  phone:     ${d.meta_phone_number ?? "(none)"}`);
+      console.log(`  templates: ${d.template_count ?? (Array.isArray(d.templates) ? d.templates.length : "?")}`);
+      if (d.summary?.byStatus) console.log(`  status:    ${JSON.stringify(d.summary.byStatus)}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}