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

package/skills/wabot-framework/references/full-example.md

@@ -1,278 +0,0 @@
-# Full Example
-
-Use this when you need an end-to-end pattern that combines most of the framework.
-
-## What this example covers
-
-- project bootstrap
-- mindset and chat routing
-- external mindset module
-- validation and mapper
-- persistence
-- REST and socket controllers
-- JWT auth
-- async command and cron
-- logger and locker
-
-## 1. Bootstrap
-
-```typescript
-import {
-  ChatAdapter,
-  ChatRepository,
-  container,
-  Env,
-  PgChatRepository,
-  runChatControllers,
-  runRestControllers,
-  WabotChatAdapter,
-} from '@wabot-dev/framework'
-import { Pool } from 'pg'
-
-import { SalesChatController } from './controllers/SalesChatController'
-import { SalesWebhookController } from './controllers/SalesWebhookController'
-
-const env = container.resolve(Env)
-container.registerInstance(Pool, new Pool({ connectionString: env.requireString('DATABASE_URL') }))
-container.registerType(ChatAdapter, WabotChatAdapter)
-container.registerType(ChatRepository, PgChatRepository)
-
-runRestControllers([SalesWebhookController])
-runChatControllers([SalesChatController])
-```
-
-## 2. Mindset and module
-
-```typescript
-import {
-  type IMindset,
-  type IMindsetIdentity,
-  type IMindsetLlm,
-  description,
-  mindset,
-  mindsetModule,
-} from '@wabot-dev/framework'
-
-@mindsetModule()
-export class LeadInsightsModule {
-  @description('Summarize the latest notes and suggest the next best action')
-  async summarizeLead(req: { note: string }) {
-    return `Next action: ${req.note}`
-  }
-}
-
-@mindset({ modules: [LeadInsightsModule] })
-export class SalesMindset implements IMindset {
-  async context() {
-    return 'Act like a helpful sales assistant.'
-  }
-
-  async identity(): Promise<IMindsetIdentity> {
-    return { name: 'Martin', language: 'Español' }
-  }
-
-  async skills() {
-    return 'Qualify leads, explain offers, and guide the next step.'
-  }
-
-  async limits() {
-    return 'Do not invent prices or promise features that are not available.'
-  }
-
-  async workflow() {
-    return 'Ask one clear question at a time and move toward qualification.'
-  }
-
-  async llms(): Promise<IMindsetLlm[]> {
-    return [{ provider: 'openai', model: 'gpt-4o-mini' }]
-  }
-}
-```
-
-## 3. Validation and persistence
-
-```typescript
-import {
-  Entity,
-  Locker,
-  Logger,
-  Mapper,
-  PgCrudRepository,
-  type IEntityData,
-  injectable,
-  isNotEmpty,
-  isNumber,
-  isString,
-  min,
-  singleton,
-} from '@wabot-dev/framework'
-import { Pool } from 'pg'
-
-export class CreateLeadDto {
-  @isString()
-  @isNotEmpty()
-  name!: string
-
-  @isNumber()
-  @min(1)
-  budget!: number
-}
-
-export interface LeadData extends IEntityData {
-  name: string
-  budget: number
-  status: 'new' | 'qualified'
-}
-
-export class Lead extends Entity<LeadData> {}
-
-@singleton()
-export class LeadRepository extends PgCrudRepository<Lead> {
-  constructor(pool: Pool) {
-    super(pool, { table: 'leads', constructor: Lead })
-  }
-}
-
-@injectable()
-export class LeadService {
-  constructor(
-    private mapper: Mapper,
-    private leads: LeadRepository,
-    private logger: Logger,
-    private locker: Locker,
-  ) {}
-
-  async create(raw: unknown) {
-    const lead = this.mapper.map(raw, CreateLeadDto)
-    await this.locker.withKey(`lead:${lead.name}`).run(async () => {
-      this.logger.info('creating lead', { name: lead.name })
-      await this.leads.create(new Lead({ name: lead.name, budget: lead.budget, status: 'new' }))
-    })
-  }
-}
-```
-
-## 4. Chat controller
-
-```typescript
-import { chatBot, chatController, ChatBot, cmd, type IReceivedMessage } from '@wabot-dev/framework'
-
-@chatController()
-export class SalesChatController {
-  constructor(@chatBot(SalesMindset) private bot: ChatBot) {}
-
-  @cmd()
-  async onMessage(context: IReceivedMessage) {
-    const fallback = 'Puedo ayudarte a revisar el caso y registrar el siguiente paso.'
-
-    await this.bot.sendMessage(context.message, async (replyMessage) => {
-      await context.reply(replyMessage ?? { text: fallback })
-    })
-  }
-}
-```
-
-## 5. REST and socket auth
-
-```typescript
-import {
-  apiKeyGuard,
-  apiKeyHandshakeGuard,
-  jwtGuard,
-  jwtHandshakeGuard,
-  onGet,
-  onPost,
-  onSocketEvent,
-  restController,
-  socketController,
-} from '@wabot-dev/framework'
-
-@restController('/api/leads')
-export class SalesApiController {
-  constructor(private leadService: LeadService) {}
-
-  @apiKeyGuard()
-  @onGet()
-  async list() {
-    return []
-  }
-
-  @jwtGuard()
-  @onPost()
-  async create(body: CreateLeadDto) {
-    return this.leadService.create(body)
-  }
-}
-
-@socketController('/sales')
-@jwtHandshakeGuard()
-export class SalesSocketController {
-  @onSocketEvent('ping')
-  async ping() {
-    return { ok: true }
-  }
-}
-
-@apiKeyHandshakeGuard()
-@socketController('/sales-admin')
-export class SalesAdminSocketController {}
-```
-
-## 6. Async and cron
-
-```typescript
-import { Async, command, commandHandler, cron, isString } from '@wabot-dev/framework'
-
-@command('sync-lead')
-export class SyncLeadCommand {
-  @isString()
-  leadId!: string
-}
-
-@commandHandler(SyncLeadCommand)
-export class SyncLeadHandler {
-  constructor(private leadService: LeadService) {}
-
-  async handle(input: SyncLeadCommand) {
-    await this.leadService.create({ name: input.leadId, budget: 1 })
-  }
-}
-
-@cron({ name: 'sync-leads', cron: '0 * * * *' })
-export class SyncLeadsCron {
-  constructor(private async: Async) {}
-
-  async handle() {
-    await this.async.runCommand(SyncLeadCommand, { leadId: 'all' })
-  }
-}
-```
-
-## 7. Operational guardrails
-
-```typescript
-import { container, Locker, Logger, PgLocker } from '@wabot-dev/framework'
-import { injectable } from '@wabot-dev/framework'
-
-container.registerType(Locker, PgLocker)
-
-@injectable()
-export class SalesOpsService {
-  constructor(private locker: Locker) {}
-
-  async sync() {
-    const logger = new Logger('sales:app')
-    logger.info('app started')
-
-    await this.locker.withKey('sales-sync').run(async () => {
-      logger.debug('syncing leads')
-    })
-  }
-}
-```
-
-## Read this example when
-
-- the user wants the whole flow
-- the task spans several framework areas
-- the answer needs a working mental model, not just one decorator

