@pikku/skills 0.12.40 → 0.12.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.40",
+  "version": "0.12.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-blueprint-to-fabric/SKILL.md

@@ -313,7 +313,7 @@ Then run the slice's scenarios. All four green — validate, codegen, `tsc`, sce
 
 Never batch. A rebuild verified only at the end gives you an undifferentiated pile of failures with no bisect point, and the whole reason for slicing is that each slice is a checkpoint you can trust.
 
-New functions with `expose: true` are versioned from the start — `pikku versions` / `pikku semver` (**pikku-meta**); you're establishing v1 contracts, not migrating them.
+New functions with `expose: true` are versioned from the start — `pikku versions` / `pikku release` (**pikku-meta**); you're establishing v1 contracts, not migrating them.
 
 ## Stage 9 — The parity report (the deliverable)
 

package/skills/pikku-build/references/platform.md

@@ -167,8 +167,8 @@ bunx --bun pikku versions init
 
 The CLI suggests this on every run of a project without it. Versioning a function
 contract, then changing it, is a short milestone that shows something no
-scaffold demonstrates on its own. `pikku semver` derives the release version by
-comparing this build's surface against a deployed one.
+scaffold demonstrates on its own. `pikku release` derives the release version by
+comparing this build's surface against the last release, then ships it.
 
 ### Addons — `pikku-addon`
 

package/skills/pikku-concepts/SKILL.md

@@ -115,7 +115,7 @@ flags; the "Read" column is the skill that teaches the thing, where one does.
 | `doc`                 | The installed API surface                                               | this skill                   |
 | `meta` / `info`       | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
 | `validate`            | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
-| `versions` / `semver` | Contract hashes, breaking-change detection, the release semver          | `pikku-meta`                 |
+| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases        | `pikku-meta`                 |
 | `audit` / `update`    | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
 | `scopes` / `roles`    | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
 | `knowledge`           | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |

package/skills/pikku-kysely/SKILL.md

@@ -293,7 +293,10 @@ const kysely = createNodeSqliteKysely<DB>({
 import { createSQLiteKysely } from '@pikku/kysely-sqlite'
 
 // Pikku's own tables — returns Kysely<KyselyPikkuDB>, not your DB
-const pikkuDb = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
+const pikkuDb = createSQLiteKysely(
+  database: SqliteDatabase | (() => Promise<SqliteDatabase>),
+  { plugins: [] } // layered ahead of the always-last SerializePlugin
+)
 ```
 
 These two are not interchangeable. `createSQLiteKysely` is typed to

package/skills/pikku-meta/SKILL.md

@@ -3,8 +3,8 @@ name: pikku-meta
 description: >-
   Use to inspect or evolve a project you did not just write — `pikku meta` and `pikku info` for
   what the project declares (functions, schemas, wires, workflows, middleware, permissions) and
-  `pikku meta apply` to change it, `pikku versions` / `pikku semver` for contract hashes,
-  breaking-change detection and the semver a release should get, and `pikku audit` / `pikku
+  `pikku meta apply` to change it, `pikku versions` / `pikku release` for contract hashes,
+  breaking-change detection, the semver a release should get and shipping it, and `pikku audit` / `pikku
   update` for dependency advisories and moving Pikku forward. TRIGGER when: user asks what
   functions or routes exist, wants a function's input/output shape, wants to retag a function or
   set config on a declaration, asks about API versioning, breaking changes, what semver a release
@@ -13,7 +13,7 @@ description: >-
   Pikku concepts (use pikku-concepts).
 installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku info *)
-argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|semver|audit|update]'
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|release|audit|update]'
 ---
 
 # Pikku Project Metadata
@@ -26,7 +26,7 @@ and change it through the write path rather than by hand.
 | You are… | Read |
 | --- | --- |
 | Asking what exists, or setting config on a declaration | `references/meta.md` |
-| Versioning a contract, or deciding a release's semver | `references/versioning.md` |
+| Versioning a contract, or versioning and shipping a release | `references/versioning.md` |
 | Chasing a dependency advisory, or upgrading Pikku | `references/audit.md` |
 
 ## Start with `pikku meta context`
@@ -41,7 +41,7 @@ they are the same ground in two shapes.
 An input is contravariant (the caller writes it) and an output is covariant (the
 caller reads it), so the same edit is not the same event on both. Adding a
 required field breaks an input and is compatible on an output; making a field
