@wabot-dev/create 0.0.4 → 2.0.0-beta.0

package/README.md

@@ -1,189 +1,90 @@
 # `@wabot-dev/create`
 
-CLI para:
+CLI para crear un nuevo proyecto Wabot desde el template oficial e instalar las
+skills de agente que **vienen empaquetadas con `@wabot-dev/framework`**.
 
-- crear un nuevo proyecto Wabot desde el template oficial
-- instalar skills empaquetadas en distintos homes o targets de agentes
+> Las skills ya no viven en este paquete: son propiedad de `@wabot-dev/framework`
+> y se versionan junto con su API. Este CLI las descubre desde el framework
+> instalado en el proyecto y las copia a `.claude/`, `.codex/` y/o `.agents/`.
 
-## Instalación
+## Uso rápido
 
 ```bash
-npm install
+npm create @wabot-dev my-wabot-app
+# o
+npx @wabot-dev/create my-wabot-app
 ```
 
-Para probar el binario local:
+El asistente pregunta: nombre, almacenamiento (memoria/postgres), proveedores de
+IA e instalación de skills de agente (por defecto sí). Luego:
 
-```bash
-node ./bin/create-wabot.mjs --help
-```
+1. clona el template oficial,
+2. corre `npm install` (deja `@wabot-dev/framework` en `node_modules`),
+3. copia las skills de ese framework a las carpetas de agente elegidas.
 
-## Comando principal
+Si no pasás `project-directory`, se pregunta el nombre en modo interactivo.
 
-Crear un proyecto nuevo:
-
-```bash
-create-wabot <project-directory>
-```
-
-Ejemplo:
-
-```bash
-create-wabot my-wabot-app
-```
-
-Variaciones:
+Opciones:
 
 ```bash
 create-wabot my-wabot-app --db-url "postgres://localhost:5432/wabot"
-create-wabot my-wabot-app --llm-url "http://localhost:3000"
-create-wabot my-wabot-app --api-key "my-api-key"
-create-wabot my-wabot-app --db-url "postgres://localhost:5432/wabot" --llm-url "http://localhost:3000" --api-key "my-api-key"
-```
-
-Si no pasás `project-directory`, el CLI pregunta el nombre del proyecto en modo interactivo.
-
-## Comando de skills
-
-Instalar una skill empaquetada:
-
-```bash
-create-wabot skill add <skill-name>
+create-wabot my-wabot-app --lang es
 ```
 
-Skill disponible actualmente:
+## Canal beta
 
-```bash
-create-wabot skill add wabot-framework
-```
-
-## Variaciones de `skill add`
+Las builds beta de `@wabot-dev/create` (versión `X.Y.Z-beta.N`) scaffoldean desde
+la rama **`beta`** del template (`wabot-dev/wabot-template#beta`), que fija la
+versión beta del framework. Las builds estables usan la rama por defecto.
 
-### 1. Instalación global por defecto
-
-Usa el home del sistema y, si no se indica target, instala para `codex`.
+Para forzar una fuente concreta del template (p. ej. probar una rama antes de
+publicar) usá la variable de entorno:
 
 ```bash
-create-wabot skill add wabot-framework
+WABOT_TEMPLATE_REF="wabot-dev/wabot-template#beta" create-wabot my-app
 ```
 
-Resultado esperado:
-
-- `<os.homedir()>/.codex/skills/wabot-framework`
+## Skills en un proyecto existente
 
-### 2. Instalación local al proyecto
-
-Instala en el workspace actual:
+Las skills se instalan solas al crear el proyecto. Para **agregarlas o
+actualizarlas** más tarde (por ejemplo tras subir la versión del framework), usá
+el bin que ships el propio framework:
 
 ```bash
-create-wabot skill add wabot-framework --local
+npx wabot-skills list                     # lista las skills empaquetadas
+npx wabot-skills sync                      # refresca las skills del proyecto a la
+                                           # versión de framework instalada
+npx wabot-skills sync --agents claude,codex
 ```
 
-Resultado esperado:
-
-- `./.agents/skills/wabot-framework`
+`sync` sobrescribe en el lugar (resync); detecta las carpetas de agente ya
+presentes en el proyecto (`.claude`, `.codex`, `.agents`) o usá `--agents`.
 
-### 3. Instalación global con home explícito
+## `create-wabot skill add` (instalación puntual)
 
