@flowapt/flowiq-cli 0.1.9 → 0.1.11

package/README.md

@@ -16,12 +16,24 @@ flowiq --version   # should print 0.1.x
 
 ## Authenticate
 
-Get a personal staff API key from a FlowIQ super-admin (an `fiq_staff_…`
-string). Then:
+Default flow — browser login (like `npm login`):
 
 ```bash
 flowiq auth login
-# paste your key when prompted
+```
+
+The CLI shows a short code (e.g. `FQ4X-9KTB`), opens
+`https://app.flowiq.live/cli-auth` when you press ENTER, and waits. A
+logged-in FlowIQ **super admin** confirms the code on the page matches the
+one in your terminal and clicks Approve — the CLI then receives a
+freshly-minted personal key automatically. **Never approve a code you
+didn't just see in your own terminal.**
+
+Fallbacks (CI / no browser):
+
+```bash
+flowiq auth login --token fiq_staff_…   # supply a key directly
+flowiq auth login --paste               # prompt for a key on stdin
 ```
 
 Your key is saved to `~/.config/flowiq/auth.json` with `chmod 600`. To
@@ -31,8 +43,16 @@ verify what you're authenticated as:
 flowiq auth whoami
 ```
 
+To rotate this device's token (mints a fresh key, revokes the old one
+server-side — run whenever you want a new secret):
+
+```bash
+flowiq auth refresh
+```
+
 To log out (deletes the local key file, does NOT revoke the key
-server-side — ask your admin to revoke):
+server-side — use `flowiq auth refresh` first if you want the old key
+dead, or ask another super admin to revoke):
 
 ```bash
 flowiq auth logout
@@ -99,6 +119,24 @@ Shipping / Returns / Promotions / Technical Support / Tone Adjustment / Other),
 `suggested_tone` (Friendly / Professional / Encouraging / Brief / Detailed),
 `status` (Pending / Resolved), `messages: []`, `media: []`.
 
+### Knowledge / text sources — `flowiq knowledge pull|push|list` (alias `kn`)
+
+Round-trips an agent's **text knowledge sources** — the `{ code, text }` entries
+in `agents.additional_config` that the agent's `get_more_answers` tool retrieves
+on demand (brand references + tethered playbooks; the "Knowledge Sources → Text"
+tab in the UI).
+
+```bash
+flowiq knowledge pull <org_id>                 # → ./.flowiq/knowledge/<slug>.json (sources[] = {code,text})
+flowiq knowledge pull <org_id> --agent <id>    # a specific (non-active) agent
+flowiq knowledge push <slug>                    # FULL-REPLACE sources[] back onto the agent
+flowiq knowledge list
+```
+
+- Codes are `UPPER_SNAKE` (`^[A-Z0-9][A-Z0-9_]{2,63}$`), validated server-side. Edit / add / remove entries in `sources[]`, then push (full-replace of the array).
+- **Object-shape guard:** some agents use `additional_config` for Flowapt-managed config (`external_woo_build`, …) rather than text sources — a pull flags that, and a push is **refused** (never clobbers managed config).
+- `--agent` + filenames behave like `prompts` (a non-active agent saves to `<org-slug>-<agent-slug>.json`). The file carries `agent_id`, so `push` targets the agent it was pulled from.
+
 ### Messages — `flowiq messages pull <contact_id>` (alias `m`)
 
 Read-only pull of a contact's `helpdesk_messages` history. Anchors on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/auth.js