package/skills/wabot-framework/references/mindset-and-chat.md

@@ -1,97 +0,0 @@
-# Mindset And Chat
-
-Use this when defining bot behavior or routing chat messages.
-
-## Mindset shape
-
-```typescript
-import { type IMindset, type IMindsetIdentity, type IMindsetLlm, mindset } from '@wabot-dev/framework'
-import { description, mindsetModule } from '@wabot-dev/framework'
-
-class LeadNotesDto {
-  note!: string
-}
-
-@mindsetModule()
-export class SalesInsightsModule {
-  @description('Summarize the lead history and suggest the next action')
-  async summarizeLead(input: LeadNotesDto) {
-    return `Lead note: ${input.note}`
-  }
-}
-
-@mindset({ modules: [SalesInsightsModule] })
-export class SalesMindset implements IMindset {
-  async context(): Promise<string> {
-    return 'You are a helpful sales assistant that keeps replies short and concrete.'
-  }
-
-  async identity(): Promise<IMindsetIdentity> {
-    return {
-      name: 'Martin',
-      language: 'Español',
-      personality: 'Calmo, persuasivo y orientado a resultados',
-      emotions: 'Empatico, confiado y directo',
-    }
-  }
-
-  async skills(): Promise<string> {
-    return `
-      Calificar prospectos.
-      Explicar beneficios con claridad.
-      Manejar objeciones sin presionar.
-    `
-  }
-
-  async limits(): Promise<string> {
-    return `
-      No prometer funciones que no existen.
-      No inventar precios ni descuentos.
-      No pedir datos sensibles.
-    `
-  }
-
-  async workflow(): Promise<string> {
-    return `
-      1. Entender la necesidad.
-      2. Hacer una pregunta clara.
-      3. Registrar datos utiles.
-      4. Proponer el siguiente paso.
-    `
-  }
-
-  async llms(): Promise<IMindsetLlm[]> {
-    return [{ provider: 'openai', model: 'gpt-4o-mini' }]
-  }
-}
-```
-
-## Mindset module
-
-Use a module when the mindset needs an extra tool-like function.
-
-## Chat controller
-
-```typescript
-import { chatBot, chatController, ChatBot, cmd, type IReceivedMessage } from '@wabot-dev/framework'
-
-@chatController()
-export class SalesChatController {
-  constructor(@chatBot(SalesMindset) private bot: ChatBot) {}
-
-  @cmd()
-  async onMessage(context: IReceivedMessage) {
-    const fallback = 'Te ayudo a elegir una solucion y avanzar al siguiente paso.'
-
-    await this.bot.sendMessage(context.message, async (replyMessage) => {
-      await context.reply(replyMessage ?? { text: fallback })
-    })
-  }
-}
-```
-
-## Good practice
-
-- Put policy and personality in the mindset.
-- Put business rules in services or modules.
-- Keep the controller only as an entry point and reply bridge.

