@pikku/skills 0.12.22 → 0.12.26

package/skills/{pikku-react-query/SKILL.md → pikku-react/references/react-query.md}

@@ -1,25 +1,5 @@
----
-name: pikku-react-query
-description: 'Use the Pikku auto-generated React Query hooks (`usePikkuQuery`, `usePikkuMutation`, `usePikkuInfiniteQuery`) to call backend RPC functions from a React frontend with full type safety. TRIGGER when: writing React components that need to call a Pikku function, fetch data, mutate data, or paginate; user mentions React Query, useQuery, useMutation, or building a frontend that talks to a Pikku backend. DO NOT TRIGGER when: working on the backend (use pikku-rpc / pikku-feature) or wiring a non-React frontend.'
-installGroups: [client, fabric]
----
-
 # Pikku React Query Hooks
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-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.
-
-Pikku generates a typed React Query layer from your backend `expose: true`
-functions. You don't write `useQuery`/`useMutation` against `fetch`
-yourself — you call hooks named after RPCs and get full type inference for
-input + output.
 
 ## Discover what's available on the client
 
@@ -77,7 +57,7 @@ The two generated files come from `pikku.config.json`'s
 `clientFiles.fetchFile` and `clientFiles.rpcWiringsFile`. Hooks live in
 the file at `clientFiles.reactQueryFile` (typically `api.gen.ts`).
 
-`apiUrl()` is the shared server-URL helper — see **pikku-react**. Never
+`apiUrl()` is the shared server-URL helper — see `references/client.md`. Never
 inline `?? 'http://localhost:3000'`: a deploy that supplies the URL as a
 runtime binding leaves `import.meta.env.VITE_API_URL` undefined in the
 bundle, so the fallback is the branch that actually runs.
@@ -206,7 +186,7 @@ instead.
 When the project defines any workflow, the same file also gains
 `useStartWorkflow(name)` (mutation → `{ runId }`), `useRunWorkflow(name)`
 (mutation → the workflow's output) and `useWorkflowStatus(name, runId?)` (query,
-disabled until `runId` is set). See the **pikku-workflows-client** skill.
+disabled until `runId` is set). See `references/workflows.md`.
 
 ## Calling RPCs without React Query
 

package/skills/{pikku-workflows-client/SKILL.md → pikku-react/references/workflows.md}

@@ -1,26 +1,5 @@
----
-name: pikku-workflows-client
-description: 'Run Pikku workflows from a React frontend and track their progress. Covers `useRunWorkflow` (run-and-wait), `useStartWorkflow` (fire-and-poll), and `useWorkflowStatus` (live status). TRIGGER when: a React component needs to invoke or display the status of a Pikku workflow, the user mentions long-running tasks / background jobs / progress UI tied to a workflow, or asks how to start/track a workflow from the client. DO NOT TRIGGER when: the user is wiring the workflow itself (use pikku-workflow) or only making regular RPC calls (use pikku-react-query).'
-installGroups: [client]
----
-
 # Pikku Workflows — Client Hooks
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-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 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).
 
 ## Discover what workflows exist
 
@@ -36,7 +15,7 @@ below.
 
 These hooks are generated into the same `api.gen.ts` as `usePikkuQuery` —
 no extra setup beyond `PikkuProvider` + `QueryClientProvider` (see the
-**pikku-react** and **pikku-react-query** skills).
+`references/client.md` and `references/react-query.md`).
 
 ## `useRunWorkflow(name, options?)` — run and wait
 

package/skills/pikku-realtime/SKILL.md

@@ -1,288 +1,147 @@
 ---
 name: pikku-realtime
-description: 'Use Pikku''s realtime feature — typed pub/sub events over WebSocket (multi-topic) or SSE (single-topic, auto-cleanup). Covers declaring EventHubTopics, scaffolding the /events channel, the auto-generated `PikkuRealtime` client, and publishing events from a function. TRIGGER when: the user asks for realtime updates, pub/sub, push notifications, server-sent events, websocket events, eventhub, or "live" data on the frontend. DO NOT TRIGGER when: the user wants RPC-style request/response (use pikku-rpc / pikku-react-query) or a custom one-off WebSocket channel (use pikku-websocket).'
+description: >-
+  Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
+  TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
+  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (that is pikku-schedule/pikku-workflow).
+installGroups: [core, client]
 ---
 