-optional is the reverse. `pikku semver` reads the generated JSON Schemas with
+optional is the reverse. `pikku release diff` reads the generated JSON Schemas with
 that asymmetry built in, so let it decide rather than eyeballing a diff.
 
 ## What NOT to do

package/skills/pikku-meta/references/versioning.md

@@ -1,6 +1,5 @@
 # Pikku Function Versioning
 
-
 ## Before You Start
 
 ```bash
@@ -122,28 +121,86 @@ the manifest alone. Fix the contract or bump the version, then run it again.
 4. If intentional: pin the old contract as `…V1` with `version: 1`, bump the
    live function to `version: 2`, then `pikku versions update`
 
-## The `pikku semver` command
+## The `pikku release` command
 
-`versions check` and `semver` answer different questions and share no state.
+`versions check` and `release` answer different questions and share no state.
 `check` is a within-repo gate — "you changed a contract without bumping
-`version:`". `semver` is a release question — "what does this build owe the
-clients of the one already deployed?" — and needs an **external baseline**,
-which is why the answer is always relative to an environment rather than to
-the previous commit.
+`version:`". `release` is a release question — "what does this build owe the
+clients of the last release, and how do we ship it?". The baseline is
+`surface.pikku.json`, the snapshot committed by the previous release.
 
 ```bash
-npx pikku semver --against https://api.acme.com/surface.json  # vs production
-npx pikku semver --against ../other-app/.pikku                # vs a checkout
-npx pikku semver --emit --out surface.json                    # publish a baseline
-npx pikku semver --against ... --fail-on major                # CI gate
+npx pikku release init                                   # first run: snapshot + CHANGELOG.md
+npx pikku release diff                                   # vs surface.pikku.json
+npx pikku release diff --against https://api.acme.com/surface.json  # vs any baseline
+npx pikku release diff --fail-on major                   # PR gate
+npx pikku release snapshot --out surface.json            # write a snapshot
+npx pikku release prepare                                # bump package.json, write changelog + snapshot
 ```
 
 `--against` takes three things and tells them apart itself: a directory is read
 as a `.pikku` tree, an `http(s)` URL is fetched as a published snapshot, and any
-other file is read as a snapshot. `--emit` produces the snapshot; **use `--out`**
-— plain `--emit` writes to stdout _after_ the CLI banner, so a bare `> file.json`
-captures the banner too. Publish the snapshot from CI on deploy and it becomes
-the baseline everyone else compares against.
+other file is read as a snapshot. `snapshot` without `--out` writes to stdout
+_after_ the CLI banner, so a bare `> file.json` captures the banner too.
+`pikku semver` is a deprecated alias for `release diff` / `release snapshot`.
+
+### Shipping a release
+
+Work lands on the trunk branch (default `staging`); production (default `main`)
+only ever fast-forwards to a release commit. pikku works the release out and
+writes it; it never commits, tags or pushes. Who does that is your call — you
+with plain git, or a platform with its own credentials.
+
+`prepare` runs on a checkout of `origin/staging` after `pikku all`. It diffs the
+surface against `surface.pikku.json`, reads the commits production does not have
+yet, bumps `package.json`, prepends a `CHANGELOG.md` section and rewrites the
+snapshot. No commits since the last release means nothing to release. It
+refuses when `main` has commits `staging` lacks (merge `main` into `staging`
+with a merge commit first). `.pikku/release.gen.json` records the version, the
+changelog section, the trunk sha it was prepared on and the files it wrote,
+named from the repository root.
+
+Shipping is then one commit on top of that trunk sha:
+
+```bash
+npx pikku release prepare
+git add package.json CHANGELOG.md surface.pikku.json
+git commit -m "release: v0.4.0"
+git tag v0.4.0
+git push --atomic origin HEAD:staging HEAD:main v0.4.0
+```
+
+The push only fast-forwards, so if `staging` moved since prepare it is rejected
+and you prepare again.
+
+The bump comes from the surface diff alone — there is no manual override. A
+release whose surface did not move is a patch. Below 1.0 a breaking change
+is a minor, like any other surface change; from 1.0 it is a major. 1.0.0 is
+never reached by a diff: `pikku release prepare --go-live` releases it once,
+when the app is live. The changelog lists the surface changes and nothing
+else from the code; a behaviour change behind an unchanged API only shows up
+if a commit carries a `Release-Note: …` trailer, which adds a line to Notes.
+A release with neither says it holds internal changes only. Branch names are configurable in `pikku.config.json`:
+
+```json
+{
+  "release": {
+    "trunk": "staging",
+    "production": "main",
+    "branch": "release/next",
+    "remote": "origin"
+  }
+}
+```
+
+`branch` is not used by pikku itself; it is passed through in
+`release.gen.json` as the name a platform gives the prepared release commit
+while it waits to ship.
+
+Functions and wirings defined under a `scaffold/` directory or in a generated
+`*.gen.*` file are platform plumbing (auth, console, a host's injected shims)
+and are left out of the surface, so the same app diffs the same locally and in
+a platform's build.
 
 The verdict, in order:
 
@@ -179,7 +236,7 @@ the wiring level only `auth` going from absent/false to true is classified as
 breaking; every other metadata change is reported as compatible, because there
 is no general way to tell a cosmetic wiring edit from a restricting one.
 
-Output is `.pikku/changes.gen.json` (override with `--out`), so it rides the
+`release diff` writes `.pikku/changes.gen.json` (override with `--out`), so it rides the
 same meta pipeline as `audit.json`:
 
 ```json