package/skills/wabot-framework/references/ops.md

@@ -1,58 +0,0 @@
-# Operations
-
-Use this when adding observability or duplicate-work protection.
-
-## Logger
-
-```typescript
-import { Logger } from '@wabot-dev/framework'
-
-const logger = new Logger('sales:lead-service')
-
-logger.info('service started')
-logger.debug('loading lead', { leadId: 'abc123' })
-logger.warn('fallback used', { reason: 'missing metadata' })
-logger.error('failed to save lead', new Error('db timeout'))
-logger.fatal('process cannot continue')
-```
-
-## Logging rule
-
-- `trace`: every request, socket event, or message.
-- `debug`: operational steps and query-level detail.
-- `info`: lifecycle milestones and meaningful state changes.
-- `warn`: recoverable issues or unusual conditions.
-- `error`: failed operations with context and error.
-- `fatal`: unrecoverable process-level failures.
-
-## Locker
-
-```typescript
-import { container, Locker, PgLocker } from '@wabot-dev/framework'
-
-container.registerType(Locker, PgLocker)
-
-const locker = container.resolve(Locker)
-
-await locker.withKey('lead-sync').run(async () => {
-  await syncLeads()
-})
-
-const maybeResult = await locker.withKey('lead-sync').tryRun(async () => {
-  await syncLeads()
-})
-```
-
-## Combining with entities
-
-```typescript
-await locker.withKey(lead).run(async () => {
-  await leadService.qualify(lead.id)
-})
-```
-
-## Rule of thumb
-
-- Use logger for visibility.
-- Use locker when duplicate processing would be harmful.
-- Prefer small lock scopes so the critical section stays short.

package/skills/wabot-framework/references/persistence.md

@@ -1,85 +0,0 @@
-# Persistence
-
-Use this when saving or loading domain information from PostgreSQL.
-
-## Entity
-
-```typescript
-import { Entity, PgCrudRepository, type IEntityData, injectable, singleton, Locker, Logger } from '@wabot-dev/framework'
-import { Pool } from 'pg'
-
-export interface LeadData extends IEntityData {
-  name: string
-  budget: number
-  status: 'new' | 'qualified' | 'won' | 'lost'
-}
-
-export class Lead extends Entity<LeadData> {
-  get name() {
-    return this['data'].name
-  }
-
-  setQualified() {
-    this.update({ status: 'qualified' })
-  }
-}
-```
-
-## Repository
-
-```typescript
-import { singleton } from '@wabot-dev/framework'
-import { Pool } from 'pg'
-import { PgCrudRepository } from '@wabot-dev/framework'
-
-@singleton()
-export class LeadRepository extends PgCrudRepository<Lead> {
-  constructor(pool: Pool) {
-    super(pool, {
-      table: 'leads',
-      constructor: Lead,
-    })
-  }
-}
-```
-
-## Service using the repository
-
-```typescript
-import { injectable } from '@wabot-dev/framework'
-
-@injectable()
-export class LeadService {
-  constructor(
-    private leads: LeadRepository,
-    private locker: Locker,
-    private logger: Logger,
-  ) {}
-
-  async qualify(id: string) {
-    return await this.locker.withKey(`lead:${id}`).run(async () => {
-      const lead = await this.leads.findOrThrow(id)
-      lead.setQualified()
-      this.logger.info('lead qualified', { id })
-      await this.leads.update(lead)
-      return lead
-    })
-  }
-}
-```
-
-## Lock key
-
-Entities already provide a `lockerKey()` implementation through `Entity`, so they can be used with the lock system.
-
-```typescript
-await locker.withKey(lead).run(async () => {
-  await leadService.qualify(lead.id)
-})
-```
-
-## Rule of thumb
-
-- Keep persistence logic in repositories.
-- Keep domain rules in entities or services.
-- Let services orchestrate repository calls.

