@pikku/skills 0.12.4 → 0.12.8

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

@@ -29,11 +29,11 @@ Build durable, multi-step workflows with automatic retry, sleep, suspend/resume,
 
 ## Choosing the right factory
 
-| Factory | When to use | Step-graph view? |
-|---|---|---|
-| `pikkuWorkflowFunc` | **Default for all new workflows.** Sequential + conditional logic; DSL mode (serialisable, replay-safe). ALL `const`/`let` declarations must be at the top level of the function body (not inside blocks). | ✅ Yes |
-| `pikkuWorkflowGraph` | DAG / fan-out with nodes and typed refs between them. | ✅ Yes |
-| `pikkuWorkflowComplexFunc` | Escape hatch only — arbitrary TypeScript, no top-level restriction (e.g. dynamic inline functions the DSL extractor cannot handle). | ❌ No (loses step-graph view) |
+| Factory                    | When to use                                                                                                                                                                                                | Step-graph view?              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `pikkuWorkflowFunc`        | **Default for all new workflows.** Sequential + conditional logic; DSL mode (serialisable, replay-safe). ALL `const`/`let` declarations must be at the top level of the function body (not inside blocks). | ✅ Yes                        |
+| `pikkuWorkflowGraph`       | DAG / fan-out with nodes and typed refs between them.                                                                                                                                                      | ✅ Yes                        |
+| `pikkuWorkflowComplexFunc` | Escape hatch only — arbitrary TypeScript, no top-level restriction (e.g. dynamic inline functions the DSL extractor cannot handle).                                                                        | ❌ No (loses step-graph view) |
 
 **Default to `pikkuWorkflowFunc`.** Use `pikkuWorkflowGraph` ONLY with explicit user approval AND only for a genuine cyclic dependency or Node.js-only import DSL cannot express. Use `pikkuWorkflowComplexFunc` ONLY with explicit user approval — a last-resort escape hatch. Never switch to either just to dodge a PKU641 error; restructure the code instead.
 
@@ -58,7 +58,11 @@ if (priority === 'high') {
 
 ```typescript
 // CORRECT — workflow factories come from the generated types file
-import { pikkuWorkflowFunc, pikkuWorkflowGraph, pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import {
+  pikkuWorkflowFunc,
+  pikkuWorkflowGraph,
+  pikkuWorkflowComplexFunc,
+} from '#pikku/workflow/pikku-workflow-types.gen.js'
 
 // WRONG — '#pikku' does not re-export them (TS2305)
 import { pikkuWorkflowFunc } from '#pikku'
@@ -73,7 +77,10 @@ import { z } from 'zod'
 import { pikkuWorkflowFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
 const ProcessOrderInput = z.object({ orderId: z.string(), amount: z.number() })
-const ProcessOrderOutput = z.object({ status: z.string(), discount: z.number().optional() })
+const ProcessOrderOutput = z.object({
+  status: z.string(),
+  discount: z.number().optional(),
+})
 
 export const processOrder = pikkuWorkflowFunc({
   description: 'Process an order through payment and fulfillment',
@@ -86,7 +93,9 @@ export const processOrder = pikkuWorkflowFunc({
     let status: string
 
     if (data.amount > 1000) {
-      const d = await workflow.do('Apply bulk discount', 'calcDiscount', { amount: data.amount })
+      const d = await workflow.do('Apply bulk discount', 'calcDiscount', {
+        amount: data.amount,
+      })
       discount = d.discountPercent
     }
 
@@ -121,13 +130,113 @@ 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.
+
+### Approval gates: who may answer
+
+`workflow.approval(reason, options)` takes a `schema` (a runtime value — the
+payload arrives from an untrusted caller, so a type generic would validate
+nothing), an optional `expiry`, and an optional policy for **who** may answer:
+
+```typescript
+const signOff = await workflow.approval('Manager sign-off', {
+  schema: SignOffSchema,
+  expiry: '3d',
+  approvers: 'not-initiator',      // four-eyes: anyone but whoever started the run
+  approverScope: 'payments:approve', // and they must hold this scope
+})
+if (signOff.status === 'expired') { ... }
 ```
 
+`approvers` is one of:
+
+| value             | who may answer                                                                                           |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `any` _(default)_ | anyone the approve entrypoint admits — the gate is a pause for a decision, not an authorization boundary |
+| `owner`           | only the user who started the run                                                                        |
+| `not-initiator`   | anyone **except** the user who started the run                                                           |
+
+Both options are enforced in two phases, because a decision can legitimately
+arrive before the run has reached the gate:
+
+- **At submission**, if the run has already reached the gate. Reaching it
+  publishes the policy into the run state, so the approve entrypoint can judge
+  the caller against it and refuse with a **403**.
+- **On replay**, for a decision that arrived before the gate — there was no
+  policy to judge it against yet, so it is accepted and judged when the workflow
+  reaches the gate. Failing there discards the decision and leaves the gate
+  closed, exactly as a decision that fails the schema does.
+
+So the same rejected decision surfaces as an HTTP error or as a silently
+re-closed gate depending on timing. Both are audited.
+
+A gate declaring neither option accepts a decision from anyone the approve
+route lets through; gate the route with `auth`/`permissions` to narrow that.
+
+#### What survives the run
+
+A settled decision carries `decidedBy` and `decidedAt`, so the answer keeps its
+provenance in the step result:
+
+```typescript
+if (signOff.status === 'decided') {
+  logger.info(`signed by ${signOff.decidedBy?.userId} at ${signOff.decidedAt}`)
+}
+```
+
+That record is deleted with the run, though — `deleteRun` cascades to steps and
+history — and an attempt that was _refused_ never reaches a step at all. So
+every answer is also written to the audit sink as `workflow.approval.decided`,
+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
+
+**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
 const users = await Promise.all(
-  data.userIds.map((userId) => workflow.do(`Fetch user ${userId}`, 'getUser', { userId }))
+  data.userIds.map((userId) =>
+    workflow.do(`Fetch user ${userId}`, 'getUser', { userId })
+  )
 )
 ```
 
@@ -148,7 +257,10 @@ export const userOnboarding = pikkuWorkflowGraph({
   config: {
     createProfile: { next: ['sendWelcome', 'setupDefaults'] }, // run in parallel
     sendWelcome: {
-      input: (ref) => ({ to: ref('createProfile', 'email'), subject: 'Welcome!' }),
+      input: (ref) => ({
+        to: ref('createProfile', 'email'),
+        subject: 'Welcome!',
+      }),
     },
   },
 })
@@ -161,7 +273,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.