-# Pikku Realtime
+# Pikku Realtime (SSE + WebSocket channels)
 
-## Agent Operating Procedure
+There is NOTHING to hand-roll and NOTHING to "find". The event-hub SSE transport
+is already wired into every app, and the two patterns below ARE the realtime
+templates. Start from them and rename — never grep the project for existing
+`sse`/`eventHub` code to copy, never write a custom `EventSource`, and never
+write a bespoke `sse: true` route for a plain live feed.
 
-Use this skill as an execution checklist, not reference material.
+## Pick the transport (almost always SSE)
 
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-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.
+- **Server → client live updates → SSE via the event-hub.** This is the DEFAULT
+  for making any view live: a board, list, dashboard, ticker, feed, or a "room"
+  (a bidding room, sale room, live auction). The client only RECEIVES — the
+  change itself happens through a NORMAL HTTP RPC (`placeBid`, `updateLot`, …)
+  that publishes the new row.
+- **Client → server push mid-session → a WebSocket channel.** ONLY when the
+  BROWSER must send up the socket without a page action: live chat messages,
+  typing indicators, cursors/presence.
 
-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:
+A screen being called a "room", or being multi-user, or being live is NOT a
+reason to use a channel. If the browser isn't pushing frames up, it's SSE.
 
-- **WebSocket** at `/events` — one connection, many topic subscriptions.
-- **SSE** at `GET /events/:topic` — one connection per topic, auto-cleanup on
-  disconnect. Good when WebSocket is blocked or for trivially streaming one topic.
+## Level 1 — live updates (event-hub SSE, the default)
 
-## 1. Declare your topics
+Two halves; both are required or nothing arrives.
 
-In your project's types file (e.g. `types/eventhub-topics.d.ts`):
+**Backend — publish after every write.** In each create/update/status function,
+AFTER the DB write, publish the changed row on a topic:
 
 ```ts
-import type { Todo } from '../src/schemas.js'
-
-export type EventHubTopics = {
-  'todo-created': { todo: Todo }
-  'todo-updated': { todo: Todo }
-  'todo-deleted': { todoId: string }
-}
-```
-
-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> {
-  // `CoreSingletonServices` declares eventHub optional; re-declare it required
-  // so functions can use it without a `if (eventHub)` guard on every publish.
-  eventHub: EventHubService<EventHubTopics>
-}
-
-// services.ts
-import { LocalEventHubService } from '@pikku/core/channel'
-const eventHub = new LocalEventHubService<EventHubTopics>()
-```
-
-For multi-instance deployments use `CloudflareEventHubService` /
-`LambdaEventHubService` / `UWSEventHubService` instead — same interface.
-
-If a deployment genuinely has no eventHub, that belongs in `services.ts` (don't
-create the service there), not as an optional type every function has to guard —
-see `pikku-services`.
-
-## 2. Enable the server side
-
-```bash
-yarn pikku enable events
+const lot = await kysely
+  .updateTable('lot')
+  .set({ status: 'sold' })
+  .where('id', '=', input.lotId)
+  .returning(['id', 'status', 'currentBid', 'updatedAt'])
+  .executeTakeFirstOrThrow()
+await eventHub.publish('lot-updated', null, { topic: 'lot-updated', data: lot })
+return lot
 ```
 
-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`.
-
-## 3. Generate the typed client
+**A topic is PUBLIC — publish a projection, never `returningAll()`.** The generated
+`/events/:topic` route is wired `auth: false` with a sessionless handler, so anyone who can
+reach the origin can subscribe to any topic name and read every frame on it. `returningAll()`
+then ships the whole row — `reservePrice`, `sellerId`, internal notes, whatever the table
+grows next — to unauthenticated subscribers, and it does it silently because the RPC's own
+`output` schema never sees the event payload. List the columns the topic is FOR, the way the
+example does. If a change genuinely has per-viewer content, it does not belong on a topic:
+publish an id-only "something changed" frame and let each client refetch through an
+authenticated RPC that applies its own permissions.
+
+The **2nd arg is the channel to EXCLUDE** from the broadcast: pass `null` from a
+normal HTTP/RPC write (there is no one to skip); pass `channel.channelId` ONLY
+when you publish from INSIDE a channel handler, or the sender gets an echo of its
+own update. `eventHub` is already injected — do not wire it.
+
+**Frontend — subscribe over SSE.** The generated
+`PikkuRealtime.subscribeToTopic(topic, handler)` opens an SSE stream to the
+built-in `/events/:topic` route. Seed state from a normal query, then patch it as
+events arrive; the event is the `{ topic, data }` envelope, so read `.data`.
 
