@pikku/skills 0.12.22 → 0.12.25

package/skills/pikku-services/SKILL.md

@@ -1,297 +1,74 @@
 ---
 name: pikku-services
 description: >-
-  Use when setting up dependency injection, creating custom services, or configuring the service
-  layer in a Pikku app. Covers pikkuServices (singleton), pikkuWireServices (per-request),
-  pikkuServerLifecycle (startup/shutdown hooks), service typing, built-in services, and
-  tree-shaking. TRIGGER when: code uses pikkuServices/pikkuWireServices/pikkuServerLifecycle, user
-  asks about services.ts, lifecycle.ts, dependency injection, service factories, startup or
-  shutdown work, or built-in services (ConsoleLogger, JoseJWTService). DO NOT TRIGGER when: user asks
-  about middleware (use pikku-middleware), auth strategies or sessions (use pikku-security),
-  permissions (use pikku-permissions), or secrets/variables (use pikku-config).
+  Use for the service layer of a Pikku app — dependency injection with pikkuServices and
+  pikkuWireServices, startup/shutdown work with pikkuServerLifecycle, configuration through the
+  secrets, variables and credentials services, the audit sink and buffer, and structured logging.
+  TRIGGER when: code uses pikkuServices/pikkuWireServices/pikkuServerLifecycle, defineSecret,
+  defineVariable or defineCredential, user asks about services.ts, lifecycle.ts, dependency
+  injection, env vars, secrets, API credentials, audit logging, AuditService, PinoLogger, or a
+  built-in service. DO NOT TRIGGER when: user asks about middleware (use pikku-middleware),
+  authentication or permissions (use pikku-auth), or a third-party backend such as Redis, S3 or
+  MongoDB (use pikku-service-backends).
 installGroups: [core]
 ---
 
