@wabot-dev/framework 0.9.27 → 2.0.0-beta.0

package/README.md

@@ -28,6 +28,7 @@
 - 🤖 **Soporte para bots con IA** - Inteligencia artificial lista para usar
 - 🧠 **Múltiples proveedores de IA** - OpenAI, Google Gemini, Anthropic Claude
 - 💬 **Múltiples canales de chat** - Telegram, WhatsApp, Socket y más
+- 🧪 **Sistema de testing integrado** - Prueba tus chatbots sin API keys ni base de datos
 - 📖 **Documentación clara y en español** - Aprende sin barreras de idioma
 
 ---
@@ -103,6 +104,32 @@ Los addons opcionales (`pg`, SDKs de IA) se mantienen como `peerDependencies` y
 
 ---
 
+## 🧪 Testing
+
+El framework incluye un sistema de testing en `@wabot-dev/framework/testing`, agnóstico al runner (node:test, vitest, bun test). Permite probar chatbots de forma determinista —sin API keys ni base de datos— y también evaluar el comportamiento real con un juez LLM.
+
+```ts
+import { createChatBotHarness, LlmJudge } from '@wabot-dev/framework/testing'
+
+// Determinista: el LLM se simula, tus tools se ejecutan de verdad
+const harness = createChatBotHarness({ mindset: EliaMindset })
+harness.adapter.callTool('saveEvent', { title: 'Demo', ... }).reply('¡Agendado!')
+
+const turn = await harness.send('agenda una demo mañana')
+// turn.replies, turn.toolCalls (con resultados reales), harness.history()
+
+// Evals: juzga conversaciones reales con un LLM
+const judge = new LlmJudge({ adapter, models: [{ model: 'claude-haiku-4-5' }] })
+await judge.assert({
+  transcript: harness.history(),
+  criteria: 'Responde en español y confirma la fecha del evento',
+})
+```
+
+También incluye harnesses para controllers de chat (`createChatControllerHarness`), endpoints REST con guards JWT/API-Key reales (`createRestHarness`), commands y crons (`createAsyncHarness`), repositorios en memoria (`useMemoryRepositories`), aserciones de validación y una suite de conformance para adapters LLM propios (`chatAdapterConformanceCases`).
+
+---
+
 ## 💬 Plataformas Soportadas
 
 Wabot se integra nativamente con las principales plataformas de mensajería:

package/bin/skills.mjs

@@ -0,0 +1,151 @@
+// Canonical skills installer for @wabot-dev/framework.
+//
+// The packaged agent skills live at `<package>/skills/<name>/SKILL.md` and are
+// versioned together with the framework API they document. This module is the
+// single source of truth for enumerating and installing them; it is consumed by
+// the `wabot-skills` bin and by @wabot-dev/create during project bootstrap.
+//
+// Dependency-free (node builtins only) so `npx wabot-skills` works with just the
+// framework installed.
+
+import fs from 'fs/promises'
+import fss from 'fs'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+export const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url))
+
+const AGENT_DIRS = {
+  claude: ['.claude', 'skills'],
+  codex: ['.codex', 'skills'],
+  agents: ['.agents', 'skills'],
+}
+
+export function listSupportedAgents() {
+  return Object.keys(AGENT_DIRS)
+}
+
+export function agentSkillsSegments(agent) {
+  const segments = AGENT_DIRS[agent]
+  if (!segments) {
+    throw new Error(
+      `Unsupported agent "${agent}". Supported: ${listSupportedAgents().join(', ')}`,
+    )
+  }
+  return segments
+}
+
+export function listSkillNames() {
+  return fss
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        fss.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md')),
+    )
+    .map((entry) => entry.name)
+    .sort()
+}
+
+export function listSkills() {
+  return listSkillNames().map((name) => ({
+    name,
+    sourceDir: path.join(SKILLS_DIR, name),
+  }))
+}
+
+export function getSkill(name) {
+  const sourceDir = path.join(SKILLS_DIR, name)
+  if (!fss.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+    return null
+  }
+  return { name, sourceDir }
+}
+
+function resolveSkills(skillNames) {
+  if (!skillNames || skillNames.length === 0) {
+    return listSkills()
+  }
+  return skillNames.map((name) => {
+    const skill = getSkill(name)
+    if (!skill) {
+      throw new Error(
+        `Unknown skill "${name}". Available skills: ${listSkillNames().join(', ')}`,
+      )
+    }
+    return skill
+  })
+}
+
+// Copy skills into `<projectDir>/.<agent>/skills`. By default existing skills are
+// left untouched (bootstrap semantics). Pass `{ overwrite: true }` to refresh them
+// to the currently installed framework version (resync semantics).
+export async function installSkillsInProject(projectDir, agents, skillNames, options = {}) {
+  if (!projectDir) {
+    throw new Error('installSkillsInProject: projectDir is required')
+  }
+
+  const resolvedAgents = (agents && agents.length > 0 ? agents : ['claude']).map((agent) => {
+    agentSkillsSegments(agent)
+    return agent
+  })
+
+  const skills = resolveSkills(skillNames)
+  const overwrite = options.overwrite === true
+  const installations = []
+
+  for (const agent of resolvedAgents) {
+    const baseDir = path.join(projectDir, ...agentSkillsSegments(agent))
+    await fs.mkdir(baseDir, { recursive: true })
+
+    for (const skill of skills) {
+      const installDir = path.join(baseDir, skill.name)
+      try {
+        await fs.cp(skill.sourceDir, installDir, {
+          recursive: true,
+          force: overwrite,
+          errorOnExist: !overwrite,
+        })
+        installations.push({
+          agent,
+          skill: skill.name,
+          installDir,
+          status: overwrite ? 'synced' : 'installed',
+        })
+      } catch (error) {
+        if (!overwrite && (error?.code === 'ERR_FS_CP_EEXIST' || error?.code === 'EEXIST')) {
+          installations.push({ agent, skill: skill.name, installDir, status: 'skipped' })
+          continue
+        }
+        throw error
+      }
+    }
+  }
+
+  return { agents: resolvedAgents, skills: skills.map((skill) => skill.name), installations }
+}
+
+// Copy a single skill into agent homes under `homeRoot` (defaults to $HOME).
+export async function installSkillGlobally(skillName, agents, homeRoot = os.homedir()) {
+  const skill = getSkill(skillName)
+  if (!skill) {
+    throw new Error(
+      `Unknown skill "${skillName}". Available skills: ${listSkillNames().join(', ')}`,
+    )
+  }
+  const resolvedAgents = (agents && agents.length > 0 ? agents : ['claude']).map((agent) => {
+    agentSkillsSegments(agent)
+    return agent
+  })
+
+  const installations = []
+  for (const agent of resolvedAgents) {
+    const baseDir = path.join(homeRoot, ...agentSkillsSegments(agent))
+    await fs.mkdir(baseDir, { recursive: true })
+    const installDir = path.join(baseDir, skill.name)
+    await fs.cp(skill.sourceDir, installDir, { recursive: true, force: true, errorOnExist: false })
+    installations.push({ agent, skill: skill.name, installDir })
+  }
+  return { skill: skill.name, homeRoot, installations }
+}

