@pikku/skills 0.12.4 → 0.12.6

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

@@ -41,10 +41,30 @@ const schema = new CFWorkerSchemaService(logger: Logger)
 
 **Methods:**
 
-- `compileSchema(schema: string, value: any): void` — Compile and register a JSON schema
+- `compileSchema(name: string, schema: any): void` — Compile and register a JSON schema under `name`
 - `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
+- `getSchemaKeys(schemaName: string): string[]` — Top-level property keys, or `[]` if the schema has no `properties`
+
+### Where it differs from AJV
+
+These two are not drop-in equivalents, and the differences are the kind that
+surface as behaviour changes rather than compile errors:
+
+- **No `useDefaults`.** AJV fills schema defaults into the validated object in
+  place; this validator does not. A field you relied on being defaulted arrives
+  `undefined` on Workers.
+- **It re-compiles when the schema value changes.** AJV caches by name forever;
+  here a `compileSchema` with a different value for the same name replaces the
+  validator, which is what lets a dev hot-reload pick up regenerated schemas.
+- **Each validator gets a deep clone of the schema** (`@cfworker/json-schema`
+  mutates what it is given, which throws on a frozen generated object).
+- A compile failure throws `Error('Failed to compile schema: <name>')` with the
+  underlying cause swallowed — check the schema by hand when you see it.
+
+A failed validation throws `UnprocessableContentError` (422) with the validator
+errors joined; a *missing* schema throws a bare string, `Missing validator for
+<name>`, not an `Error`.
 
 ## Usage Patterns
 

package/skills/pikku-security/SKILL.md

@@ -23,6 +23,10 @@ For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see
 
 ## Session Management
 
+`session`, `setSession` and `clearSession` live on the **wire** — the function's
+third argument — not on services. `setSession`/`clearSession` may be async
+(cookie and session-store backends write on the way out), so await them.
+
 ```typescript
 // Read session in pikkuFunc (session guaranteed to exist)
 const getProfile = pikkuFunc({
@@ -36,7 +40,7 @@ const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
+    await setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
@@ -44,28 +48,31 @@ const login = pikkuFunc({
 // Clear session (logout)
 const logout = pikkuFunc({
   func: async ({}, _data, { clearSession }) => {
-    clearSession()
+    await clearSession()
   },
 })
 ```
 
+`login` is `auth: false` because the caller has no session yet — a `pikkuFunc`
+with the default `auth` would be rejected before its body ever ran.
+
 ## Built-in Auth Strategies
 
 Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
+import { addHTTPMiddleware } from '#pikku'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
 
-// Cookie-based sessions — auto-refreshes JWT
+// Cookie-based sessions — re-issues the cookie when the session changes
 addHTTPMiddleware('*', [
   authCookie({
     name: 'session',
     expiresIn: { value: 30, unit: 'day' },
-    options: { httpOnly: true, secure: true },
+    options: { sameSite: 'strict' },
   }),
 ])
 
@@ -73,6 +80,40 @@ addHTTPMiddleware('*', [
 addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 ```
 
+All three share the same escape hatch: they do nothing when there is no HTTP
+request, or when a session is already set. That is what lets you stack several —
+whichever runs first and finds a credential wins, and the rest step aside — and
+it is also why none of them authenticate a queue job, a scheduled task or a
+channel message. Those need a session set another way.
+
+Each decodes its credential with the `jwt` service; without one registered, they
+silently authenticate nobody.
+
+**`authBearer` in static-token mode.** Passing `token` switches it from decoding
+a JWT to comparing (in constant time) against a fixed value — the shape to use
+for a service-to-service caller or a demo:
+
+```typescript
+authBearer({
+  token: {
+    secretId: 'AGENT_DEMO_TOKEN', // or: value: 'literal-token'
+    userSession: { userId: 'demo-user' },
+  },
+})
+```
+
+An unset secret leaves the middleware inert rather than erroring, so a template
+that ships this is safe until someone provides the secret. A malformed
+`Authorization` header (no `Bearer ` scheme) throws `InvalidSessionError` in
+either mode.
+
+**`authCookie` options.** `name`, `expiresIn` and `options` are all part of the
+config; `options` merges over the defaults `{ httpOnly: true, secure: true,
+sameSite: 'lax', path: '/' }`, so only override what you need. The cookie is
+re-issued after the request only when the session actually changed, which is how
+a rolling session extends itself without writing a `Set-Cookie` on every
+response.
+
 ## Complete Example
 
 ```typescript
@@ -84,10 +125,14 @@ export const isVerified = pikkuAuth(async (_services, session) => !!session?.ema
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
+import { addHTTPMiddleware } from '#pikku'
 
 addHTTPMiddleware('*', [
-  authCookie({ name: 'session', expiresIn: { value: 30, unit: 'day' } }),
+  authCookie({
+    name: 'session',
+    expiresIn: { value: 30, unit: 'day' },
+    options: {},
+  }),
 ])
 
 // functions/auth.functions.ts
@@ -95,14 +140,14 @@ export const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
+    await setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
 
 export const logout = pikkuFunc({
   func: async ({}, _data, { clearSession }) => {
-    clearSession()
+    await clearSession()
   },
 })
 ```

package/skills/pikku-services/SKILL.md

@@ -2,11 +2,13 @@
 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), service
-  typing, built-in services, and tree-shaking. TRIGGER when: code uses
-  pikkuServices/pikkuWireServices, user asks about services.ts, dependency injection, service
-  factories, or built-in services (ConsoleLogger, JoseJWTService). DO NOT TRIGGER when: user asks
-  about auth middleware (use pikku-security) or secrets/variables (use pikku-config).
+  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).
 installGroups: [core]
 ---
 
@@ -74,6 +76,39 @@ export const createWireServices = pikkuWireServices(
 )
 ```
 
+### `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:
@@ -97,7 +132,7 @@ export type RequiredSingletonServices = Pick<
 
 ### 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` 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.
+**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
@@ -122,15 +157,20 @@ const getUser = pikkuFunc({
 
 **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 `requireSingletonServices` therefore never creates it. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+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 = RequiredSingletonServices & Services
+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
@@ -232,7 +272,7 @@ export const createSingletonServices = pikkuServices(async (config) => {
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => ({
-    scopedLogger: new ScopedLogger(wire.session?.initial?.userId),
+    scopedLogger: new ScopedLogger(wire.session?.userId),
   })
 )
 

package/skills/pikku-services/references/audit-wire-service.md

@@ -23,7 +23,8 @@ The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions
 ```typescript
 const deleteUser = pikkuFunc({
   func: async ({ audit }, { userId }) => {
-    await audit.audit({ type: 'user.deleted', actor_user_id: userId })
+    // The user identity comes from the wire session — the payload is metadata.
+    await audit.write({ type: 'user.deleted', source: 'explicit', metadata: { userId } })
     // ...
   },
 })

package/skills/pikku-template-clone/SKILL.md

@@ -18,11 +18,16 @@ commit, separate from any feature work.
    _template_, not the user's project — leaving it in place is misleading.
    Either delete it (`git rm README.md`) or rewrite it with the new project's
    name and purpose. Never ship a clone with the generic template README.
-2. **Keep the lockfile committed.** Templates ship a committed `yarn.lock`; do
-   NOT re-add `yarn.lock` to `.gitignore`. A real project commits its lockfile
-   for reproducible installs. The correct pattern is `yarn.lock` followed by
-   `!/yarn.lock`, which commits the root lockfile while keeping generated
-   per-unit lockfiles under `.deploy/` (and `e2e/`) ignored.
+2. **Keep the lockfile committed.** Do NOT re-add `yarn.lock` to `.gitignore`.
+   A real project commits its lockfile for reproducible installs. The correct
+   pattern is `yarn.lock` followed by `!/yarn.lock`, which commits the root
+   lockfile while keeping generated per-unit lockfiles under `.deploy/` (and
+   `e2e/`) ignored.
+
+   `create-pikku` keeps only the chosen package manager's lockfile and deletes
+   the other, and for yarn it may have written an **empty** `yarn.lock` as a
+   marker. Commit the lockfile *after* the first install has filled it in —
+   committing the empty placeholder pins nothing.
 3. **Rename template identifiers.** Update `name` in the root `package.json`
    (and any `@project/*` or other placeholder names) to the real project.
 4. **Drop template-only artifacts.** Remove any `TEMPLATE.md`, demo docs, or

package/skills/pikku-trigger/SKILL.md

@@ -35,16 +35,23 @@ See `pikku-concepts` for the core mental model.
 
 ## API Reference
 
+All three come from `#pikku`. A trigger is deliberately split in two: the
+**source** owns the connection to the outside world and the **trigger** names the
+function to run, so one source can be swapped (Redis → PG) without touching the
+handler, and a handler can exist before any source is wired.
+
 ### `wireTrigger(config)`
 
 Define the target function that handles trigger events:
 
 ```typescript
-import { wireTrigger } from '@pikku/core/trigger'
+import { wireTrigger } from '#pikku'
 
 wireTrigger({
   name: string, // Trigger name (matches source)
   func: PikkuFunc, // Function to call when event fires
+  description?: string,
+  tags?: string[],
 })
 ```
 
@@ -53,18 +60,24 @@ wireTrigger({
 Define the event source that fires triggers:
 
 ```typescript
-import { wireTriggerSource } from '@pikku/core/trigger'
+import { wireTriggerSource } from '#pikku'
 
 wireTriggerSource({
-  name: string, // Must match wireTrigger name
-  func: PikkuTriggerFunc, // Source function (sets up listener)
-  input: object, // Configuration for the source
+  name: string, // Must match a wireTrigger name
+  func: PikkuTriggerFunc, // Source function (sets up the listener)
+  input: object, // Configuration handed to the source
 })
 ```
 
+`input` is required whenever the source function declares an input type, and the
+name must be unique — wiring the same source name twice throws
+`Trigger source already exists`.
+
 ### `pikkuTriggerFunc<TInput, TEvent>`
 
-Define a trigger source function. Returns a cleanup function.
+A trigger source function runs **once at startup**, not once per event. It sets
+up a listener, calls `trigger.invoke(...)` for each event it sees, and returns a
+teardown function:
 
 ```typescript
 import { pikkuTriggerFunc } from '#pikku'
@@ -83,6 +96,37 @@ const source = pikkuTriggerFunc<
 })
 ```
 
+It receives **singleton services only** — there is no session, no request and no
+per-wire services, because a listener outlives every event it will ever emit.
+The config-object form (`pikkuTriggerFunc({ func, title, description, tags,
+input, output })`) is also accepted when you want schemas or metadata on the
+source.
+
+## Starting triggers
+
+Nothing fires until a `TriggerService` is started. For a single process,
+`InMemoryTriggerService` walks every wired source that has at least one matching
+target and sets it up:
+
+```typescript
+import { InMemoryTriggerService } from '@pikku/core/services'
+
+const triggerService = new InMemoryTriggerService()
+await triggerService.start()
+// on shutdown
+await triggerService.stop() // runs every source's teardown
+```
+
+A source with no matching `wireTrigger` is logged and skipped rather than
+erroring — the two halves are wired independently, so a half-wired trigger is a
+normal intermediate state.
+
+**If a wiring is silently skipped**, look for
+`Skipping trigger … metadata not found` in the logs. Both wirings read metadata
+generated by the inspector, and it warns rather than throwing; the usual fix is
+the one the warning suggests — move the wiring into its own file so codegen
+picks it up.
+
 ## Usage Patterns
 
 ### Redis Pub/Sub Source

package/skills/pikku-versioning/SKILL.md

@@ -34,20 +34,22 @@ See `pikku-concepts` for the core mental model.
 
 ## Function Versioning
 
-When you need to introduce a breaking change, keep the old function as a pinned version and let the new one become the latest.
+A function with `version: N` is registered under the id `name@vN`. The bare
+name still resolves to it, so callers that don't care about versions keep
+working while a pinned `getBook@v1` stays addressable for the ones that do.
 
-**The pattern:**
+**The pattern:** when you need to introduce a breaking change, copy the current
+function into a pinned `v1` and bump the live one to `version: 2`.
 
-1. Create a new file `my-function-v1.function.ts` — export a variable with the `V1` suffix
-2. Set `override: 'myFunction'` — this is the contract key the manifest groups under
-3. Set `version: 1` — pins this as version 1 of the contract
-4. The existing `my-function.function.ts` (no `version:` field) automatically becomes the latest version
+1. Create `my-function-v1.function.ts` exporting `getBookV1` with `version: 1` —
+   the trailing `V1` matching the version is stripped automatically, so the id
+   becomes `getBook@v1`
+2. Add `version: 2` to the existing `getBook`
 
 ```typescript
 // my-function-v1.function.ts — old contract, kept for running workflows/agents
 export const getBookV1 = pikkuFunc({
-  override: 'getBook', // REQUIRED — links this to the 'getBook' contract family
-  version: 1,
+  version: 1, // id becomes getBook@v1 — the V1 suffix is stripped
   input: z.object({ bookId: z.string() }),
   output: z.object({ title: z.string() }),
   func: async ({ db }, { bookId }) => {
@@ -55,8 +57,9 @@ export const getBookV1 = pikkuFunc({
   },
 })
 
-// my-function.function.ts — latest contract, no version: field
+// my-function.function.ts — latest contract, id becomes getBook@v2
 export const getBook = pikkuFunc({
+  version: 2,
   input: z.object({
     bookId: z.string(),
     format: z.enum(['full', 'summary']),
@@ -72,7 +75,17 @@ export const getBook = pikkuFunc({
 })
 ```
 
-**Why `override` is required:** The manifest groups functions by a shared contract key. Without `override: 'getBook'`, `getBookV1` is stored internally as `getBookV1@v1` (key: `getBookV1`), which is a different contract family from `getBook`. With `override: 'getBook'`, it becomes `getBook@v1` (key: `getBook`), which groups with the unversioned `getBook` — and the unversioned one is automatically promoted to `getBook@v2`.
+**Bump the live function explicitly.** Nothing promotes an unversioned function
+to the next version for you — without `version: 2` it is treated as version 1 of
+the `getBook` contract, colliding with the pinned `getBook@v1` and making
+`versions check` report the published contract as modified.
+
+**`override` is the escape hatch, not the requirement.** The contract key comes
+from the exported name with a matching `V<n>` suffix removed, so
+`getBookV1` + `version: 1` already lands on `getBook`. Use
+`override: 'getBook'` only when the export can't follow that convention — for
+instance `legacyGetBook` with `version: 1`, which would otherwise key under
+`legacyGetBook`.
 
 ## Version Manifest (`versions.pikku.json`)
 
@@ -99,22 +112,38 @@ Pikku tracks contract hashes to detect breaking changes:
 }
 ```
 
-Each hash is derived from the function's input and output schemas plus the contract key. If a schema changes without a version bump, `pikku versions check` will fail.
+Each hash is derived from the function's input and output schemas plus the
+contract key. If a schema changes without a version bump, `pikku versions check`
+will fail.
+
+The manifest lives at `versions.pikku.json` in the project's `rootDir`, and its
+presence is what switches versioning on — with no manifest, nothing is checked.
 
 ## CLI Commands
 
 ```bash
-npx pikku versions init     # Initialize versioning manifest (run once)
+npx pikku versions init     # Create an empty versioning manifest (run once)
 npx pikku versions check    # Detect contract changes (use in CI)
-npx pikku versions update   # Update contract hashes after version bump
+npx pikku versions update   # Record current contract hashes
 ```
 
+`init` writes `{ "manifestVersion": 1, "contracts": {} }` and nothing more — it
+does **not** capture the hashes of the functions you already have. Run
+`versions update` straight after it to record the current state, otherwise
+`check` has nothing to compare against and silently passes.
+
+`update` refuses to save when a published version's hash changed, so it can
+never overwrite an immutable record; it reports that as a diagnostic and leaves
+the manifest alone. Fix the contract or bump the version, then run it again.
+
 **Workflow:**
 
-1. `pikku versions init` — run once to create `versions.pikku.json`
+1. `pikku versions init` then `pikku versions update` — once, to create and
+   populate `versions.pikku.json`
 2. Develop normally — add/modify functions
 3. `pikku versions check` — CI catches unversioned breaking changes
-4. If intentional: create `my-function-v1.function.ts` with `override` + `version: 1`, then `pikku versions update`
+4. If intentional: pin the old contract as `…V1` with `version: 1`, bump the
+   live function to `version: 2`, then `pikku versions update`
 
 ## CI Integration
 
@@ -135,9 +164,8 @@ jobs:
 ## Complete Example
 
 ```typescript
-// create-todo-v1.function.ts — v1 locked contract
+// create-todo-v1.function.ts — v1 locked contract, id: createTodo@v1
 export const createTodoV1 = pikkuSessionlessFunc({
-  override: 'createTodo', // groups under 'createTodo' contract family
   version: 1,
   input: z.object({ title: z.string() }),
   output: z.object({ id: z.string(), title: z.string() }),
@@ -146,6 +174,7 @@ export const createTodoV1 = pikkuSessionlessFunc({
 
 // create-todo.function.ts — v2 (latest), called by default
 export const createTodo = pikkuSessionlessFunc({
+  version: 2,
   input: z.object({
     title: z.string(),
     priority: z.enum(['low', 'medium', 'high']),