@pikku/skills 0.12.21 → 0.12.25

package/skills/pikku-services/references/services.md

@@ -0,0 +1,272 @@
+# Pikku Services (Dependency Injection)
+
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See which services existing functions use
+pikku info tags --verbose        # Understand project organization
+```
+
+## API Reference
+
+### `pikkuServices(factory)` — singleton services (created once at startup)
+
+```typescript
+import { pikkuServices } from '#pikku/setup'
+import { ConsoleLogger } from '@pikku/core/services'
+import { JoseJWTService } from '@pikku/jose'
+
+export const createSingletonServices = pikkuServices(
+  async (config, existingServices?) => {
+    // config: your CoreConfig object
+    // existingServices: optional, for chaining factories
+    const logger = new ConsoleLogger()
+    const database = new DatabasePool(config.database)
+    await database.connect()
+    const jwt = new JoseJWTService(
+      async () => [{ id: 'my-key', value: config.jwtSecret }],
+      logger
+    )
+    return { config, logger, database, jwt, books: new BookService() }
+  }
+)
+```
+
+### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
+
+```typescript
+import { pikkuWireServices } from '#pikku/setup'
+
+export const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => {
+    // singletonServices: all singleton services
+    // wire: transport context (session, channel, etc.)
+    // Pikku merges these with singleton services automatically
+    return {
+      userSession: createUserSessionService(wire),
+      dbTransaction: new DatabaseTransaction(singletonServices.database),
+    }
+  }
+)
+```
+
+### `pikkuServerLifecycle(hooks)` — startup and shutdown work
+
+A service factory should **construct** services, not run startup side effects. Seeding a database, warming a cache, starting a background consumer or draining a queue belongs in lifecycle hooks, which receive the singleton services after they are built:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely) // before the port opens
+  },
+  afterStart: async (services) => {
+    await seedDevData(services) // server is accepting traffic
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain() // services are still alive here
+  },
+  afterStop: async () => {
+    await releaseExternalLock() // services are ALREADY stopped
+  },
+})
+```
+
+Every hook is optional. Order is `beforeStart` → server starts → `afterStart`, then on SIGINT `beforeStop` → services stopped → server stopped → `afterStop`.
+
+**`afterStop` runs after the singleton services have been stopped.** It still receives the services object, but the services inside it are shut down — using one there is a use-after-close bug. Anything that needs a live service goes in `beforeStop`.
+
+Export **exactly one** `pikkuServerLifecycle` from anywhere in `srcDirectories`; the inspector finds it by the wrapper call, so the filename is free (`src/lifecycle.ts` by convention). It must be an exported `const` initialized with a direct call to `pikkuServerLifecycle` — a re-export or a conditional wrapper is invisible to the inspector.
+
+**Only `pikku dev` and `pikku serve` run these hooks.** If you bootstrap your own server (Express, Fastify, uWS, Lambda, Cloudflare, Next.js), no runtime adapter invokes them — put the work in your entrypoint instead.
+
+### Auto-Generated Service Manifest
+
+After `npx pikku all`, Pikku generates `.pikku/pikku-services.gen.ts`, a manifest of which services are actually used by wired functions:
+
+```typescript
+export const requiredSingletonServices = {
+  database: true, // used by getUser, deleteUser
+  audit: true, // used by deleteUser
+  cache: false, // not used by any wired function
+  jwt: true, // used by auth middleware
+} as const
+
+export type RequiredSingletonServices = Pick<
+  SingletonServices,
+  'database' | 'audit' | 'jwt'
+> &
+  Partial<Omit<SingletonServices, 'database' | 'audit' | 'jwt'>>
+```
+
+## Usage Patterns
+
+### Using Services in Functions
+
+**Every service must be declared in `SingletonServices` (or `Services`) in `application-types.d.ts`.** Never access a service via a body-level cast (`services as typeof services & { myService: MyService }`) — that means the type is missing. Add the import and the field to `SingletonServices`, then destructure inline in the function signature. The inspector emits `SERVICES_NOT_DESTRUCTURED` (`PKU410`) and tree-shaking breaks when the first param is a plain identifier rather than an object pattern. Never `new` a service inside a function — services arrive only via injection.
+
+```typescript
+// ✅ Correct — inline destructure, no cast
+const getUser = pikkuFunc({
+  title: 'Get User',
+  func: async ({ db, logger, jwt }, { userId }) => {
+    logger.info('Fetching user', { userId })
+    return { user: await db.getUser(userId) }
+  },
+})
+
+// ❌ Wrong — named param + body cast; inspector warns + tree-shaking breaks
+const getUser = pikkuFunc({
+  func: async (services, { userId }) => {
+    const { db } = services as typeof services & { db: DbService }
+    // ...
+  },
+})
+```
+
+### Services Are Never Optional Inside a Function
+
+**Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
+
+Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means _"this may not be created"_, not _"this may be missing at call time"_. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+
+The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
+
+```typescript
+export type WiredSingletonServices = RequiredSingletonServices &
+  SingletonServices
+export type WiredServices = SecretlessServices<
+  RequiredSingletonServices & Services
+>
+```
+
+The `SecretlessServices<...>` wrapper is why `secrets` never appears in a
+function's services: it is stripped at the type level, not merely omitted by
+convention. Read secrets in a service factory or middleware and hand the value
+to a service instead.
+
+so a service that is `foo?: Foo` in `SingletonServices` arrives as a non-optional `Foo` in every function, permission and middleware that uses it. There is nothing to guard against.
+
+```typescript
+// ✅ Correct — destructure and use; creation is guaranteed by the manifest
+const listThreads = pikkuFunc({
+  func: async ({ agentRunService }, { threadId }) => {
+    return await agentRunService.getThreadMessages(threadId)
+  },
+})
+
+// ❌ Wrong — unreachable guard; signals a misunderstanding of service wiring
+const listThreads = pikkuFunc({
+  func: async ({ agentRunService }, { threadId }) => {
+    if (!agentRunService) throw new MissingServiceError('agentRunService')
+    return await agentRunService.getThreadMessages(threadId)
+  },
+})
+```
+
+If a service really is conditional at runtime (e.g. an optional integration a deployment may not configure), that is a **configuration** concern: branch on config, or fail fast at startup in `services.ts` — not per-request in every function.
+
+### Dynamic Import Optimization
+
+Use the generated manifest to conditionally import heavy dependencies — only the services actually wired get instantiated:
+
+```typescript
+import { requiredSingletonServices } from '.pikku/pikku-services.gen.js'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+
+  let jwt: JWTService | undefined
+  if (requiredSingletonServices.jwt) {
+    const { JoseJWTService } = await import('@pikku/jose')
+    jwt = new JoseJWTService(keys, logger)
+  }
+
+  let database: Database | undefined
+  if (requiredSingletonServices.database) {
+    database = await createDatabase(config.databaseUrl)
+  }
+
+  return { config, logger, jwt, database }
+})
+```
+
+### Audit Wire Service
+
+`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.
+
+### Built-in Services
+
+| Service                 | Package                | Purpose                                 |
+| ----------------------- | ---------------------- | --------------------------------------- |
+| `ConsoleLogger`         | `@pikku/core/services` | Console-based logging                   |
+| `JoseJWTService`        | `@pikku/jose`          | JWT sign/verify via jose                |
+| `LocalSecretService`    | `@pikku/core/services` | Local development secrets               |
+| `LocalVariablesService` | `@pikku/core/services` | Local environment variables             |
+| `PinoLogger`            | `@pikku/pino`          | Structured logging via Pino             |
+| `createInvocationAudit` | `@pikku/core/services` | Per-request audit buffer                |
+| `createAuditedKysely`   | `@pikku/kysely`        | Auto-capture DB queries as audit events |
+
+## Complete Example
+
+```typescript
+// services.ts
+import { pikkuServices, pikkuWireServices } from '#pikku/setup'
+import { ConsoleLogger } from '@pikku/core/services'
+import { JoseJWTService } from '@pikku/jose'
+
+// Custom service
+class TodoStore {
+  private todos: Map<string, Todo> = new Map()
+  async create(title: string, priority: string) {
+    const todo = { id: crypto.randomUUID(), title, priority, completed: false }
+    this.todos.set(todo.id, todo)
+    return todo
+  }
+  async get(id: string) {
+    return this.todos.get(id)
+  }
+  async list() {
+    return [...this.todos.values()]
+  }
+  async delete(id: string) {
+    this.todos.delete(id)
+  }
+}
+
+export const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const jwt = new JoseJWTService(
+    async () => [{ id: 'my-key', value: config.jwtSecret }],
+    logger
+  )
+  return {
+    config,
+    logger,
+    jwt,
+    secrets: new LocalSecretService(),
+    variables: new LocalVariablesService(),
+    todoStore: new TodoStore(),
+  }
+})
+
+export const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => ({
+    scopedLogger: new ScopedLogger(wire.session?.userId),
+  })
+)
+
+// functions/todos.functions.ts — services are auto-injected
+export const createTodo = pikkuFunc({
+  title: 'Create Todo',
+  func: async ({ todoStore, logger }, { title, priority }) => {
+    const todo = await todoStore.create(title, priority)
+    logger.info('Created todo', { id: todo.id })
+    return { todo }
+  },
+})
+```

package/skills/pikku-software-archaeology/README.md

@@ -74,7 +74,11 @@ pikku-software-archaeology/
 ├── README.md                         # this file
 ├── references/
 │   ├── blueprint.schema.json         # the output contract (JSON Schema)
-│   └── pikku-mapping.md              # blueprint → Pikku primitives
+│   ├── pikku-mapping.md              # blueprint → Pikku primitives
+│   ├── second-opinion.md             # blueprint → owner-facing report: method, voice, red flags
+│   └── second-opinion-report-template.md  # the layered structure to fill in
+├── example/
+│   └── second-opinion-sample-report.md    # worked example (competitor-tracking area, founder voice)
 └── scripts/
     └── validate.mjs                  # schema + cross-file validation (node, no deps)
 ```

