@pikku/skills 0.12.4 → 0.12.8

package/skills/pikku-jose/SKILL.md

@@ -45,15 +45,28 @@ await jwt.init()
 
 **Constructor Parameters:**
 
-- `getSecrets` — Async function returning an array of `{ id, value }` key pairs. First key is used for signing; all keys are tried for verification (supports rotation).
+- `getSecrets` — Async function returning an array of `{ id, value }` key pairs. The **first** entry signs; every entry can verify.
 - `logger` — Optional logger instance.
 
 **Methods:**
 
 - `init(): Promise<void>` — Fetch and cache secrets. Call at startup.
-- `encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string>` — Create a signed JWT.
-- `decode<T>(token: string): Promise<T>` — Decode a JWT payload without verification.
-- `verify(token: string): Promise<void>` — Verify a JWT signature and expiry.
+- `encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string>` — Create a signed JWT, stamping the signing key's `id` as the token's `kid` header.
+- `decode<T>(token: string): Promise<T>` — **Verifies** the signature and expiry, then returns the payload.
+- `verify(token: string): Promise<void>` — The same check, discarding the payload.
+
+`decode` is not an unchecked read: both methods run `jose.jwtVerify` and both
+throw on a bad signature or an expired token. There is no way to inspect an
+untrusted payload through this service — reach for `jose.decodeJwt` directly if
+you genuinely need that, and treat the result as unauthenticated input.
+
+Tokens are signed **HS256** with a symmetric secret. The algorithm is fixed and
+pinned on verification, so a token arriving with any other `alg` is rejected —
+but it also means this service has no asymmetric (RS256/ES256) mode.
+
+`init()` is not strictly required: `encode` calls it lazily on first use. Call it
+at startup anyway so a missing or unreachable secret fails at boot rather than
+on the first request that needs a token.
 
 ## Usage Patterns
 
