@flowapt/flowiq-cli 0.1.9 → 0.1.10

package/README.md

@@ -99,6 +99,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.10",
   "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/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
@@ -290,5 +291,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);
 }