package/skills/pikku-software-archaeology/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-software-archaeology
-description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app). TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", or points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules, or a rebuild plan. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or code review.'
+description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner who holds the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator audience. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or an engineer-facing code review.'
 ---
 
 # Software Archaeology
@@ -132,7 +132,7 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 
 **Frontend** (`frontend.json` + `frontend-routes.json` + `frontend-components.json`, optional) — the web UI, which needs its own treatment because frontends vary wildly (framework, router, styling, state, data, auth) and the rebuild target is opinionated: **everything in one component system (Mantine), one data layer, one auth**.
 
-- `frontend.json` records the stack as FACTS: framework (e.g. TanStack Start), rendering (SSR/streaming/SPA), router, styling/design system, `designSystemConsistency`, state management, data layer (e.g. pikku-react-query vs REST helpers), auth (e.g. better-auth), i18n. Name the real technologies — the second-opinion skill weighs their tradeoffs, so record them precisely (do NOT editorialize here; this file is facts).
+- `frontend.json` records the stack as FACTS: framework (e.g. TanStack Start), rendering (SSR/streaming/SPA), router, styling/design system, `designSystemConsistency`, state management, data layer (e.g. pikku-react vs REST helpers), auth (e.g. better-auth), i18n. Name the real technologies — the second-opinion skill weighs their tradeoffs, so record them precisely (do NOT editorialize here; this file is facts).
 - `frontend-routes.json` is the page tree: each route's `purpose` in product terms, `auth`, the `dataFrom` (query/command names it reads — reuse the backend concept names so the UI ties back to the domain), the `usesComponents`, and the `userFlows` it belongs to.
 - `frontend.json.designFindings` captures **broken/inconsistent design patterns** as concrete, cited observations (not taste). Actively hunt for: _interaction inconsistency_ (the same job done as a modal in one place and a drawer in another; inconsistent confirm dialogs); _theming not tokenized_ (hardcoded hex colors, magic spacing/font sizes, inline styles instead of theme tokens/variables — grep for `#[0-9a-f]{3,6}`, `style={{`, raw `px` values); _cross-page inconsistency_ (the same element — button, page header, card — styled differently across routes); _component duplication_ (three near-identical cards/tables for one purpose); _design-system bypass_ (raw HTML/CSS where a library component exists). Each finding gets an example, its impact (feels unpolished / a color change means hunting every file), and a fix (standardize on one pattern / move to tokens / extract one shared component). These are almost always cheap cleanups, and they are exactly what a non-technical owner perceives as "the app looks off" without being able to say why.
 - `frontend-components.json` is where the frontend's real migration cost lives, in the **`rebuild`** field: `mantine-standard` (maps 1:1 to a Mantine component — trivial), `mantine-composition` (built from Mantine primitives — straightforward), `custom-style` (diverges only visually — normalize to Mantine), or **`custom-logic`** (bespoke behavior — a custom chart, a virtualized/complex table, a canvas, drag-and-drop, a rich editor — that must be **ported**, not re-skinned). A `custom-logic` component MUST fill `customLogic` explaining the behavior, and should list the `dependencies` (charting/table/editor libs) that make it a real port. This split — "trivially re-Mantine-able" vs "carries logic that must survive the port" — is the single most useful thing the frontend extraction produces.
