@pikku/skills 0.12.4 → 0.12.6

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.