@pikku/skills 0.12.2 → 0.12.6

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']),

package/skills/pikku-websocket/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   generated WebSocket client. TRIGGER when: code uses wireChannel, user asks about WebSocket,
   real-time, live updates, chat, pub/sub, or the generated WebSocket client. DO NOT TRIGGER when:
   user asks about HTTP/REST (use pikku-http), SSE (use pikku-http with sse: true), or WebSocket
-  deployment specifics (use pikku-deploy-uws).
+  deployment specifics (use pikku-deploy-uws), or typed pub/sub events (use pikku-realtime).
+installGroups: [core]
 ---
 
 # Pikku WebSocket Wiring
@@ -41,19 +42,32 @@ import { wireChannel } from '@pikku/core/channel'
 
 wireChannel({
   name: string,                      // Channel name (e.g. 'todos')
-  onConnect: async () => {},         // Called when client connects
-  onDisconnect: async () => {},      // Called when client disconnects
-  onMessageWiring: {                 // Action → function mapping
-    [actionName: string]: {
-      func: PikkuFunc,
-      auth?: boolean,                // Override channel-level auth
-      permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
+  route: string,                     // REQUIRED — the URL path (e.g. '/todos')
+  auth?: boolean,                    // Channel-level auth default
+  onConnect?: PikkuFunc,             // Called when client connects
+  onDisconnect?: PikkuFunc,          // Called when client disconnects
+  onMessage?: PikkuFunc,             // Catch-all for unrouted messages
+  onMessageWiring?: {                // TWO levels — see below
+    [messageField: string]: {
+      [fieldValue: string]: {
+        func: PikkuFunc,
+        auth?: boolean,              // Override channel-level auth
+        middleware?: PikkuMiddleware[],
+      }
     }
   },
+  middleware?: PikkuMiddleware[],
   channelMiddleware?: PikkuChannelMiddleware[],
+  binary?: boolean | null,
+  onBinaryMessage?: (services, data, channel) => ...,
+  tags?: string[],                   // Targets tag middleware
 })
 ```
 
+Note there is **no `permissions` key on a message wiring** — wire-level
+permissions were removed in #972. Authorization lives on the function's own
+`permissions` field (see `pikku-permissions`).
+
 ### `pikkuChannelMiddleware(fn)`
 
 ```typescript
@@ -78,37 +92,46 @@ addChannelMiddleware('todos', [addTimestamp, filterSensitive])
 ```typescript
 wireChannel({
   name: 'todos',
-  onConnect: async () => {},
-  onDisconnect: async () => {},
+  route: '/todos',
   onMessageWiring: {
-    create: { func: createTodo },
-    list: { func: listTodos, auth: false },
+    action: {                                  // ← the field to route on
+      create: { func: createTodo },            // ← its possible values
+      list: { func: listTodos, auth: false },
+    },
   },
 })
 ```
 
 ### Action Routing with Auth
 
-Clients send `{ action: 'create', data: {...} }`. Pikku routes to the matching function.
+`onMessageWiring` nests two levels because the routing key is configurable. The
+**outer** key names the field in the incoming message to dispatch on; the
+**inner** keys are the values that field can take. With the conventional outer
+key `action`, a client sending `{ action: 'create', data: {...} }` reaches
+`createTodo` — but a CLI channel might route on `command` instead, which is why
+the field is not hardcoded.
 
 ```typescript
-const authenticate = pikkuFunc({
+const authenticate = pikkuSessionlessFunc({
   title: 'Authenticate',
-  func: async ({ setSession }, { token }) => {
+  // setSession lives on the WIRE (third param), not on services
+  func: async (services, { token }, { setSession }) => {
     const session = await verifyJWT(token)
-    setSession(session)
+    await setSession(session)
     return { success: true }
   },
 })
 
 wireChannel({
   name: 'todos',
-  onConnect: async () => {},
-  onDisconnect: async () => {},
+  route: '/todos',
+  auth: true,
   onMessageWiring: {
-    auth: { func: authenticate, auth: false }, // No session required
-    subscribe: { func: subscribeTodos }, // Session required
-    create: { func: createTodo },
+    action: {
+      authenticate: { func: authenticate, auth: false }, // No session required
+      subscribe: { func: subscribeTodos },               // Session required
+      create: { func: createTodo },
+    },
   },
 })
 ```
@@ -120,25 +143,28 @@ Use EventHub for real-time broadcasting across connections:
 ```typescript
 wireChannel({
   name: 'todos',
-  onConnect: async ({ eventHub, channel }) => {
+  route: '/todos',
+  // eventHub is a service (1st param); channel lives on the wire (3rd)
+  onConnect: async ({ eventHub }, _data, { channel }) => {
     eventHub.subscribe('todos:updated', (data) => {
       channel.send(data)
     })
   },
-  onDisconnect: async () => {},
   onMessageWiring: {
-    create: {
-      func: pikkuFunc({
-        title: 'Create Todo',
-        func: async ({ db, eventHub }, { text }) => {
-          const todo = await db.createTodo({ text })
-          eventHub.publish('todos:updated', {
-            event: 'created',
-            todo,
-          })
-          return { todo }
-        },
-      }),
+    action: {
+      create: {
+        func: pikkuFunc({
+          title: 'Create Todo',
+          func: async ({ db, eventHub }, { text }) => {
+            const todo = await db.createTodo({ text })
+            eventHub.publish('todos:updated', {
+              event: 'created',
+              todo,
+            })
+            return { todo }
+          },
+        }),
+      },
     },
   },
 })
@@ -167,9 +193,8 @@ addChannelMiddleware('todos', [addTimestamp, filterSensitive])
 // Or inline on wiring
 wireChannel({
   name: 'todos',
+  route: '/todos',
   channelMiddleware: [addTimestamp],
-  onConnect: async () => {},
-  onDisconnect: async () => {},
   onMessageWiring: { ... },
 })
 ```
@@ -179,7 +204,7 @@ wireChannel({
 After `npx pikku all`:
 
 ```typescript
-import { PikkuWebSocket } from '.pikku/pikku-websocket.gen.js'
+import { PikkuWebSocket } from '#pikku/pikku-websocket.gen.js'
 
 const pikku = new PikkuWebSocket(ws)
 const todosRoute = pikku.getRoute('todos')
@@ -197,7 +222,7 @@ todosRoute.subscribe('todos:updated', (data) => {
 
 ```typescript
 // functions/chat.functions.ts
-export const authenticate = pikkuFunc({
+export const authenticate = pikkuSessionlessFunc({
   title: 'Authenticate',
   func: async ({ jwt }, { token }, { setSession }) => {
     const payload = await jwt.verify(token)
@@ -228,16 +253,19 @@ export const listMessages = pikkuSessionlessFunc({
 // wirings/chat.channel.ts
 wireChannel({
   name: 'chat',
-  onConnect: async ({ eventHub, channel }) => {
+  route: '/chat',
+  auth: true,
+  onConnect: async ({ eventHub }, _data, { channel }) => {
     eventHub.subscribe('chat:message', (data) => {
       channel.send(data)
     })
   },
-  onDisconnect: async () => {},
   onMessageWiring: {
-    auth: { func: authenticate, auth: false },
-    send: { func: sendMessage },
-    history: { func: listMessages, auth: false },
+    action: {
+      authenticate: { func: authenticate, auth: false },
+      send: { func: sendMessage },
+      history: { func: listMessages, auth: false },
+    },
   },
 })
 ```

package/skills/pikku-workflow/SKILL.md

@@ -121,8 +121,42 @@ await workflow.sleep('Wait 5 minutes', '5min')
 
 // Suspend — pause until externally resumed (e.g. awaiting approval), then continue
 await workflow.suspend('Awaiting approval')
+
+// Approval — suspend for a human decision and resume with the answer
+await workflow.approval('Manager sign-off', { ... })
 ```
 
+`workflow.name`, `workflow.runId` and `await workflow.getRun()` identify the
+current run if a step needs to reference it.
+
+### Error handling: `onError`, 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.
+
+Use the `onError` step option instead: it names an RPC to invoke when the step
+has failed *after* exhausting its retries.
+
+```typescript
+await workflow.do('Charge', 'chargePayment', { orderId }, {
+  retries: 3,
+  retryDelay: '1s',
+  onError: 'refundReservation',   // compensation RPC
+})
+```
+
+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`).
+
 ### Parallel fan-out
 
 ```typescript
@@ -161,7 +195,7 @@ export const userOnboarding = pikkuWorkflowGraph({
 
 ## Step dispatch & HTTP wiring
 
-For per-step inline-vs-queue dispatch (`inline: false` and the `dispatchStep` rules), the manual `workflowStart`/`workflow`/`workflowStatus` HTTP wirings, and a suspend/resume example, read `references/workflow-reference.md`.
+For per-step inline-vs-queue dispatch (`workflowQueued: true` and the `dispatchStep` rules), the manual `workflowStart`/`workflow`/`workflowStatus` HTTP wirings, and a suspend/resume example, read `references/workflow-reference.md`.
 
 ## After writing
 

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

@@ -2,31 +2,36 @@
 
 ## 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 `inline` flag. `workflow.do(...)` options are only `retries`/`retryDelay`/`description`.
+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`.
 
 - **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.
-- **`inline: false` opts a function out.** Set `inline: false` 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.
+- **`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.
 - **Run-level `inline` is separate** and only controls whether the *whole run* executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
 
 The rule (`dispatchStep`):
 
-| Function `inline` | `queueService` present? | Result |
+| Function `workflowQueued` | `queueService` present? | Result |
 |---|---|---|
-| default / `true` | any | **inline** |
-| `false` | yes | **queued** (own worker) |
-| `false` | no | **inline + a `logger.warn`** (misconfiguration: can't dispatch) |
+| default / `false` | any | **inline** |
+| `true` | yes | **queued** (own worker) |
+| `true` | no | **throws** |
 
 ```typescript
 // Push this one expensive step onto the queue; every other step stays inline:
 export const renderLargeReport = pikkuSessionlessFunc({
-  inline: false, // dispatch via queue instead of running inline
+  workflowQueued: true, // dispatch via queue instead of running inline
+  workflowRetries: 3,
+  workflowTimeout: '5m',
   input: ReportInput,
   output: ReportOutput,
   func: async (services, data) => { /* ... */ },
 })
 ```
 
-`inline: false` requires a `queueService`; without one the step still runs (so the workflow progresses) but emits a `logger.warn` so the misconfiguration is visible.
+`workflowQueued: true` **requires** a `queueService`. Without one the step throws
+rather than quietly running inline — a step marked for its own worker usually
+carries timeout and concurrency expectations that inline execution would silently
+violate, so failing loudly is safer than proceeding.
 
 ## HTTP workflow wiring (manual)
 

package/skills/pikku-workflows-client/SKILL.md

@@ -16,8 +16,8 @@ Use this skill as an execution checklist, not reference material.
 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.
 
-When a project has `pikkuWorkflowGraph` workflows, three React Query
-hooks are auto-generated alongside the standard RPC hooks. They handle
+When a project defines any workflow — DSL or `pikkuWorkflowGraph` — three
+React Query hooks are auto-generated alongside the standard RPC hooks. They handle
 the two common shapes: **run-and-wait** (short workflows where the
 client waits for the result) and **fire-and-poll** (long workflows where
 the client gets a `runId` and polls status).
@@ -103,8 +103,14 @@ function VideoStatus({ runId }: { runId: string }) {
 
 Status values: `'running' | 'suspended' | 'completed' | 'failed' | 'cancelled'`.
 
-The hook stops auto-polling when the run reaches a terminal state (set
-`refetchInterval` to false in those cases — pattern shown above).
+**Stopping the poll is your job.** The hook adds no terminal-state logic of its
+own — the `refetchInterval` callback above is what ends it, by returning `false`
+once `status` is no longer `running`. Leave that out and a finished run keeps
+being polled forever.
+
+The hook is disabled until `runId` is set, so passing `undefined` while the run
+has not started yet is the intended shape rather than something to guard around.
+That `enabled` is owned by the hook and cannot be overridden through `options`.
 
 ## Putting it together — start + observe
 
@@ -140,8 +146,9 @@ docs).
 
 ## What NOT to do
 
-- Don't poll status manually — use `useWorkflowStatus` with
-  `refetchInterval`. It dedupes and stops on terminal states.
+- Don't poll status manually with `setInterval` — use `useWorkflowStatus`
+  with a `refetchInterval` callback, which dedupes across components and
+  lets you stop on a terminal state in one place.
 - Don't call `useRunWorkflow` for workflows that take more than a few
   seconds. The user-facing component will hold a long-running pending
   state with no progress indication; use start + status instead.

package/skills/pikku-ws/SKILL.md

@@ -31,17 +31,53 @@ yarn add @pikku/ws ws
 
 ### Basic Setup
 
+The package exports one function, `pikkuWebsocketHandler` — there is no server
+class. You own the `http.Server` and the `WebSocketServer`; the handler attaches
+the upgrade and message plumbing to them.
+
 ```typescript
-import { PikkuWSServer } from '@pikku/ws'
+import { pikkuWebsocketHandler } from '@pikku/ws'
+import { stopSingletonServices } from '@pikku/core'
+import { Server } from 'http'
+import { WebSocketServer } from 'ws'
+
+import '../.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const server = new Server()
+const wss = new WebSocketServer({ noServer: true })
 
-const wsServer = new PikkuWSServer({
-  server: httpServer, // Node.js HTTP server
-  singletonServices,
-  createWireServices,
-  channelStore,
+pikkuWebsocketHandler({
+  server,
+  wss,
+  logger: singletonServices.logger,
+  logRoutes: true, // print the wired channels at startup
+  loadSchemas: true, // compile input schemas up front
 })
 
-await wsServer.init()
+server.listen(4002, 'localhost')
 ```
 
-This runtime bridges the `ws` WebSocket library with Pikku's channel wiring. See `pikku-websocket` for channel wiring details and `pikku-deploy-fastify`/`pikku-deploy-express` for integrating with HTTP servers.
+`noServer: true` is not optional decoration — the handler performs the upgrade
+itself so it can run pikku's HTTP middleware chain (auth, cors) against the
+upgrade request before a channel exists. Letting `ws` bind the server directly
+would skip that.
+
+Services come from the bootstrap import and the global singleton registry, which
+is why nothing is passed in. The event hub is taken from
+`singletonServices.eventHub` when it is a `LocalEventHubService`, and a local one
+is created otherwise — so a single-process app gets pub/sub for free, while a
+multi-instance deployment must register a distributed hub (see `pikku-realtime`).
+
+The options type also extends `RunHTTPWiringOptions`, so per-request settings
+such as `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` are accepted
+here too.
+
+On shutdown, call `stopSingletonServices()` then close `wss` and `server`.
+
+See `pikku-websocket` for channel wiring details, and
+`pikku-deploy-fastify`/`pikku-deploy-express` when the WebSocket server shares a
+port with an HTTP app.