@@ -215,7 +272,7 @@ jobs:
       - run: npm ci
       - run: npx pikku versions check
       # Refuse to ship a breaking change to production unintentionally.
-      - run: npx pikku semver --against https://api.acme.com/surface.json --fail-on major
+      - run: npx pikku release diff --fail-on major
 ```
 
 ## Complete Example

package/skills/pikku-wiring/references/trigger.md

@@ -94,6 +94,60 @@ 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.
 
+## Webhook sources
+
+When the outside world pushes to you (Stripe, GitHub, Slack), the source is an
+HTTP route, not a listener. `wireTriggerWebhookSource` declares it; triggers
+subscribe to its events as `<source>:<event>`:
+
+```ts snippet:wireTriggerWebhookSource
+
+```
+
+- The route is `POST /webhooks/<name>` unless `method`/`route` say otherwise.
+  It needs no session.
+- `events` maps each event name to a schema. An event that fails its schema is
+  logged and dropped; so is one no `wireTrigger` listens for. Both still get a
+  `200`, so the provider does not retry forever.
+- `receive(services, { body, headers, method, url, query })` gets the **raw
+  bytes** — verify the signature over those — and returns `{ events: [{ name,
+id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
+  rejects the request with the error's status (`UnauthorizedError` → 401).
+  Omitted, the JSON body becomes one event dispatched to a trigger named just
+  `<source>`.
+- Every accepted event is queued on `pikku-incoming-webhooks` and run by a
+  generated worker, so the provider is answered quickly and a failing trigger is
+  retried by the queue. This needs a `queueService` and an
+  `incomingWebhookService: new IncomingWebhookService(queueService)` in your
+  singleton services. The event `id` becomes the job id.
+- With a database, use `KyselyIncomingWebhookService(queueService, db)` from
+  `@pikku/kysely` instead (and `await service.init()`). It keeps a receipt per
+  event, so a provider's redelivery of an event already accepted is dropped
+  even on queues that ignore job ids, and records each attempt and its last
+  error. Its `webhookReceipt` table comes from `pikku db generate`; `pikku dev`
+  and `pikku serve` use it when a Kysely database is configured.
+- `receive` sees singleton services without `secrets`: read the signing secret
+  in a service method, and declare it with `defineSecret`. Name it in `secret`
+  so deploy knows where `setup` should store it.
+
+`check`, `setup` and `teardown` register the route with the provider. Each gets
+`{ url, label, events, previous? }`, where `events` are only the ones some
+trigger subscribes to. The CLI runs them:
+
+```bash
+pikku webhooks status   --url https://api.example.com --labelPrefix shop:prod
+pikku webhooks setup    --url https://api.example.com --labelPrefix shop:prod
+pikku webhooks teardown --url https://api.example.com --labelPrefix shop:prod --previous state.json
+```
+
+Each prints one JSON line per source (`ok`, `missing`, `drifted`, `created`,
+`updated`, `unchanged`, `manual`, `deleted`, `absent`, `skipped`, `failed`). `setup` only
+runs where `check` does not report `ok`, and a `setup` that returns a new signing
+secret prints it with the `secret` name to store it under. In CI pass
+`--secretsOut <file>`: secrets are written there (mode 600) as
+`{ secretName: secret }` and left out of stdout. Any step can be
+`ref('<addon>:<fn>')` to use an addon's implementation.
+
 ## Usage Patterns
 
 ### Redis Pub/Sub Source
@@ -139,7 +193,6 @@ wireTriggerSource({
 })
 ```
 
-
 ## Complete Example
 
 ```typescript