@@ -1,8 +1,23 @@
-// `flowiq auth login` / `flowiq auth logout` / `flowiq auth whoami`.
-// Stores a `fiq_staff_…` bearer token at ~/.config/flowiq/auth.json.
+// `flowiq auth login` / `logout` / `whoami` / `refresh`.
+//
+// Default login = browser device flow (like `npm login` / `gh auth login`):
+//   1. POST /cli/login-start (unauthenticated) → device_code + user_code
+//   2. Show the user code, press ENTER → open https://app.flowiq.live/cli-auth
+//   3. A logged-in SUPER ADMIN confirms the codes match and approves
+//   4. Poll /cli/login-poll until the key is minted server-side (mint-at-claim)
+//
+// Fallbacks: `--token <key>` (direct) or `--paste` (interactive paste) keep
+// the original flow for CI or when no browser is handy.
+//
+// `flowiq auth refresh` rotates the saved key in place via /cli/token-rotate —
+// run it on each device whenever you want a fresh secret; the old key is
+// revoked server-side. If the saved key is already dead it falls back to the
+// full browser login.
 
 import readline from "node:readline";
-import { loadConfig, saveConfig, clearConfig, configFilePath } from "../config.js";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { loadConfig, saveConfig, clearConfig } from "../config.js";
 import { http } from "../http.js";
 
 function prompt(question, { silent = false } = {}) {
@@ -41,25 +56,42 @@ function prompt(question, { silent = false } = {}) {
   });
 }
 
-export async function login(opts = {}) {
-  const cfg = await loadConfig();
-  if (opts.apiUrl) cfg.api_url = opts.apiUrl;
-
-  let token = opts.token;
-  if (!token) {
-    process.stdout.write(`API URL: ${cfg.api_url}\n`);
-    token = await prompt("Paste your staff API key (fiq_staff_…): ", { silent: true });
-    token = token.trim();
+// Unauthenticated POST — login-start / login-poll run BEFORE a token exists,
+// so they can't go through http.js (which requires the saved token).
+async function unauthedPost(apiUrl, endpoint, body) {
+  const url = `${apiUrl.replace(/\/$/, "")}/cli/${endpoint}`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify(body ?? {}),
+  });
+  const text = await resp.text();
+  let parsed;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; }
+  if (!resp.ok) {
+    throw new Error(parsed.message || parsed.error || `${endpoint} → HTTP ${resp.status}`);
   }
+  return parsed;
+}
 
-  if (!token.startsWith("fiq_staff_")) {
-    console.error(`Error: token must start with "fiq_staff_" (got ${token.slice(0, 12)}…).`);
-    process.exit(1);
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd, args;
+  if (platform === "darwin") { cmd = "open"; args = [url]; }
+  else if (platform === "win32") { cmd = "cmd"; args = ["/c", "start", "", url]; }
+  else { cmd = "xdg-open"; args = [url]; }
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
   }
+}
 
