@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-rtl/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: pikku-rtl
+description: 'Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.'
+installGroups: [core]
+---
+
+# Pikku RTL (Arabic + English)
+
+This skill sits **on top of** `pikku-i18n`. That skill maps a locale to `t()`
+tokens; this one adds the second axis: a locale also has a **direction**.
+Arabic is not special-cased — it is just another locale file (`ar.json`,
+registered `satisfies typeof en`) plus the document being told it is `rtl`.
+
+## The one idea
+
+Set `dir` **once at the document root** from the active locale, then let the
+browser and Mantine mirror everything — *provided* every custom style is written
+**flow-relative** (start/end), never **physical** (left/right). Get those two
+things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
+RTL code.
+
+## Agent Operating Procedure
+
+1. **Tokens first.** Every visible string is already a `t()` token via
+   `pikku-i18n`. Arabic copy goes in `i18n/ar.json`, mirroring `en.json`'s keys,
+   registered with `satisfies typeof en` so a missing key is a compile error.
+2. **Add the direction helper** to the i18n config (one home for locale→dir):
+   ```ts
+   const RTL_LOCALES = new Set(['ar', 'he', 'fa', 'ur'])
+   export function localeDir(locale: string = defaultLocale): 'rtl' | 'ltr' {
+     return RTL_LOCALES.has(locale.split('-')[0]) ? 'rtl' : 'ltr'
+   }
+   ```
+   (The bundled templates already ship this helper — use it, don't reinvent it.)
+3. **Apply `dir` + `lang` at the root**, once, from the active locale — pick the
+   recipe for your framework below.
+4. **Write every layout style flow-relative.** This is the part that actually
+   makes mirroring work; see the rules. When editing existing UI to be
+   RTL-ready, the job is mostly a search-and-replace of physical properties.
+5. **Flip directional icons** (chevrons, back/forward arrows) — the one thing
+   logical properties can't do for you.
+6. Validate with the app's `tsc`, then load `?i18n-debug` / set `dir` and
+   eyeball that the layout mirrors and nothing is stuck on the wrong edge.
+
+## Flow-relative, not physical — the rules that make it mirror
+
+Use the **inline-axis logical** property; never the physical one:
+
+| Don't (physical)            | Do (flow-relative)                          |
+| --------------------------- | ------------------------------------------- |
+| `margin-left` / `marginLeft`| `margin-inline-start` / `marginInlineStart` |
+| `margin-right`              | `margin-inline-end` / `marginInlineEnd`     |
+| `padding-left/right`        | `padding-inline-start/end`                  |
+| `left: 0` / `right: 0`      | `inset-inline-start: 0` / `inset-inline-end`|
+| `text-align: left/right`    | `text-align: start / end`                   |
+| `border-top-left-radius`    | `border-start-start-radius`                 |
+| `float: left/right`         | `float: inline-start / inline-end`          |
+
+In **Mantine**, use the logical style props — they emit the logical CSS above:
+
+| Don't        | Do            |
+| ------------ | ------------- |
+| `ml` / `mr`  | `ms` / `me`   |
+| `pl` / `pr`  | `ps` / `pe`   |
+
+Mantine's own components already use logical properties internally, so once the
+direction is set they mirror automatically — you only have to be disciplined in
+**your** styles.
+
+**Leave flexbox and grid alone.** `display:flex` already follows `dir`:
+`justify-content: flex-start` resolves to the right edge under RTL on its own.
+Never "fix" RTL by swapping to `flex-direction: row-reverse` or reordering DOM —
+that double-flips and breaks the moment direction changes. The DOM order is
+logical order; let `dir` handle the visual order.
+
+## Applying direction at the root
+
+### Mantine app (e.g. environment-template)
+Mantine ships first-class RTL: wrap the tree in `DirectionProvider` and set the
+matching `dir` on `<html>`.
+
+```tsx
+import { DirectionProvider, MantineProvider } from '@mantine/core'
+import i18n, { detectLocale, localeDir } from './i18n/config'
+
+const locale = typeof window !== 'undefined'
+  ? detectLocale(window.location.pathname)
+  : 'en'
+const dir = localeDir(locale)
+
+if (typeof document !== 'undefined') {
+  document.documentElement.lang = locale
+  document.documentElement.dir = dir   // Mantine + browser read this
+}
+
+root.render(
+  <DirectionProvider initialDirection={dir}>
+    <MantineProvider theme={theme} defaultColorScheme="dark">
+      {/* …app… */}
+    </MantineProvider>
+  </DirectionProvider>,
+)
+```
+To flip direction live (a language switcher) call
+`document.documentElement.setAttribute('dir', localeDir(next))` and Mantine's
+`useDirection().setDirection(dir)`; both read the same value.
+
+### Plain Vite SPA (kanban, test-harness vite-spa)
+No Mantine — just put `dir`/`lang` on `<html>` at bootstrap, after the locale is
+detected (the same `detectLocale` the i18n config uses):
+
+```ts
+import { detectLocale, localeDir } from './i18n/config'
+
+const locale = detectLocale(window.location.pathname)
+document.documentElement.lang = locale
+document.documentElement.dir = localeDir(locale)
+```
+Everything below inherits `dir` from `<html>`; logical CSS does the mirroring.
+
+### Vite SSR (test-harness vite-ssr)
+The worker renders the full HTML, so set `lang`/`dir` on the server `<html>`
+from the **URL** locale (the client inherits it on hydration — no flash):
+
+```tsx
+import { detectLocale, localeDir } from './i18n/config'
+
+const locale = detectLocale(new URL(request.url).pathname)
+const dir = localeDir(locale)
+const html = `<!doctype html>
+<html lang="${locale}" dir="${dir}">
+  …
+</html>`
+```
+i18next's active language must match: call `i18n.changeLanguage(locale)` before
+`renderToString` so the SSR'd text and `dir` agree.
+
+### Next.js app-router (test-harness next-ssr / next-static)
+Set it on the `<html>` in `app/layout.tsx`. With locale-prefixed routes the
+segment gives the locale; for a single-locale build it's a constant:
+
+```tsx
+import { localeDir, defaultLocale } from './i18n/config'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const locale = defaultLocale // or the [lang] route segment / params
+  return (
+    <html lang={locale} dir={localeDir(locale)}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+For `output: 'export'` with `/ar` prefixes, derive `locale` from the route
+segment so each statically-exported tree carries the right `dir`.
+
+## Directional icons — the manual bit
+
+Logical properties mirror box layout, **not glyphs**. An icon that points
+somewhere (chevron, back/next arrow, send, undo) must flip under RTL; a
+non-directional icon (search, settings, avatar) must **not**. Flip with the
+`:dir()` selector — no JS, no per-locale branching:
+
+```css
+:dir(rtl) .icon-directional { transform: scaleX(-1); }
+```
+Or in CSS-in-JS / inline, gate on the resolved direction:
+`transform: localeDir(locale) === 'rtl' ? 'scaleX(-1)' : undefined`.
+Prefer logical icon components if your icon set ships them.
+
+## Arabic typography niceties
+
+- **Font:** the default Latin stack renders Arabic with the system fallback,
+  which is inconsistent. Add an Arabic-capable family (e.g. *Noto Sans Arabic*,
+  *IBM Plex Sans Arabic*) to `font-family` so both scripts look intentional.
+- **Numerals:** don't hardcode digits. Format numbers/dates with
+  `Intl.NumberFormat`/`Intl.DateTimeFormat` (or i18next formatters) given the
+  active locale, so Western vs Arabic-Indic digits follow the locale choice.
+- **Line height:** Arabic diacritics sit tall — a slightly larger `line-height`
+  on Arabic body text avoids clipping. Keep it locale-scoped, not global.
+
+## Adding Arabic to an existing app — checklist
+
+1. `i18n/ar.json` mirroring `en.json`; register
+   `ar: { translation: ar satisfies typeof en }` and add `'ar'` to
+   `supportedLocales`. (Type-complete or it won't compile — the deploy blocks.)
+2. Confirm the `localeDir` helper includes `ar` (it does by default).
+3. Confirm the root sets `dir` from the locale (recipe above).
+4. Sweep the app's styles: replace every `left/right`, `ml/mr`, `text-align:
+   left` with the flow-relative equivalent; revert any manual `row-reverse`.
+5. Flip directional icons.
+6. `tsc`, then load the Arabic route and verify the whole layout mirrors —
+   sidebar on the right, text right-aligned, arrows pointing the other way.
+
+## What NOT to do
+
+- Don't use physical `left`/`right` (or `ml`/`mr`) in any new layout style — even
+  in an English-only app. Writing logical from the start is the seam Arabic
+  slots into, exactly like tokens are for copy.
+- Don't fake RTL with `flex-direction: row-reverse`, reversed DOM order, or
+  per-locale `if (rtl)` layout branches. Set `dir` once; let layout follow.
+- Don't set `dir` on individual components — it belongs on `<html>` so the whole
+  document (and Mantine) agrees.
+- Don't translate Arabic copy outside the `t()` token system; an RTL language is
+  a normal locale, governed by `pikku-i18n`.

package/skills/pikku-schedule/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pikku-schedule
+description: 'Use when setting up in-memory cron scheduling in a Pikku app. Covers InMemorySchedulerService for running scheduled tasks.
+TRIGGER when: code uses InMemorySchedulerService, PikkuTaskScheduler, or user asks about in-memory scheduling, cron jobs without external dependencies, or @pikku/schedule.
+DO NOT TRIGGER when: user asks about cron wiring (use pikku-cron) or queue-based scheduling with BullMQ/PgBoss (use pikku-queue).'
+installGroups: [core]
+---
+
+# Pikku Schedule (In-Memory Scheduler)
+
+## 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/schedule` provides an in-memory cron scheduler for running Pikku scheduled functions without external dependencies like Redis or PostgreSQL.
+
+## Installation
+
+```bash
+yarn add @pikku/schedule
+```
+
+## API Reference
+
+### `InMemorySchedulerService`
+
+```typescript
+import { InMemorySchedulerService } from '@pikku/schedule'
+
+const scheduler = new InMemorySchedulerService()
+```
+
+Implements the scheduler service interface. Schedules are held in memory — they do not survive process restarts. Suitable for development and single-instance deployments.
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { InMemorySchedulerService } from '@pikku/schedule'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const scheduler = new InMemorySchedulerService()
+  return { config, scheduler }
+})
+```
+
+For distributed or persistent scheduling, use BullMQ (`BullSchedulerService`) or PgBoss (`PgBossSchedulerService`) from the queue packages instead. See `pikku-queue` for details.

package/skills/pikku-schema-ajv/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pikku-schema-ajv
+description: 'Use when setting up JSON schema validation with AJV in a Pikku app. Covers AjvSchemaService for request/response validation.
+TRIGGER when: code uses AjvSchemaService, user asks about AJV, JSON schema validation, or @pikku/schema-ajv.
+DO NOT TRIGGER when: user asks about Cloudflare Workers schema validation (use pikku-schema-cfworker).'
+installGroups: [core]
+---
+
+# Pikku Schema AJV (JSON Schema Validation)
+
+## 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/schema-ajv` provides JSON schema validation using [AJV](https://ajv.js.org/). Implements the `SchemaService` interface from `@pikku/core`. This is the default schema validator for Node.js environments.
+
+## Installation
+
+```bash
+yarn add @pikku/schema-ajv
+```
+
+## API Reference
+
+### `AjvSchemaService`
+
+```typescript
+import { AjvSchemaService } from '@pikku/schema-ajv'
+
+const schema = new AjvSchemaService(logger: Logger)
+```
+
+**Methods:**
+
+- `compileSchema(schema: string, value: any): void` — Compile and register a JSON schema
+- `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
+- `getSchemaNames(): Set<string>` — Get all registered schema names
+- `getSchemaKeys(schemaName: string): string[]` — Get property keys for a schema
+
+## Usage Patterns
+
+### With Pikku Services
+
+```typescript
+import { AjvSchemaService } from '@pikku/schema-ajv'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const schema = new AjvSchemaService(logger)
+  return { config, logger, schema }
+})
+```
+
+Pikku automatically uses the schema service to validate function inputs and outputs when schemas are defined in your function definitions.

package/skills/pikku-schema-cfworker/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pikku-schema-cfworker
+description: 'Use when setting up JSON schema validation for Cloudflare Workers in a Pikku app. Covers CFWorkerSchemaService as a lightweight alternative to AJV.
+TRIGGER when: code uses CFWorkerSchemaService, user asks about schema validation on Cloudflare Workers, or @pikku/schema-cfworker.
+DO NOT TRIGGER when: user asks about AJV schema validation (use pikku-schema-ajv).'
+installGroups: [core, fabric]
+---
+
+# Pikku Schema CFWorker (Cloudflare Workers Validation)
+
+## 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/schema-cfworker` provides JSON schema validation using [@cfworker/json-schema](https://github.com/cfworker/cfworker), a lightweight validator compatible with Cloudflare Workers (no `eval` or `new Function`). Implements the `SchemaService` interface from `@pikku/core`.
+
+## Installation
+
+```bash
+yarn add @pikku/schema-cfworker
+```
+
+## API Reference
+
+### `CFWorkerSchemaService`
+
+```typescript
+import { CFWorkerSchemaService } from '@pikku/schema-cfworker'
+
+const schema = new CFWorkerSchemaService(logger: Logger)
+```
+
+**Methods:**
+
+- `compileSchema(schema: string, value: any): void` — Compile and register a JSON schema
+- `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
+- `getSchemaNames(): Set<string>` — Get all registered schema names
+- `getSchemaKeys(schemaName: string): string[]` — Get property keys for a schema
+
+## Usage Patterns
+
+### With Cloudflare Workers
+
+```typescript
+import { CFWorkerSchemaService } from '@pikku/schema-cfworker'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const schema = new CFWorkerSchemaService(logger)
+  return { config, logger, schema }
+})
+```
+
+Use this instead of `@pikku/schema-ajv` when deploying to Cloudflare Workers, as AJV uses `eval` which is not permitted in the Workers runtime.

package/skills/pikku-security/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: pikku-security
+description: 'Use when adding authentication, authorization, permissions, middleware, or security to a Pikku app. Covers pikkuAuth, pikkuPermission, pikkuMiddleware, built-in auth strategies (bearer, cookie, API key), and permission scoping.
+TRIGGER when: code uses pikkuAuth/pikkuPermission/pikkuMiddleware, user asks about auth, login, session, permissions, RBAC, middleware, or API keys.
+DO NOT TRIGGER when: user asks about JWT service setup (use pikku-services) or secrets/env vars (use pikku-config).'
+installGroups: [core]
+---
+
+# Pikku Security (Auth, Permissions, Middleware)
+
+## 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 provides a layered security model: authentication middleware (who are you?), auth checks (are you logged in?), and permissions (can you do this?). All work across every transport (HTTP, WebSocket, CLI, queue, etc.).
+
+## Before You Start
+
+```bash
+pikku info middleware --verbose    # See existing middleware and where it's applied
+pikku info permissions --verbose   # See existing permissions
+pikku info functions --verbose     # See which functions have auth/permissions
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### Session Management
+
+Functions access session via the wire object:
+
+```typescript
+// In pikkuFunc (authenticated)
+const getProfile = pikkuFunc({
+  func: async ({ db }, _data, { session }) => {
+    return await db.getUser(session.userId)
+  },
+})
+
+// Set session (e.g., after login)
+const login = pikkuFunc({
+  auth: false,
+  func: async ({ jwt, db }, { email, password }, { setSession }) => {
+    const user = await db.verifyCredentials(email, password)
+    setSession({ userId: user.id, role: user.role })
+    return { token: jwt.sign({ userId: user.id }) }
+  },
+})
+
+// Clear session (logout)
+const logout = pikkuFunc({
+  func: async ({}, _data, { clearSession }) => {
+    clearSession()
+  },
+})
+```
+
+### `pikkuAuth(fn)` — Session-Only Checks
+
+Use for authentication gates that only need the session (no request data).
+
+```typescript
+import { pikkuAuth } from '#pikku'
+
+// Receives (services, session)
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+```
+
+### `pikkuPermission(fn)` — Data-Aware Checks
+
+Use when authorization depends on the actual request data.
+
+```typescript
+import { pikkuPermission } from '#pikku'
+
+// Receives (services, data, wire)
+export const isOwner = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    const book = await db.getBook(bookId)
+    return book?.authorId === session?.userId
+  }
+)
+
+export const hasBookAccess = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    return await db.hasAccess(session?.userId, bookId)
+  }
+)
+```
+
+### Permission Groups (OR/AND Logic)
+
+```typescript
+{
+  admin: isAdmin,                          // OR: admins can access
+  owner: isOwner,                          // OR: owners can access
+  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
+}
+// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
+```
+
+### `pikkuMiddleware(fn)` — Before/After Wrapping
+
+```typescript
+import { pikkuMiddleware } from '#pikku'
+
+const logRequest = pikkuMiddleware(async ({ logger }, wire, next) => {
+  logger.info('Before')
+  await next()
+  logger.info('After')
+})
+```
+
+### Built-in Auth Middleware
+
+```typescript
+import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
+
+// JWT bearer token — reads Authorization header
+addHTTPMiddleware([authBearer()])
+
+// Cookie-based sessions — auto-refreshes JWT
+addHTTPMiddleware([
+  authCookie({
+    name: 'session',
+    expiresIn: { value: 30, unit: 'day' },
+    options: { httpOnly: true, secure: true },
+  }),
+])
+
+// API key — from x-api-key header or ?apiKey= query
+addHTTPMiddleware([authAPIKey({ source: 'all' })])
+```
+
+### Scoping: Where to Apply
+
+Four levels of scoping, from broadest to narrowest:
+
+```typescript
+// 1. Global: all HTTP routes
+addHTTPMiddleware('*', [authBearer()])
+
+// 2. Prefix-based: URL pattern
+addHTTPMiddleware('/admin/*', [auditLog])
+addHTTPPermission('/admin/*', { admin: requireAdmin })
+
+// 3. Tag-based: any wiring with matching tag
+addMiddleware('api', [rateLimiter])
+addPermission('api', { auth: requireAuth })
+
+// 4. Inline: per-wiring
+wireHTTP({
+  route: '/books/:id',
+  func: getBook,
+  middleware: [cacheControl],
+  permissions: { owner: requireOwnership },
+})
+```
+
+### Per-Function Permissions
+
+```typescript
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+  },
+  permissions: {
+    admin: isAdmin,
+    owner: isOwner,
+    reviewer: [isAuthenticated, hasBookAccess],
+  },
+})
+```
+
+## Complete Example
+
+```typescript
+// permissions.ts
+import { pikkuAuth, pikkuPermission } from '#pikku'
+
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+
+export const isBookOwner = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    const book = await db.getBook(bookId)
+    return book?.authorId === session?.userId
+  }
+)
+
+// middleware.ts
+import { pikkuMiddleware } from '#pikku'
+
+export const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
+  const start = Date.now()
+  await next()
+  await db.createAuditLog({
+    duration: Date.now() - start,
+  })
+})
+
+// wirings/security.wiring.ts
+import { authBearer } from '@pikku/core/middleware'
+import { addHTTPMiddleware, addHTTPPermission } from '#pikku'
+
+// All routes require bearer auth
+addHTTPMiddleware('*', [authBearer()])
+
+// Admin routes need admin permission + audit logging
+addHTTPMiddleware('/admin/*', [auditLog])
+addHTTPPermission('/admin/*', { admin: isAdmin })
+
+// functions/books.functions.ts
+export const deleteBook = pikkuFunc({
+  title: 'Delete Book',
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+    return { deleted: true }
+  },
+  permissions: {
+    admin: isAdmin,
+    owner: isBookOwner,
+  },
+})
+```