-Instala usando un home root manual:
+También podés instalar una skill suelta con este CLI. La fuente es el
+`@wabot-dev/framework` resoluble desde el proyecto/entorno actual.
 
 ```bash
-create-wabot skill add wabot-framework --global --home "/Users/demo"
-create-wabot skill add wabot-framework --global --home "C:\\Users\\demo"
-```
-
-### 4. Instalación global para un target único
-
-```bash
-create-wabot skill add wabot-framework --global --target codex
+create-wabot skill add wabot-framework --local          # ./.agents/skills/...
 create-wabot skill add wabot-framework --global --target claude
-create-wabot skill add wabot-framework --global --target agents
-```
-
-Con `--home`:
-
-```bash
-create-wabot skill add wabot-framework --global --home "C:\\Users\\demo" --target codex
-create-wabot skill add wabot-framework --global --home "C:\\Users\\demo" --target claude
-create-wabot skill add wabot-framework --global --home "C:\\Users\\demo" --target agents
+create-wabot skill add wabot-framework --global --targets agents,codex,claude --home "/Users/demo"
 ```
 
-Rutas esperadas:
-
-- `codex` -> `<home>/.codex/skills/wabot-framework`
-- `claude` -> `<home>/.claude/skills/wabot-framework`
-- `agents` -> `<home>/.agents/skills/wabot-framework`
-
-### 5. Instalación global para múltiples targets
-
-```bash
-create-wabot skill add wabot-framework --global --targets codex,claude
-create-wabot skill add wabot-framework --global --targets agents,codex,claude
-```
-
-Con `--home`:
-
-```bash
-create-wabot skill add wabot-framework --global --home "C:\\Users\\demo" --targets agents,codex,claude
-```
-
-Esto instala la misma skill en múltiples destinos dentro del mismo home root.
-
-## Reglas útiles
+Reglas:
 
 - `--local` y `--global` son excluyentes.
 - `--home`, `--target` y `--targets` aplican solo con `--global`.
-- Si no se pasa `--target` ni `--targets`, el default es `codex`.
-- Si el destino ya existe, el comando falla y no sobreescribe.
-- Si el target no existe en la lista soportada, el comando falla.
-
-## Targets soportados
-
-```text
-agents
-codex
-claude
-```
-
-## Ejemplos completos
-
-Crear un proyecto:
-
-```bash
-create-wabot my-bot
-```
+- Si no se pasa `--target`/`--targets`, el default es `codex`.
+- Si el destino ya existe, falla y no sobrescribe (usá `wabot-skills sync` para refrescar).
 
-Crear un proyecto con variables iniciales:
-
-```bash
-create-wabot my-bot \
-  --db-url "postgres://localhost:5432/mybot" \
-  --llm-url "http://localhost:3000" \
-  --api-key "secret"
-```
-
-Instalar la skill local al repo:
-
-```bash
-create-wabot skill add wabot-framework --local
-```
-
-Instalar la skill para Claude en otro home:
-
-```bash
-create-wabot skill add wabot-framework --global --home "C:\\Users\\another-user" --target claude
-```
-
-Instalar la skill para varios agentes en el mismo home:
-
-```bash
-create-wabot skill add wabot-framework --global --home "C:\\Users\\another-user" --targets agents,codex,claude
-```
+Targets soportados: `agents`, `codex`, `claude`.
 
 ## Desarrollo
 
-Mostrar ayuda:
-
 ```bash
+npm install                # linkea @wabot-dev/framework (file:../wabot-ts) para tests
+npm run test:smoke         # smokes del instalador de skills
 node ./bin/create-wabot.mjs --help
 node ./bin/create-wabot.mjs skill add --help
 ```

package/lib/create-project.mjs

@@ -6,11 +6,28 @@ import fs from 'fs/promises'
 import { spawn } from 'child_process'
 
 import { installSkillsInProject, listSupportedAgents } from './skills/install.mjs'
-import { listSkills } from './skills/registry.mjs'
 import { createTranslator } from './i18n.mjs'
 
 const REQUIRED_NODE_MAJOR = 22
 
