nubot-lite 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Nubot
+
+This license covers this repository except the compiled panel in apps/panel,
+which has its own license (LICENSE-PANEL.md).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-PANEL.md

@@ -0,0 +1,39 @@
+# Licencia del panel de Nubot Lite
+
+Copyright © 2026 Nubot (https://nubot.io). Todos los derechos reservados.
+
+Esta licencia cubre el panel compilado: la carpeta `apps/panel` de este repositorio y su copia `panel/` en cada
+instalación. No cubre el resto del repositorio, que se distribuye bajo la licencia MIT (ver `LICENSE`).
+
+El panel no es software libre ni de código abierto, y su código fuente no se publica.
+
+## Puedes, sin costo
+
+- Usar el panel tal como se distribuye, junto con el servidor de Nubot Lite, para atender a tu empresa.
+- Copiarlo dentro de tu instalación de Nubot Lite y actualizarlo con `npx nubot-lite update`.
+- Instalar Nubot Lite con su panel para otra empresa, siempre que esa empresa lo use para sí misma bajo estas
+  mismas condiciones.
+
+## No puedes
+
+- Modificar, descompilar, desofuscar o hacer obras derivadas del panel, salvo lo que la ley permita expresamente.
+- Usarlo con un servidor, backend o producto distinto de Nubot Lite.
+- Redistribuirlo, venderlo, sublicenciarlo u ofrecerlo como servicio, por separado o dentro de otro producto,
+  fuera de lo que permite la sección anterior.
+- Quitar o cambiar las marcas, los logos o los avisos de Nubot que contiene.
+
+## Marcas
+
+«Nubot» y su logo son marcas de Nubot. Esta licencia no da derecho a usarlas fuera del panel.
+
+## Sin garantía
+
+El panel se entrega «tal cual», sin garantías de ningún tipo. En la medida en que la ley lo permita, Nubot no
+responde por daños derivados de su uso.
+
+## Fin de la licencia
+
+Esta licencia termina sola si incumples cualquiera de sus condiciones. En ese caso tienes que dejar de usar el
+panel y borrar sus copias.
+
+Para otros usos (varias empresas, agencias, reventa o integraciones), escribe a Nubot: https://nubot.io

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# nubot-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Instala **Nubot Lite** en tu cuenta de Cloudflare: una bandeja de WhatsApp con agente de IA (Claude) y embudo
+de ventas, para una sola empresa. Corre en la capa gratuita de Cloudflare, sin tarjeta. WhatsApp entra y sale
+por [Zernio](https://zernio.com).
+
+```
+npx nubot-lite init
+```
+
+Necesitas Node.js 20 o más nuevo. Las cuentas de Cloudflare, Anthropic y Zernio se crean en el paso en que
+hacen falta.
+
+## Paso a paso
+
+| Paso | Comando |
+|---|---|
+| 1. Levantar el CRM en Cloudflare (gratis, sin tarjeta) | `npx nubot-lite init` |
+| 2. Conectar el agente de IA (llave de Anthropic) | `npx nubot-lite claude` |
+| 3. Conectar WhatsApp (Zernio) | `npx nubot-lite whatsapp` |
+| 4. Enseñarle el negocio al agente | `npx nubot-lite apply <carpeta>` |
+
+Los pasos 2 a 4 se corren dentro de la carpeta que crea `init`. Con Claude Code puedes pedirlo con tus palabras:
+«Instala Nubot Lite para mi empresa», «Conecta mi agente», «Conecta mi WhatsApp», «Arma el agente de mi empresa».
+
+| Comando | Qué hace |
+|---|---|
+| `npx nubot-lite doctor` | Revisa que todo funcione y dice qué falta |
+| `npx nubot-lite update` | Trae la versión nueva sin pisar los archivos que cambiaste |
+| `npx nubot-lite test "hola" "¿precio?"` | Conversación de prueba con el agente real, sin WhatsApp |
+
+La guía completa está en [GitHub](https://github.com/aichain-research/nubot-lite/blob/main/docs/GUIA.md).
+
+## Licencia
+
+La CLI y el servidor son [MIT](https://github.com/aichain-research/nubot-lite/blob/main/LICENSE). El panel
+compilado que se instala con ellos tiene su propia licencia
+([LICENSE-PANEL.md](https://github.com/aichain-research/nubot-lite/blob/main/LICENSE-PANEL.md)): se usa sin costo
+con Nubot Lite, pero no es código abierto.
+
+¿Necesitas varios agentes, Instagram, Messenger, campañas o workflows? Eso es [Nubot](https://nubot.io).

package/bin/nubot-lite.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { parseArgs } from "../lib/args.mjs";
+import { CliError, red } from "../lib/ui.mjs";
+import { init } from "../lib/commands/init.mjs";
+import { claude, doctor, update, whatsapp } from "../lib/commands/maintenance.mjs";
+import {
+  addKnowledge,
+  applyAgent,
+  applyFolder,
+  applyFunnel,
+  applyQuickReplies,
+  applyRequestTypes,
+  applyTags,
+  importCatalog,
+  testAgent,
+} from "../lib/commands/content.mjs";
+
+const HELP = `Nubot Lite: bandeja de WhatsApp con agente de IA en tu cuenta de Cloudflare.
+
+Paso a paso
+  npx nubot-lite init              1. Levanta tu CRM en Cloudflare y te da el link
+      --business "Casa Norte"  --dir ./carpeta  --timezone America/Lima  --yes
+  npx nubot-lite claude            2. Conecta el agente de IA (pide tu llave de Anthropic y la prueba)
+      --model claude-sonnet-5-5  --anthropic-key ...
+  npx nubot-lite whatsapp          3. Conecta tu número de WhatsApp por Zernio
+      --zernio-key ...
+
+Mantener
+  npx nubot-lite doctor            Revisa que todo funcione y dice qué falta
+  npx nubot-lite update            Trae la versión nueva sin pisar tus cambios (--force para pisarlos)
+
+Armar el agente (desde la carpeta de la instalación)
+  npx nubot-lite apply <carpeta>                Aplica una carpeta completa (agente, embudo, catálogo, conocimiento…)
+  npx nubot-lite agent <agente.json>
+  npx nubot-lite funnel <embudo.json>
+  npx nubot-lite tags <etiquetas.json>
+  npx nubot-lite requests <solicitudes.json>
+  npx nubot-lite quick-replies <respuestas.json>
+  npx nubot-lite catalog <catalogo.json> --media <carpeta de fotos>
+  npx nubot-lite knowledge <archivo.md|carpeta>...
+  npx nubot-lite test "mensaje 1" "mensaje 2"   Conversación de prueba con el agente real (--file, --json)
+`;
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { positional, flags } = parseArgs(rest);
+  const need = (n, usage) => {
+    if (positional.length < n) throw new CliError(`Uso: npx nubot-lite ${usage}`);
+  };
+  switch (command) {
+    case "init":
+      return init(flags);
+    case "doctor":
+      return doctor();
+    case "update":
+      return update(flags);
+    case "claude":
+      return claude(flags);
+    case "whatsapp":
+      return whatsapp(flags);
+    case "apply":
+      need(1, "apply <carpeta>");
+      return applyFolder(positional[0]);
+    case "agent":
+      need(1, "agent <agente.json>");
+      return applyAgent(positional[0]);
+    case "funnel":
+      need(1, "funnel <embudo.json>");
+      return applyFunnel(positional[0]);
+    case "tags":
+      need(1, "tags <etiquetas.json>");
+      return applyTags(positional[0]);
+    case "requests":
+      need(1, "requests <solicitudes.json>");
+      return applyRequestTypes(positional[0]);
+    case "quick-replies":
+      need(1, "quick-replies <respuestas.json>");
+      return applyQuickReplies(positional[0]);
+    case "catalog":
+      need(1, "catalog <catalogo.json> --media <carpeta>");
+      return importCatalog(positional[0], flags.media === true ? undefined : flags.media);
+    case "knowledge":
+      need(1, "knowledge <archivo.md|carpeta>...");
+      return addKnowledge(positional);
+    case "test":
+      return testAgent(positional, flags);
+    case undefined:
+    case "help":
+    case "--help":
+      console.log(HELP);
+      return;
+    default:
+      throw new CliError(`No conozco el comando "${command}". Mira la ayuda: npx nubot-lite help`);
+  }
+}
+
+main().catch((err) => {
+  console.error(`\n${red("✗")} ${err instanceof CliError ? err.message : err.stack ?? err}`);
+  process.exitCode = 1;
+});

package/lib/api.mjs

@@ -0,0 +1,69 @@
+import { CliError } from "./ui.mjs";
+
+/** Cliente de la API del Worker con la llave de admin de esta instalación. */
+export function apiClient({ url, adminToken }) {
+  async function call(method, path, body, { form = false } = {}) {
+    let res;
+    try {
+      res = await fetch(`${url}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${adminToken}`, ...(form || body === undefined ? {} : { "Content-Type": "application/json" }) },
+        body: form ? body : body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (err) {
+      throw new CliError(`No pude conectar con ${url}: ${err.message}`);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new CliError(data.error ?? `${method} ${path} respondió ${res.status}`);
+    return data;
+  }
+  return {
+    get: (path) => call("GET", path),
+    post: (path, body) => call("POST", path, body),
+    put: (path, body) => call("PUT", path, body),
+    patch: (path, body) => call("PATCH", path, body),
+    del: (path) => call("DELETE", path),
+    upload: (path, form) => call("POST", path, form, { form: true }),
+  };
+}
+
+export const ZERNIO_API = "https://zernio.com/api";
+
+export const WEBHOOK_EVENTS = ["message.received", "message.sent", "message.delivered", "message.read", "message.failed"];
+
+async function zernio(key, method, path, body) {
+  const res = await fetch(`${ZERNIO_API}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${key}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 401) throw new CliError("La API key de Zernio no es válida.");
+  if (!res.ok) throw new CliError(`Zernio respondió ${res.status}: ${data.error ?? data.message ?? ""}`);
+  return data;
+}
+
+export async function whatsappAccounts(key) {
+  const data = await zernio(key, "GET", "/v1/accounts?platform=whatsapp");
+  const accounts = (data.accounts ?? []).map((a) => ({ id: a._id ?? a.id ?? a.accountId, name: a.displayName ?? a.username ?? "WhatsApp", active: a.isActive !== false }));
+  // El número de prueba compartido de Zernio no está entre las cuentas: sale en sus números.
+  const { sandbox } = await zernio(key, "GET", "/v1/phone-numbers").catch(() => ({}));
+  if (sandbox?.accountId && !accounts.some((a) => a.id === sandbox.accountId)) {
+    accounts.push({ id: sandbox.accountId, name: `Sandbox de Zernio (${sandbox.phoneNumber}, solo para probar)`, active: true });
+  }
+  return accounts;
+}
+
+/** Registra (o actualiza) el webhook que lleva los mensajes de WhatsApp al Worker. */
+export async function ensureWebhook(key, { url, secret, accountId }) {
+  const target = `${url}/webhooks/zernio`;
+  const { webhooks = [] } = await zernio(key, "GET", "/v1/webhooks/settings");
+  const body = { name: "Nubot Lite", url: target, secret, events: WEBHOOK_EVENTS, isActive: true, accountIds: accountId ? [accountId] : [] };
+  const existing = webhooks.find((w) => w.url === target);
+  if (existing) {
+    await zernio(key, "PUT", "/v1/webhooks/settings", { _id: existing._id, ...body });
+    return "updated";
+  }
+  await zernio(key, "POST", "/v1/webhooks/settings", body);
+  return "created";
+}

package/lib/args.mjs

@@ -0,0 +1,30 @@
+/** `--clave valor`, `--clave=valor` y `--bandera`; lo demás son posicionales. */
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split(/=(.*)/s);
+    const name = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (inline !== undefined) flags[name] = inline;
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) flags[name] = argv[++i];
+    else flags[name] = true;
+  }
+  return { positional, flags };
+}
+
+export function slugify(text) {
+  return (
+    text
+      .toLowerCase()
+      .normalize("NFD")
+      .replace(/[̀-ͯ]/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 40) || "empresa"
+  );
+}

package/lib/cloudflare.mjs

@@ -0,0 +1,89 @@
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { wrangler } from "./sh.mjs";
+import { CliError, closePrompts, info } from "./ui.mjs";
+
+export function parseD1Id(output) {
+  return output.match(/"database_id":\s*"([0-9a-f-]{36})"/)?.[1] ?? null;
+}
+
+export function parseKvId(output) {
+  return output.match(/"?id"?\s*[:=]\s*"([0-9a-f]{32})"/)?.[1] ?? null;
+}
+
+export function parseWorkerUrl(output) {
+  return output.match(/https:\/\/[a-z0-9-]+\.[a-z0-9-]+\.workers\.dev/)?.[0] ?? null;
+}
+
+export async function ensureLogin(workerDir) {
+  const who = await wrangler(workerDir, ["whoami"], { capture: true });
+  if (who.code === 0 && !/not authenticated/i.test(who.out)) return;
+  info("Se abrirá el navegador para entrar a tu cuenta de Cloudflare (es gratis y no pide tarjeta).");
+  // El login usa la terminal directamente: suelto el teclado mientras tanto.
+  closePrompts();
+  const login = await wrangler(workerDir, ["login"], { interactive: true });
+  if (login.code !== 0) throw new CliError("No se pudo entrar a Cloudflare. Vuelve a intentar con: npx nubot-lite init");
+}
+
+export async function createD1(workerDir, name) {
+  const r = await wrangler(workerDir, ["d1", "create", name], { capture: true });
+  const id = parseD1Id(r.out);
+  if (id) return id;
+  if (/already exists/i.test(r.out)) {
+    const list = await wrangler(workerDir, ["d1", "list", "--json"], { capture: true });
+    const found = JSON.parse(list.out.slice(list.out.indexOf("["))).find((db) => db.name === name);
+    if (found) return found.uuid;
+  }
+  throw new CliError(`No se pudo crear la base de datos D1.\n${r.out}`);
+}
+
+export async function createKv(workerDir, title) {
+  const r = await wrangler(workerDir, ["kv", "namespace", "create", title], { capture: true });
+  const id = parseKvId(r.out);
+  if (id) return id;
+  if (/already exists/i.test(r.out)) {
+    const list = await wrangler(workerDir, ["kv", "namespace", "list"], { capture: true });
+    const found = JSON.parse(list.out.slice(list.out.indexOf("["))).find((ns) => ns.title === title || ns.title.endsWith(title));
+    if (found) return found.id;
+  }
+  throw new CliError(`No se pudo crear el espacio de archivos (KV).\n${r.out}`);
+}
+
+export async function migrate(workerDir) {
+  const r = await wrangler(workerDir, ["d1", "migrations", "apply", "DB", "--remote"], { capture: true, env: { CI: "1" } });
+  if (r.code !== 0) throw new CliError(`Fallaron las migraciones de la base de datos.\n${r.out}`);
+}
+
+export async function deploy(workerDir) {
+  let r = await wrangler(workerDir, ["deploy"], { capture: true });
+  if (r.code !== 0 && /workers\.dev subdomain/i.test(r.out)) {
+    // Cuenta nueva sin subdominio: Wrangler lo pide en la terminal y lo registra.
+    info("Tu cuenta todavía no tiene una dirección *.workers.dev. Cloudflare te va a pedir un nombre corto para crearla.");
+    closePrompts();
+    await wrangler(workerDir, ["deploy"], { interactive: true });
+    r = await wrangler(workerDir, ["deploy"], { capture: true });
+  }
+  if (r.code !== 0) {
+    if (/workers\.dev subdomain/i.test(r.out)) {
+      throw new CliError(
+        "Tu cuenta de Cloudflare no tiene una dirección *.workers.dev. Abre dash.cloudflare.com → Workers & Pages (con entrar se crea) y vuelve a correr el mismo comando.",
+      );
+    }
+    throw new CliError(`No se pudo publicar en Cloudflare. Esto respondió Cloudflare:\n${r.out.trim().split("\n").slice(-15).join("\n")}`);
+  }
+  const url = parseWorkerUrl(r.out);
+  if (!url) throw new CliError(`Se publicó, pero no encontré la dirección en la salida de Wrangler:\n${r.out}`);
+  return url;
+}
+
+/** Carga los secretos de una vez. El archivo temporal se borra aunque algo falle. */
+export async function putSecrets(workerDir, secrets) {
+  const file = join(workerDir, ".secrets.tmp.json");
+  writeFileSync(file, JSON.stringify(secrets));
+  try {
+    const r = await wrangler(workerDir, ["secret", "bulk", ".secrets.tmp.json"], { capture: true });
+    if (r.code !== 0) throw new CliError(`No se pudieron guardar los secretos.\n${r.out}`);
+  } finally {
+    rmSync(file, { force: true });
+  }
+}

package/lib/commands/content.mjs

@@ -0,0 +1,209 @@
+// Comandos para cargar el agente y su contenido. Los usa la skill de Claude Code:
+// Claude arma archivos en la carpeta de la empresa y los aplica con estos comandos.
+// Todos se pueden repetir: actualizan lo que ya existe en vez de duplicarlo.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { apiClient } from "../api.mjs";
+import { readState, requireProject } from "../project.mjs";
+import { bold, CliError, dim, info, ok, step, warn } from "../ui.mjs";
+
+const IMAGE_TYPES = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp", ".gif": "image/gif" };
+
+function api() {
+  const dir = requireProject();
+  const config = readState(dir, "config.json");
+  if (!config?.url) throw new CliError("La instalación quedó a medias. Termínala con: npx nubot-lite init --dir .");
+  return apiClient(config);
+}
+
+function readJson(file) {
+  const path = resolve(file);
+  if (!existsSync(path)) throw new CliError(`No existe el archivo ${path}`);
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new CliError(`${basename(path)} no es un JSON válido: ${err.message}`);
+  }
+}
+
+const norm = (s) => String(s ?? "").toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").trim();
+
+/** agente.json: { businessName, agentName, agentRole, instructions, timezone, model } */
+export async function applyAgent(file, client = api()) {
+  const data = readJson(file);
+  const { settings } = await client.put("/api/settings/agent", data);
+  ok(`Agente: ${settings.agentName} (${settings.model})`);
+}
+
+/** embudo.json: { name, stages: ["Nuevo", ...], default: true } o una lista de esos. */
+export async function applyFunnel(file, client = api()) {
+  const data = readJson(file);
+  for (const f of Array.isArray(data) ? data : [data]) {
+    if (!f.name || !Array.isArray(f.stages) || !f.stages.length) throw new CliError("Cada embudo necesita name y stages.");
+    const { funnels } = await client.get("/api/funnels");
+    let funnel = funnels.find((x) => norm(x.name) === norm(f.name));
+    if (!funnel) {
+      const { funnel: created } = await client.post("/api/funnels", { name: f.name, stages: f.stages });
+      ok(`Embudo ${f.name} creado con ${f.stages.length} etapas`);
+      funnel = { id: created.id, stages: [] };
+    } else {
+      const have = new Set(funnel.stages.map((s) => norm(s.name)));
+      for (const s of f.stages.filter((s) => !have.has(norm(s)))) await client.post(`/api/funnels/${funnel.id}/stages`, { name: s });
+      const { funnels: fresh } = await client.get("/api/funnels");
+      const current = fresh.find((x) => x.id === funnel.id).stages;
+      const order = f.stages.map((s) => current.find((c) => norm(c.name) === norm(s))?.id).filter(Boolean);
+      // Las etapas que ya no están en el archivo se borran si no tienen conversaciones; si tienen, se quedan al final.
+      const kept = [];
+      for (const extra of current.filter((c) => !order.includes(c.id))) {
+        try {
+          await client.del(`/api/funnels/${funnel.id}/stages/${extra.id}`);
+        } catch {
+          kept.push(extra);
+        }
+      }
+      await client.put(`/api/funnels/${funnel.id}/stages/order`, { stageIds: [...order, ...kept.map((c) => c.id)] });
+      ok(`Embudo ${f.name} actualizado`);
+      if (kept.length) warn(`Quedaron etapas que no están en el archivo porque tienen conversaciones: ${kept.map((c) => c.name).join(", ")}`);
+    }
+    if (f.default) await client.put(`/api/funnels/${funnel.id}`, { isDefault: true });
+  }
+}
+
+/** etiquetas.json: ["Compra", "Alquiler", ...] */
+export async function applyTags(file, client = api()) {
+  const names = readJson(file);
+  const { tags } = await client.get("/api/tags");
+  const have = new Set(tags.map((t) => norm(t.name)));
+  let created = 0;
+  for (const name of names) {
+    if (have.has(norm(name))) continue;
+    await client.post("/api/tags", { name });
+    created++;
+  }
+  ok(`Etiquetas: ${created} nuevas, ${names.length - created} ya existían`);
+}
+
+/** respuestas.json: [{ shortcut, title, content }] */
+export async function applyQuickReplies(file, client = api()) {
+  const list = readJson(file);
+  const { quickReplies } = await client.get("/api/quick-replies");
+  for (const q of list) {
+    const existing = quickReplies.find((x) => x.shortcut === String(q.shortcut).replace(/^\/+/, "").toLowerCase());
+    if (existing) await client.put(`/api/quick-replies/${existing.id}`, q);
+    else await client.post("/api/quick-replies", q);
+  }
+  ok(`Respuestas rápidas: ${list.length}`);
+}
+
+/** solicitudes.json: [{ name, description, fields: [{ label, required }] }] */
+export async function applyRequestTypes(file, client = api()) {
+  const list = readJson(file);
+  const { types } = await client.get("/api/requests/types");
+  for (const t of list) {
+    const existing = types.find((x) => norm(x.name) === norm(t.name));
+    if (existing) await client.put(`/api/requests/types/${existing.id}`, t);
+    else await client.post("/api/requests/types", t);
+  }
+  ok(`Tipos de solicitud: ${list.map((t) => t.name).join(", ")}`);
+}
+
+/**
+ * catalogo.json: [{ name, description, price, currency, externalId, images: ["depa-surco-1.jpg"] }]
+ * Las fotos se buscan en la carpeta --media. Solo se suben a productos que todavía no tienen fotos.
+ */
+export async function importCatalog(file, mediaDir, client = api()) {
+  const list = readJson(file);
+  const { products } = await client.get("/api/products");
+  let created = 0;
+  let updated = 0;
+  let photos = 0;
+  for (const p of list) {
+    const existing = products.find((x) => (p.externalId && x.external_id === String(p.externalId)) || norm(x.name) === norm(p.name));
+    const body = { name: p.name, description: p.description ?? "", price: p.price ?? null, currency: p.currency ?? "PEN", externalId: p.externalId ?? null, active: p.active !== false };
+    let id;
+    if (existing) {
+      await client.put(`/api/products/${existing.id}`, body);
+      id = existing.id;
+      updated++;
+    } else {
+      id = (await client.post("/api/products", body)).product.id;
+      created++;
+    }
+    const hasImages = existing && JSON.parse(existing.images || "[]").length > 0;
+    if (!hasImages && Array.isArray(p.images) && p.images.length) {
+      if (!mediaDir) throw new CliError("El catálogo trae fotos: indica la carpeta con --media");
+      const form = new FormData();
+      for (const name of p.images.slice(0, 10)) {
+        const path = resolve(mediaDir, name);
+        const type = IMAGE_TYPES[extname(path).toLowerCase()];
+        if (!existsSync(path) || !type) {
+          warn(`${p.name}: no encontré la foto ${name} (jpg, png, webp o gif)`);
+          continue;
+        }
+        form.append("file", new Blob([readFileSync(path)], { type }), basename(path));
+        photos++;
+      }
+      if (form.has("file")) await client.upload(`/api/products/${id}/images`, form);
+    }
+  }
+  ok(`Catálogo: ${created} nuevos, ${updated} actualizados, ${photos} fotos subidas`);
+}
+
+/** Cada .md o .txt es un documento; el título es el primer encabezado o el nombre del archivo. */
+export async function addKnowledge(paths, client = api()) {
+  const files = paths.flatMap((p) => {
+    const full = resolve(p);
+    if (!existsSync(full)) throw new CliError(`No existe ${full}`);
+    return statSync(full).isDirectory() ? readdirSync(full).filter((f) => /\.(md|txt)$/i.test(f)).map((f) => join(full, f)) : [full];
+  });
+  const { docs } = await client.get("/api/knowledge");
+  for (const path of files) {
+    const text = readFileSync(path, "utf8").trim();
+    const heading = text.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    const title = heading ?? basename(path).replace(/\.(md|txt)$/i, "").replace(/[-_]+/g, " ");
+    const existing = docs.find((d) => norm(d.title) === norm(title));
+    if (existing) await client.put(`/api/knowledge/${existing.id}`, { title, content: text });
+    else await client.post("/api/knowledge", { title, content: text });
+    ok(`${existing ? "Actualizado" : "Agregado"}: ${title}`);
+  }
+}
+
+/**
+ * Aplica una carpeta completa con el formato de un agente (también el de los Giros):
+ * agente.json, embudo.json, etiquetas.json, solicitudes.json, respuestas.json,
+ * catalogo.json con fotos/, y conocimiento/ con archivos .md.
+ */
+export async function applyFolder(folder) {
+  const dir = resolve(folder);
+  if (!existsSync(dir)) throw new CliError(`No existe la carpeta ${dir}`);
+  const client = api();
+  const has = (name) => existsSync(join(dir, name));
+  step(`Aplicando ${dir}`);
+  if (has("agente.json")) await applyAgent(join(dir, "agente.json"), client);
+  if (has("etiquetas.json")) await applyTags(join(dir, "etiquetas.json"), client);
+  if (has("embudo.json")) await applyFunnel(join(dir, "embudo.json"), client);
+  if (has("solicitudes.json")) await applyRequestTypes(join(dir, "solicitudes.json"), client);
+  if (has("respuestas.json")) await applyQuickReplies(join(dir, "respuestas.json"), client);
+  if (has("catalogo.json")) await importCatalog(join(dir, "catalogo.json"), has("fotos") ? join(dir, "fotos") : undefined, client);
+  if (has("conocimiento")) await addKnowledge([join(dir, "conocimiento")], client);
+}
+
+/** Conversación de prueba con el agente real, sin WhatsApp. Cada argumento es un mensaje del cliente. */
+export async function testAgent(messages, flags) {
+  const turns = flags.file ? readFileSync(resolve(flags.file), "utf8").split(/\r?\n/).map((l) => l.trim()).filter(Boolean) : messages;
+  if (!turns.length) throw new CliError('Escribe al menos un mensaje: npx nubot-lite test "Hola, ¿tienen depas en Surco?"');
+  const result = await api().post("/api/system/agent/test", { messages: turns });
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  for (const t of result.turns) {
+    console.log(`\n${bold("Cliente:")} ${t.customer}`);
+    for (const tool of t.tools) console.log(dim(`  ↳ ${tool.tool}(${JSON.stringify(tool.input)}) ${tool.isError ? "✗" : "→"} ${String(tool.result).slice(0, 160)}`));
+    for (const r of t.replies) console.log(`${bold("Agente:")} ${r}`);
+    if (!t.replies.length) console.log(dim(`  (sin respuesta: ${t.outcome})`));
+  }
+  if (result.usage?.errors) console.log(`\n  Error de la IA: ${result.usage.errors}`);
+  if (result.usage) info(`\nTokens: ${result.usage.input ?? 0} de entrada, ${result.usage.output ?? 0} de salida, ${result.usage.cached ?? 0} desde caché`);
+}