@wabot-dev/create 0.0.2 → 0.0.3

package/lib/skills/install.mjs

@@ -0,0 +1,179 @@
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+import { getSkill, listSkillNames } from './registry.mjs'
+
+const supportedAgents = {
+  codex: ['.codex', 'skills'],
+  claude: ['.claude', 'skills'],
+  agents: ['.agents', 'skills'],
+}
+
+export async function installSkill(skillName, options, cwd = process.cwd()) {
+  const skill = getSkill(skillName)
+
+  if (!skill) {
+    throw new Error(
+      `Unknown skill "${skillName}". Available skills: ${listSkillNames().join(', ')}`,
+    )
+  }
+
+  const plan = await buildInstallPlan(skill, options, cwd)
+
+  for (const destination of plan.destinations) {
+    await fs.mkdir(destination.baseDir, { recursive: true })
+    await fs.cp(skill.sourceDir, destination.installDir, {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    })
+  }
+
+  return {
+    skill,
+    mode: plan.mode,
+    homeRoot: plan.homeRoot,
+    installations: plan.destinations.map((destination) => ({
+      agent: destination.agent,
+      installDir: destination.installDir,
+    })),
+  }
+}
+
+async function buildInstallPlan(skill, options, cwd) {
+  await assertPathExists(skill.sourceDir, `Packaged skill source not found at ${skill.sourceDir}`)
+
+  if (options.local && options.global) {
+    throw new Error('Choose only one install mode: --local or --global')
+  }
+
+  if (!options.global && (options.target || options.targets || options.home)) {
+    throw new Error('--home, --target, and --targets can only be used together with --global')
+  }
+
+  if (options.local) {
+    const installDir = path.join(cwd, '.agents', 'skills', skill.name)
+    await assertDestinationAvailable(installDir)
+
+    return {
+      mode: 'local',
+      homeRoot: null,
+      destinations: [
+        {
+          agent: 'agents',
+          baseDir: path.join(cwd, '.agents', 'skills'),
+          installDir,
+        },
+      ],
+    }
+  }
+
+  const homeRoot = resolveHomeRoot(options.home)
+  const targets = resolveTargets(options)
+  const destinations = targets.map((agent) => {
+    const baseDir = resolveAgentSkillsDir(homeRoot, agent)
+
+    return {
+      agent,
+      baseDir,
+      installDir: path.join(baseDir, skill.name),
+    }
+  })
+
+  await Promise.all(destinations.map((destination) => assertDestinationAvailable(destination.installDir)))
+
+  return {
+    mode: 'global',
+    homeRoot,
+    destinations,
+  }
+}
+
+function resolveTargets(options) {
+  const parsedTargets = []
+
+  if (options.target) {
+    parsedTargets.push(options.target)
+  }
+
+  if (options.targets) {
+    parsedTargets.push(
+      ...String(options.targets)
+        .split(',')
+        .map((target) => target.trim())
+        .filter(Boolean),
+    )
+  }
+
+  if (parsedTargets.length === 0) {
+    return ['codex']
+  }
+
+  const uniqueTargets = [...new Set(parsedTargets)]
+
+  if (uniqueTargets.length !== parsedTargets.length) {
+    throw new Error('Duplicate targets are not allowed in --target/--targets')
+  }
+
+  for (const target of uniqueTargets) {
+    if (!supportedAgents[target]) {
+      throw new Error(
+        `Unsupported target "${target}". Supported targets: ${Object.keys(supportedAgents).join(', ')}`,
+      )
+    }
+  }
+
+  return uniqueTargets
+}
+
+function resolveHomeRoot(explicitHome) {
+  if (explicitHome) {
+    return path.resolve(explicitHome)
+  }
+
+  const homeRoot = os.homedir()
+
+  if (!homeRoot) {
+    throw new Error('Unable to resolve a home directory. Pass --home <path> explicitly.')
+  }
+
+  return path.resolve(homeRoot)
+}
+
+function resolveAgentSkillsDir(homeRoot, agent) {
+  const segments = supportedAgents[agent]
+
+  if (!segments) {
+    throw new Error(
+      `Unsupported target "${agent}". Supported targets: ${Object.keys(supportedAgents).join(', ')}`,
+    )
+  }
+
+  return path.join(homeRoot, ...segments)
+}
+
+async function assertDestinationAvailable(installDir) {
+  try {
+    await fs.access(installDir)
+    throw new Error(`Skill already exists at ${installDir}`)
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return
+    }
+
+    throw error
+  }
+}
+
+async function assertPathExists(targetPath, errorMessage) {
+  try {
+    await fs.access(targetPath)
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(errorMessage)
+    }
+
+    throw error
+  }
+}

