@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-feature/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: pikku-feature
+description: 'Drive create-a-feature work for a Pikku project: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "build a todo app", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, or asks about Pikku concepts (use pikku-concepts).'
+installGroups: [core]
+allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
+argument-hint: '<feature description>'
+---
+
+# Pikku Create-a-Feature
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+End-to-end flow: **discover → state intent → branch → implement → verify → commit → hand to reviewer**.
+
+There is **no plan JSON**. The branch + diff IS the contract. The reviewer
+sees real, compiled, working code. Apply = merge. Reject = `git branch -D`.
+
+## Stage 1 — Discover
+
+Run **once** at the start of every feature request:
+
+```bash
+yarn pikku meta context --json
+```
+
+This single call returns functions, wires, middleware, permissions, workflows,
+`capabilities` (which wire types are in use), and `layout` (where new files
+should land).
+
+Only fall back to targeted commands when you need full input/output JSON
+schemas (`yarn pikku meta functions get <id>`) or workflow steps
+(`yarn pikku meta workflows get <id>`).
+
+**Capability rule:** do not introduce new wires of a type whose
+`capabilities.<type>` is `false` unless the user explicitly asked for it.
+
+## Stage 2 — State intent in plain English (BEFORE writing code)
+
+Before touching any files, give the user one paragraph stating exactly what
+you'll do. This is the lightweight "plan" — it is chat, not JSON.
+
+> I'll add a `todos` table via a new migration in `sql/`, and two
+> `pikkuSessionlessFunc`s (`createTodo`, `listTodos` with
+> `readonly: true`) in `packages/functions/src/functions/`. Both
+> `expose: true`, so they'll be reachable via the auto-generated RPC
+> client and React Query hooks — no HTTP wiring needed. No new
+> dependencies. OK to proceed?
+
+Wait for the user to confirm or redirect. They can ask for changes ("use the
+existing tasks table" / "make it a queue not http") in normal chat — no
+schema, no JSON, no ceremony.
+
+**Non-interactive runs (auto mode, CI, batch jobs):** state intent in one
+paragraph and proceed without waiting. Surface course corrections promptly
+in the post-implementation report.
+
+## Stage 3 — Branch off
+
+After confirmation, ensure the working tree is clean and create a feature
+branch off the current default branch (whatever `git branch --show-current`
+returns at the start — `main`, `master`, `develop`, all fine):
+
+```bash
+git status
+git switch -c feature/<short-slug>
+```
+
+If the working tree is dirty, **stop and ask** — never stash silently or
+overwrite uncommitted work.
+
+## Stage 4 — Implement
+
+Write the code as a normal human contributor would. Use the project's
+existing conventions (look at neighbour files in `srcDirectories[0]/functions/`
+and `.../wirings/` for style).
+
+### RPC is the default transport
+
+**Just write the function with `expose: true`** — that's enough to make it
+callable. Pikku auto-generates an RPC client (and React Query hooks if the
+project's `clientFiles.reactQueryFile` is set) from every exposed function.
+You do **not** need an HTTP wiring for callers to reach the function.
+
+Default flow for a feature:
+
+1. Write the function file with `expose: true` (and `readonly: true` for
+   reads).
+2. Run `pikku all` — RPC map, fetch client, and React Query hooks are
+   regenerated. Frontends call `useListTodos()` / `mutation.mutate(...)`
+   without you wiring anything.
+
+Add an HTTP wiring **only when** the feature genuinely needs a specific
+REST shape (third-party callers, webhooks, REST-conventional URLs). Most
+in-app features don't.
+
+### Hard rules that always apply
+
+- **`expose: true`** for any function called from a frontend or another
+  service. Without it the RPC client won't generate hooks for it.
+- **`readonly: true` for queries.** Mark read functions as `readonly: true`
+  on the function config. The runner uses this to enforce read-only sessions
+  (a write func called under a readonly session is rejected). The RPC layer
+  also uses it to pick `useQuery` (cacheable) vs `useMutation` for client
+  hooks. Mutations leave `readonly` unset (or `false`).
+- **`kind` ⇔ `auth` coupling for HTTP wirings (when you have one).** If the
+  function is `pikkuFunc` (session-aware), the HTTP wiring needs
+  `auth: true`. `pikkuSessionlessFunc` ⇒ `auth: false`. Mismatching is a
+  hard error (PKU573).
+- **HTTP method by intent (when you wire HTTP).** Reads → `GET`. Writes →
+  `POST`/`PUT`/`PATCH`/`DELETE` per REST conventions.
+- **Workflows.** Prefer `pikkuWorkflowGraph` (DSL) over
+  `pikkuWorkflowComplexFunc`. `mode: 'inline'` is sync; `'distributed'` is
+  queue-dispatched.
+- **Auth checks belong on the function or wiring**, not in function bodies.
+  Use the `permissions` field with a `pikkuPermission` factory.
+- **Throw typed errors** from `@pikku/core/errors` — `NotFoundError`,
+  `ConflictError`, `BadRequestError`. Never bare `Error`.
+- **Migrations are inline SQL files** in the project's migrations dir
+  (typically `sql/`). Use a numbered prefix matching existing files.
+- **Secrets and env-vars: NEVER `process.env`.** Declare them with
+  `wireSecret` (sensitive) or `wireVariable` (non-sensitive) — both with a
+  zod schema for type-safe access. Read with
+  `services.secrets.getSecretJSON('NAME')` or `services.variables.get('NAME')`.
+  See the **pikku-config** skill for the full pattern (including
+  OAuth2 credentials). This applies even in `config.ts` and singleton
+  service factories.
+
+### Conventions to copy from neighbours
+
+Some patterns vary by project; **read a neighbour file before writing**:
+
+- **Function shape**: zod schemas as exported `const`s (`CreateTodoInput`,
+  `CreateTodoOutput`) passed to `input`/`output` on the func config — vs
+  generic-typed config. Schema name **must match codegen expectations** (the
+  exported const name = the schema name in generated `.gen.json`).
+- **Imports**: usually `'#pikku'` for `pikkuFunc` / `pikkuSessionlessFunc`
+  etc. Copy what neighbours do.
+- **Service usage**: e.g. `kysely`, `redis`. Look at how an existing function
+  destructures services from its first arg. **Check `application-types.d.ts`**
+  to see whether services like `kysely` are typed (`Kysely<DB>`) or untyped
+  (`Kysely<any>`) — that drives whether you can lean on generated DB types
+  or have to coerce manually.
+- **DB schema namespace**: many projects put tables under a `CREATE SCHEMA`
+  (e.g. `app.todos`). Read the first migration in `sql/` to see the
+  convention; reuse helper functions/triggers (e.g. `update_last_updated_at`)
+  rather than redefining them.
+- **HTTP wiring style** (only relevant if you're adding one). Two common
+  shapes — match what the project already uses:
+  - Per-route `wireHTTP({ method, route, func, auth })`.
+  - Single map: `const routes = defineHTTPRoutes({ auth: false, routes: {
+fooName: { method: 'post', route: '/foo', func: fooFunc } }}); wireHTTPRoutes(routes)`.
+
+For shared wiring files (e.g. `todos.http.ts` holding both create and list):
+create the file with imports if it doesn't exist; **append** wire calls and
+add missing imports if it does.
+
+## Stage 5 — Verify
+
+Both must complete cleanly **for your changes** before committing:
+
+```bash
+yarn pikku all
+# Type-check the workspaces you touched:
+cd packages/functions && npx tsc --noEmit
+```
+
+Notes on running `tsc`:
+
+- A root-level `yarn tsc` may be a no-op in monorepos that don't define a
+  `tsc` script in each workspace. Don't trust an exit-zero from the root if
+  no actual checking happened — verify by running `npx tsc --noEmit` in the
+  package(s) you touched.
+
+### What "fails" means
+
+**Trust the exit code, not the stderr noise.** `yarn pikku all` may print
+warnings, `[PKUxxx]` messages, even `level: critical` log lines, while
+still exiting `0` — those are pre-existing project state, not your
+problem. Same for `meta context --json`: it streams logs to stderr that
+look scary on a clean baseline. The exit code is the source of truth.
+
+If a command exits non-zero, that's a real failure — fix or stop.
+
+### Baseline noise — only your errors matter
+
+Many real-world projects ship with pre-existing warnings or errors
+(legacy types, version drift, gen-layer messages). Those are not your
+problem; do not "fix" them.
+
+To distinguish your errors from baseline:
+
+1. **Before implementing** (Stage 4), capture the baseline:
+   ```bash
+   yarn pikku all 2>&1 | tee /tmp/pikku-before.log
+   ```
+2. **After implementing**, compare:
+   ```bash
+   yarn pikku all 2>&1 | tee /tmp/pikku-after.log
+   diff /tmp/pikku-before.log /tmp/pikku-after.log
+   ```
+
+A clean diff means your changes introduced no new issues — even if the
+underlying logs both show pre-existing warnings.
+
+If something genuinely failed because of YOUR change, fix the actual issue.
+**Do not** mask errors with `as any`, `@ts-ignore`, or `--no-verify`. If
+you're stuck, surface the failure to the user — don't hand them a broken
+branch.
+
+## Stage 6 — Commit
+
+```bash
+git add -A
+git commit -m "feat: <short title>"
+```
+
+## Stage 7 — Hand off
+
+Tell the user the branch name and how to review. Two options:
+
+- **Local review:** open the pikku console — the changes view diffs the
+  current branch against `main` with pikku-aware structure (added functions,
+  new wires, migrations).
+- **PR review:** ask before pushing. Once they confirm, `git push -u origin
+feature/<slug>` and surface the PR-create URL.
+
+Do not push without explicit confirmation. Do not merge.
+
+## Hard constraints
+
+The skill's `allowed-tools` does **not** permit:
+
+- `yarn add` / `npm install` / dependency changes (ask the user first)
+- `yarn dbmigrate` (never run migrations against the real DB during planning)
+- `pikku deploy apply` (never deploy)
+- secret writes
+- network calls beyond what the implementation requires
+
+If the feature genuinely needs any of these, **stop and ask** with a clear
+explanation of why and what would change.
+
+## Output discipline
+
+- Stage 2 (intent statement) is plain English, one paragraph.
+- Between stages, give one-line updates: "Discovered 30 functions, http+queue
+  in use. Drafting intent..." → "Branch `feature/todos` created, implementing..."
+  → "`pikku all` clean, `tsc` clean, committed. Review via console or run
+  `git diff main`."
+- Don't narrate file-by-file. Only surface what's interesting (new patterns,
+  judgment calls, things you suppressed).

package/skills/pikku-gateway-slack/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: pikku-gateway-slack
+description: 'Use when integrating Slack with a Pikku app. Covers SlackGatewayAdapter, slash commands, OAuth flow, message handling, and signature verification.
+TRIGGER when: code uses SlackGatewayAdapter, parseSlashCommand, buildSlackInstallUrl, or user asks about Slack integration, Slack bots, or @pikku/gateway-slack.
+DO NOT TRIGGER when: user asks about general gateway/webhook patterns (use pikku-trigger).'
+---
+
+# Pikku Gateway Slack
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+`@pikku/gateway-slack` provides a Slack Events API gateway adapter, slash command handling, OAuth installation flow, and message utilities.
+
+## Installation
+
+```bash
+yarn add @pikku/gateway-slack @slack/web-api
+```
+
+## API Reference
+
+### `SlackGatewayAdapter`
+
+```typescript
+import { SlackGatewayAdapter } from '@pikku/gateway-slack'
+
+const adapter = new SlackGatewayAdapter(options: SlackGatewayAdapterOptions)
+```
+
+Bridges Slack Events API webhooks with Pikku's gateway system for processing Slack events as Pikku functions.
+
+### `SlackGatewayHelper`
+
+Helper for handling Slack messages and metadata within gateway functions.
+
+### Slash Commands
+
+```typescript
+import { parseSlashCommand, respondToSlashCommand } from '@pikku/gateway-slack'
+
+const command = parseSlashCommand(request)
+await respondToSlashCommand(responseUrl, { text: 'Done!' })
+```
+
+### OAuth Flow
+
+```typescript
+import {
+  buildSlackInstallUrl,
+  exchangeSlackOAuthCode,
+  RECOMMENDED_BOT_SCOPES,
+} from '@pikku/gateway-slack'
+
+const installUrl = buildSlackInstallUrl({
+  clientId: config.slackClientId,
+  scopes: RECOMMENDED_BOT_SCOPES,
+  redirectUri: config.slackRedirectUri,
+})
+
+const tokens = await exchangeSlackOAuthCode({
+  clientId: config.slackClientId,
+  clientSecret: config.slackClientSecret,
+  code: oauthCode,
+  redirectUri: config.slackRedirectUri,
+})
+```
+
+### Signature Verification
+
+```typescript
+import { verifySlackSignature } from '@pikku/gateway-slack'
+
+verifySlackSignature(signingSecret, timestamp, body, signature)
+```
+
+## Usage Patterns
+
+### Slack Bot Gateway
+
+```typescript
+import { SlackGatewayAdapter } from '@pikku/gateway-slack'
+
+const slackGateway = new SlackGatewayAdapter({
+  signingSecret: config.slackSigningSecret,
+  botToken: config.slackBotToken,
+})
+
+// Register with your HTTP runner to handle /slack/events endpoint
+```
+
+### Slash Command Handler
+
+```typescript
+const handleSlashCommand = pikkuSessionlessFunc({
+  title: 'Handle Slack Command',
+  func: async ({ db }, data) => {
+    const command = parseSlashCommand(data)
+    // Process command...
+    await respondToSlashCommand(command.response_url, {
+      text: `Processed: ${command.text}`,
+    })
+  },
+})
+```

package/skills/pikku-http/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: pikku-http
+description: 'Use when adding HTTP routes, REST APIs, web endpoints, or SSE streams to a Pikku app. Covers wireHTTP, defineHTTPRoutes, route groups, auth, middleware, permissions, SSE, and generated fetch client.
+TRIGGER when: code uses wireHTTP/defineHTTPRoutes/wireHTTPRoutes, user asks about REST endpoints, API routes, SSE, or the generated fetch client.
+DO NOT TRIGGER when: user asks about WebSocket (use pikku-websocket), queue workers (use pikku-queue), or deployment (use pikku-deploy-*).'
+installGroups: [core]
+---
+
+# Pikku HTTP Wiring
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Wire Pikku functions to HTTP endpoints. Supports single routes, composable route groups, auth, middleware, permissions, SSE, and auto-generated type-safe clients.
+
+## Before You Start
+
+Run these commands to understand the current project:
+
+```bash
+pikku info functions --verbose   # See existing functions, their types, tags, middleware
+pikku info tags --verbose        # Understand project organization and naming conventions
+pikku info middleware --verbose  # See what middleware is already applied
+```
+
+Follow existing patterns you find (naming, tag usage, file organization). See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `wireHTTP(config)`
+
+Wire a single function to an HTTP endpoint.
+
+```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)`
+
+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
+
+### `addHTTPMiddleware(pattern, middlewares)`
+
+```typescript
+addHTTPMiddleware('*', [authBearer()]) // All routes
+addHTTPMiddleware('/api/*', [rateLimit()]) // Pattern match
+```
+
+### `addHTTPPermission(pattern, permissions)`
+
+```typescript
+addHTTPPermission('/admin/*', { admin: [isAdmin] })
+```
+
+## Data Flow
+
+Pikku merges route params, query params, and request body into a single `data` object:
+
+```typescript
+// POST /books/42?format=pdf  with body { title: "New Title" }
+wireHTTP({ method: 'post', route: '/books/:bookId', func: updateBook })
+// → updateBook receives: { bookId: "42", format: "pdf", title: "New Title" }
+```
+
+## Usage Patterns
+
+### Single Route
+
+```typescript
+wireHTTP({
+  method: 'get',
+  route: '/books/:bookId',
+  func: getBook,
+})
+```
+
+### Route Groups (Recommended for CRUD)
+
+```typescript
+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 },
+  },
+})
+
+const todosRoutes = defineHTTPRoutes({
+  auth: false,
+  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,
+  },
+})
+// Results in: GET /api/v1/books, POST /api/v1/books, etc.
+```
+
+### Auth & Permissions
+
+```typescript
+// Public route (no auth)
+wireHTTP({ method: 'get', route: '/books', func: listBooks, auth: false })
+
+// Route with permission check
+wireHTTP({
+  method: 'delete',
+  route: '/books/:bookId',
+  func: deleteBook,
+  permissions: { admin: isAdmin },
+})
+
+// Pattern-based permissions
+addHTTPPermission('/admin/*', { admin: isAdmin })
+```
+
+### Middleware
+
+```typescript
+import { cors, authBearer } from '@pikku/core/middleware'
+
+// Global middleware
+addHTTPMiddleware('*', [
+  cors({ origin: 'https://app.example.com', credentials: true }),
+  authBearer(),
+])
+
+// Scoped middleware
+addHTTPMiddleware('/api/*', [rateLimit({ maxRequests: 100, windowMs: 60_000 })])
+
+// Per-route middleware
+wireHTTP({
+  method: 'delete',
+  route: '/books/:bookId',
+  func: deleteBook,
+  middleware: [auditLog],
+})
+```
+
+### SSE (Server-Sent Events)
+
+```typescript
+wireHTTP({
+  method: 'get',
+  route: '/todos',
+  func: getTodos,
+  sse: true,
+})
+
+const getTodos = pikkuFunc({
+  title: 'Get Todos',
+  func: async ({ db, channel }, {}) => {
+    const todos = await db.getTodos()
+
+    if (channel) {
+      for (const todo of todos) {
+        channel.send({ todo })
+        await sleep(100)
+      }
+      return
+    }
+
+    return { todos }
+  },
+})
+```
+
+### Generated Fetch Client
+
+After `npx pikku prebuild`, a type-safe client is generated:
+
+```typescript
+import { pikkuFetch } from '.pikku/pikku-fetch.gen.js'
+
+pikkuFetch.setServerUrl('http://localhost:4002')
+
+const books = await pikkuFetch.get('/api/v1/books', {})
+const book = await pikkuFetch.get('/api/v1/books/:bookId', { bookId: '42' })
+const created = await pikkuFetch.post('/api/v1/books', {
+  title: 'The Pikku Guide',
+  author: 'You',
+})
+
+pikkuFetch.setAuthorizationJWT(token)
+const deleted = await pikkuFetch.delete('/api/v1/books/:bookId', {
+  bookId: created.bookId,
+})
+```
+
+## Complete Example
+
+```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) }
+  },
+})
+
+export const getBook = pikkuFunc({
+  title: 'Get Book',
+  description: 'Retrieve a book by ID',
+  func: async ({ db }, { bookId }) => {
+    return 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'
+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()])
+```