@@ -63,15 +76,20 @@ await jwt.init()
 import { JoseJWTService } from '@pikku/jose'
 
 const jwt = new JoseJWTService(
-  async () => [{ id: 'key-1', value: process.env.JWT_SECRET! }],
+  async () => [{ id: 'key-1', value: await secrets.getSecret('JWT_SECRET') }],
   logger
 )
 await jwt.init()
 ```
 
+A signing key is a secret, so it comes from the secrets service rather than
+`process.env` — and because `getSecrets` is a function called on demand, reading
+it there (not once at construction) is what makes the re-init-on-unknown-kid path
+above actually see a rotated key. See `pikku-config`.
+
 ### Secret Rotation
 
-Supply multiple keys. The first is used for signing; all are tried for verification:
+Supply multiple keys. The first signs; the rest stay available for verification:
 
 ```typescript
 const jwt = new JoseJWTService(async () => [
@@ -80,6 +98,17 @@ const jwt = new JoseJWTService(async () => [
 ])
 ```
 
+Verification resolves the key by the token's `kid` header rather than trying each
+secret in turn — which is why `encode` stamps the signing key's `id` there, and
+why the ids must stay stable across a rotation. Keep an id in the list for as
+long as tokens bearing it can still be in flight.
+
+When a `kid` isn't in the cache, the service re-runs `getSecrets()` once before
+giving up with `Missing secret for id: <kid>`. That is what lets a running server
+pick up a newly added key without a restart, provided `getSecrets` reads from
+something live (a secret store) rather than a value captured at boot. A token
+with no `kid` at all falls back to the current signing key.
+
 ### With Pikku Services
 
 ```typescript

package/skills/pikku-knowledge/SKILL.md

@@ -5,13 +5,14 @@ description: >-
   notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
   note (path-as-identity markdown, YAML frontmatter, only `type` required), the sections of the
   app-project profile (slices, entities, decisions, questions, wishlist) and the one question each
-  answers, slice status/entities/gherkin rules, the `resource:` URI scheme that ties a note to the
+  answers, slice status/entities/gherkin rules, the `resource:` URI scheme tying a note to the
   code it is about, the shapes that are NOT a knowledge base, and the `pikku knowledge
-  validate|index` commands. TRIGGER when: user asks to write down a decision, a requirement, an
-  entity or an open question; asks what the app does or is; asks about knowledge/, notes, slices,
-  or an index.md; or hands over a product brief to record. DO NOT TRIGGER when: user asks what
+  validate|index` commands. TRIGGER when: user asks to write down a decision, requirement, entity
+  or open question; asks what the app does or is; asks about knowledge/, notes, slices,
+  an index.md, or a diagram, callout or decision block; or hands over a product
+  brief to record. DO NOT TRIGGER when: user asks what
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
-  note), or asks to write a scenario test (use pikku-scenario).
+  note), or to write a scenario test (use pikku-scenario).
 installGroups: [core]
 ---
 
@@ -142,7 +143,49 @@ And writing again replaces it rather than adding a second
 
 - **`status`** is `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally.
 - **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
-- **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected.
+- **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
+
+## Showing it
+
+A note is markdown, and four kinds of block are **drawn** rather than printed. Every one of them degrades to something readable — a diagram falls back to its source, a callout to a blockquote, a decision to a code block — so writing one costs nothing where it is not rendered.
+
+None of this changes the governing rule. A diagram of the schema is still a copy of `pikku meta` that drifts, and it drifts while looking more authoritative than prose would. These are for the part no generator can derive.
+
+**```mermaid — when the relationship is the point.** Prose is bad at graphs: "an entry belongs to a day, a day belongs to an owner, and a grant lets another owner read a day" is a sentence a reader has to re-read twice and draw themselves. Reach for one when a note is about how several things relate, an order of steps across time, or a state machine. Do not draw one thing, or two things and an arrow — that is a sentence.
+
+````markdown
+```mermaid
+flowchart LR
+  owner -->|writes| entry
+  entry -->|belongs to| day
+  owner -->|grants read on| day
+```
+````
+
+**`> [!NOTE]` — when a line must survive skimming.** Five kinds: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`. Use one for the thing a reader who skips the paragraph must still not miss — a trap, a constraint that is easy to violate, an assumption the rest of the note rests on. Two callouts in a note is normal; six means the note has no prose left and nothing stands out.
+
+```markdown
+> [!WARNING]
+> A grant is checked on every request, not cached. A permission change is
+> immediate everywhere, and there is no invalidation step to forget.
+```
+
+**```decision — the answer a decision note owes.** `decisions/` answers "what was chosen, and what does that rule out?", and the second half is the half that gets dropped. The fence makes it checkable: `pikku knowledge validate` warns when a fence says what was chosen and never says what it closes off.
+
+````markdown
+```decision
+chosen: A revoked grant stops working immediately, everywhere.
+rules-out:
+  - A "revoked but valid until midnight" state
+  - A scheduled cleanup job
+because: Two people disagreeing about who can see today is worse than one of
+  them losing access mid-session.
+```
+````
+
+It is a **summary, not the note** — the argument continues in prose underneath. `rules-out:` takes one line or a `- item` block, and any value too long for one line wraps onto indented lines under it, as `because:` does above. A decision genuinely argued in prose needs no fence, and validate never asks for one; what it does ask is that a fence you did write is complete.
+
+**Fences of any other language are code** — highlighted and copyable, which is right for a snippet and wrong for a scenario or a decision, so do not put either in a bare fence.
 
 ## `resource:` — tying a note to the code
 
@@ -196,7 +239,7 @@ pikku knowledge index           # refresh every index.md
 pikku knowledge index --check   # report stale indexes without writing (CI gate)
 ```
 
-`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, slices with a bad or missing `status`, slices over three entities, slices with no gherkin block or a first-person one, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
+`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, slices with a bad or missing `status`, slices over three entities, slices with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 

package/skills/pikku-kysely/SKILL.md

@@ -28,7 +28,7 @@ Use this skill as an execution checklist, not reference material.
 
 ## Writing Queries — the Kysely query builder
 
-In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Pikku wires the **CamelCasePlugin**, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a `` sql`` `` literal**. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).
+In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Every connection factory below wires the **CamelCasePlugin** by default, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a `` sql`` `` literal**. If a project opted out (`createNodeSqliteKysely({ camelCase: false })`), that inverts — check how the instance was built before assuming. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).
 
 ```typescript
 import { sql } from 'kysely'
@@ -92,12 +92,19 @@ await kysely.transaction().execute(async (trx) => {
 })
 ```
 
-Pikku provides SQL database services through four packages:
+Pikku provides SQL database services through six packages:
 