-# Pikku Services (Dependency Injection)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. 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 uses factory functions for dependency injection. Singleton services are created once at startup; wire services are created fresh per request/job/command. See `pikku-concepts` for the core mental model.
-
-## 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 }
-  },
-})
-```
+# Pikku Services
+
+Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the
+installed surface. This skill is the part the compiler cannot tell you: where a
+value is allowed to be read, and what a service's lifetime commits you to.
+
+## Two lifetimes, and that is the whole model
+
+**Singleton services** (`pikkuServices`) are built once at startup and live for
+the process. **Wire services** (`pikkuWireServices`) are built fresh per HTTP
+request, queue job, channel message or CLI command, and receive the wire.
+
+Everything else follows from that split: a database pool is a singleton, a
+request-scoped logger or audit buffer is a wire service, and startup work that
+needs the singletons goes in `pikkuServerLifecycle` rather than in a module's
+top level.
+
+## Pick the reference
+
+| You are…                                                                     | Read                                                         |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Writing or wiring `services.ts` / `lifecycle.ts`, or adding a custom service | `references/services.md`                                     |
+| Reading config — secrets, env vars, or a per-user API credential             | `references/config.md`                                       |
+| Recording audit events, or choosing a sink                                   | `references/audit.md` and `references/audit-wire-service.md` |
+| Setting up structured logging                                                | `references/pino.md`                                         |
+| Reaching for Redis, S3, SQS, MongoDB or a schema backend                     | `pikku-service-backends`                                     |
+| Sending outgoing webhooks to a customer's endpoint                           | `pikku-webhook`                                              |
+
+## Where a value may be read
+
+- **Never `process.env` inside a Pikku function.** Use `services.variables.get()`
+  or `services.secrets`. `process.env` belongs to server bootstrap (`start.ts`)
+  — and under `pikku dev` / `pikku serve` there is no `start.ts` at all, so
+  startup work goes in a `pikkuServerLifecycle` hook, which receives the
+  singletons and reads through `variables` too.
+- **`secrets` never reaches a function.** `WiredServices` is wrapped in
+  `SecretlessServices<…>`, so it is stripped at the type level rather than merely
+  omitted by convention. Read a secret in a service factory or middleware and
+  hand the resulting service the value.
+
+## What NOT to do
+
+- **Do not guard a service's existence in a function body.** `if (!db) throw …`
+  is dead code. Optionality lives only in the `SingletonServices` declaration and
+  means "may not be created" — a service is optional precisely because nothing
+  destructures it. The inspector records every service destructured by a wired
+  `func`, `permissions` or `middleware` and marks it required, so inside the
+  function it is a non-optional value. A genuinely conditional integration is a
+  configuration concern: branch in `services.ts` or fail fast at startup.
+- **Do not take `services` as a named parameter and cast in the body.** The
+  inspector reads the destructuring pattern to build the manifest; a cast makes
+  the service invisible to it, so tree-shaking drops what the function needs.
+- **Do not hand-roll an audit table.** `auditLog.write()` on an `audit: true`
+  function enriches the event with the function id, wire type, trace id and user
+  identity; an `insertInto('audit_log')` of your own gets none of that, and a
+  write inside a transaction that later rolls back records nothing.
+- **Do not log an unrevealed secret.** Every logger argument is `Safe<>`-guarded,
+  so a `SecretValue` nested anywhere in the call collapses it to `never` and it
+  stops compiling. That is deliberate — it would have printed `[secret]` anyway.

package/skills/{pikku-audit/SKILL.md → pikku-services/references/audit.md}

@@ -1,27 +1,5 @@
----
-name: pikku-audit
-description: >-
-  Use when adding audit / activity-history / change-tracking to a Pikku app, or when a function
-  needs to record who changed what. Covers the built-in AuditService sink, the per-invocation
-  auditLog buffer (createInvocationAudit / pikkuWireServices), the `audit: true` function flag,
-  explicit `auditLog.write()` domain events, automatic query-level capture via
-  createAuditedKysely, and the durable KyselyAuditService sink. TRIGGER when: user asks for an
-  audit log, change history, activity feed, "who did this", or a custom audit/history table; code
-  uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when:
-  user wants app logging/telemetry (use the logger) or DB migrations in general (use
-  pikku-kysely).
----
-
 # Pikku Audit
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Check how services are wired (`services.ts`) and whether an `audit` table migration exists before adding audit calls.
-2. NEVER hand-roll a custom `audit_log` / history table with direct `insertInto('audit_log')` calls. The framework owns audit. A bespoke table drifts from the runtime (missing user/trace/wire context, hand-written CHECK constraints that reject valid events, no prod sink). Use the built-in path below.
-3. Make the smallest source change: mark the function `audit: true`, inject `auditLog`, call `auditLog.write(...)`. Do not invent a new service.
-4. Validate with `pikku all` (regenerates the service flags) then run the app / e2e.
 
 ## Mental model — two layers
 

package/skills/{pikku-config/SKILL.md → pikku-services/references/config.md}

@@ -1,29 +1,5 @@
----
-name: pikku-config
-description: >-
-  Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app.
-  Covers defineSecret, defineVariable, defineCredential, and typed config access. TRIGGER when:
-  code uses defineSecret/defineVariable/defineCredential, user asks about env vars, secrets,
-  config, OAuth2, SecretValue/.reveal(), SecretCoercionError, or "how do I access environment
-  variables". DO NOT TRIGGER when: user asks about API versioning/breaking changes (use
-  pikku-versioning), service factories (use pikku-services), middleware (use pikku-middleware), or
-  auth strategies and sessions (use pikku-security).
-installGroups: [core]
----
-
 # Pikku Config, Secrets & OAuth2
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. 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.
-
-Manage secrets, variables, and OAuth2 credentials. Never use `process.env` in Pikku functions — use typed services instead.
 
 ## Before You Start
 
@@ -228,7 +204,7 @@ const apiKey = process.env.API_KEY
 const apiKey = services.variables.get('API_KEY')
 ```
 
-`process.env` belongs only in server bootstrap code (`start.ts`). Under `pikku dev` / `pikku serve` there is no `start.ts` — startup work goes in a `pikkuServerLifecycle` export, and the hooks receive the singleton services, so read configuration through `variables` there too (see pikku-services).
+`process.env` belongs only in server bootstrap code (`start.ts`). Under `pikku dev` / `pikku serve` there is no `start.ts` — startup work goes in a `pikkuServerLifecycle` export, and the hooks receive the singleton services, so read configuration through `variables` there too (see `references/services.md`).
 
 ### Lint rules
 

package/skills/{pikku-pino/SKILL.md → pikku-services/references/pino.md}

@@ -1,25 +1,5 @@
----
-name: pikku-pino
-description: >-
-  Use when setting up structured logging with Pino in a Pikku app. Covers PinoLogger setup and log
-  levels. TRIGGER when: code uses PinoLogger, user asks about structured logging, Pino, or
-  @pikku/pino. DO NOT TRIGGER when: user asks about ConsoleLogger (use pikku-services) or general
-  service setup.
----
-
 # Pikku Pino (Structured Logging)
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. 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/pino` provides structured JSON logging via [Pino](https://getpino.io/). Implements the `Logger` interface from `@pikku/core`.
 
 ## Installation