@pikku/skills 0.12.46 → 0.12.49

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -292,8 +292,14 @@ Author the DDL per dialect:
 ```text
 db/sqlite/0001-labels.sql
 db/postgres/0001-labels.sql
+db/mysql/0001-labels.sql
 ```
 
+`db/mysql` is the one that needs a server to publish: MySQL has no embedded
+engine, so `pikku all` applies the SQL to a scratch database on the server named
+by `db.mysqlUrl` in the addon's `pikku.config.json`, and refuses to build
+without one. Use `varchar(n)` for a key column — MySQL rejects `TEXT` there.
+
 `pikku all` publishes `<outDir>/db/pikku-db-meta.gen.json` on every build — per
 dialect, the SQL verbatim plus a table/column map — and writes it **empty** when
 the addon has no tables, because a consumer reads an absent file as a package

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

@@ -436,7 +436,8 @@ covered_. A stack of half-milestones cannot be reviewed and cannot be handed
 over, and an uncovered function is a half-milestone whether or not the note says
 `built`.
 
-1. **Migration.** SQL in `db/sqlite/` at the project root, numbered on from the
+1. **Migration.** SQL in `db/sqlite/` at the project root (`db/postgres/` or
+   `db/mysql/` when `createConfig` sets `postgresUrl` or `mysqlUrl`), numbered on from the
    ones already there. Apply with `bunx --bun pikku db migrate`, which also
    regenerates the Kysely types your functions import. **Neither `pikku all` nor
    restarting `pikku dev` applies a migration** — so a new column reads as

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

@@ -103,7 +103,8 @@ codegen depends on; without it your first `db migrate` fails with
 
 Then, in this order — it is the order codegen depends on:
 
-1. **Migration** — SQL in `db/sqlite/`, numbered on from what is there. Apply
+1. **Migration** — SQL in `db/sqlite/` (or `db/postgres/`, `db/mysql/` when
+   `createConfig` sets `postgresUrl` or `mysqlUrl`), numbered on from what is there. Apply
    with `bunx --bun pikku db migrate`, which regenerates the Kysely types.
 2. **Seed** — rows in `db/sqlite-dev-seed.sql`. There is no seed command:
    `bunx --bun pikku db reset` wipes, migrates and seeds in one go, and is the

package/skills/pikku-fabric/SKILL.md

@@ -522,6 +522,22 @@ It mints a short-lived operator token for the stage and calls the stage's own
 a 404 is refused by name and nothing is created. A generated password is printed
 once; one you passed is never echoed. With no TTY, pass `--password` or pipe it.
 
+### Opening a private stage
+
+A non-production stage is private: without a link it answers "This preview is
+private". `pikku fabric stage link` prints the link that opens it:
+
+```bash
+pikku fabric stage link access -b develop --route /login   # use the stage
+pikku fabric stage link changes -b develop                 # use it with the changes panel
+pikku fabric stage visibility public -b develop            # or: private
+```
+
+A stage has one live link of each kind, so asking again returns the same one
+until it expires. A `changes` link turns the panel on first; if that needs a
+deploy, the command says so. `visibility public` opens the stage to anyone with
+its URL — hand out an `access` link instead when that is all you need.
+
 ## Versioning
 
 Functions with `expose: true` are versioned via `versions.pikku.json`. When you change a function's input or output schema, you must bump its version number — otherwise `pikku all` will report a breaking change and callers' generated clients become stale.

package/skills/pikku-kysely/SKILL.md

@@ -305,6 +305,25 @@ than the CamelCasePlugin, because it exists to back the stores below. Reach for
 `createNodeSqliteKysely` / `createBunSqliteKysely` for the instance your
 functions query.
 
