@wabot-dev/create 0.0.2 → 0.0.4

package/lib/skills/install.mjs

@@ -0,0 +1,238 @@
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+import { getSkill, listSkillNames, listSkills } from './registry.mjs'
+
+const supportedAgents = {
+  codex: ['.codex', 'skills'],
+  claude: ['.claude', 'skills'],
+  agents: ['.agents', 'skills'],
+}
+
+export function listSupportedAgents() {
+  return Object.keys(supportedAgents)
+}
+
+export async function installSkillsInProject(projectDir, agents, skillNames) {
+  if (!projectDir) {
+    throw new Error('installSkillsInProject: projectDir is required')
+  }
+
+  const resolvedAgents = (agents && agents.length > 0 ? agents : ['claude']).map((agent) => {
+    if (!supportedAgents[agent]) {
+      throw new Error(
+        `Unsupported agent "${agent}". Supported: ${Object.keys(supportedAgents).join(', ')}`,
+      )
+    }
+    return agent
+  })
+
+  const skills =
+    skillNames && skillNames.length > 0 ? skillNames.map((name) => requireSkill(name)) : listSkills()
+
+  const installations = []
+
+  for (const agent of resolvedAgents) {
+    const baseDir = path.join(projectDir, ...supportedAgents[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: false,
+          errorOnExist: true,
+        })
+        installations.push({ agent, skill: skill.name, installDir, status: 'installed' })
+      } catch (error) {
+        if (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 }
+}
+
+function requireSkill(name) {
+  const skill = getSkill(name)
+  if (!skill) {
+    throw new Error(
+      `Unknown skill "${name}". Available skills: ${listSkillNames().join(', ')}`,
+    )
+  }
+  return skill
+}
+
+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,64 @@
+import { fileURLToPath } from 'url'
+
+function packagedSkill(name, description) {
+  return {
+    name,
+    description,
+    sourceDir: fileURLToPath(new URL(`../../skills/${name}`, import.meta.url)),
+  }
+}
+
+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',
+  ),
+}
+
+export function getSkill(skillName) {
+  return skillDefinitions[skillName] ?? null
+}
+
+export function listSkillNames() {
+  return Object.keys(skillDefinitions).sort()
+}
+
+export function listSkills() {
+  return listSkillNames().map((name) => skillDefinitions[name])
+}

package/package.json