package/bin/wabot-skills.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+// wabot-skills — install / resync the packaged Wabot agent skills that ship with
+// the installed @wabot-dev/framework version.
+//
+//   wabot-skills list
+//   wabot-skills sync   [--agents claude,codex,agents] [--project <dir>]
+//   wabot-skills add <skill> [--agents claude,codex,agents] [--home <dir>]
+//
+// `sync` refreshes the project's skills to match the currently installed framework
+// version (overwrites in place). Run it after upgrading @wabot-dev/framework.
+
+import fss from 'fs'
+import path from 'path'
+
+import {
+  installSkillGlobally,
+  installSkillsInProject,
+  listSkillNames,
+  listSupportedAgents,
+} from './skills.mjs'
+
+function parseFlags(argv) {
+  const flags = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true
+      } else {
+        flags[key] = next
+        i++
+      }
+    } else {
+      positional.push(arg)
+    }
+  }
+  return { flags, positional }
+}
+
+function parseAgents(value) {
+  if (!value || value === true) return listSupportedAgents()
+  return String(value)
+    .split(',')
+    .map((a) => a.trim())
+    .filter(Boolean)
+}
+
+function usage() {
+  console.log(`wabot-skills — manage packaged Wabot agent skills
+
+Usage:
+  wabot-skills list
+  wabot-skills sync [--agents claude,codex,agents] [--project <dir>]
+  wabot-skills add <skill> [--agents claude,codex,agents] [--home <dir>]
+
+sync refreshes existing project skills to the installed framework version.`)
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2)
+  const { flags, positional } = parseFlags(rest)
+
+  if (!command || command === 'help' || flags.help) {
+    usage()
+    return
+  }
+
+  if (command === 'list') {
+    for (const name of listSkillNames()) console.log(name)
+    return
+  }
+
+  if (command === 'sync') {
+    const projectDir = path.resolve(flags.project || process.cwd())
+    // Default to the agent dirs that already exist in the project; fall back to claude.
+    let agents = flags.agents
+      ? parseAgents(flags.agents)
+      : listSupportedAgents().filter((agent) =>
+          fss.existsSync(path.join(projectDir, `.${agent}`, 'skills')),
+        )
+    if (agents.length === 0) agents = ['claude']
+
+    const result = await installSkillsInProject(projectDir, agents, undefined, { overwrite: true })
+    const byAgent = new Map()
+    for (const item of result.installations) {
+      byAgent.set(item.agent, (byAgent.get(item.agent) ?? 0) + 1)
+    }
+    for (const [agent, count] of byAgent) {
+      console.log(`✓ synced ${count} skills into .${agent}/skills`)
+    }
+    return
+  }
+
+  if (command === 'add') {
+    const skillName = positional[0]
+    if (!skillName) {
+      console.error('Error: `wabot-skills add` requires a skill name')
+      process.exit(1)
+    }
+    const agents = parseAgents(flags.agents)
+    const result = await installSkillGlobally(skillName, agents, flags.home || undefined)
+    for (const item of result.installations) {
+      console.log(`✓ installed ${result.skill} -> ${item.installDir}`)
+    }
+    return
+  }
+
+  console.error(`Error: unknown command "${command}"`)
+  usage()
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error('Error:', error.message)
+  process.exit(1)
+})