package/skills/wabot-framework/references/quickstart.md

@@ -1,56 +0,0 @@
-# Quickstart
-
-Use this when starting a new Wabot app or explaining how the app boots.
-
-## Minimal bootstrap
-
-```typescript
-import {
-  ChatAdapter,
-  ChatRepository,
-  container,
-  Env,
-  PgChatRepository,
-  runChatControllers,
-  WabotChatAdapter,
-} from '@wabot-dev/framework'
-import { Pool } from 'pg'
-
-import { MyChatController } from './controllers/MyChatController'
-
-const env = container.resolve(Env)
-
-container.registerInstance(
-  Pool,
-  new Pool({ connectionString: env.requireString('DATABASE_URL') }),
-)
-container.registerType(ChatAdapter, WabotChatAdapter)
-container.registerType(ChatRepository, PgChatRepository)
-
-runChatControllers([MyChatController])
-```
-
-## Starter flow
-
-1. Create the app scaffold.
-2. Add the database connection.
-3. Register the chat adapter and chat repository.
-4. Run the chat controller.
-
-## Typical files
-
-```text
-src/
-  run.ts
-  controllers/MyChatController.ts
-  mindsets/MyMindset.ts
-```
-
-## First commands
-
-```bash
-npx @wabot-dev/create
-npm install
-npm run dev
-```
-

package/skills/wabot-framework/references/validation-and-data.md

@@ -1,88 +0,0 @@
-# Validation And Data
-
-Use this when shaping DTOs or mapping raw data into typed objects.
-
-## Common validators
-
-```typescript
-import {
-  isArray,
-  isBoolean,
-  isDate,
-  isIn,
-  isModel,
-  isNotEmpty,
-  isNumber,
-  isOptional,
-  isPresent,
-  isRecord,
-  isString,
-  max,
-  min,
-} from '@wabot-dev/framework'
-
-export class AddressDto {
-  @isString()
-  @isNotEmpty()
-  street!: string
-}
-
-export class CreateLeadDto {
-  @isString()
-  @isPresent()
-  @isNotEmpty()
-  name!: string
-
-  @isNumber()
-  @min(1)
-  @max(1000)
-  budget!: number
-
-  @isBoolean()
-  isQualified!: boolean
-
-  @isDate()
-  followUpAt?: Date
-
-  @isString()
-  @isIn(['new', 'qualified', 'won', 'lost'])
-  status!: string
-
-  @isArray({ minLength: 1 })
-  @isString()
-  tags!: string[]
-
-  @isModel(AddressDto)
-  address?: AddressDto
-
-  @isRecord('string', 'string')
-  metadata?: Record<string, string>
-
-  @isString()
-  @isOptional()
-  source?: string
-}
-```
-
-## Mapper
-
-```typescript
-import { injectable, Mapper } from '@wabot-dev/framework'
-
-@injectable()
-export class LeadService {
-  constructor(private mapper: Mapper) {}
-
-  create(raw: unknown) {
-    const lead = this.mapper.map(raw, CreateLeadDto)
-    return lead
-  }
-}
-```
-
-## Practical rule
-
-- Use validation decorators on the DTO itself.
-- Use `Mapper` when the input is raw, unknown, or nested.
-- Keep transformation and validation together before the service work starts.
-