@pikku/cli 0.12.91 → 0.12.92

package/skills/pikku-concepts/references/concept-mapping.md

@@ -1,556 +0,0 @@
-# Concept Mapping: Generic Backend → Pikku
-
-Authoritative mapping table plus side-by-side code examples showing how common backend patterns translate to Pikku.
-
-## Quick Reference Table
-
-| Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |
-| --------------------------------------- | --------------------------------------------------------------- | ----------------- |
-| **Controller / Route Handler**          | `pikkuFunc` / `pikkuSessionlessFunc`                            | `pikku-concepts`  |
-| **Route definition** (`GET /users/:id`) | `wireHTTP({ route, method, func })`                             | `pikku-http`      |
-| **Middleware** (Express/Koa-style)      | `pikkuMiddleware`                                               | `pikku-security`  |
-| **Auth Guard / Auth Middleware**        | `authBearer()` / `authCookie()` / `authApiKey()`                | `pikku-security`  |
-| **Authorization / Permissions**         | `pikkuPermission` / `pikkuAuth`                                 | `pikku-security`  |
-| **DTO / Request Validation**            | Standard Schema (Zod, Valibot, ArkType)                         | `pikku-concepts`  |
-| **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
-| **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
-| **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
-| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
-| **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
-| **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
-| **Type-safe API client**                | `npx pikku all` generates clients                          | `pikku-concepts`  |
-| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
-
-## Route Handler / Controller → pikkuFunc
-
-**Traditional (generic):**
-
-```typescript
-// A controller method tied to HTTP
-class TodoController {
-  async create(req: Request, res: Response) {
-    const { title, priority } = req.body
-    const todo = await this.todoService.create(title, priority)
-    res.json({ todo })
-  }
-}
-// Route: router.post('/todos', controller.create)
-```
-
-**Pikku:**
-
-```typescript
-// Function knows nothing about HTTP.
-// input/output are Zod schemas; the data + return types are inferred from them.
-const createTodo = pikkuSessionlessFunc({
-  input: CreateTodoInput,
-  output: TodoOutput,
-  func: async ({ todoStore, logger }, { title, priority }) => {
-    const todo = todoStore.createTodo(title, priority)
-    logger.info(`Created todo: ${todo.id}`)
-    return { todo }
-  },
-})
-
-// Wiring (separate file) - grouped with defineHTTPRoutes
-export const todoRoutes = defineHTTPRoutes({
-  basePath: '/todos',
-  tags: ['todos'],
-  auth: false,
-  routes: {
-    create: { method: 'post', route: '', func: createTodo },
-    list: { method: 'get', route: '', func: listTodos },
-  },
-})
-
-// Compose into top-level API
-wireHTTPRoutes({
-  basePath: '/api',
-  routes: { todos: todoRoutes },
-})
-```
-
-**Key difference:** The function receives `{ title, priority }` as typed data - it doesn't know if it came from HTTP body, WebSocket message, or CLI args. Routes are grouped with `defineHTTPRoutes` (like a controller) and composed with `wireHTTPRoutes`.
-
----
-
-## Route Parameters → Merged into Data
-
-**Traditional:**
-
-```typescript
-// Must extract from req.params, req.query, req.body separately
-async getUser(req: Request, res: Response) {
-  const id = req.params.id           // from URL
-  const fields = req.query.fields     // from query string
-  const updates = req.body            // from body
-}
-```
-
-**Pikku:**
-
-```typescript
-// All sources merged into a single typed `data` object.
-// input/output are Zod schemas; the data + return types are inferred from them.
-const getUser = pikkuSessionlessFunc({
-  input: z.object({ id: z.string(), fields: z.string().optional() }),
-  output: UserOutput,
-  func: async (services, { id, fields }) => {
-    // id comes from route param, fields from query - function doesn't care
-    return { user: await services.db.getUser(id, fields) }
-  },
-})
-
-wireHTTP({ method: 'get', route: '/users/:id', func: getUser, auth: false })
-```
-
-Pikku merges route params + query string + body + headers into a single typed input.
-
----
-
-## Middleware → pikkuMiddleware
-
-**Traditional:**
-
-```typescript
-// Express-style middleware
-function logRequest(req: Request, res: Response, next: NextFunction) {
-  console.log(`${req.method} ${req.url}`)
-  next()
-  console.log(`Response: ${res.statusCode}`)
-}
-app.use(logRequest)
-```
-
-**Pikku:**
-
-```typescript
-const logRequest = pikkuMiddleware(async ({ logger }, wire, next) => {
-  logger.info('Request started')
-  await next()
-  logger.info('Request completed')
-})
-
-// Apply globally
-addHTTPMiddleware('*', [logRequest])
-
-// Apply by route pattern
-addHTTPMiddleware('/api/*', [logRequest])
-```
-
-**Key difference:** Pikku middleware receives services (injected), not raw req/res.
-
----
-
-## Auth Guard → Built-in Auth Middleware
-
-**Traditional:**
-
-```typescript
-// Custom auth middleware
-function authMiddleware(req, res, next) {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  if (!token) return res.status(401).json({ error: 'Unauthorized' })
-  try {
-    req.user = jwt.verify(token)
-    next()
-  } catch {
-    res.status(401).json({ error: 'Invalid token' })
-  }
-}
-```
-
-**Pikku:**
-
-```typescript
-import { authBearer } from '@pikku/core/middleware'
-
-// One line - handles token extraction, JWT verification, session population
-addHTTPMiddleware('*', [authBearer({})])
-```
-
-Other built-in options: `authCookie({ cookieName })`, `authApiKey({ header })`.
-
----
-
-## Authorization / Role Checks → pikkuPermission
-
-**Traditional:**
-
-```typescript
-// Guard or middleware that checks roles
-function requireRole(role: string) {
-  return (req, res, next) => {
-    if (req.user.role !== role)
-      return res.status(403).json({ error: 'Forbidden' })
-    next()
-  }
-}
-router.delete('/users/:id', requireRole('admin'), deleteUser)
-```
-
-**Pikku:**
-
-```typescript
-const isOwner = pikkuPermission(async ({ db }, { userId }, wire) => {
-  const { session } = wire
-  return session?.userId === userId
-})
-
-// Declare on the function definition (the only place permissions live).
-// A capability like "may delete users" is a scope, not a permission.
-export const deleteUser = pikkuFunc({
-  func: async (services, data) => {
-    /* ... */
-  },
-  scopes: ['admin:users:delete'],
-  permissions: { owner: [isOwner] },
-})
-
-// App-wide baseline every function must also pass (AND gate, narrow-only)
-addGlobalPermission([signedInUser])
-```
-
-**Permission groups:** `{ groupA: [perm1, perm2], groupB: [perm3] }` means `(perm1 AND perm2) OR perm3`.
-
-> Route-pattern (`addHTTPPermission`) and wire-level `permissions` were removed in #972 — permissions live on the function, plus the optional global gate.
-
----
-
-## DTO / Request Validation → Standard Schema
-
-**Traditional (class-validator):**
-
-```typescript
-class CreateTodoDTO {
-  @IsString()
-  @IsNotEmpty()
-  @MaxLength(200)
-  title: string
-
-  @IsOptional()
-  @IsIn(['low', 'medium', 'high'])
-  priority?: string
-}
-```
-
-**Pikku (Zod):**
-
-```typescript
-const CreateTodoInputSchema = z.object({
-  title: z.string().min(1).max(200),
-  priority: z.enum(['low', 'medium', 'high']).optional(),
-})
-
-// Schema declared on function - auto-validated before function runs
-const createTodo = pikkuSessionlessFunc({
-  input: CreateTodoInputSchema,
-  output: TodoOutputSchema,
-  func: async (services, data) => { ... },
-})
-```
-
-Also supports Valibot, ArkType, or any Standard Schema-compatible library.
-
----
-
-## Dependency Injection → Service Factories
-
-**Traditional (class-based DI):**
-
-```typescript
-@Injectable()
-class TodoService {
-  constructor(
-    @Inject('DATABASE') private db: Database,
-    private logger: Logger
-  ) {}
-
-  async create(title: string) {
-    this.logger.info('Creating todo')
-    return this.db.insert('todos', { title })
-  }
-}
-```
-
-**Pikku:**
-
-```typescript
-// Define services once at startup
-const createSingletonServices = pikkuServices(async (config) => ({
-  logger: new ConsoleLogger(),
-  db: new KyselyService(config.database),
-  todoStore: new TodoStore(),
-}))
-
-// Functions destructure what they need
-const createTodo = pikkuSessionlessFunc(
-  async ({ logger, todoStore }, { title }) => {
-    logger.info('Creating todo')
-    return { todo: todoStore.createTodo(title) }
-  }
-)
-```
-
-**Key difference:** No container, no decorators, no class hierarchy. Just a factory function returning an object.
-
-Per-request services (like scoped loggers) use `pikkuWireServices`:
-
-```typescript
-const createWireServices = pikkuWireServices(
-  async (singletonServices, wire) => ({
-    scopedLogger: new ScopedLogger(wire.session?.initial?.userId),
-  })
-)
-```
-
----
-
-## WebSocket Handlers → wireChannel
-
-**Traditional:**
-
-```typescript
-wss.on('connection', (ws) => {
-  ws.on('message', (raw) => {
-    const { type, payload } = JSON.parse(raw)
-    switch (type) {
-      case 'subscribe':
-        handleSubscribe(ws, payload)
-        break
-      case 'create':
-        handleCreate(ws, payload)
-        break
-    }
-  })
-  ws.on('close', () => handleDisconnect(ws))
-})
-```
-
-**Pikku:**
-
-```typescript
-wireChannel({
-  name: 'todos-live',
-  route: '/',
-  onConnect, // pikkuVoidFunc
-  onDisconnect, // pikkuVoidFunc
-  onMessageWiring: {
-    action: {
-      // First level of message routing
-      subscribe: { func: subscribe },
-      create: { func: createTodo },
-      auth: { func: login, auth: false },
-    },
-  },
-})
-```
-
-Functions send data back via `wire.channel.send(data)`. Structured message routing replaces manual switch/case parsing.
-
----
-
-## Job Queue Workers → wireQueueWorker
-
-**Traditional (Bull/BullMQ):**
-
-```typescript
-const queue = new Queue('reminders')
-
-// Producer
-await queue.add('send-reminder', { todoId: '123', userId: 'user1' })
-
-// Consumer
-const worker = new Worker('reminders', async (job) => {
-  const { todoId, userId } = job.data
-  await sendReminder(todoId, userId)
-})
-```
-
-**Pikku:**
-
-```typescript
-// Same pikkuFunc shape - knows nothing about queues
-const processReminder = pikkuSessionlessFunc(
-  async ({ todoStore, logger }, { todoId, userId }) => {
-    const todo = todoStore.getTodo(todoId)
-    if (todo && !todo.completed) {
-      logger.info(`Sending reminder for: ${todo.title}`)
-    }
-    return { processed: true }
-  }
-)
-
-// Wire it to a queue
-wireQueueWorker({ name: 'todo-reminders', func: processReminder })
-
-// Enqueue from other functions via queue service
-await services.queueService.addJob('todo-reminders', {
-  todoId: '123',
-  userId: 'user1',
-})
-```
-
----
-
-## Cron / Scheduled Tasks → wireScheduler
-
-**Traditional:**
-
-```typescript
-import cron from 'node-cron'
-cron.schedule('0 9 * * *', async () => {
-  const stats = await todoService.getStats()
-  console.log(`Daily: ${stats.completed}/${stats.total}`)
-})
-```
-
-**Pikku:**
-
-```typescript
-const dailySummary = pikkuVoidFunc(async ({ logger, todoStore }) => {
-  const stats = todoStore.getStats('user1')
-  logger.info(`Daily: ${stats.completed}/${stats.total}`)
-})
-
-wireScheduler({
-  name: 'dailySummary',
-  schedule: '0 9 * * *',
-  func: dailySummary,
-})
-```
-
----
-
-## Module / Feature Grouping → Tags + File Organization
-
-**Traditional (NestJS):**
-
-```typescript
-@Module({
-  imports: [DatabaseModule],
-  controllers: [TodoController],
-  providers: [TodoService],
-  exports: [TodoService],
-})
-export class TodoModule {}
-```
-
-**Pikku:**
-
-```text
-// No module system. Organize by convention:
-src/
-├── functions/
-│   └── todos.functions.ts     # All todo business logic
-├── wirings/
-│   └── todos.http.ts          # All todo HTTP routes
-└── schemas.ts                 # Shared schemas
-
-// Use tags for cross-cutting concerns:
-wireHTTP({ route: '/todos', func: listTodos, tags: ['todos', 'public'] })
-addMiddleware('todos', [loggingMiddleware])  // Applies to all 'todos'-tagged functions
-```
-
----
-
-## Error Handling → Typed Errors
-
-**Traditional:**
-
-```typescript
-if (!todo) {
-  res.status(404).json({ error: 'Todo not found' })
-  return
-}
-if (!canEdit(user, todo)) {
-  res.status(403).json({ error: 'Forbidden' })
-  return
-}
-```
-
-**Pikku:**
-
-```typescript
-import { NotFoundError, ForbiddenError } from '@pikku/core/errors'
-
-const updateTodo = pikkuFunc(async (services, { id, title }, wire) => {
-  const todo = services.todoStore.getTodo(id)
-  if (!todo) throw new NotFoundError('Todo not found')
-
-  const { session } = wire
-  if (todo.userId !== session.userId) throw new ForbiddenError()
-
-  return { todo: services.todoStore.update(id, { title }) }
-})
-```
-
-Pikku catches these errors and maps them to appropriate HTTP status codes automatically.
-
----
-
-## Session Management
-
-**Traditional:**
-
-```typescript
-// Express session
-app.use(session({ store: new RedisStore({ client: redis }), secret: 'key' }))
-
-// In handler
-req.session.userId = user.id // Set
-const userId = req.session.userId // Get
-req.session.destroy() // Clear
-```
-
-**Pikku:**
-
-```typescript
-// Session is on the wire context, managed by auth middleware
-const login = pikkuSessionlessFunc(
-  async ({ jwt }, { username, password }, wire) => {
-    const user = authenticate(username, password)
-    const token = await jwt.sign({ userId: user.id })
-    await wire.setSession({ userId: user.id, user }) // Set
-    return { token, user }
-  }
-)
-
-const getMe = pikkuFunc(async (services, data, wire) => {
-  const { session } = wire // Get
-  return { user: session.user }
-})
-
-const logout = pikkuFunc(async (services, data, wire) => {
-  await wire.clearSession() // Clear
-  return { success: true }
-})
-```
-
----
-
-## API Client Generation
-
-**Traditional:**
-
-```typescript
-// Manually written or generated via OpenAPI
-const response = await fetch('/api/todos', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ title: 'New todo' }),
-})
-const data: unknown = await response.json()
-```
-
-**Pikku (auto-generated, fully typed):**
-
-```typescript
-import { createPikkuFetchClient } from './.pikku/pikku-fetch.gen.js'
-
-const client = createPikkuFetchClient({ baseUrl: 'http://localhost:4002' })
-const result = await client.post('/todos', { title: 'New todo' })
-// result is fully typed as TodoOutput - no manual type casting
-```
-
-Generated by running `npx pikku all`. Both HTTP and WebSocket clients available.