-  // Save first so http.js can use it, then verify with /cli/whoami.
-  const file = await saveConfig({ api_url: cfg.api_url, token });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+async function saveAndVerify(apiUrl, token) {
+  const file = await saveConfig({ api_url: apiUrl, token });
   try {
     const me = await http.get("whoami");
     console.log(`Logged in as ${me.user_email || me.user_id} (super_admin=${me.is_super_admin})`);
@@ -73,6 +105,109 @@ export async function login(opts = {}) {
   }
 }
 
+async function browserLogin(cfg) {
+  const deviceName = `${os.hostname()} (${os.platform()})`;
+  let start;
+  try {
+    start = await unauthedPost(cfg.api_url, "login-start", { device_name: deviceName });
+  } catch (e) {
+    console.error(`Could not start browser login: ${e.message}`);
+    console.error("Fallback: flowiq auth login --paste");
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log("First, confirm this code matches the one shown in your browser:");
+  console.log("");
+  console.log(`    ${start.user_code}`);
+  console.log("");
+  console.log(`Approval page: ${start.verification_url}`);
+  await prompt("Press ENTER to open in the browser... ");
+  if (!openBrowser(start.verification_url)) {
+    console.log("(Could not open a browser — visit the URL above manually.)");
+  }
+
+  const intervalMs = Math.max(2, start.interval || 5) * 1000;
+  const deadline = Date.now() + (start.expires_in || 600) * 1000;
+  process.stdout.write("Waiting for a super admin to approve");
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let poll;
+    try {
+      poll = await unauthedPost(cfg.api_url, "login-poll", { device_code: start.device_code });
+    } catch (e) {
+      console.error(`\nPolling failed: ${e.message}`);
+      process.exit(1);
+    }
+
+    if (poll.status === "pending") { process.stdout.write("."); continue; }
+    if (poll.status === "slow_down") { await sleep(intervalMs); continue; }
+    process.stdout.write("\n");
+
+    if (poll.status === "approved") {
+      console.log(`Approved${poll.user_email ? ` by ${poll.user_email}` : ""}.`);
+      await saveAndVerify(cfg.api_url, poll.token);
+      return;
+    }
+    if (poll.status === "denied") { console.error("Login was DENIED in the browser."); process.exit(1); }
+    if (poll.status === "expired") { console.error("Login request expired. Re-run `flowiq auth login`."); process.exit(1); }
+    if (poll.status === "claimed") { console.error("This login was already claimed. Re-run `flowiq auth login`."); process.exit(1); }
+    console.error(`Unexpected status: ${poll.status}`); process.exit(1);
+  }
+
+  console.error("\nTimed out waiting for approval. Re-run `flowiq auth login`.");
+  process.exit(1);
+}
+
+export async function login(opts = {}) {
+  const cfg = await loadConfig();
+  if (opts.apiUrl) cfg.api_url = opts.apiUrl;
+
+  // Fallback paths: --token (direct) or --paste (interactive paste).
+  let token = opts.token;
+  if (!token && opts.paste) {
+    process.stdout.write(`API URL: ${cfg.api_url}\n`);
+    token = (await prompt("Paste your staff API key (fiq_staff_…): ", { silent: true })).trim();
+  }
+
+  if (token) {
+    if (!token.startsWith("fiq_staff_")) {
+      console.error(`Error: token must start with "fiq_staff_" (got ${token.slice(0, 12)}…).`);
+      process.exit(1);
+    }
+    await saveAndVerify(cfg.api_url, token);
+    return;
+  }
+
+  // Default: browser device flow.
+  await browserLogin(cfg);
+}
+
+export async function refresh() {
+  const cfg = await loadConfig();
+  if (!cfg.token) {
+    console.log("No saved token — starting browser login instead.");
+    await browserLogin(cfg);
+    return;
+  }
+
+  try {
+    const rotated = await http.post("token-rotate", {});
+    await saveConfig({ api_url: cfg.api_url, token: rotated.token });
+    console.log(`Token rotated (${rotated.rotated_from} → ${rotated.key_prefix}).`);
+    console.log(rotated.old_key_revoked ? "Old key revoked." : "WARNING: old key could not be revoked — revoke it manually.");
+  } catch (e) {
+    if (e.status === 401) {
+      console.log("Saved token is no longer valid — starting browser login…");
+      await browserLogin(cfg);
+      return;
+    }
+    console.error(`Refresh failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 export async function logout() {
   const removed = await clearConfig();
   console.log(removed ? "Logged out." : "Already logged out.");

package/src/commands/knowledge.js

@@ -0,0 +1,156 @@
+// `flowiq knowledge pull <org_id> [--agent <id>]` / `push <slug>` / `list`.
+// Round-trips an agent's TEXT knowledge sources — the `{ code, text }` entries
+// in `agents.additional_config` that the get_more_answers tool serves (brand
+// references + tethered playbooks). Via /cli/knowledge; no DB creds on disk.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const KN_DIR = path.resolve(process.cwd(), ".flowiq", "knowledge");
+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; }
+}
+
+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(KN_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(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("knowledge", { organization_id: orgId, agent_id: opts.agent });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(KN_DIR, { recursive: true });
+  // Non-active agents get an agent-suffixed filename (same as prompts) so
+  // pulling multiple agents from one org doesn't clobber each other.
+  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(KN_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(`  agent:     ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  sources:   ${resp.source_count}`);
+  console.log(`  content:   ${(resp.total_chars || 0).toLocaleString()} chars`);
+  for (const s of resp.sources || []) {
+    console.log(`    ${s.code.padEnd(28)} ${(s.text?.length || 0).toLocaleString()} chars`);
+  }
+  if (resp.shape === "object") {
+    console.log("");
+    console.log("  ⚠ this agent's additional_config is object-shaped (Flowapt-managed config,");
+    console.log("    e.g. external_woo_build) — it holds NO text sources and CANNOT be pushed to.");
+  } else if (resp.shape === "empty") {
+    console.log("");
+    console.log("  note: no text sources yet — add {code, text} entries to the JSON and push to create them.");
+  }
+}
+
+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.organization_id || !UUID_RE.test(data.organization_id)) {
+    console.error(`${filePath}: organization_id missing or invalid`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.sources)) {
+    console.error(`${filePath}: sources must be an array of { code, text }`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("knowledge", {
+      organization_id: data.organization_id,
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
+      sources: data.sources.map((s) => ({ code: s.code, text: s.text })),
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Pushed ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  agent:     ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  sources:   ${resp.source_count}`);
+  console.log(`  content:   ${(resp.total_chars || 0).toLocaleString()} chars`);
+  console.log(`  codes:     ${(resp.codes || []).join(", ")}`);
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(KN_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local knowledge files; run `knowledge pull <org_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local knowledge files; run `knowledge pull <org_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(KN_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(`  agent:     ${d.agent_name ?? "?"} (${d.agent_id ?? "?"})`);
+      console.log(`  sources:   ${d.source_count ?? (Array.isArray(d.sources) ? d.sources.length : "?")}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/index.js

@@ -22,6 +22,7 @@ import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
+import * as knowledgeCmd from "./commands/knowledge.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
@@ -39,10 +40,14 @@ export function run(argv) {
   // auth
   const auth = program.command("auth").description("Manage CLI authentication");
   auth.command("login")
-    .description("Save a staff API key (fiq_staff_…)")
-    .option("--token <token>", "supply the token via flag instead of stdin")
+    .description("Log in via the browser (super-admin approval); --token/--paste for the old key-paste flow")
+    .option("--token <token>", "supply a staff API key directly instead of the browser flow")
+    .option("--paste", "prompt for a staff API key on stdin instead of the browser flow")
     .option("--api-url <url>", "override the API host (default https://api.flowiq.live)")
     .action((opts) => authCmd.login(opts));
+  auth.command("refresh")
+    .description("Rotate this device's token in place (old key is revoked server-side)")
+    .action(() => authCmd.refresh());
   auth.command("logout").description("Remove the saved token").action(() => authCmd.logout());
   auth.command("whoami").description("Show the user behind the saved token").action(() => authCmd.whoami());
 
@@ -290,5 +295,20 @@ export function run(argv) {
     .option("--out <path>", "output file (default .flowiq/agent-test/judge_input.json)")
     .action((orgId, opts) => testCmd.extract(orgId, opts));
 
+  // knowledge (agent text knowledge sources: additional_config {code,text} → get_more_answers)
+  const knowledge = program.command("knowledge")
+    .alias("kn")
+    .description("Round-trip an agent's TEXT knowledge sources (additional_config {code,text} — the get_more_answers playbooks/references)");
+  knowledge.command("pull <organization_id>")
+    .description("Fetch the agent's {code,text} text sources into a local JSON file (default: active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => knowledgeCmd.pull(orgId, opts));
+  knowledge.command("push <slug-or-path>")
+    .description("FULL-REPLACE the agent's text sources with the local JSON's sources[] (refused if additional_config is object-shaped/managed)")
+    .action((id) => knowledgeCmd.push(id));
+  knowledge.command("list")
+    .description("List local knowledge snapshots")
+    .action(() => knowledgeCmd.list());
+
   program.parseAsync(argv);
 }