-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",
-  },
-}
-```
-
-Run `pikku all` (or `pikku realtime` to regenerate just this file). Everything is
-on one class — both transports are methods, so switching from WebSocket to SSE is
-a one-word change, not a different import:
-
-```ts
-export class PikkuRealtime {
-  constructor(options?: {
-    reconnect?: boolean
-    reconnectDelayMs?: number
-    reconnectMaxDelayMs?: number
-  })
-  setPikkuFetch(fetch: PikkuFetch): void // server URL + auth come from here, not the constructor
-
-  // WebSocket at /events — many topics on one connection
-  subscribe<K extends keyof EventHubTopics>(
-    topic: K,
-    handler: (data: EventHubTopics[K]) => void
-  ): () => void
-  unsubscribe<K extends keyof EventHubTopics>(
-    topic: K,
-    handler?: (data: EventHubTopics[K]) => void
-  ): void
-
-  // SSE at GET /events/:topic — one EventSource per topic
-  subscribeToTopic<K extends keyof EventHubTopics>(
-    topic: K,
-    handler: (data: EventHubTopics[K]) => void
-  ): { close: () => void }
+```tsx
+import { useEffect } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { realtime } from '../lib/pikku'
 
-  // generic escape hatches — see references/other-routes.md
-  subscribeToSSE<T>(
-    path: string,
-    handler: (data: T) => void
-  ): { close: () => void }
-  connectToChannel(
-    channelRoute: string,
-    protocols?: string | string[]
-  ): WebSocket
+export function useLiveLots() {
+  const queryClient = useQueryClient()
 
-  close(): void
+  useEffect(() => {
+    const subscription = realtime.subscribeToTopic('lot-updated', () => {
+      queryClient.invalidateQueries({ queryKey: ['listLots'] })
+    })
+    return () => subscription.close()
+  }, [queryClient])
 }
 ```
 
-Without `realtimeEventHubTopicsImport`, the client falls back to
-`Record<string, unknown>` — usable but untyped. Set the import for full typed
-subscribe/unsubscribe.
+**Invalidate; do not hand-patch the cache.** The generated hooks key a query as
+`[name, input]` — `['listLots', { status: 'open', cursor: undefined }]`, one entry per set of
+arguments — so `setQueryData(['listLots'], …)` writes to a key nothing reads and the screen
+never changes. `invalidateQueries({ queryKey: ['listLots'] })` prefix-matches, so it refreshes
+every variant of that list whatever input each one was fetched with.
 
-## 4. Publish events from a function
+Patching also has to know the payload's shape, and a list RPC returns
+`ListOutput<Lot>` — `{ rows, nextCursor, totalCount? }`, not `Lot[]` — so a `rows.map(...)`
+updater is reading `.map` off an object. Refetching sidesteps both, and it re-applies the server's own filtering,
+which a locally patched row does not: a lot that just moved to `sold` may no longer belong in
+an "open lots" list at all.
 
-The `/events` channel listens for client subscriptions; the eventHub fans out
-publishes:
-
-```ts
-publish(topic, channelId: string | null, data, isBinary?)
-```
+`subscribeToTopic` returns `{ close }` — ALWAYS close on unmount or you leak the
+stream. Never hand-roll an `EventSource`.
 
-The middle argument is the channel to **skip**, not the one to send to — pass
-`null` to reach every subscriber, or the current `channel.channelId` when the
-originating connection has already applied the change locally and would otherwise
-render it twice.
+## Level 2 — two-way channel
 
-Envelope the payload as `{ topic, data }`: the generated client dispatches on the
-`topic` field, so a bare payload arrives but no handler fires.
+Only when the client pushes up the socket. The backend channel lives in its own
+`*.channel.ts` with `onConnect`/`onMessage` handlers:
 
 ```ts
-import { pikkuFunc } from '#pikku/function'
+import { pikkuChannelFunc, wireChannel } from '#pikku/channel'
 
-export const createTodo = pikkuFunc({
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  func: async ({ kysely, eventHub }, data) => {
-    const todo = await kysely
-      .insertInto('todos')
-      .values(data)
-      .returningAll()
-      .executeTakeFirstOrThrow()
-
-    await eventHub.publish('todo-created', null, {
-      topic: 'todo-created',
-      data: { todo },
-    })
-    return { id: todo.id }
+export const onMessage = pikkuChannelFunc<{ text: string }>({
+  func: async ({ eventHub }, input, { channel, session }) => {
+    const message = { id: crypto.randomUUID(), text: input.text, userId: session!.userId }
+    await eventHub.publish('room', channel.channelId, { topic: 'room', data: message })
+    return message
   },
 })
-```
-
-A thin helper removes the duplication:
-
-```ts
-async function publishEvent<K extends keyof EventHubTopics>(
-  hub: EventHubService<EventHubTopics>,
-  topic: K,
-  data: EventHubTopics[K]
-) {
-  return hub.publish(topic, null, { topic, data })
-}
-// 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.
-
-```tsx
-import { createPikku, PikkuProvider } from '@pikku/react'
-import { PikkuFetch } from './pikku/pikku-fetch.gen'
-import { PikkuRPC } from './pikku/pikku-rpc.gen'
-import { PikkuRealtime } from './pikku/realtime.gen'
-
-const pikku = createPikku(
-  PikkuFetch,
-  PikkuRPC,
-  PikkuRealtime, // pass the realtime class as the third arg
-  { serverUrl: apiUrl() } // shared env helper — see pikku-react
-)
-// pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
-
-createRoot(document.getElementById('root')!).render(
-  <PikkuProvider pikku={pikku}>
-    <App />
-  </PikkuProvider>
-)
-```
 
-Or wire manually:
-
-```ts
-const realtime = new PikkuRealtime()
-realtime.setPikkuFetch(pikku.fetch) // inherits serverUrl + auth
+wireChannel({ name: 'room', route: '/room', auth: true, onMessage })
 ```
 
-## 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()`:
+The frontend opens it with `PikkuRealtime.connectToChannel(path)`, which returns
+a socket you both `.send(...)` on and read via `onmessage`:
 
 ```tsx
-import { useEffect, useState } from 'react'
-
-function TodoList() {
-  const { realtime } = usePikku() // a hook over your context
-  const [todos, setTodos] = useState<Todo[]>([])
-
-  useEffect(() => {
-    // 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>
-  )
-}
+useEffect(() => {
+  const socket = realtime.connectToChannel('/room')
+  socket.onmessage = (event) => appendMessage(JSON.parse(event.data))
+  return () => socket.close()
+}, [])
 ```
 
-## Other SSE / WebSocket routes
-
-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
-
-| Need                                       | Use                         |
-| ------------------------------------------ | --------------------------- |
-| Many topics in one connection              | `realtime.subscribe`        |
-| Single live stream, simple cleanup         | `realtime.subscribeToTopic` |
-| Bidirectional (client also sends messages) | `realtime.subscribe`        |
-| WebSockets blocked by infra                | `realtime.subscribeToTopic` |
-
-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`.
-- 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.
+Publish server→client fan-out from a channel handler with
+`eventHub.publish(topic, channel.channelId, envelope)` — the 2nd arg excludes the
+sender, so the browser that sent the message does not receive its own echo.
+
+## Do NOT
+
+- Do **not** grep the project for existing SSE/eventHub infra to reverse-engineer
+  or copy — the patterns above ARE the template (same rule as never reading
+  `.gen.ts` to learn an API).
+- Do **not** write a custom `sse: true` HTTP route or a bespoke `EventSource` for
+  an ordinary live feed — the event-hub covers it. (A dedicated `sse: true` route
+  is only for a long-job PROGRESS stream, and is not needed for an initial build.)
+- Do **not** use a WebSocket channel for a live board/ticker/room — that is SSE.
+  A channel is for client→server push (chat/presence) ONLY.
+- Do **not** forget the backend `eventHub.publish(...)` — a subscribed frontend
+  with no publisher is a silent, empty stream.