package/skills/pikku-concepts/references/packages.md

@@ -1,29 +0,0 @@
-# Available Pikku Packages
-
-## Runtime Adapters
-
-| Package                       | Use Case                              |
-| ----------------------------- | ------------------------------------- |
-| `@pikku/express-server`       | Express standalone server             |
-| `@pikku/express-middleware`   | Express as middleware in existing app |
-| `@pikku/fastify-server`       | Fastify standalone                    |
-| `@pikku/fastify-plugin`       | Fastify plugin                        |
-| `@pikku/next`                 | Next.js API routes                    |
-| `@pikku/aws-lambda`           | AWS Lambda handlers                   |
-| `@pikku/cloudflare`           | Cloudflare Workers                    |
-| `@pikku/uws-server`           | uWebSockets.js (high perf)            |
-| `@pikku/modelcontextprotocol` | MCP server                            |
-
-## Service Packages
-
-| Package                  | Provides                                             |
-| ------------------------ | ---------------------------------------------------- |
-| `@pikku/jose`            | JWT (sign/verify) via jose library                   |
-| `@pikku/schema-ajv`      | Schema validation via AJV                            |
-| `@pikku/schema-cfworker` | Schema validation for Cloudflare                     |
-| `@pikku/pino`            | Structured logging via Pino                          |
-| `@pikku/kysely`          | Type-safe SQL via Kysely (PostgreSQL, SQLite, MySQL) |
-| `@pikku/redis`           | Redis client                                         |
-| `@pikku/queue-bullmq`    | Job queues via BullMQ                                |
-| `@pikku/queue-pg-boss`   | Job queues via PgBoss                                |
-| `@pikku/aws-services`    | AWS SDK (SQS, DynamoDB, etc.)                        |