-- `@pikku/kysely` — Base service implementations (database-agnostic)
-- `@pikku/kysely-postgres` — PostgreSQL-specific implementations + `PikkuKysely` connection wrapper
+- `@pikku/kysely` — Base service implementations (database-agnostic), the serialize plugins, `createAuditedKysely` and the `pikkuSchemas` helpers
+- `@pikku/kysely-postgres` — PostgreSQL-specific implementations + the `PikkuKysely` connection wrapper and `PgEventHubService` (LISTEN/NOTIFY-backed)
 - `@pikku/kysely-mysql` — MySQL-specific implementations
-- `@pikku/kysely-sqlite` — SQLite-specific implementations + `createSQLiteKysely` factory
+- `@pikku/kysely-sqlite` — SQLite-specific implementations, `createSQLiteKysely`, and the `LibsqlWebDialect`
+- `@pikku/kysely-node-sqlite` — `createNodeSqliteKysely` over `node:sqlite`, plus user-defined SQL functions and the coercion plugin
+- `@pikku/kysely-bun-sqlite` — the same over `bun:sqlite`
+
+The last two are runtime adapters rather than service sets: they build the
+`Kysely<DB>` you inject into functions, while the dialect packages above supply
+Pikku's own stores. They differ in one place — `bun:sqlite` cannot register
+scalar functions, so `createBunSqliteKysely` throws if you pass `functions`.
 
 All implement standard Pikku interfaces from `@pikku/core`.
 
@@ -105,9 +112,11 @@ All implement standard Pikku interfaces from `@pikku/core`.
 
 ```bash
 # Pick your database
-yarn add @pikku/kysely @pikku/kysely-postgres   # PostgreSQL
-yarn add @pikku/kysely @pikku/kysely-mysql      # MySQL
-yarn add @pikku/kysely @pikku/kysely-sqlite     # SQLite
+yarn add @pikku/kysely @pikku/kysely-postgres     # PostgreSQL
+yarn add @pikku/kysely @pikku/kysely-mysql        # MySQL
+yarn add @pikku/kysely @pikku/kysely-sqlite       # SQLite (stores)
+yarn add @pikku/kysely-node-sqlite                # SQLite on Node
+yarn add @pikku/kysely-bun-sqlite                 # SQLite on Bun
 ```
 
 ## API Reference
@@ -120,7 +129,8 @@ import { PikkuKysely } from '@pikku/kysely-postgres'
 const db = new PikkuKysely<DB>(
   logger: Logger,
   connectionOrConfig: postgres.Sql | postgres.Options | string,
-  defaultSchemaName?: string
+  defaultSchemaName?: string,
+  poolConfig?: PostgresConfig   // maxPool, connectTimeout, idleTimeout, maxLifetime, prepare, statementTimeout
 )
 
 await db.init()
@@ -128,14 +138,39 @@ db.kysely  // Kysely<DB> instance for queries
 await db.close()
 ```
 
-### SQLite Factory — `createSQLiteKysely`
+It builds a postgres.js-backed Kysely with the CamelCasePlugin. Pass an existing
+`postgres.Sql` when something else owns the pool — the wrapper then leaves it
+open on `close()`. `poolConfig` keys are only forwarded when set, so postgres.js
+keeps its own defaults for the rest, and it is ignored entirely when you hand in
+an already-constructed connection.
+
+### SQLite factories
+
+```typescript
+import { createNodeSqliteKysely } from '@pikku/kysely-node-sqlite'
+
+// Your application DB — CamelCasePlugin on by default
+const kysely = createNodeSqliteKysely<DB>({
+  filename: 'app.db',       // or ':memory:'
+  camelCase: true,
+  plugins: [],              // layered on top
+  functions: {},            // scalar UDFs, registered as deterministic (Node only)
+})
+```
 
 ```typescript
 import { createSQLiteKysely } from '@pikku/kysely-sqlite'
 
-const kysely = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
+// Pikku's own tables — returns Kysely<KyselyPikkuDB>, not your DB
+const pikkuDb = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
 ```
 
+These two are not interchangeable. `createSQLiteKysely` is typed to
+`KyselyPikkuDB` and wires the `SerializePlugin` (JSON columns in and out) rather
+than the CamelCasePlugin, because it exists to back the stores below. Reach for
+`createNodeSqliteKysely` / `createBunSqliteKysely` for the instance your
+functions query.
+
 ### Available Services
 
 Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLite`, or base `Kysely`):
@@ -151,24 +186,52 @@ Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLi
 | `*AgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
 | `*SecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
 
