@pikku/cli 0.12.54 → 0.12.56

package/skills/pikku-cli/SKILL.md

@@ -172,110 +172,24 @@ wireCLI({
 
 ### Custom Renderers
 
+A renderer receives `(services, data)` where `data` is the func's output. Set `render` on `wireCLI` as the program-wide default; set `render` on a `pikkuCLICommand` to override it for that command.
+
 ```typescript
 const todoRenderer = pikkuCLIRender<{ todo: Todo }>((_services, { todo }) => {
   console.log(`✓ Created: ${todo.text} (priority: ${todo.priority})`)
 })
 
-const todosRenderer = pikkuCLIRender<{ todos: Todo[] }>(
-  (_services, { todos }) => {
-    todos.forEach((t, i) => {
-      const check = t.completed ? '✓' : ' '
-      console.log(`  ${i + 1}. ${t.text}  ${check}`)
-    })
-  }
-)
-
-// Default renderer for program, override per-command
 wireCLI({
   program: 'todos',
-  render: jsonRenderer,
+  render: jsonRenderer, // default for all commands
   commands: {
-    add: pikkuCLICommand({
-      func: createTodo,
-      render: todoRenderer, // Overrides jsonRenderer
-    }),
+    add: pikkuCLICommand({ func: createTodo, render: todoRenderer }), // overrides jsonRenderer
   },
 })
 ```
 
-## Complete Example
-
-```typescript
-// functions/admin.functions.ts
-export const createUser = pikkuFunc({
-  title: 'Create User',
-  func: async ({ db }, { username, email, admin }) => {
-    const user = await db.createUser({
-      username,
-      email,
-      role: admin ? 'admin' : 'user',
-    })
-    return { user }
-  },
-})
-
-export const listUsers = pikkuSessionlessFunc({
-  title: 'List Users',
-  func: async ({ db }, { limit }) => {
-    return { users: await db.listUsers(limit || 50) }
-  },
-})
-
-export const deleteUser = pikkuFunc({
-  title: 'Delete User',
-  func: async ({ db }, { username }) => {
-    await db.deleteUser(username)
-    return { deleted: username }
-  },
-})
+The func's input is the positional `parameters` plus `options`, merged (e.g. `parameters: '<username> <email>'` + an `admin` option → func input `{ username, email, admin }`).
 
-// wirings/cli.wiring.ts
-const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
-  console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)
-})
-
-const usersRenderer = pikkuCLIRender<{ users: User[] }>(
-  (_services, { users }) => {
-    console.log(`Users (${users.length}):`)
-    users.forEach((u) =>
-      console.log(`  ${u.username} <${u.email}> [${u.role}]`)
-    )
-  }
-)
+## Complete Example
 
-wireCLI({
-  program: 'admin',
-  commands: {
-    user: {
-      description: 'User management',
-      subcommands: {
-        create: pikkuCLICommand({
-          parameters: '<username> <email>',
-          func: createUser,
-          render: userRenderer,
-          options: {
-            admin: {
-              description: 'Create as admin',
-              short: 'a',
-              default: false,
-            },
-          },
-        }),
-        list: pikkuCLICommand({
-          func: listUsers,
-          render: usersRenderer,
-          options: {
-            limit: { description: 'Max results', short: 'l' },
-          },
-        }),
-        delete: pikkuCLICommand({
-          parameters: '<username>',
-          func: deleteUser,
-          description: 'Delete a user',
-        }),
-      },
-    },
-  },
-})
-```
+For a full functions + renderers + nested-subcommand wiring walkthrough, see `references/complete-example.md`.

package/skills/pikku-cli/references/complete-example.md

@@ -0,0 +1,82 @@
+# Complete CLI Example
+
+End-to-end: functions + renderers + nested-subcommand wiring. Note how each func's input is the positional `parameters` plus `options`, merged (e.g. `parameters: '<username> <email>'` + option `admin` → func input `{ username, email, admin }`).
+
+```typescript
+// functions/admin.functions.ts
+export const createUser = pikkuFunc({
+  title: 'Create User',
+  func: async ({ db }, { username, email, admin }) => {
+    const user = await db.createUser({
+      username,
+      email,
+      role: admin ? 'admin' : 'user',
+    })
+    return { user }
+  },
+})
+
+export const listUsers = pikkuSessionlessFunc({
+  title: 'List Users',
+  func: async ({ db }, { limit }) => {
+    return { users: await db.listUsers(limit || 50) }
+  },
+})
+
+export const deleteUser = pikkuFunc({
+  title: 'Delete User',
+  func: async ({ db }, { username }) => {
+    await db.deleteUser(username)
+    return { deleted: username }
+  },
+})
+
+// wirings/cli.wiring.ts
+const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
+  console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)
+})
+
+const usersRenderer = pikkuCLIRender<{ users: User[] }>(
+  (_services, { users }) => {
+    console.log(`Users (${users.length}):`)
+    users.forEach((u) =>
+      console.log(`  ${u.username} <${u.email}> [${u.role}]`)
+    )
+  }
+)
+
+wireCLI({
+  program: 'admin',
+  commands: {
+    user: {
+      description: 'User management',
+      subcommands: {
+        create: pikkuCLICommand({
+          parameters: '<username> <email>',
+          func: createUser,
+          render: userRenderer,
+          options: {
+            admin: {
+              description: 'Create as admin',
+              short: 'a',
+              default: false,
+            },
+          },
+        }),
+        list: pikkuCLICommand({
+          func: listUsers,
+          render: usersRenderer,
+          options: {
+            limit: { description: 'Max results', short: 'l' },
+          },
+        }),
+        delete: pikkuCLICommand({
+          parameters: '<username>',
+          func: deleteUser,
+          description: 'Delete a user',
+        }),
+      },
+    },
+  },
+})
+```

package/skills/pikku-concepts/SKILL.md

@@ -53,42 +53,32 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-| Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |
-| --------------------------------------- | --------------------------------------------------------------- | ----------------- |
-| **Controller / Route Handler**          | `pikkuFunc` / `pikkuSessionlessFunc`                            | (this skill)      |
-| **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)                         | (this skill)      |
-| **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                                             | (this skill)      |
-| **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | (this skill)      |
-| **Type-safe API client**                | `npx pikku prebuild` generates clients                          | (this skill)      |
-| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
+Controllers/routes → `pikkuFunc`; middleware/auth/permissions → `pikku-security`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
 Three main function types:
 
 ```typescript
-// Requires authentication — receives session in wire context
-const updateTodo = pikkuFunc<UpdateInput, TodoOutput>(
-  async (services, data, wire) => {
+// Requires authentication — receives session in wire context.
+// input/output are Zod schemas; the data + return types are inferred from them.
+const updateTodo = pikkuFunc({
+  input: UpdateTodoInput,
+  output: TodoOutput,
+  func: async (services, data, wire) => {
     const session = await wire.session.get()
     return services.todoStore.update(data.id, data)
-  }
-)
+  },
+})
 
 // No authentication required
-const listTodos = pikkuSessionlessFunc<ListInput, TodoListOutput>(
-  async (services, data) => {
+const listTodos = pikkuSessionlessFunc({
+  input: ListTodosInput,
+  output: TodoListOutput,
+  func: async (services, data) => {
     return { todos: services.todoStore.list(data.filters) }
-  }
-)
+  },
+})
 
 // No input or output (for scheduled tasks, lifecycle hooks)
 const cleanup = pikkuVoidFunc(async (services) => {
@@ -96,23 +86,7 @@ const cleanup = pikkuVoidFunc(async (services) => {
 })
 ```
 
-Config object form (recommended):
-
-```typescript
-const createTodo = pikkuSessionlessFunc({
-  title: 'Create Todo',
-  description: 'Create a new todo item',
-  input: CreateTodoInputSchema,
-  output: CreateTodoOutputSchema,
-  func: async ({ logger, todoStore }, { title, priority }) => {
-    const todo = todoStore.createTodo(title, priority)
-    logger.info(`Created todo: ${todo.id}`)
-    return { todo }
-  },
-})
-```
-
-Full config options:
+Services can be destructured inline in the `func` signature (e.g. `async ({ logger, todoStore }, { title }) => ...`). Full config options:
 
 ```typescript
 pikkuFunc({
@@ -243,33 +217,7 @@ expect(result.todos).toHaveLength(3)
 
 ## Available 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.)                        |
+Pikku ships runtime adapters (`@pikku/express-server`, `@pikku/fastify-server`, `@pikku/next`, `@pikku/aws-lambda`, `@pikku/cloudflare`, `@pikku/uws-server`, `@pikku/modelcontextprotocol`, ...) and service packages (`@pikku/jose`, `@pikku/schema-ajv`, `@pikku/pino`, `@pikku/kysely`, `@pikku/redis`, `@pikku/queue-bullmq`, `@pikku/queue-pg-boss`, ...). For the full list with use cases, read `references/packages.md`.
 
 ## Key Differences from Traditional Frameworks
 

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

@@ -1,6 +1,25 @@
 # Concept Mapping: Generic Backend → Pikku
 
-Side-by-side code examples showing how common backend patterns translate to 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 prebuild` generates clients                          | `pikku-concepts`  |
+| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
 
 ## Route Handler / Controller → pikkuFunc
 
@@ -21,14 +40,17 @@ class TodoController {
 **Pikku:**
 
 ```typescript
-// Function knows nothing about HTTP
-const createTodo = pikkuSessionlessFunc<CreateTodoInput, TodoOutput>(
-  async ({ todoStore, logger }, { title, priority }) => {
+// 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({
@@ -68,13 +90,15 @@ async getUser(req: Request, res: Response) {
 **Pikku:**
 
 ```typescript
-// All sources merged into a single typed `data` object
-const getUser = pikkuSessionlessFunc<
-  { id: string; fields?: string },
-  UserOutput
->(async (services, { id, fields }) => {
-  // id comes from route param, fields from query - function doesn't care
-  return { user: await services.db.getUser(id, fields) }
+// 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 })

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

@@ -0,0 +1,29 @@
+# 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.)                        |

package/skills/pikku-http/SKILL.md

@@ -34,67 +34,14 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-### `wireHTTP(config)`
+- `wireHTTP(config)` (from `@pikku/core/http`) — wire one function to one endpoint.
+- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` (from `.pikku/pikku-types.gen.js`) — group routes with shared config; composable/nestable.
 
-Wire a single function to an HTTP endpoint.
+Function input/output types come from the function's own `input:`/`output:` zod schemas — never declared in the wiring. Route `:params`, query params, and body are merged into the function's `data` arg (see Data Flow).
 
-```typescript
-import { wireHTTP } from '@pikku/core/http'
-
-wireHTTP({
-  method: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head',
-  route: string,          // e.g. '/books/:bookId' — :params become data fields
-  func: PikkuFunc,        // The function to call
-  auth?: boolean,         // Override default auth (true = require session)
-  tags?: string[],        // For grouping, middleware targeting
-  permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
-  middleware?: PikkuMiddleware[],
-  sse?: boolean,          // Enable Server-Sent Events
-  contentType?: 'xml' | 'json',  // Response content type
-  timeout?: number,       // Request timeout in ms
-  headers?: HTTPHeadersSchema,   // Expected headers schema
-  docs?: HTTPRouteDocsConfig,    // OpenAPI docs config
-})
-```
-
-### `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
+Config cascading across groups: `basePath` concatenates down the chain, `tags` merge (union), `auth` child overrides parent.
 
-Group routes with shared configuration. Groups are composable and nestable.
-
-```typescript
-import { defineHTTPRoutes, wireHTTPRoutes } from '.pikku/pikku-types.gen.js'
-
-const routes = defineHTTPRoutes({
-  basePath?: string,       // Prepended to all route paths
-  tags?: string[],         // Applied to all routes in group
-  auth?: boolean,          // Default auth for all routes (overridable per-route)
-  middleware?: PikkuMiddleware[],
-  routes: {
-    [key: string]: {
-      method: string,
-      route: string,
-      func: PikkuFunc,
-      auth?: boolean,      // Override group auth
-      permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
-      middleware?: PikkuMiddleware[],
-    }
-  }
-})
-
-wireHTTPRoutes({
-  basePath?: string,       // Top-level prefix (e.g. '/api/v1')
-  middleware?: PikkuMiddleware[],
-  routes: {
-    [key: string]: ReturnType<typeof defineHTTPRoutes>,
-  }
-})
-```
-
-Config cascading rules:
-
-- `basePath` — concatenates down the chain
-- `tags` — merge (union)
-- `auth` — child overrides parent
+For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read `references/http-options.md`.
 
 ### `addHTTPMiddleware(pattern, middlewares)`
 
@@ -137,7 +84,7 @@ wireHTTP({
 const booksRoutes = defineHTTPRoutes({
   tags: ['books'],
   routes: {
-    list: { method: 'get', route: '/books', func: listBooks, auth: false },
+    list: { method: 'get', route: '/books', func: listBooks, auth: false }, // per-route override
     get: { method: 'get', route: '/books/:bookId', func: getBook },
     create: { method: 'post', route: '/books', func: createBook },
     delete: { method: 'delete', route: '/books/:bookId', func: deleteBook },
@@ -145,24 +92,19 @@ const booksRoutes = defineHTTPRoutes({
 })
 
 const todosRoutes = defineHTTPRoutes({
-  auth: false,
+  auth: false, // group-level default, overridable per-route
   tags: ['todos'],
   routes: {
     list: { method: 'get', route: '/todos', func: listTodos },
-    create: { method: 'post', route: '/todos', func: createTodo },
-    get: { method: 'get', route: '/todos/:id', func: getTodo },
   },
 })
 
 wireHTTPRoutes({
   basePath: '/api/v1',
   middleware: [cors()],
-  routes: {
-    books: booksRoutes,
-    todos: todosRoutes,
-  },
+  routes: { books: booksRoutes, todos: todosRoutes },
 })
-// Results in: GET /api/v1/books, POST /api/v1/books, etc.
+// Results in: GET /api/v1/books, POST /api/v1/books, GET /api/v1/todos, etc.
 ```
 
 ### Auth & Permissions
@@ -258,60 +200,27 @@ const deleted = await pikkuFetch.delete('/api/v1/books/:bookId', {
 
 ## Complete Example
 
+Functions live in their own files (one per file) and supply behavior + `permissions`; the wiring file imports them and wires routes. Sessionless funcs need no session; `pikkuFunc` does.
+
 ```typescript
 // functions/books.functions.ts
 import { pikkuFunc, pikkuSessionlessFunc } from '#pikku'
 
 export const listBooks = pikkuSessionlessFunc({
   title: 'List Books',
-  func: async ({ db }, { limit }) => {
-    return { books: await db.listBooks(limit) }
-  },
+  func: async ({ db }, { limit }) => ({ books: await db.listBooks(limit) }),
 })
 
 export const getBook = pikkuFunc({
   title: 'Get Book',
   description: 'Retrieve a book by ID',
-  func: async ({ db }, { bookId }) => {
-    return await db.getBook(bookId)
-  },
+  func: async ({ db }, { bookId }) => await db.getBook(bookId),
   permissions: { user: isAuthenticated },
 })
 
-export const createBook = pikkuFunc({
-  title: 'Create Book',
-  func: async ({ db }, { title, author }) => {
-    return await db.createBook({ title, author })
-  },
-})
-
-export const deleteBook = pikkuFunc({
-  title: 'Delete Book',
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-    return { deleted: true }
-  },
-})
-
-// wirings/books.http.ts
-import { defineHTTPRoutes, wireHTTPRoutes } from '.pikku/pikku-types.gen.js'
+// wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
 import { addHTTPMiddleware } from '@pikku/core/http'
 import { cors, authBearer } from '@pikku/core/middleware'
 
-const booksRoutes = defineHTTPRoutes({
-  tags: ['books'],
-  routes: {
-    list: { method: 'get', route: '/books', func: listBooks, auth: false },
-    get: { method: 'get', route: '/books/:bookId', func: getBook },
-    create: { method: 'post', route: '/books', func: createBook },
-    delete: { method: 'delete', route: '/books/:bookId', func: deleteBook },
-  },
-})
-
-wireHTTPRoutes({
-  basePath: '/api',
-  routes: { books: booksRoutes },
-})
-
 addHTTPMiddleware('*', [cors(), authBearer()])
 ```

package/skills/pikku-http/references/http-options.md

@@ -0,0 +1,57 @@
+# wireHTTP / defineHTTPRoutes / wireHTTPRoutes — full option reference
+
+## `wireHTTP(config)`
+
+Wire a single function to an HTTP endpoint. Import from `@pikku/core/http`.
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head'` | HTTP verb |
+| `route` | `string` | e.g. `/books/:bookId` — `:params` become `data` fields |
+| `func` | `PikkuFunc` | The function to call |
+| `auth?` | `boolean` | Override default auth (`true` = require session) |
+| `tags?` | `string[]` | For grouping, middleware targeting |
+| `permissions?` | `Record<string, PikkuPermission \| PikkuPermission[]>` | Permission checks |
+| `middleware?` | `PikkuMiddleware[]` | Per-route middleware |
+| `sse?` | `boolean` | Enable Server-Sent Events |
+| `contentType?` | `'xml' \| 'json'` | Response content type |
+| `timeout?` | `number` | Request timeout in ms |
+| `headers?` | `HTTPHeadersSchema` | Expected headers schema |
+| `docs?` | `HTTPRouteDocsConfig` | OpenAPI docs config |
+
+## `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
+
+Group routes with shared configuration. Groups are composable and nestable. Import from `.pikku/pikku-types.gen.js`.
+
+```typescript
+const routes = defineHTTPRoutes({
+  basePath?: string,       // Prepended to all route paths
+  tags?: string[],         // Applied to all routes in group
+  auth?: boolean,          // Default auth for all routes (overridable per-route)
+  middleware?: PikkuMiddleware[],
+  routes: {
+    [key: string]: {
+      method: string,
+      route: string,
+      func: PikkuFunc,
+      auth?: boolean,      // Override group auth
+      permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
+      middleware?: PikkuMiddleware[],
+    }
+  }
+})
+
+wireHTTPRoutes({
+  basePath?: string,       // Top-level prefix (e.g. '/api/v1')
+  middleware?: PikkuMiddleware[],
+  routes: {
+    [key: string]: ReturnType<typeof defineHTTPRoutes>,
+  }
+})
+```
+
+Config cascading rules:
+
+- `basePath` — concatenates down the chain
+- `tags` — merge (union)
+- `auth` — child overrides parent