@@ -187,3 +187,16 @@ node <skill-dir>/scripts/validate.mjs <repo>/.knowledge
 
 - Schema/contract: `references/blueprint.schema.json`
 - How Pikku consumes the blueprint: `references/pikku-mapping.md`
+
+## The second phase — a report the owner can act on
+
+Extraction produces a blueprint for a machine to rebuild from. The same
+`.knowledge/` directory is also the input to a second opinion for the person who
+holds the app: what works, what is holding them back, and what you would build
+instead, argued in business outcomes rather than architecture.
+
+That phase has its own voice rules, structure and red flags — read
+`references/second-opinion.md`, fill in
+`references/second-opinion-report-template.md`, and match the tone of
+`example/second-opinion-sample-report.md`. It consumes the blueprint; it never
+re-derives facts from the code, so run the extraction first.

package/skills/{pikku-product-second-opinion/example/sample-report.md → pikku-software-archaeology/example/second-opinion-sample-report.md}

@@ -2,7 +2,7 @@
 
 _A second opinion on the competitor-tracking system_
 
-> Worked example for the pikku-product-second-opinion skill. Shows the voice and the
+> Worked example for the pikku-software-archaeology skill. Shows the voice and the
 > layered structure on one real area (competitor tracking), drawn from a
 > pikku-software-archaeology blueprint + parity report. A full report would repeat
 > Part 2 for each major area, and cover every significant technology bet — not just