+### MySQL and `pikku db`
+
+`mysqlUrl` in `createConfig` makes MySQL the third dialect the `pikku db`
+commands drive, with migrations in `db/mysql/` and the seed in
+`db/mysql-dev-seed.sql`. It behaves like the other two with four differences:
+
+- **No embedded engine.** Commands that need a throwaway database create and drop
+  a `pikku_scratch_<hex>` one on your server, so the account needs `CREATE` and
+  `DROP`.
+- **DDL is not transactional.** A migration that fails halfway is replayed from
+  the top, so write migrations that are safe to run twice.
+- **Inline `REFERENCES` is discarded** — declare foreign keys as
+  `FOREIGN KEY (...) REFERENCES ...` or none exists.
+- **A key column cannot be `TEXT`**, nor can a `TEXT` column have a literal
+  default. Use `varchar(n)`, or `DEFAULT ('...')` for an expression default.
+
+`db.schema` is refused (a MySQL schema is a database), and a standalone bundle
+cannot target MySQL yet.
+
 ### Available Services
 
 Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLite`, or base `Kysely`):

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

@@ -107,17 +107,30 @@ subscribe to its events as `<source>:<event>`:
 - The route is `POST /webhooks/<name>` unless `method`/`route` say otherwise.
   `method` may be a list, e.g. `['get', 'post']` for a provider that verifies
   the URL with a GET and delivers events with a POST, or `['head', 'post']`
-  for one that checks the URL with a HEAD.
-  It needs no session.
+  for one that checks the URL with a HEAD. A HEAD is answered with a `200`
+  before `verify` or `receive` run. 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
+- `receive(services, { body, headers, method, url, query }, { http })` gets the
+  **raw bytes** and only parses them: it returns `{ events: [{ name, id?, data }] }`.
+  A handshake returns nothing and answers through `http.response`
+  (`http.response.header('x-hook-secret', secret)`,
+  `http.response.json({ challenge })`), which is sent only then. 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>`.
+- A named `receive` is declared with `pikkuWebhookReceive` from `#pikku/trigger`
+  (`#pikku/addon/trigger` in an addon), never `pikkuSessionlessFunc`: it is
+  public, typed to the request, and never callable as an RPC. The inspector
+  rejects any other wrapper. `parseJson` from `#pikku/utils`
+  (`#pikku/addon/utils`) parses the bytes and answers a body that is not JSON
+  with a 400:
+
+  ```ts snippet:pikkuWebhookReceive
+
+  ```
+
 - 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
@@ -129,12 +142,31 @@ id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
   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`. Declare the signing
-  secret with `defineCredential({ type: 'singleton', ... })` and hold it as
-  `WebhookSigningSecret.fromCredential(provider, credentialService, name)`
-  from `@pikku/core/hmac`; `receive` calls `await signingSecret.load()` and
-  checks against what it returns. A handshake that hands over the secret
-  (Asana) stores it with `credentialService.set`.
+- Signature checks belong in `verify`, never in `receive`. pikku runs it on
+  every request against the secret in the credential
+  `<name>WebhookSecret` (camelCased: `microsoft-outlook` →
+  `microsoftOutlookWebhookSecret`; `credential` overrides it). Declaring
+  `verify` declares that credential as a singleton string, so there is no
+  `defineCredential` and no service holding the secret; `credentialDescription`
+  tells whoever sets it where to find it. Pick the declared form that matches
+  the provider:
+  - `{ hmac: { header, prefix?, algorithm, encoding, secretEncoding? } }`:
+    a signature over the raw body in one header (GitHub, Shopify, Linear).
+  - `{ token: { header, prefix? } }`: the provider echoes the shared secret
+    (GitLab, Telegram).
+  - `{ publicKey: { header, algorithm?, dsaEncoding? } }`: signed with the
+    provider's private key; the stored secret is its PEM public key (Wise).
+  - Anything else (a timestamp in the signed payload, a signature in the body
+    or query, a URL in the signed string) is a function
+    `(request, secret, services) => boolean`, built from `hmacDigest`,
+    `verifyHmacSignature`, `verifyPublicKeySignature` and
+    `timingSafeStringEqual` in `@pikku/core/hmac`.
+
+  A request with a body that fails is refused with a 401. A bodiless request
+  that fails (a validation token in the query) still reaches
+  `receive` so it can answer the handshake, but any events it returns are
+  refused. A handshake that hands over the secret (Asana) stores it with
+  `credentialService.set` under the same credential name.
 
 `check`, `setup` and `teardown` register the route with the provider. Each gets
 `{ url, label, events, previous? }`, where `events` are only the ones some

package/skills/pikku-workflow/SKILL.md

@@ -237,38 +237,52 @@ with `outcome: 'success' | 'denied'`, the decider under `userIdentity`, and the
 run, reason and refusal in `metadata`. Wire an `audit` service to keep it; a
 project without one records nothing and is otherwise unaffected.
 
-### Error handling: `onError`, never try/catch
+### Failure: `compensate`, never try/catch
 
 **Do not wrap steps in try/catch.** The DSL extractor serialises the body into a
 step graph, and a `catch` block is control flow it cannot represent — so the
-graph would no longer describe what actually runs, which is the whole point of
-the DSL mode. This is a settled design decision, not a temporary limitation.
+graph would no longer describe what actually runs. This is a settled design
+decision, not a temporary limitation.
 
-Use the `onError` step option instead: it names an RPC to invoke when the step
-has failed _after_ exhausting its retries.
+Declare how a function is undone **on the function itself**. When a later step
+fails (after its retries), the engine runs the `compensate` of every earlier
+step that completed, newest first, then the failed step's own:
 
 ```typescript