package/lib/skills/registry.mjs

@@ -0,0 +1,17 @@
+import { fileURLToPath } from 'url'
+
+const skillDefinitions = {
+  'wabot-framework': {
+    name: 'wabot-framework',
+    sourceDir: fileURLToPath(new URL('../../skills/wabot-framework', import.meta.url)),
+    description: 'Wabot Framework packaged skill',
+  },
+}
+
+export function getSkill(skillName) {
+  return skillDefinitions[skillName] ?? null
+}
+
+export function listSkillNames() {
+  return Object.keys(skillDefinitions).sort()
+}

package/package.json

@@ -1,19 +1,18 @@
 {
   "name": "@wabot-dev/create",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Project creator for Wabot Framework",
   "license": "ISC",
   "author": "",
   "type": "module",
   "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "bin": {
     "create-wabot": "./bin/create-wabot.mjs"
   },
   "files": [
-    "bin"
+    "bin",
+    "lib",
+    "skills"
   ],
   "dependencies": {
     "chalk": "^5.4.1",

package/skills/wabot-framework/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: wabot-framework
+description: Use when building, reviewing, or debugging apps with @wabot-dev/framework. This skill is self-contained and includes offline examples for project setup, dependency injection, mindsets, external function modules, validation, persistence, chat controllers, REST and socket controllers, async commands, cron, auth, logger, and locking.
+---
+
+# Wabot Framework
+
+Use this skill for Wabot application work. It is self-contained: read the bundled examples first and do not depend on web access for normal tasks.
+
+## How To Use
+
+Load the reference file that matches the request:
+
+- `references/quickstart.md` for project bootstrap and first run
+- `references/core-patterns.md` for dependency injection and service lifecycles
+- `references/mindset-and-chat.md` for bot personality, tools, and chat routing
+- `references/validation-and-data.md` for DTOs, validation, and `Mapper`
+- `references/persistence.md` for entities, repositories, and PostgreSQL persistence
+- `references/controllers-and-auth.md` for REST, socket, and JWT auth
+- `references/async-and-cron.md` for commands and scheduled work
+- `references/ops.md` for logger and locking
+- `references/full-example.md` for an end-to-end sales bot app
+
+## Rules
+
+- Keep prose in Spanish when explaining to the team.
+- Keep code identifiers in English.
+- Use `@wabot-dev/framework` imports in examples.
+- Do not invent APIs. If a detail is not covered by the bundled examples, say what is missing instead of guessing.
+- Keep controllers thin and push business logic into services or modules.
+- Use `@scoped()` only when request, chat, or socket isolation matters.
+- Prefer the smallest example that demonstrates the pattern.

package/skills/wabot-framework/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Wabot Framework"
+  short_description: "Build apps with @wabot-dev/framework"
+  default_prompt: "Use this skill to implement, review, or debug Wabot applications using the bundled offline examples and reference files."
+

package/skills/wabot-framework/references/async-and-cron.md

@@ -0,0 +1,57 @@
+# Async And Cron
+
+Use this when scheduling work in the background or recurring jobs.
+
+## Command and handler
+
+```typescript
+import { command, commandHandler, type ICommandHandler } from '@wabot-dev/framework'
+import { isString } from '@wabot-dev/framework'
+
+@command('save-test-tag')
+export class SaveTestTag {
+  @isString()
+  value!: string
+}
+
+@commandHandler(SaveTestTag)
+export class SaveTestTagHandler implements ICommandHandler<SaveTestTag> {
+  constructor(private tags: TagRepository) {}
+
+  async handle(input: SaveTestTag) {
+    await this.tags.save(input.value)
+  }
+}
+```
+
+## Run or schedule a command
+
+```typescript
+import { Async } from '@wabot-dev/framework'
+
+const job = await async.runCommand(SaveTestTag, { value: 'hello' })
+await async.scheduleCommand(SaveTestTag, { value: 'later' }, { minutes: 10 })
+```
+
+## Cron handler
+
+```typescript
+import { cron } from '@wabot-dev/framework'
+
+@cron({ name: 'sync-leads', cron: '0 * * * *' })
+export class SyncLeadsCron {
+  constructor(private leadService: LeadService) {}
+
+  async handle() {
+    await this.leadService.sync()
+  }
+}
+```
+
+## Good practice
+
+- Use commands for one-off background work.
+- Use cron for repeated schedules.
+- Keep command DTOs validated and small.
+- Keep cron handlers idempotent because they can run many times.
+

package/skills/wabot-framework/references/controllers-and-auth.md

@@ -0,0 +1,104 @@
+# Controllers And Auth
+
+Use this when exposing HTTP endpoints, socket events, or protected routes.
+
+## REST controller
+
+```typescript
+import { IncomingMessage } from 'http'
+import { onPost, restController } from '@wabot-dev/framework'
+
+class PaymentService {
+  processWebhook(rawBody: string) {
+    return { ok: true, rawBody }
+  }
+}
+
+@restController('/webhooks/bold')
+export class BoldWebhookController {
+  constructor(private paymentService: PaymentService) {}
+
+  @onPost({
+    disableJsonParser: true,
+    disableUrlEncodedParser: true,
+  })
+  async receiveWebhook(request: IncomingMessage) {
+    const rawBody = await this.readRawBody(request)
+    return this.paymentService.processWebhook(rawBody)
+  }
+}
+```
+
+## Socket controller
+
+```typescript
+import { jwtHandshakeGuard, onSocketEvent, socketController } from '@wabot-dev/framework'
+
+@jwtHandshakeGuard()
+@socketController('/sales')
+export class SalesSocketController {
+  @onSocketEvent('message')
+  async onMessage(payload: { text: string }) {
+    return { ok: true, received: payload.text }
+  }
+}
+```
+
+## JWT and API key auth
+
+Use JWT when the client already has a signed token. Use API keys when the client should present a shared secret.
+
+```typescript
+import {
+  apiKeyGuard,
+  apiKeyHandshakeGuard,
+  jwtGuard,
+  jwtHandshakeGuard,
+  onGet,
+  onPost,
+  restController,
+  socketController,
+} from '@wabot-dev/framework'
+
+class CreateLeadDto {
+  name!: string
+}
+
+class LeadService {
+  async create(body: CreateLeadDto) {
+    return { created: true, lead: body }
+  }
+}
+
+@restController('/api/leads')
+export class LeadApiController {
+  constructor(private leadService: LeadService) {}
+
+  @apiKeyGuard()
+  @onGet()
+  async listLeads() {
+    return []
+  }
+
+  @jwtGuard()
+  @onPost()
+  async createLead(body: CreateLeadDto) {
+    return this.leadService.create(body)
+  }
+}
+
+@socketController('/lead-room')
+@jwtHandshakeGuard()
+export class LeadRoomSocketController {}
+
+@apiKeyHandshakeGuard()
+@socketController('/api-room')
+export class ApiRoomSocketController {}
+```
+
+## Rule of thumb
+
+- REST for request/response workflows, webhooks, and admin APIs.
+- Socket for live events and long-lived sessions.
+- JWT when the client already has a signed token.
+- API key when the client should present a shared secret.

package/skills/wabot-framework/references/core-patterns.md

@@ -0,0 +1,83 @@
+# Core Patterns
+
+Use this when deciding how to register and inject services.
+
+## Lifecycles
+
+| Decorator | Use for | Example |
+| --- | --- | --- |
+| `@singleton()` | Shared clients, repositories, config, caches | one DB repository for the app |
+| `@injectable()` | Stateless services and modules | calculators, adapters, helpers |
+| `@scoped(Lifecycle.ContainerScoped)` | Request/chat/socket-local state | auth context, request context |
+
+## Singleton example
+
+```typescript
+import { singleton } from '@wabot-dev/framework'
+
+@singleton()
+export class ProductRepository {
+  private products = new Map<string, string>()
+
+  save(id: string, name: string) {
+    this.products.set(id, name)
+  }
+}
+```
+
+## Injectable example
+
+```typescript
+import { injectable } from '@wabot-dev/framework'
+
+@injectable()
+export class QuoteCalculator {
+  total(base: number, discount: number) {
+    return base - base * discount
+  }
+}
+```
+
+## Scoped example
+
+```typescript
+import { Lifecycle, scoped } from '@wabot-dev/framework'
+
+@scoped(Lifecycle.ContainerScoped)
+export class RequestContext {
+  private userId?: string
+
+  setUserId(userId: string) {
+    this.userId = userId
+  }
+
+  requireUserId() {
+    if (!this.userId) throw new Error('Unauthorized')
+    return this.userId
+  }
+}
+```
+
+## Token injection
+
+```typescript
+import { container, inject, injectable } from '@wabot-dev/framework'
+
+container.register('SMTP_HOST', { useValue: 'smtp.example.com' })
+container.register('SMTP_PORT', { useValue: 587 })
+
+@injectable()
+export class Mailer {
+  constructor(
+    @inject('SMTP_HOST') private smtpHost: string,
+    @inject('SMTP_PORT') private smtpPort: number,
+  ) {}
+}
+```
+
+## Rule of thumb
+
+- Use singleton for shared infrastructure.
+- Use injectable for pure business logic.
+- Use scoped only when state must not leak across requests or chats.
+