@@ -1,19 +1,18 @@
 {
   "name": "@wabot-dev/create",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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-async/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: wabot-async
+description: Use when running background work in Wabot — fire-and-forget commands, scheduled deferred commands, cron handlers, or wrapping side-effectful methods in a DB transaction. Covers @command, @commandHandler, @cronHandler, @transaction, the Async service (runCommand, scheduleCommand, IScheduleAt), ICommandHandler / ICronHandler, and how the in-memory vs PG job/cron stores are wired by the project runner.
+---
+
+# Async commands, cron, and transactions
+
+Wabot's async layer handles three kinds of work:
+
+- **Commands** — typed messages with a registered handler. Run immediately (`runCommand`) or scheduled (`scheduleCommand`).
+- **Crons** — handlers that fire on a cron expression.
+- **Transactions** — wrap a method so all repository writes happen inside one DB transaction per registered adapter.
+
+The job store, cron job store, and transaction adapter are auto-selected by the project runner based on `DATABASE_URL` (in-memory ↔ PostgreSQL). No manual registration.
+
+## Commands
+
+A command is a plain class decorated with `@command(name)`. Fields use the standard validators from `wabot-validation`.
+
+```typescript
+import { command, isNumber, isString, min } from '@wabot-dev/framework'
+
+@command('orders.charge')
+export class ChargeOrder {
+  @isString() orderId!: string
+  @isNumber() @min(1) amountCents!: number
+}
+```
+
+The handler implements `ICommandHandler<C>` and is bound with `@commandHandler(Command)`:
+
+```typescript
+import { commandHandler, ICommandHandler, injectable } from '@wabot-dev/framework'
+import { ChargeOrder } from './ChargeOrder'
+
+@commandHandler(ChargeOrder)
+export class ChargeOrderHandler implements ICommandHandler<ChargeOrder> {
+  constructor(private payments: PaymentService) {}
+
+  async handle(cmd: ChargeOrder) {
+    await this.payments.charge(cmd.orderId, cmd.amountCents)
+  }
+}
+```
+
+Trigger it with the `Async` singleton:
+
+```typescript
+import { Async, container } from '@wabot-dev/framework'
+
+const async = container.resolve(Async)
+
+// Run as soon as a worker is free
+await async.runCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 })
+
+// Schedule for later: absolute Date or relative delay
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, { minutes: 30 })
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, new Date('2026-12-31T08:00:00Z'))
+```
+
+`IScheduleAt = Date | { seconds: number } | { minutes: number } | { hours: number } | { days: number }`.
+
+`Async.runCommand` returns a `Job` immediately (it has an `id` you can persist). The payload is validated against the command class before the job is stored — bad shapes throw `CustomError`.
+
+`@commandHandler` applies `@injectable()`. There is at most one handler per command name; registering a second throws.
+
+## Cron handlers
+
+```typescript
+import { cronHandler, ICronHandler } from '@wabot-dev/framework'
+
+@cronHandler({ name: 'daily-cleanup', cron: '0 3 * * *' })
+export class DailyCleanup implements ICronHandler {
+  constructor(private games: GameRepository) {}
+
+  async handle() {
+    // ...
+  }
+
+  // Optional. Called when handle() throws.
+  async handleError(err: any) {
+    // ...
+  }
+}
+```
+
+- `cron` accepts standard 5-field or 6-field (with seconds) cron expressions.
+- `disabled: true` turns a handler off without removing it (useful for guarded rollouts).
+- `@cronHandler` applies `@singleton()` automatically — do not stack lifecycle decorators.
+
+The runner registers these into `CronScheduler`, which persists per-cron state in `CronJobRepository` so missed runs aren't replayed on restart.
+
+## Transactions
+
+`@transaction(dbNames?)` wraps an async method so every adapter listed runs the call inside a transaction. Without arguments, all registered adapters participate (today there is one: `'pg'` when `DATABASE_URL` is Postgres).
+
+```typescript
+import { transaction } from '@wabot-dev/framework'
+
+@injectable()
+export class Checkout {
+  @transaction(['pg'])
+  async checkout(orderId: string) {
+    await this.orderRepository.update(...)
+    await this.paymentRepository.create(...)
+  }
+}
+```
+
+Behavior:
+- Repository writes performed inside the method go to the same client/connection.
+- Throwing rolls back; returning commits.
+- Nested `@transaction`-decorated calls reuse the outer transaction (no nested begin).
+- If you decorate with `@transaction(['pg'])` and the app is running without Postgres, the call still executes but no PG transaction wraps it (the in-memory adapter is a no-op).
+
+## Manual run / stop
+
+In production the runner discovers and starts everything. For testing or custom hosts:
+
+```typescript
+import { runCommandHandlers, runCronHandlers, stopCommandHandlers, stopCronHandlers } from '@wabot-dev/framework'
+
+runCommandHandlers([ChargeOrderHandler])
+runCronHandlers([DailyCleanup])
+
+// later
+stopCommandHandlers([ChargeOrderHandler])
+stopCronHandlers([DailyCleanup])
+```
+
+`testAsync` is exported for integration tests against the real job/cron schedulers — see `wabot-ts/src/feature/async/testAsync.ts` for an example.
+
+## Rules
+
+- Command classes are *data* classes. Don't put behavior on them — that belongs in the handler.
+- Don't reuse a command name for two handlers. The framework throws on boot.
+- Don't `await async.runCommand(...)` inside a request handler expecting it to finish synchronously — `runCommand` schedules the job and returns immediately. Use `async.scheduleCommand(..., { seconds: 0 })` if you want the same fire-and-forget behavior explicitly.
+- Cron expressions in seconds (6 fields) are supported but be careful: the in-memory adapter polls fast, the PG adapter polls at a lower rate.
+- Wrap multi-repository writes in `@transaction(['pg'])` rather than chaining manual `withPgTransaction` calls.

package/skills/wabot-auth/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: wabot-auth
+description: Use when adding authentication to a Wabot REST endpoint or Socket.IO namespace, issuing JWT access/refresh tokens, or protecting endpoints with API keys. Covers the chat/request-scoped Auth<D> service, @jwtGuard / @jwtHandshakeGuard, JwtConfig and the JWT_* env vars, Jwt.createToken / findRefreshTokenAuthInfo, JwtRefreshToken, and @apiKeyGuard / @apiKeyHandshakeGuard with PgApiKeyRepository / RemoteApiKeyRepository.
+---
+
+# Authentication
+
+Wabot's auth is request-scoped. A guard middleware verifies the credential, then writes the resolved auth info into the per-request/socket `Auth<D>` instance. Downstream code reads it with `auth.require()`.
+
+## `Auth<D>`
+
+```typescript
+import { Auth, injectable } from '@wabot-dev/framework'
+
+interface SessionInfo {
+  userId: string
+  role: 'admin' | 'user'
+}
+
+@injectable()
+export class OrdersService {
+  constructor(private auth: Auth<SessionInfo>) {}
+
+  list() {
+    const session = this.auth.require() // throws CustomError({ httpCode: 401 }) if not assigned
+    return this.repo.findByUserId(session.userId)
+  }
+}
+```
+
+`Auth` is `@scoped(Lifecycle.ContainerScoped)` and exists once per request, chat, or socket connection. Methods:
+
+- `assign(info)` — sets the auth info (used by guards). Throws if already assigned.
+- `override(info)` — replaces even when assigned (use cautiously).
+- `require()` — returns the info or throws 401.
+- `isAssigned()` / `wasOverrided()` / `clear()`.
+
+## JWT — REST
+
+```typescript
+import { jwtGuard, onGet, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/account')
+export class AccountController {
+  @onGet('/me')
+  @jwtGuard()
+  async me(_, auth: Auth<SessionInfo>) {
+    return auth.require()
+  }
+}
+```
+
+`@jwtGuard()` reads `Authorization: Bearer <token>`, verifies it with `JwtConfig` (env-driven, see below), and calls `auth.assign(payload)`.
+
+## JWT — Socket
+
+```typescript
+import { jwtHandshakeGuard, socketController } from '@wabot-dev/framework'
+
+@socketController('private')
+@jwtHandshakeGuard()
+export class PrivateSocketController { /* ... */ }
+```
+
+The token is read from `socket.handshake.auth.token` first, falling back to the `Authorization` header.
+
+## Issuing tokens
+
+```typescript
+import { Auth, Jwt, JwtAccessAndRefreshTokenDto, injectable, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/auth')
+export class AuthController {
+  constructor(private jwt: Jwt, private auth: Auth<SessionInfo>) {}
+
+  @onPost('/login')
+  async login(body: LoginRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.userService.verify(body)
+    this.auth.assign(session)
+    return this.jwt.createToken({ device: body.device ?? 'unknown' })
+  }
+
+  @onPost('/refresh')
+  async refresh(body: RefreshRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.jwt.findRefreshTokenAuthInfo(body.refreshToken)
+    this.auth.override(session)
+    return this.jwt.createToken()
+  }
+}
+```
+
+`Jwt.createToken(metadata?)`:
+- Reads the current `auth.require()` info.
+- Persists a `JwtRefreshToken` via `JwtRefreshTokenRepository` (the runner picks `PgJwtRefreshTokenRepository` under PG; you can register your own).
+- Returns `{ access: { token, expiration }, refresh: { token, expiration } }`.
+
+`Jwt.findRefreshTokenAuthInfo(secret)` validates the refresh secret (hash-compare + expiration + revocation) and returns the original auth payload. Throws 401 if any check fails.
+
+### Env vars
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `JWT_SECRET` | (required) | Symmetric secret or asymmetric key used for sign/verify |
+| `JWT_ALGORITHM` | `HS256` | Any `jsonwebtoken.Algorithm` |
+| `JWT_ACCESS_EXPIRATION_SECONDS` | `600` (10 min) | Access token lifetime |
+| `JWT_REFRESH_EXPIRATION_SECONDS` | `31536000` (1 yr) | Refresh token lifetime |
+
+`JwtConfig` is `@singleton()` and reads these at boot.
+
+### Refresh-token metadata
+
+`JwtRefreshToken<D>` exposes `metadata` (the arbitrary `Record<string, string>` you passed to `createToken`), `expirationTime`, `revoke()`, and `isValidToken(secret)`. The repository exposes `findByMetadata(metadata)` so you can revoke all tokens issued to a device.
+
+## API key
+
+```typescript
+import { apiKeyGuard, apiKeyHandshakeGuard, onGet, restController, socketController } from '@wabot-dev/framework'
+
+@restController('/internal')
+export class InternalController {
+  @onGet('/health')
+  @apiKeyGuard()
+  async health() { return { ok: true } }
+}
+
+@socketController('admin')
+@apiKeyHandshakeGuard()
+export class AdminSocketController { /* ... */ }
+```
+
+The guard reads the `X-Api-Key` header (REST) or `socket.handshake.auth.apiKey` (socket), validates via `ApiKeyRepository`, and assigns the lookup result to `Auth`.
+
+`ApiKeyRepository` defaults to `PgApiKeyRepository` under Postgres. A `RemoteApiKeyRepository` is also exported for delegating validation to an external service:
+
+```typescript
+import { container, ApiKeyRepository, RemoteApiKeyRepository } from '@wabot-dev/framework'
+
+container.registerType(ApiKeyRepository, RemoteApiKeyRepository)
+```
+
+Set `WABOT_API_KEY` and `WABOT_LLM_URL` to point `RemoteApiKeyRepository` at your auth service (it expects the same shape as the Wabot platform).
+
+## Rules
+
+- Always type `Auth<D>` with your session shape. `auth.require()` returns the typed value.
+- A guard runs once per request/connection. Don't reassign manually — use `override(...)` only on token refresh.
+- `@jwtGuard()` and `@apiKeyGuard()` work on REST endpoints; their `*HandshakeGuard()` variants work on socket controllers. Don't mix them up.
+- Never log `auth.require()` results — they may contain PII or token claims. Use a redacted view.
+- If you need a custom guard, implement `IMiddleware` (REST) or `IHandshakeMiddleware` (socket) and wire it with `@middleware(...)` / `@handshakeMiddlewares([...])`.