-await workflow.do(
-  'Charge',
-  'chargePayment',
-  { orderId },
-  {
-    retries: 3,
-    retryDelay: '1s',
-    onError: 'refundReservation', // compensation RPC
-  }
-)
+export const chargePayment = pikkuFunc({
+  func: async ({ payments }, { orderId }) => payments.charge(orderId),
+  compensate: async ({ payments }, { orderId }, { workflow }) => {
+    const { ok, output } = workflow!.compensatingFor!
+    // ok: false → the charge itself failed; output is null, `error` is set
+    if (ok) await payments.refund(output.chargeId)
+  },
+})
 ```
 
-The handler receives `{ error: { message } }`, and the original error is still
-thrown afterwards — so the workflow still fails. `onError` is **compensation, not
-recovery**: it exists to undo work, not to swallow the failure and carry on. If
-you genuinely need to branch on a failure, have the step return a result object
-(`{ success: false, reason }`) and branch on that, the way the `processOrder`
-example branches on `payment.success`.
-
-Full step options: `description`, `retries`, `retryDelay`, `onError` (plus
-`actor`, which is scenario-only — see `pikku-scenario`).
+- `compensate` gets the **same input** as the forward call. `wire.workflow.compensatingFor`
+  is `{ ok: true, output, stepName }` or `{ ok: false, output: null, error, stepName }`.
+- It is never callable over HTTP, MCP or RPC — only the engine runs it, as the
+  durable step `<step>:compensate` with the same retry defaults as forward steps.
+- Opt a call site out with `{ compensate: false }` (graph nodes likewise).
+- A run ends `compensated` (everything undone), `compensation_failed` (a
+  compensation ran out of retries; `stuckSteps` names them — steps that ran
+  before a stuck one are not undone, parallel siblings still are) or `failed`
+  (nothing needed undoing).
+- `await workflow.milestone('paid')` bounds the unwind: steps finished before the
+  last milestone are kept, and the run ends `compensated` with `restedAt: 'paid'`.
+- A failing child workflow unwinds itself first; a stuck child makes the parent
+  `compensation_failed`. Cancelling a run (`cancelRun`) unwinds it the same way,
+  children first.
+
+To **recover** instead of undo, use a graph node's `recover`:
+`recover: 'nodeId' | ['a','b'] | 'ignore'`. The failure is routed to those nodes
+(`'ignore'` continues to `next` with a null output) and the failing step is not
+compensated. The error arrives as `wire.graph.recoveringFrom`
+(`{ nodeId, stepName, error }`). The DSL has no recovery — branch on a result
+object (`{ success: false, reason }`) instead.
+
+Full step options: `description`, `retries`, `retryDelay`, `compensate: false`
+(plus `actor`, which is scenario-only — see `pikku-scenario`).
 
 ### Parallel fan-out
 

package/skills/pikku-workflow/references/workflow-reference.md

@@ -2,7 +2,7 @@
 
 ## Step execution: inline vs queue dispatch
 
-Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call dispatch flag. `workflow.do(...)` options are only `description`/`retries`/`retryDelay`/`onError`.
+Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call dispatch flag. `workflow.do(...)` options are only `description`/`retries`/`retryDelay`/`compensate: false`.
 
 - **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
 - **`workflowQueued: true` opts a function out.** Set it on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits. `workflowRetries` and `workflowTimeout` sit alongside it.