+A handful more live only on the base package — there is no `Pg`/`MySQL`/`SQLite`
+variant to reach for, you import them from `@pikku/kysely` whatever the engine:
+
+| Service                    | Purpose                                       |
+| -------------------------- | --------------------------------------------- |
+| `KyselySessionStore`        | Persisted user sessions                       |
+| `KyselyScopeService`        | Scope and role storage                        |
+| `KyselyWebhookService`      | Webhook registrations and deliveries          |
+| `KyselyCredentialService`   | Encrypted third-party credentials             |
+| `KyselyAIRunStateService`   | AI run state (also implemented by AIStorage)  |
+| `KyselyWorkflowMirror`      | Mirrors workflow runs into queryable tables   |
+| `KyselyAuditService`        | Durable audit sink (see `pikku-audit`)        |
+
 All services take a `Kysely<KyselyPikkuDB>` instance in their constructor and have an `init()` method that creates tables if needed.
 
 ### Secret Service
 
+Envelope encryption: each secret gets its own DEK, wrapped by a KEK derived from
+`key` plus a stored per-version salt. Keeping `previousKey` around is what makes
+rotation possible — `rotateKEK` re-wraps every secret from the old key to the
+current one and returns the new version, and it throws if no `previousKey` is
+configured.
+
 ```typescript
 import { PgKyselySecretService } from '@pikku/kysely-postgres'
 
 const secrets = new PgKyselySecretService(db.kysely, {
-  kekSecret: 'your-key-encryption-key',
-  salt: 'your-salt',
+  key: 'your-key-encryption-passphrase',
+  keyVersion: 2, // defaults to 1
+  previousKey: 'the-passphrase-you-are-rotating-away-from',
+  audit: true, // log write/delete/rotate through the audit sink
+  auditReads: false, // reads too — noisy, off by default
 })
 await secrets.init()
 
 await secrets.setSecret('api-key', { key: 'sk-...' })
-const value = await secrets.getSecret<{ key: string }>('api-key')
-await secrets.rotateKEK() // Re-encrypt all secrets with new KEK
+const secret = await secrets.getSecret<{ key: string }>('api-key')
+await secrets.hasSecret('api-key')
+await secrets.deleteSecret('api-key')
+const newVersion = await secrets.rotateKEK()
 ```
 
+`getSecret` hands back a `SecretValue<T>`, not the bare value — it serializes as
+`[secret]` until something reveals it, which is what stops a secret drifting into
+a log line or an audit row. See `pikku-config` for the reveal rules.
+
 ## Usage Patterns
 
 ### PostgreSQL Setup

package/skills/pikku-machine-auth/SKILL.md

@@ -157,7 +157,42 @@ addHTTPMiddleware([
 
 When the api-key header is present it is authoritative — the middleware never
 falls through to `getSession` (a bare mock session would shadow the scoped one).
-When it is absent, the human `getSession` path runs as normal.
+When it is absent, the human `getSession` path runs as normal. Either way the
+middleware bails out entirely if a session is already set, and it checks the
+*live* session rather than the wire's construction-time snapshot, so it can't
+clobber one an earlier middleware resolved.
+
+### Restricting a key below its owner
+
+Set `scopes` on the session `mapKey` returns and that set is **authoritative** —
+including an empty one. It is never widened back out to everything the owning
+service user holds:
+
+```typescript
+mapKey: async (key) => ({
+  userId: 'sandbox-runtime',
+  scopes: ['sandbox:read'], // this key can do only this
+})
+```
+
+Leave `scopes` unset for a key that acts with its owner's full rights. This is
+what makes one stable service user safely able to own keys of very different
+power — the restriction lives on the key, not on a proliferation of identities.
+
+### Failure handling is deliberately split
+
+A key that fails to verify is logged and treated as an ordinary "not
+authenticated" — an unusable credential is not an outage. A failure *inside*
+`mapKey` (your scope store is down) propagates as a real error instead. That
+asymmetry is on purpose: a scope lookup that silently failed would serve the
+request anonymously, which is exactly the wrong direction to fail in.
+
+### `betterAuthStatelessSession` has no machine path
+
+The lean cookie-cache middleware (`betterAuthStatelessSession` — no
+`services.auth()`, no DB) handles only the human path. Machine auth needs
+`betterAuthSession`, because `verifyApiKey` is a server call there is no
+stateless equivalent of. Both accept an `impersonation` option.
 
 ### WebSocket channels authenticate on the upgrade handshake