@pikku/cli 0.12.54 → 0.12.56

package/skills/pikku-middleware/SKILL.md

@@ -77,20 +77,17 @@ wireHTTP({
 
 ## Global Middleware (`addGlobalMiddleware`)
 
-`addGlobalMiddleware` registers middleware that runs before everything else — across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns like telemetry that must wrap every invocation regardless of transport.
+Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
 
 ```typescript
 import { addGlobalMiddleware } from '@pikku/core'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
-// Outer telemetry: wraps the full call (highest priority)
-addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])
-
-// Inner telemetry: closest to the function body (lowest priority)
-addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])
+addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])  // wraps the full call
+addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])  // closest to the function body
 ```
 
-`telemetryOuter` ships with `priority: 'highest'` and `telemetryInner` with `priority: 'lowest'` — so even if both are added in the same call, priority sorting places outer first regardless of array order.
+`telemetryOuter` ships with `priority: 'highest'`, `telemetryInner` with `priority: 'lowest'` — so priority sorting places outer first regardless of array/call order.
 
 ## HTTP & Prefix Middleware (`addHTTPMiddleware`)
 
@@ -165,15 +162,13 @@ const earlyMiddleware = pikkuMiddleware({
 })
 ```
 
-Within the same priority level, registration order is preserved. Priority is the primary sort key — use it when a middleware must run before or after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
-
-## Common Patterns
+Priority is the primary sort key; within the same level, registration order is preserved. Use priority when a middleware must run before/after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
 
-### Service-to-Service Bearer Auth
+## Service-to-Service Bearer Auth (canonical pattern)
 
-The canonical pattern for a server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent):
+A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
 
-**On the server (the service being called):**
+**On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
 
 ```typescript
 // lib/host-token.ts
@@ -217,63 +212,11 @@ export const myFunc = pikkuSessionlessFunc({
 })
 ```
 
-**On the client (the caller):**
-
-Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
-
-```typescript
-import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
-
-export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
-  return async (name: string, data?: unknown) => {
-    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ data: data ?? {} }),
-    })
-    if (!res.ok) {
-      const text = await res.text().catch(() => '')
-      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
-    }
-    return res.json()
-  } as RPCInvoke
-}
-```
-
-### Session-Setting Middleware
-
-```typescript
-const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
-  if (session) return next()  // already authenticated
-
-  const header = http?.request?.header?.('x-api-key')
-  if (!header) return next()
-
-  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
-  if (row) setSession?.({ userId: row.userId })
-
-  return next()
-})
-
-addTagMiddleware('api-key-auth', [apiKeyAuth])
-```
-
-Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
+**On the client (the caller):** use the generated `RPCInvoke` type — never hand-write a `fetch` wrapper's types. See `references/middleware-patterns.md`.
 
-### Request Logging / Audit
+## More patterns
 
-```typescript
-const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
-  const start = Date.now()
-  await next()
-  await db.createAuditLog({ duration: Date.now() - start })
-})
-
-addHTTPMiddleware('/admin/*', [auditLog])
-```
+`references/middleware-patterns.md` covers the client-side `RPCInvoke` caller, session-setting middleware (set a session from an API key), and request logging / audit middleware.
 
 ## After Changes
 

package/skills/pikku-middleware/references/middleware-patterns.md

@@ -0,0 +1,61 @@
+# Middleware Patterns (extended)
+
+Detailed, less-common middleware recipes. The common-path bearer-auth pattern lives inline in SKILL.md; this file holds the client-side caller, session-setting, and audit recipes.
+
+## Service-to-Service: the client (caller) side
+
+Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
+
+```typescript
+import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
+
+export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
+  return async (name: string, data?: unknown) => {
+    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({ data: data ?? {} }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
+    }
+    return res.json()
+  } as RPCInvoke
+}
+```
+
+## Session-Setting Middleware
+
+```typescript
+const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
+  if (session) return next()  // already authenticated
+
+  const header = http?.request?.header?.('x-api-key')
+  if (!header) return next()
+
+  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
+  if (row) setSession?.({ userId: row.userId })
+
+  return next()
+})
+
+addTagMiddleware('api-key-auth', [apiKeyAuth])
+```
+
+Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
+
+## Request Logging / Audit
+
+```typescript
+const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
+  const start = Date.now()
+  await next()
+  await db.createAuditLog({ duration: Date.now() - start })
+})
+
+addHTTPMiddleware('/admin/*', [auditLog])
+```

package/skills/pikku-realtime/SKILL.md

@@ -16,16 +16,13 @@ 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.
 
-Most realtime UI is just typed pub/sub: a server pushes `todo-created`, the
-client renders it. Pikku's realtime feature ships exactly that, two ways:
+Most realtime UI is just typed pub/sub: a server pushes `todo-created`, the client
+renders it. Pikku ships exactly that, two ways — both use the same `EventHubService`
+and the same publish call, so choose by transport, not by code shape:
 
 - **WebSocket** at `/events` — one connection, many topic subscriptions.
-- **SSE** at `GET /events/:topic` — one connection per topic, auto-cleanup
-  on disconnect. Good for environments where WebSocket is blocked or for
-  trivially streaming one topic.
-
-Both transports use the same `EventHubService` and the same publish call.
-Choose by transport, not by code shape.
+- **SSE** at `GET /events/:topic` — one connection per topic, auto-cleanup on
+  disconnect. Good when WebSocket is blocked or for trivially streaming one topic.
 
 ## 1. Declare your topics
 
@@ -41,28 +38,24 @@ export type EventHubTopics = {
 }
 ```
 