+const TEMPLATE_REPO = 'wabot-dev/wabot-template'
+const TEMPLATE_BETA_BRANCH = 'beta'
+
+// Beta builds of @wabot-dev/create scaffold from the matching `beta` branch of the
+// template (which pins the beta framework); stable builds use the default branch.
+// `WABOT_TEMPLATE_REF` overrides both (e.g. to test a branch before release).
+async function resolveTemplateRepo() {
+  if (process.env.WABOT_TEMPLATE_REF) {
+    return process.env.WABOT_TEMPLATE_REF
+  }
+
+  const pkgRaw = await fs.readFile(new URL('../package.json', import.meta.url), 'utf-8')
+  const version = JSON.parse(pkgRaw).version ?? ''
+  const isBeta = version.includes('-beta')
+
+  return isBeta ? `${TEMPLATE_REPO}#${TEMPLATE_BETA_BRANCH}` : TEMPLATE_REPO
+}
+
 const AI_PROVIDERS = [
   {
     value: 'openrouter',
@@ -194,13 +211,12 @@ async function collectSetup(options, t) {
 
 async function collectSkillsSetup({ onCancel }, t) {
   const supportedAgents = listSupportedAgents()
-  const availableSkills = listSkills()
 
   const { install } = await prompts(
     {
       type: 'confirm',
       name: 'install',
-      message: t('skills.installPrompt', availableSkills.length),
+      message: t('skills.installPrompt'),
       initial: true,
     },
     { onCancel },
@@ -227,10 +243,12 @@ async function collectSkillsSetup({ onCancel }, t) {
     { onCancel },
   )
 
+  // Empty list = install every skill the installed framework ships; the actual
+  // set is resolved at install time from @wabot-dev/framework in the new project.
   return {
     install: true,
     agents,
-    skills: availableSkills.map((skill) => skill.name),
+    skills: [],
   }
 }
 
@@ -241,7 +259,12 @@ async function createProject(projectName, setup, t) {
 
   console.log(chalk.blue(t('project.creating', chalk.green(targetDir))))
 
-  const emitter = degit('wabot-dev/wabot-template', {
+  const templateRepo = await resolveTemplateRepo()
+  if (templateRepo !== TEMPLATE_REPO) {
+    console.log(chalk.gray(t('project.templateSource', templateRepo)))
+  }
+
+  const emitter = degit(templateRepo, {
     cache: false,
     force: true,
     verbose: true,

package/lib/i18n.mjs

@@ -19,6 +19,7 @@ const STRINGS = {
     'project.cancelled': 'Setup cancelled',
     'project.exists': (name) => `Directory ${name} already exists`,
     'project.creating': (dir) => `\nCreating a new Wabot project in ${dir}\n`,
+    'project.templateSource': (repo) => `  Using template source: ${repo}`,
 
     'storage.prompt': 'How do you want to store data?',
     'storage.memory': 'In-memory (quickest start, data resets on restart)',
@@ -33,8 +34,7 @@ const STRINGS = {
     'providers.anthropic': 'Claude models',
     'providers.google': 'Gemini models',
 
-    'skills.installPrompt': (count) =>
-      `Install Wabot agent skills (${count}) into the new project?`,
+    'skills.installPrompt': 'Install Wabot agent skills into the new project?',
     'skills.agentsPrompt': 'Install for which agents? (space to toggle, enter to confirm)',
     'skills.agentsHint': 'Each adds a folder of <agent>/skills under the project root',
     'skills.installing': '\nInstalling Wabot agent skills...\n',
@@ -44,7 +44,7 @@ const STRINGS = {
       `  ⚠  ${count} skill folder(s) already existed and were left untouched.`,
     'skills.failed': (msg) => `  ✖ Failed to install agent skills: ${msg}`,
     'skills.installLater':
-      '  You can install them later with `create-wabot skill add <skill>`.',
+      '  You can install/refresh them later with `npx wabot-skills sync`.',
 
     'deps.installing': '\nInstalling dependencies with npm...\n',
     'deps.exitCode': (code) => `npm install exited with code ${code}`,
@@ -89,6 +89,7 @@ const STRINGS = {
     'project.cancelled': 'Configuración cancelada',
     'project.exists': (name) => `El directorio ${name} ya existe`,
     'project.creating': (dir) => `\nCreando un nuevo proyecto Wabot en ${dir}\n`,
+    'project.templateSource': (repo) => `  Usando fuente del template: ${repo}`,
 
     'storage.prompt': '¿Cómo deseas almacenar los datos?',
     'storage.memory': 'En memoria (inicio más rápido, los datos se pierden al reiniciar)',
@@ -106,8 +107,7 @@ const STRINGS = {
     'providers.anthropic': 'Modelos Claude',
     'providers.google': 'Modelos Gemini',
 
-    'skills.installPrompt': (count) =>
-      `¿Instalar las skills de agente de Wabot (${count}) en el nuevo proyecto?`,
+    'skills.installPrompt': '¿Instalar las skills de agente de Wabot en el nuevo proyecto?',
     'skills.agentsPrompt':
       '¿Para qué agentes instalarlas? (espacio para alternar, enter para confirmar)',
     'skills.agentsHint':
@@ -119,7 +119,7 @@ const STRINGS = {
       `  ⚠  ${count} carpeta(s) de skill ya existían y no se modificaron.`,
     'skills.failed': (msg) => `  ✖ Fallo al instalar las skills de agente: ${msg}`,
     'skills.installLater':
-      '  Puedes instalarlas más tarde con `create-wabot skill add <skill>`.',
+      '  Puedes instalarlas/actualizarlas más tarde con `npx wabot-skills sync`.',
 
     'deps.installing': '\nInstalando dependencias con npm...\n',
     'deps.exitCode': (code) => `npm install terminó con código ${code}`,

package/lib/skills/framework-source.mjs

@@ -0,0 +1,68 @@
+import { createRequire } from 'module'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const require = createRequire(import.meta.url)
+
+const FRAMEWORK_PKG = '@wabot-dev/framework'
+const FRAMEWORK_SEGMENTS = FRAMEWORK_PKG.split('/')
+
+function packageRootFromEntry(entryPath) {
+  let dir = path.dirname(entryPath)
+  const { root } = path.parse(dir)
+  while (dir && dir !== root) {
+    const pkgFile = path.join(dir, 'package.json')
+    if (fs.existsSync(pkgFile)) {
+      try {
+        if (JSON.parse(fs.readFileSync(pkgFile, 'utf8')).name === FRAMEWORK_PKG) {
+          return dir
+        }
+      } catch {
+        // ignore malformed package.json and keep walking up
+      }
+    }
+    dir = path.dirname(dir)
+  }
+  return null
+}
+
+// Locate the packaged `skills/` directory shipped by @wabot-dev/framework.
+//
+// The framework owns the skills and versions them with its API. When bootstrapping
+// or resyncing a project, resolve them from the framework installed *in that
+// project* (`fromDir`) so the copied skills match the project's pinned framework
+// version. For standalone use (e.g. `skill add`) fall back to the framework
+// resolvable from this package.
+export function resolveFrameworkSkillsDir(fromDir) {
+  const candidates = []
+
+  if (fromDir) {
+    candidates.push(path.join(fromDir, 'node_modules', ...FRAMEWORK_SEGMENTS, 'skills'))
+  }
+
+  try {
+    const pkgRoot = packageRootFromEntry(require.resolve(FRAMEWORK_PKG))
+    if (pkgRoot) candidates.push(path.join(pkgRoot, 'skills'))
+  } catch {
+    // framework not resolvable via node resolution; try the node_modules lookups below
+  }
+
+  const createPkgRoot = fileURLToPath(new URL('../../', import.meta.url))
+  candidates.push(path.join(createPkgRoot, 'node_modules', ...FRAMEWORK_SEGMENTS, 'skills'))
+  candidates.push(path.join(process.cwd(), 'node_modules', ...FRAMEWORK_SEGMENTS, 'skills'))
+
+  // Monorepo dev fallback: the framework lives beside this package as a sibling
+  // checkout (`../wabot-ts`). Used so smoke tests can resolve skills without the
+  // framework being installed as a dependency; installed lookups above win.
+  candidates.push(path.join(createPkgRoot, '..', 'wabot-ts', 'skills'))
+
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(dir)) return dir
+  }
+
+  throw new Error(
+    `Could not locate ${FRAMEWORK_PKG} skills. Ensure ${FRAMEWORK_PKG} is installed ` +
+      `(the packaged skills ship with the framework as of the version that added them).`,
+  )
+}

package/lib/skills/install.mjs

@@ -3,6 +3,7 @@ import os from 'os'
 import path from 'path'
 
 import { getSkill, listSkillNames, listSkills } from './registry.mjs'
+import { resolveFrameworkSkillsDir } from './framework-source.mjs'
 
 const supportedAgents = {
   codex: ['.codex', 'skills'],
@@ -28,8 +29,11 @@ export async function installSkillsInProject(projectDir, agents, skillNames) {
     return agent
   })
 
+  const skillsDir = resolveFrameworkSkillsDir(projectDir)
   const skills =
-    skillNames && skillNames.length > 0 ? skillNames.map((name) => requireSkill(name)) : listSkills()
+    skillNames && skillNames.length > 0
+      ? skillNames.map((name) => requireSkill(name, skillsDir))
+      : listSkills(skillsDir)
 
   const installations = []
 
@@ -59,22 +63,23 @@ export async function installSkillsInProject(projectDir, agents, skillNames) {
   return { agents: resolvedAgents, skills: skills.map((skill) => skill.name), installations }
 }
 
-function requireSkill(name) {
-  const skill = getSkill(name)
+function requireSkill(name, skillsDir) {
+  const skill = getSkill(name, skillsDir)
   if (!skill) {
     throw new Error(
-      `Unknown skill "${name}". Available skills: ${listSkillNames().join(', ')}`,
+      `Unknown skill "${name}". Available skills: ${listSkillNames(skillsDir).join(', ')}`,
     )
   }
   return skill
 }
 
 export async function installSkill(skillName, options, cwd = process.cwd()) {
-  const skill = getSkill(skillName)
+  const skillsDir = resolveFrameworkSkillsDir(cwd)
+  const skill = getSkill(skillName, skillsDir)
 
   if (!skill) {
     throw new Error(
-      `Unknown skill "${skillName}". Available skills: ${listSkillNames().join(', ')}`,
+      `Unknown skill "${skillName}". Available skills: ${listSkillNames(skillsDir).join(', ')}`,
     )
   }
 

package/lib/skills/registry.mjs

@@ -1,64 +1,34 @@
-import { fileURLToPath } from 'url'
+import fs from 'fs'
+import path from 'path'
 
-function packagedSkill(name, description) {
-  return {
-    name,
-    description,
-    sourceDir: fileURLToPath(new URL(`../../skills/${name}`, import.meta.url)),
-  }
-}
+import { resolveFrameworkSkillsDir } from './framework-source.mjs'
 
-const skillDefinitions = {
-  'wabot-framework': packagedSkill(
-    'wabot-framework',
-    'Umbrella skill — project boot, layout, scripts, and where to dive for each subsystem',
-  ),
-  'wabot-di-config': packagedSkill(
-    'wabot-di-config',
-    'DI lifecycles, Env, and typed config references',
-  ),
-  'wabot-validation': packagedSkill(
-    'wabot-validation',
-    'Validators, @description, validateAndTransform, Mapper',
-  ),
-  'wabot-persistence': packagedSkill(
-    'wabot-persistence',
-    'Entities, repositories, query DSL, mem/pg extensions',
-  ),
-  'wabot-mindset': packagedSkill(
-    'wabot-mindset',
-    'Mindsets, modules, models, ChatOperator',
-  ),
-  'wabot-chat': packagedSkill(
-    'wabot-chat',
-    'Chat controllers, channels (cmd/socket/telegram/whatsapp/wasender), chat-bot adapters',
-  ),
-  'wabot-rest-socket': packagedSkill(
-    'wabot-rest-socket',
-    'REST and Socket.IO controllers, middlewares, handshake guards',
-  ),
-  'wabot-async': packagedSkill(
-    'wabot-async',
-    'Commands, cron handlers, @transaction, the Async service',
-  ),
-  'wabot-auth': packagedSkill(
-    'wabot-auth',
-    'Auth<D> scope, JWT and API key guards, token issuing',
-  ),
-  'wabot-ops': packagedSkill(
-    'wabot-ops',
-    'Logger, Locker, CustomError, Password, Random',
-  ),
-}
+// Skills are owned and versioned by @wabot-dev/framework. The registry discovers
+// them from the framework's packaged `skills/` directory rather than bundling its
+// own copy, so adding a skill upstream requires no change here.
 
-export function getSkill(skillName) {
-  return skillDefinitions[skillName] ?? null
+export function listSkillNames(skillsDir = resolveFrameworkSkillsDir()) {
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')),
+    )
+    .map((entry) => entry.name)
+    .sort()
 }
 
-export function listSkillNames() {
-  return Object.keys(skillDefinitions).sort()
+export function listSkills(skillsDir = resolveFrameworkSkillsDir()) {
+  return listSkillNames(skillsDir).map((name) => ({
+    name,
+    sourceDir: path.join(skillsDir, name),
+  }))
 }
 
-export function listSkills() {
-  return listSkillNames().map((name) => skillDefinitions[name])
+export function getSkill(name, skillsDir = resolveFrameworkSkillsDir()) {
+  const sourceDir = path.join(skillsDir, name)
+  if (!fs.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+    return null
+  }
+  return { name, sourceDir }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wabot-dev/create",
-  "version": "0.0.4",
+  "version": "2.0.0-beta.0",
   "description": "Project creator for Wabot Framework",
   "license": "ISC",
   "author": "",
@@ -11,9 +11,11 @@
   },
   "files": [
     "bin",
-    "lib",
-    "skills"
+    "lib"
   ],
+  "scripts": {
+    "test:smoke": "node scripts/smoke-skills-bulk-install.mjs && node scripts/smoke-skill-installer.mjs"
+  },
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^14.0.0",