package/skills/pikku-software-archaeology/references/blueprint.schema.json

@@ -961,7 +961,7 @@
         "stateManagement": { "type": "string" },
         "dataLayer": {
           "type": "string",
-          "description": "how the UI talks to the backend: e.g. pikku-react-query, REST fetch helpers, tRPC, GraphQL client"
+          "description": "how the UI talks to the backend: e.g. pikku-react hooks, REST fetch helpers, tRPC, GraphQL client"
         },
         "auth": {
           "type": "string",

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -1,6 +1,6 @@
 # How Pikku Consumes a Product Blueprint
 
-The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-feature`) walks the JSON files in this order:
+The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-build`) walks the JSON files in this order:
 
 | Blueprint source                                                            | Pikku target                                                                                                                                                                                                                                                                                                                    |
 | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -26,8 +26,8 @@ The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pi
 | `interfaces.json` kind=cli                                                  | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose                                                                                                                                                                                                                                                   |
 | `interfaces.json` kind=mcp                                                  | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates)                                                                                                                                                                                                                        |
 | `interfaces.json` kind=openapi-rest / sdk                                   | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen                                                                                                                                                                                                                    |
-| `interfaces.json` kind=websocket-realtime                                   | `pikku-realtime` EventHub topics / channels                                                                                                                                                                                                                                                                                     |
-| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
+| `interfaces.json` kind=websocket-realtime                                   | `pikku-wiring` EventHub topics / channels                                                                                                                                                                                                                                                                                     |
+| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
 | `frontend-routes.json`                                                      | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views                                                                                                                                         |
 | `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk                                                                                                                                                                                                                           |
 | `frontend-components.json` rebuild=`custom-logic`                           | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items                                                                                             |

package/skills/{pikku-product-second-opinion/SKILL.md → pikku-software-archaeology/references/second-opinion.md}

@@ -1,8 +1,3 @@
----
-name: pikku-product-second-opinion
-description: 'Use when a non-technical owner (founder, PM, operator) wants a plain-language report on an app they hold but did not build — explaining how it works and how it could be better. Reads the .knowledge/ blueprint from pikku-software-archaeology and produces a layered, jargon-free report that credits what works, names what does not (with business impact + effort), and argues an opinionated better design. TRIGGER: "explain how my app works", "what would you do differently", "review my app for a non-technical audience", "I inherited/am stuck with an agency-built app", "is this built well?". DO NOT TRIGGER for: extracting the machine-readable blueprint itself (use pikku-software-archaeology), or an engineer-facing technical code review.'
----
-
 # Product Second Opinion
 
 ## Overview
@@ -11,7 +6,7 @@ Turn an extracted product blueprint into a **report a non-technical owner can ac
 
 The reader is a founder/PM/operator, not an engineer. If they finish a section and don't know what it means for their business or what to do about it, the report failed — no matter how correct it is.
 
-**REQUIRED INPUT:** the `.knowledge/` blueprint produced by **pikku-software-archaeology**. If none exists, run that skill first — this one consumes its output (`product.json`, `domains.json`, `workflows.json`, `gaps.json`, `invariants.json`, `migration.json`, and any `parity-*.md`), it does not re-derive facts from the code. When the optional consumer-surface files are present (`interfaces.json`, `frontend.json`, `frontend-routes.json`, `frontend-components.json`), cover them too — see "The frontend and the other ways your app is used" and "Technology choices" below.
+**REQUIRED INPUT:** the `.knowledge/` blueprint produced by the extraction phase (see SKILL.md). If none exists, run that first — this one consumes its output (`product.json`, `domains.json`, `workflows.json`, `gaps.json`, `invariants.json`, `migration.json`, and any `parity-*.md`), it does not re-derive facts from the code. When the optional consumer-surface files are present (`interfaces.json`, `frontend.json`, `frontend-routes.json`, `frontend-components.json`), cover them too — see "The frontend and the other ways your app is used" and "Technology choices" below.
 
 ## The cardinal rule: translate, don't dump
 
@@ -52,7 +47,7 @@ Write these three parts in order. A reader can stop after Part 1.
 - _The headline_: the 3–5 biggest risks/opportunities, one plain line each.
 - _Recommended order_: a table (Fix | Why it matters | Effort | Payoff). This is the part they act on.
 
-**Part 2 — One section per major area** (drive the areas from `domains.json`; skip domains with nothing worth saying). Each section follows this shape (see `example/sample-report.md`):
+**Part 2 — One section per major area** (drive the areas from `domains.json`; skip domains with nothing worth saying). Each section follows this shape (see `example/second-opinion-sample-report.md`):
 
 - _What this does_ — the capability in business terms.
 - _How it works today_ — a plain walkthrough, ideally as a small story ("on a timer, the app re-reads each site, compares…").
@@ -162,6 +157,6 @@ Produce **both**:
 | A design point with no "why it matters"               | Taste, not advice. Tie every design finding to user perception (polish/trust) or maintenance cost (change-once vs hunt-everywhere), plus effort. |
 | Reads like a code review                              | Wrong audience. Would a founder know what to _do_ after this paragraph?                                                                          |
 
-## Relationship to pikku-software-archaeology
+## Relationship to the extraction phase
 
-`pikku-software-archaeology` = facts → `.knowledge/` blueprint, for a machine to rebuild from. **This skill** = blueprint → opinionated report, for a human to decide from. One extracts; one advises. Run archaeology first (or point this skill at an existing `.knowledge/`), then translate its `gaps.json` + `invariants.json` + `migration.json` into the business-language report above.
+Extraction = facts → `.knowledge/` blueprint, for a machine to rebuild from. This report = blueprint → opinionated argument, for a human to decide from. One extracts; one advises. Run the extraction first (or point this at an existing `.knowledge/`), then translate its `gaps.json` + `invariants.json` + `migration.json` into the business-language report above.

package/skills/pikku-webhook/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: pikku-webhook
+description: >-
+  Use when an application needs to SEND outgoing webhooks — notifying a customer's endpoint that
+  something happened, with signing, retries and a delivery log. Covers WebhookService,
+  QueueWebhookService, the `pikku-outgoing-webhooks` queue worker, `scaffold.webhook`,
+  `config.webhook`, signature verification on the receiving side, and KyselyWebhookService's
+  delivery history. TRIGGER when: code uses webhookService, QueueWebhookService,
+  KyselyWebhookService, pikkuWebhookWorkerFunc, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
+  SendWebhookInput or X-Pikku-Signature. TRIGGER when: the user asks to emit events to a
+  customer URL, build a webhook endpoint settings screen, add a signing secret, or show
+  delivery attempts. DO NOT TRIGGER when: the user is RECEIVING webhooks from a third party
+  into a route — that is an ordinary wireHTTP function (use pikku-wiring).
+installGroups: [core]
+---
+
+# Pikku Outgoing Webhooks
+
+Pikku ships an outgoing webhook primitive, so an application never hand-rolls
+`fetch` + HMAC + retries. `WebhookService.send()` signs the body, enqueues a
+delivery job, and the generated `pikku-outgoing-webhooks` queue worker POSTs it;
+a non-2xx throws, so the queue retries with backoff. Swapping the queue-only
+default for `KyselyWebhookService` adds a durable delivery + attempt history
+with no change to call sites.
+
+**Do not write a bespoke `fetch(url, { headers: { 'x-my-signature': … } })` for
+an outgoing event.** If the shipped signing scheme or delivery model genuinely
+does not fit, subclass `WebhookService` — it is an abstract class precisely so
+an app can substitute its own transport (direct send, Svix) and keep the same
+call sites and delivery history.
+
+## Agent Operating Procedure
+
+1. Turn the feature on: `"scaffold": { "webhook": true }` in `pikku.config.json`.
+2. Run `pikku all`. It writes `<scaffold.pikkuDir>/webhook/webhook.gen.ts` (the
+   queue worker) and `webhook.schemas.gen.ts`. Never hand-edit either.
+3. Register a `webhookService` singleton in `createSingletonServices`. Without
+   it `services.webhookService` is `undefined` and nothing sends.
+4. Make sure a queue backend is wired. The worker is an ordinary
+   `wireQueueWorker` — with no `queueService`, `send()` throws.
+5. Call `webhookService.send(...)` from a function body. Never call `fetch`
+   directly for an outgoing event.
+6. Validate with `pikku all` and the project's typecheck.
+
+## Config
+
+```jsonc
+// pikku.config.json
+{
+  "scaffold": {
+    "pikkuDir": "src/pikku",
+    "webhook": true, // on or off — it exposes no endpoint and has no path override
+  },
+}
+```
+
+`scaffold.webhook` is a plain boolean, unlike the other scaffold flags which
+accept `{ path }`. The two generated paths are derived
+(`webhookWorkersFile`, `webhookSchemasFile`) and can be set explicitly in
+`pikku.config.json` if a project needs them somewhere else.
+
+Runtime defaults live on `CoreConfig.webhook`:
+
+```ts
+export interface Config extends CoreConfig {}
+
+const config: Config = {
+  webhook: {
+    secret: 'WEBHOOK_SIGNING_KEY', // a secret NAME, resolved via services.secrets
+    signatureHeader: 'X-Pikku-Signature', // default
+    retries: 3, // default; attempts = retries + 1
+    retryDelay: '30s', // omit for exponential backoff
+    allowedHosts: ['hooks.example.com'], // SSRF allowlist
+  },
+}
+```
+
+`allowedHosts` set means _only_ those hostnames are deliverable. Omitted, every
+public host is allowed and private/internal ranges are blocked — loopback,
+RFC1918, link-local `169.254.0.0/16` (cloud metadata), CGNAT `100.64.0.0/10`
+(Alibaba's metadata endpoint), multicast and the TEST-NETs. A URL is
+user-supplied data; do not bypass `safeFetch` by delivering yourself.
+
+## Sending
+
+```ts
+import { pikkuFunc } from '#pikku/function'
+
+export const notifyOrderShipped = pikkuFunc({
+  func: async ({ webhookService }, { endpointUrl, orderId, secret }) => {
+    const { jobId } = await webhookService.send({
+      url: endpointUrl,
+      event: 'order.shipped',
+      data: { orderId, shippedAt: new Date().toISOString() },
+      secret, // per-endpoint raw key; overrides config.webhook.secret
+      organizationId: orgId, // persisted by store-backed services only
+    })
+    return { jobId }
+  },
+})
+```
+
+`send()` returns as soon as the job is enqueued — it is **not** a delivery
+receipt. `jobId` is the queue job; with `KyselyWebhookService` it is also the
+`deliveryId`, so it is stable across retries and is what a UI polls.
+
+The two `secret` fields are deliberately different and are the most common
+mistake:
+
+| Where                     | Meaning                                                             |
+| ------------------------- | ------------------------------------------------------------------- |
+| `config.webhook.secret`   | a secret **name**, read through `services.secrets` at enqueue time  |
+| `SendWebhookInput.secret` | a **raw HMAC key**, for per-endpoint secrets held in your own table |
+
+The raw key never enters the queue payload: the body is signed at enqueue time
+and only the resulting header travels with the job. That is also why the body
+is serialized once — a retry re-POSTs identical bytes, so the signature stays
+valid.
+
+With neither secret set, deliveries go **unsigned**. A missing named secret is
+logged as an error and still sends unsigned; treat that log line as a
+misconfiguration, not noise.
+
+## Verifying on the receiving side
+
+`sign()` produces `sha256=<hex>` (GitHub style, body only, no timestamp) into
+`X-Pikku-Signature`, and `X-Pikku-Event` carries the event name. `verify()` is
+public because receivers share the scheme:
+
+```ts
+const raw = await request.text()
+if (
+  !webhookService.verify(secret, request.headers.get('x-pikku-signature')!, raw)
+) {
+  throw new UnauthorizedError()
+}
+```
+
+It compares in constant time via `timingSafeStringEqual`. Never compare
+signatures with `===`, and verify against the **raw body text**, not a
+re-serialized parsed object.
+
+## Delivery history
+
+The default `QueueWebhookService` keeps no history: `listDeliveries`,
+`getDelivery` and `recordAttempt` throw `NotImplementedError`. Register
+`KyselyWebhookService` from `@pikku/kysely` to get them.
+
+```ts
+import { KyselyWebhookService } from '@pikku/kysely'
+
+const webhookService = new KyselyWebhookService(queueService, kysely)
+await webhookService.init() // creates webhookDelivery + webhookDeliveryAttempt
+```
+
+`init()` is idempotent and creates the tables through the pikku schema
+bootstrap. Do not write your own migration for these tables.
+
+- `webhookDelivery` — one row per `send()`: `deliveryId`, `organizationId`,
+  `url`, `event`, `status` (`pending` | `delivered` | `failed`), `attempts`,
+  `createdAt`, `updatedAt`, `deliveredAt`.
+- `webhookDeliveryAttempt` — one row per try: `attemptNumber`, `statusCode`,
+  `responseBody` (failures only, truncated to 2000 chars), `error`.
+
+Read them through the service, not with your own query:
+
+```ts
+const deliveries = await webhookService.listDeliveries({
+  organizationId,
+  limit: 25,
+})
+const detail = await webhookService.getDelivery(deliveryId) // { delivery, attempts }
+```
+
+Building a console screen is `listDeliveries` for the list and `getDelivery` for
+the drill-in. A hand-written select over `webhookDelivery` is a sign the wrong
+service is registered.
+
+## What the worker does
+
+The generated worker is a thin wrapper over `pikkuWebhookWorkerFunc`. It POSTs
+through `safeFetch` with a 30s timeout, treats 2xx as delivered, captures the
+response body on failure, records the attempt when a `deliveryId` is present,
+and **throws** on failure so the queue retries. Attempt recording is
+best-effort: a store error is logged and does not fail the delivery. Retry
+exhaustion is logged by the queue runner — there is no `onFailure` hook.
+
+## Gotchas
+
+- `webhookService` is optional on `CoreSingletonServices`, but do **not** guard
+  it in a function body — destructuring it marks it required (see
+  `pikku-services`). Register it in `services.ts` or fail fast at startup.
+- The queue name is `pikku-outgoing-webhooks`, not `pikku-webhooks`.
+- `retries: 0` means one attempt and no backoff, not "retry forever".
+- The gateway's inbound `webhook` transport type is a different feature. This
+  skill is outbound only.
+- Signing is body-only with no timestamp, so it does not defend against replay
+  on its own. If a receiver needs replay protection, put a nonce or timestamp
+  **inside** the payload, where it is covered by the signature.