-Reference it in `application-types.d.ts`:
+Reference it in `application-types.d.ts` and instantiate it in `services.ts`:
 
 ```ts
+// application-types.d.ts
 import type { EventHubService } from '@pikku/core/channel'
 import type { EventHubTopics } from './eventhub-topics.js'
 
 export interface SingletonServices extends CoreSingletonServices<Config> {
   eventHub?: EventHubService<EventHubTopics>
-  // ...
 }
-```
-
-And instantiate it in `services.ts`:
 
-```ts
+// services.ts
 import { LocalEventHubService } from '@pikku/core/channel'
-// ...
 const eventHub = new LocalEventHubService<EventHubTopics>()
 ```
 
-(For multi-instance deployments use `CloudflareEventHubService` /
-`LambdaEventHubService` / `UWSEventHubService` instead — same interface.)
+For multi-instance deployments use `CloudflareEventHubService` /
+`LambdaEventHubService` / `UWSEventHubService` instead — same interface.
 
 ## 2. Enable the server side
 
@@ -71,15 +64,13 @@ yarn pikku enable events           # auth required by default
 yarn pikku enable events --noAuth  # public events
 ```
 
-This sets `scaffold.events` in `pikku.config.json`. The next `pikku all`
-generates `events.gen.ts` in your scaffold dir, which wires:
+This sets `scaffold.events` in `pikku.config.json`. The next `pikku all` generates
+`events.gen.ts` in your scaffold dir, wiring (using whatever `eventHub` is in your
+singletons — you write neither by hand):
 
 - A WebSocket channel at `/events` handling `{action: 'subscribe' | 'unsubscribe', topic}` messages.
 - An SSE handler at `GET /events/:topic`.
 
-You don't write either by hand. They use whatever `eventHub` service is
-in your singletons.
-
 ## 3. Generate the typed client
 
 Add to `pikku.config.json`:
@@ -87,7 +78,6 @@ Add to `pikku.config.json`:
 ```jsonc
 {
   "clientFiles": {
-    // ...
     "realtimeFile": "packages/sdk/src/pikku/realtime.gen.ts",
     // Optional: full type inference for subscribe/unsubscribe
     "realtimeEventHubTopicsImport": "../../../functions/types/eventhub-topics.js#EventHubTopics",
@@ -95,8 +85,8 @@ Add to `pikku.config.json`:
 }
 ```
 
-Run `pikku all` (or `pikku realtime` to regenerate just this file). The
-generated file exports two surfaces:
+Run `pikku all` (or `pikku realtime` to regenerate just this file). The generated
+file exports two surfaces:
 
 ```ts
 export class PikkuRealtime {
@@ -112,13 +102,15 @@ export function subscribeToTopicViaSSE<K extends keyof EventHubTopics>(
 ```
 
 Without `realtimeEventHubTopicsImport`, the client falls back to
-`Record<string, unknown>` — usable but untyped. Set the import for full
-typed subscribe/unsubscribe.
+`Record<string, unknown>` — usable but untyped. Set the import for full typed
+subscribe/unsubscribe.
 
 ## 4. Publish events from a function
 
-The `/events` channel listens for client subscriptions; the eventHub fans
-out publishes. Functions publish like this:
+The `/events` channel listens for client subscriptions; the eventHub fans out
+publishes. Envelope the payload with `topic` so the client dispatcher works; the
+`null` channelId means "broadcast to all subscribers" (pass a specific channel id
+to exclude/include a single connection):
 
 ```ts
 import { pikkuFunc } from '#pikku'
@@ -128,47 +120,35 @@ export const createTodo = pikkuFunc({
   output: CreateTodoOutput,
   func: async ({ kysely, eventHub }, data) => {
     const todo = await kysely
-      .insertInto('todos')
-      .values(data)
-      .returningAll()
+      .insertInto('todos').values(data).returningAll()
       .executeTakeFirstOrThrow()
 
     if (eventHub) {
-      // Envelope the payload with `topic` so the client dispatcher works.
       await eventHub.publish('todo-created', null, {
         topic: 'todo-created',
         data: { todo },
       })
     }
-
     return { id: todo.id }
   },
 })
 ```
 
-The `null` channelId means "broadcast to all subscribers." Pass a
-specific channel id to exclude/include a single connection.
-
 A thin helper removes the duplication:
 
 ```ts
 async function publishEvent<K extends keyof EventHubTopics>(
-  hub: EventHubService<EventHubTopics>,
-  topic: K,
-  data: EventHubTopics[K]
+  hub: EventHubService<EventHubTopics>, topic: K, data: EventHubTopics[K]
 ) {
   return hub.publish(topic, null, { topic, data })
 }
-
-// usage:
-await publishEvent(eventHub, 'todo-created', { todo })
+// usage: await publishEvent(eventHub, 'todo-created', { todo })
 ```
 
 ## 5. Wire it up — share fetch with PikkuRPC
 
-`PikkuRealtime` mirrors `PikkuRPC`: it wraps the same `PikkuFetch`, so
-server URL + auth are configured **once** and shared across HTTP, RPC,
-and realtime transports.
+`PikkuRealtime` mirrors `PikkuRPC`: it wraps the same `PikkuFetch`, so server URL +
+auth are configured **once** and shared across HTTP, RPC, and realtime transports.
 
 ```tsx
 import { createPikku, PikkuProvider } from '@pikku/react'
@@ -185,9 +165,7 @@ const pikku = createPikku(
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
 
 createRoot(document.getElementById('root')!).render(
-  <PikkuProvider pikku={pikku}>
-    <App />
-  </PikkuProvider>
+  <PikkuProvider pikku={pikku}><App /></PikkuProvider>
 )
 ```
 
@@ -200,64 +178,38 @@ realtime.setPikkuFetch(pikku.fetch) // inherits serverUrl + auth
 
 ## 6. Subscribe from React
 
+Subscribe inside `useEffect` (never the render path, or you create a subscription
+per render). `subscribe` returns an unsubscribe function; SSE's `subscribeToTopic`
+returns a handle with `close()`:
+
 ```tsx
 import { useEffect, useState } from 'react'
 
 function TodoList() {
-  const { realtime } = usePikku() // assuming you expose a hook over your context
+  const { realtime } = usePikku() // a hook over your context
   const [todos, setTodos] = useState<Todo[]>([])
 
   useEffect(() => {
-    const off = realtime.subscribe('todo-created', ({ todo }) => {
-      setTodos((prev) => [...prev, todo])
-    })
+    // WebSocket multi-topic:
+    const off = realtime.subscribe('todo-created', ({ todo }) =>
+      setTodos((prev) => [...prev, todo]))
     return off
+
+    // Single-topic SSE (auto-cleanup on close) instead:
+    // const sub = realtime.subscribeToTopic('todo-created', ({ todo }) =>
+    //   setTodos((prev) => [...prev, todo]))
+    // return () => sub.close()
   }, [realtime])
 
-  return (
-    <ul>
-      {todos.map((t) => (
-        <li key={t.id}>{t.title}</li>
-      ))}
-    </ul>
-  )
+  return <ul>{todos.map((t) => <li key={t.id}>{t.title}</li>)}</ul>
 }
 ```
 
-Single-topic SSE (auto-cleanup on close):
-
-```tsx
-useEffect(() => {
-  const sub = realtime.subscribeToTopic('todo-created', ({ todo }) => {
-    setTodos((prev) => [...prev, todo])
-  })
-  return () => sub.close()
-}, [realtime])
-```
-
-## Subscribing to other SSE / WebSocket routes
-
-Same client also handles generic SSE + channel routes — use the path,
-the base URL is inherited from PikkuFetch:
-
-```ts
-// Any sse: true HTTP route
-const sub = realtime.subscribeToSSE<{ progress: number }>(
-  `/workflow-run/${runId}/stream`,
-  (event) => setProgress(event.progress)
-)
-// later: sub.close()
-
-// Any wireChannel — open a raw socket, wrap in PikkuWebSocket for typed I/O
-const ws = realtime.connectToChannel('/ws/kanban')
-const typed = new PikkuWebSocket<'kanban-live'>(ws)
-typed.getRoute('command').subscribe('message', (data) => {
-  /* ... */
-})
-```
+## Other SSE / WebSocket routes
 
-Discover what's available with `pikku meta clients --json` — `channels`
-and any HTTP `sse: true` routes are listed there.
+The same client also subscribes to generic `sse: true` routes and raw `wireChannel`
+sockets (`subscribeToSSE`, `connectToChannel`). See
+[references/other-routes.md](references/other-routes.md).
 
 ## When to pick which transport
 
@@ -268,18 +220,17 @@ and any HTTP `sse: true` routes are listed there.
 | Bidirectional (client also sends messages) | **PikkuRealtime**             |
 | WebSockets blocked by infra                | **subscribeToTopicViaSSE**    |
 
-Both auto-clean on the server (the eventHub's `onChannelClosed` hook
-unsubscribes all topics for the dead channel id). Don't write manual
-cleanup unless you're unsubscribing partway through a session.
+Both auto-clean on the server (the eventHub's `onChannelClosed` hook unsubscribes
+all topics for the dead channel id). Don't write manual cleanup unless you're
+unsubscribing partway through a session.
 
 ## What NOT to do
 
-- Don't call `eventHub.publish(topic, ..., rawData)` without the
-  `{topic, data}` envelope — clients use `topic` to dispatch handlers.
-- Don't create your own `/events` channel by hand — `pikku enable events`
-  already does it correctly with disconnect cleanup.
-- Don't subscribe inside the render path — use `useEffect`. Otherwise
-  you'll create a subscription per render.
-- Don't subscribe to topics that don't exist in `EventHubTopics`. The
-  generated client's types prevent it; if you find yourself reaching for
-  `as any` to subscribe to a string, declare the topic first.
+- Don't call `eventHub.publish(topic, ..., rawData)` without the `{topic, data}`
+  envelope — clients use `topic` to dispatch handlers.
+- Don't create your own `/events` channel by hand — `pikku enable events` already
+  does it correctly with disconnect cleanup.
+- Don't subscribe inside the render path — use `useEffect`.
+- Don't subscribe to topics that don't exist in `EventHubTopics`. The generated
+  client's types prevent it; if you reach for `as any` to subscribe to a string,
+  declare the topic first.

package/skills/pikku-realtime/references/other-routes.md

@@ -0,0 +1,23 @@
+# Subscribing to other SSE / WebSocket routes
+
+The same `PikkuRealtime` client also handles generic SSE + channel routes (not just
+`/events` topics). Use the path; the base URL is inherited from `PikkuFetch`.
+
+```ts
+// Any `sse: true` HTTP route
+const sub = realtime.subscribeToSSE<{ progress: number }>(
+  `/workflow-run/${runId}/stream`,
+  (event) => setProgress(event.progress)
+)
+// later: sub.close()
+
+// Any wireChannel — open a raw socket, wrap in PikkuWebSocket for typed I/O
+const ws = realtime.connectToChannel('/ws/kanban')
+const typed = new PikkuWebSocket<'kanban-live'>(ws)
+typed.getRoute('command').subscribe('message', (data) => {
+  /* ... */
+})
+```
+
+Discover what's available with `pikku meta clients --json` — `channels` and any HTTP
+`sse: true` routes are listed there.