@pikku/cli 0.12.90 → 0.12.92

package/skills/pikku-websocket/SKILL.md

@@ -1,243 +0,0 @@
----
-name: pikku-websocket
-description: >-
-  Use when adding real-time features, WebSocket channels, live updates, chat, or pub/sub to a
-  Pikku app. Covers wireChannel, action routing, auth, EventHub pub/sub, channel middleware, and
-  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).
----
-
-# Pikku WebSocket Wiring
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-Wire Pikku functions to WebSocket channels with structured message routing, auth per-action, pub/sub via EventHub, and auto-generated type-safe clients.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their types
-pikku info tags --verbose        # Understand project organization
-```
-
-Follow existing patterns. See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `wireChannel(config)`
-
-```typescript
-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[]>,
-    }
-  },
-  channelMiddleware?: PikkuChannelMiddleware[],
-})
-```
-
-### `pikkuChannelMiddleware(fn)`
-
-```typescript
-import { pikkuChannelMiddleware } from '@pikku/core'
-
-const middleware = pikkuChannelMiddleware(async (services, event, next) => {
-  // Transform or filter events before/after
-  await next(event) // Pass modified event, or next(null) to drop
-})
-```
-
-### `addChannelMiddleware(domain, middlewares)`
-
-```typescript
-addChannelMiddleware('todos', [addTimestamp, filterSensitive])
-```
-
-## Usage Patterns
-
-### Basic Channel
-
-```typescript
-wireChannel({
-  name: 'todos',
-  onConnect: async () => {},
-  onDisconnect: async () => {},
-  onMessageWiring: {
-    create: { func: createTodo },
-    list: { func: listTodos, auth: false },
-  },
-})
-```
-
-### Action Routing with Auth
-
-Clients send `{ action: 'create', data: {...} }`. Pikku routes to the matching function.
-
-```typescript
-const authenticate = pikkuFunc({
-  title: 'Authenticate',
-  func: async ({ setSession }, { token }) => {
-    const session = await verifyJWT(token)
-    setSession(session)
-    return { success: true }
-  },
-})
-
-wireChannel({
-  name: 'todos',
-  onConnect: async () => {},
-  onDisconnect: async () => {},
-  onMessageWiring: {
-    auth: { func: authenticate, auth: false }, // No session required
-    subscribe: { func: subscribeTodos }, // Session required
-    create: { func: createTodo },
-  },
-})
-```
-
-### Pub/Sub with EventHub
-
-Use EventHub for real-time broadcasting across connections:
-
-```typescript
-wireChannel({
-  name: 'todos',
-  onConnect: async ({ eventHub, 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 }
-        },
-      }),
-    },
-  },
-})
-```
-
-### Channel Middleware
-
-```typescript
-const addTimestamp = pikkuChannelMiddleware(
-  async ({ logger }, event, next) => {
-    logger.info({ phase: 'before-send', event })
-    await next({ ...event, sentAt: Date.now() })
-  }
-)
-
-const filterSensitive = pikkuChannelMiddleware(
-  async (_services, event, next) => {
-    if (event.internal) return await next(null)  // Drop event
-    await next(event)
-  }
-)
-
-// Apply globally to a domain
-addChannelMiddleware('todos', [addTimestamp, filterSensitive])
-
-// Or inline on wiring
-wireChannel({
-  name: 'todos',
-  channelMiddleware: [addTimestamp],
-  onConnect: async () => {},
-  onDisconnect: async () => {},
-  onMessageWiring: { ... },
-})
-```
-
-### Generated WebSocket Client
-
-After `npx pikku all`:
-
-```typescript
-import { PikkuWebSocket } from '.pikku/pikku-websocket.gen.js'
-
-const pikku = new PikkuWebSocket(ws)
-const todosRoute = pikku.getRoute('todos')
-
-// Send action (type-safe)
-const result = await todosRoute.send('create', { text: 'Buy milk' })
-
-// Subscribe to events
-todosRoute.subscribe('todos:updated', (data) => {
-  console.log(data.event, data.todo)
-})
-```
-
-## Complete Example
-
-```typescript
-// functions/chat.functions.ts
-export const authenticate = pikkuFunc({
-  title: 'Authenticate',
-  func: async ({ jwt }, { token }, { setSession }) => {
-    const payload = await jwt.verify(token)
-    setSession({ userId: payload.userId })
-    return { success: true }
-  },
-})
-
-export const sendMessage = pikkuFunc({
-  title: 'Send Message',
-  func: async ({ db, eventHub }, { text }, { session }) => {
-    const message = await db.createMessage({
-      text,
-      userId: session.userId,
-    })
-    eventHub.publish('chat:message', { message })
-    return { message }
-  },
-})
-
-export const listMessages = pikkuSessionlessFunc({
-  title: 'List Messages',
-  func: async ({ db }, { limit }) => {
-    return { messages: await db.listMessages(limit) }
-  },
-})
-
-// wirings/chat.channel.ts
-wireChannel({
-  name: 'chat',
-  onConnect: async ({ eventHub, 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 },
-  },
-})
-```

package/skills/pikku-workflow/SKILL.md

@@ -1,172 +0,0 @@
----
-name: pikku-workflow
-description: >-
-  Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku.
-  Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
-  TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
-  multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
-  when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use
-  pikku-cron).
-installGroups: [core]
----
-
-# Pikku Workflow Wiring
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Capture baseline. Run `pikku-verify` (or `pikku all`) BEFORE writing code; note existing errors — only NEW errors are yours to fix.
-2. Discover before editing. Prefer `pikku-meta` / `pikku info functions --verbose` and `pikku info tags --verbose` to see functions usable as steps and project organization; inspect only the focused output you need.
-3. Identify the source files that own the behavior. Do not start from generated output, `.pikku`, `node_modules`, vendored packages, or build artifacts.
-4. Make the smallest source change. Keep generated files generated — never hand-edit SDKs, schema output, or typegen to paper over errors; fix the source cause.
-5. Validate with the narrowest relevant command, then re-run `pikku-verify`. If only files you did not touch still error, those are pre-existing — leave them unless asked.
-6. Call `pikku-workflow-view` only when `pikku-verify` fully passes (codegen AND type check both green) — never after a partial pass.
-
-See `pikku-concepts` for the core mental model.
-
-Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
-
-## 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) |
-
-**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.
-
-### PKU641 — DSL static analysis error
-
-`pikkuWorkflowFunc` statically analyzes the body: **every `const`/`let` must be top-level, not inside any block (`if`, `for`, `while`, …).** Assignments inside blocks are fine — only declarations trigger it.
-
-```typescript
-// ❌ PKU641 — declaration inside block
-if (priority === 'high') {
-  const bugCard = await workflow.do(...)
-}
-
-// ✅ hoist the declaration, assign inside the block
-let bugCard: Awaited<ReturnType<typeof workflow.do>>
-if (priority === 'high') {
-  bugCard = await workflow.do(...)
-}
-```
-
-## Import path
-
-```typescript
-// CORRECT — workflow factories come from the generated types file
-import { pikkuWorkflowFunc, pikkuWorkflowGraph, pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
-
-// WRONG — '#pikku' does not re-export them (TS2305)
-import { pikkuWorkflowFunc } from '#pikku'
-```
-
-## Defining a workflow
-
-Declare input/output as Zod schemas (like any function) — never TypeScript generic params (no `pikkuWorkflowFunc<In, Out>(...)`; that skips runtime validation). `data` is typed from the input schema.
-
-```typescript
-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() })
-
-export const processOrder = pikkuWorkflowFunc({
-  description: 'Process an order through payment and fulfillment',
-  tags: ['orders'],
-  input: ProcessOrderInput,
-  output: ProcessOrderOutput,
-  func: async (services, data, { workflow }) => {
-    // Declare ALL variables at top level — even those only assigned in branches (PKU641)
-    let discount: number | undefined
-    let status: string
-
-    if (data.amount > 1000) {
-      const d = await workflow.do('Apply bulk discount', 'calcDiscount', { amount: data.amount })
-      discount = d.discountPercent
-    }
-
-    const payment = await workflow.do('Charge', 'chargePayment', {
-      orderId: data.orderId,
-      amount: discount ? data.amount * (1 - discount / 100) : data.amount,
-    })
-
-    if (payment.success) {
-      await workflow.do('Fulfill', 'fulfillOrder', { orderId: data.orderId })
-      status = 'fulfilled'
-    } else {
-      status = 'payment-failed'
-    }
-
-    return { status, discount }
-  },
-})
-```
-
-### Workflow step types
-
-```typescript
-// RPC step — run a registered Pikku function as a step (opts: retries, retryDelay, description)
-const result = await workflow.do('Step name', 'rpcFunctionName', { ...data }, { retries: 3, retryDelay: '1s' })
-
-// Inline closure step — immediate execution, cached for replay
-const msg = await workflow.do('Generate', async () => `Welcome, ${data.email}!`)
-
-// Sleep — durable pause (duration: '30s', '5min', '1h', '1d')
-await workflow.sleep('Wait 5 minutes', '5min')
-
-// Suspend — pause until externally resumed (e.g. awaiting approval), then continue
-await workflow.suspend('Awaiting approval')
-```
-
-### Parallel fan-out
-
-```typescript
-const users = await Promise.all(
-  data.userIds.map((userId) => workflow.do(`Fetch user ${userId}`, 'getUser', { userId }))
-)
-```
-
-### Graph workflow (DAG)
-
-`pikkuWorkflowGraph` derives types from the RPC map — no explicit `input`/`output`. Nodes map `nodeName → Pikku function name`; `config.<node>.next` lists nodes to run after it (in parallel); `config.<node>.input: (ref) => ...` transforms input using refs to prior node outputs.
-
-```typescript
-import { pikkuWorkflowGraph } from '#pikku/workflow/pikku-workflow-types.gen.js'
-
-export const userOnboarding = pikkuWorkflowGraph({
-  description: 'Onboard a new user',
-  nodes: {
-    createProfile: 'createUserProfile',
-    sendWelcome: 'sendEmail',
-    setupDefaults: 'createDefaultTodos',
-  },
-  config: {
-    createProfile: { next: ['sendWelcome', 'setupDefaults'] }, // run in parallel
-    sendWelcome: {
-      input: (ref) => ({ to: ref('createProfile', 'email'), subject: 'Welcome!' }),
-    },
-  },
-})
-```
-
-## File conventions
-
-- Place workflows in `packages/functions/src/wirings/*.workflow.ts`; export the variable so the inspector discovers it (no manual registration).
-- HTTP start/run/status routes are auto-scaffolded via `scaffold.workflow` in `pikku.config.json`.
-
-## 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`.
-
-## After writing
-
-1. `pikku-verify` (codegen + tsc).
-2. PKU641 → a `const`/`let` is inside a block; hoist it to the top of the function body.
-3. Import errors → use `#pikku/workflow/pikku-workflow-types.gen.js`, not `#pikku`.
-4. Type errors only in files you did not touch → pre-existing template errors; safe to ignore.
-5. Both green → call `pikku-workflow-view` with the workflow name.

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

@@ -1,63 +0,0 @@
-# Pikku Workflow Reference
-
-## 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`.
-
-- **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.
-- **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 |
-|---|---|---|
-| default / `true` | any | **inline** |
-| `false` | yes | **queued** (own worker) |
-| `false` | no | **inline + a `logger.warn`** (misconfiguration: can't dispatch) |
-
-```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
-  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.
-
-## HTTP workflow wiring (manual)
-
-Usually auto-scaffolded via `scaffold.workflow`. To wire by hand:
-
-```typescript
-// Start a workflow
-wireHTTP({ method: 'post', route: '/onboard', func: workflowStart('onboardUser') })
-
-// Execute workflow steps (called by the orchestrator)
-wireHTTP({ method: 'post', route: '/onboard/run', func: workflow('onboardUser') })
-
-// Check workflow status
-wireHTTP({ method: 'get', route: '/onboard/status/:runId', func: workflowStatus('onboardUser') })
-```
-
-## Suspend / resume example
-
-```typescript
-import { z } from 'zod'
-import { pikkuWorkflowFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
-
-export const approval = pikkuWorkflowFunc({
-  description: 'Submit a request and wait for approval',
-  input: z.object({ requestId: z.string() }),
-  output: z.object({ approved: z.boolean() }),
-  func: async (services, data, { workflow }) => {
-    await workflow.do('Submit request', 'submitRequest', data)
-    await workflow.suspend('Awaiting approval') // pauses here until externally resumed
-    const result = await workflow.do('Check result', 'getApprovalResult', data)
-    return { approved: result.approved }
-  },
-})
-```

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

@@ -1,150 +0,0 @@
----
-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: [core]
----
-
-# Pikku Workflows — Client Hooks
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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 has `pikkuWorkflowGraph` workflows, 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
-
-```bash
-yarn pikku meta clients --json | jq '.workflows'
-```
-
-Each entry has `name`, `description`, `mode` (inline | distributed), plus
-`input` / `output` type names. Pass the workflow **name** to the hooks
-below.
-
-## Setup
-
-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).
-
-## `useRunWorkflow(name, options?)` — run and wait
-
-For short, synchronous-feeling workflows. Returns a mutation that
-resolves to the workflow's output.
-
-```tsx
-import { useRunWorkflow } from './pikku/api.gen'
-
-function ChargeButton({ orderId }: { orderId: string }) {
-  const run = useRunWorkflow('chargeOrder', {
-    onSuccess: (output) => toast.success(`Charged: $${output.amount}`),
-  })
-  return (
-    <button onClick={() => run.mutate({ orderId })} disabled={run.isPending}>
-      {run.isPending ? 'Charging…' : 'Charge'}
-    </button>
-  )
-}
-```
-
-Use this when the workflow finishes in seconds and the UI can hold open
-a loading state until done.
-
-## `useStartWorkflow(name, options?)` — fire-and-poll
-
-Returns a mutation that resolves to `{ runId: string }` immediately. The
-workflow keeps running on the server. Pair with `useWorkflowStatus` to
-render progress.
-
-```tsx
-const start = useStartWorkflow('processVideo', {
-  onSuccess: ({ runId }) => setActiveRunId(runId),
-})
-
-start.mutate({ videoId: '123' })
-```
-
-Use this for long-running workflows (uploads, batch jobs, AI generation,
-anything you'd want a progress bar for).
-
-## `useWorkflowStatus(workflowName, runId, options?)` — observe
-
-Polls the workflow runtime for a run's status. Returns a typed status
-object with `status`, optional `output`, and optional `error`.
-
-```tsx
-import { useWorkflowStatus } from './pikku/api.gen'
-
-function VideoStatus({ runId }: { runId: string }) {
-  const { data: status } = useWorkflowStatus('processVideo', runId, {
-    refetchInterval: (query) =>
-      query.state.data?.status === 'running' ? 1000 : false,
-  })
-
-  if (!status) return null
-  if (status.status === 'running') return <Spinner />
-  if (status.status === 'completed') return <Result {...status.output} />
-  if (status.status === 'failed')
-    return <Error message={status.error?.message} />
-  return null
-}
-```
-
-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).
-
-## Putting it together — start + observe
-
-```tsx
-function ProcessVideoFlow({ videoId }: { videoId: string }) {
-  const [runId, setRunId] = useState<string>()
-  const start = useStartWorkflow('processVideo', {
-    onSuccess: ({ runId }) => setRunId(runId),
-  })
-  const status = useWorkflowStatus('processVideo', runId)
-
-  if (!runId) {
-    return (
-      <button
-        onClick={() => start.mutate({ videoId })}
-        disabled={start.isPending}
-      >
-        Start
-      </button>
-    )
-  }
-  return <ProgressBar status={status.data?.status} />
-}
-```
-
-## Backend: streaming richer progress
-
-The status hook returns a coarse-grained state machine (`running`,
-`completed`, etc.). For step-by-step updates inside a long workflow,
-publish events from the workflow itself via `eventHub` or open a
-WebSocket channel — out of scope for this skill (see workflow + channel
-docs).
-
-## What NOT to do
-
-- Don't poll status manually — use `useWorkflowStatus` with
-  `refetchInterval`. It dedupes and stops on terminal states.
-- 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.
-- Don't use these hooks for non-workflow RPCs — they only resolve
-  workflow-shaped names. Regular RPCs go through `usePikkuQuery` /
-  `usePikkuMutation`.

package/skills/pikku-ws/SKILL.md

@@ -1,47 +0,0 @@
----
-name: pikku-ws
-description: >-
-  Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime
-  adapter for Pikku channels. TRIGGER when: code uses @pikku/ws, user asks about ws library
-  WebSocket server, or Node.js WebSocket runtime. DO NOT TRIGGER when: user asks about WebSocket
-  wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).
----
-
-# Pikku WS (WebSocket Server Runtime)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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/ws` provides a WebSocket server runtime using the [ws](https://github.com/websockets/ws) library, connecting Pikku's channel system to a Node.js WebSocket server.
-
-## Installation
-
-```bash
-yarn add @pikku/ws ws
-```
-
-## Usage Patterns
-
-### Basic Setup
-
-```typescript
-import { PikkuWSServer } from '@pikku/ws'
-
-const wsServer = new PikkuWSServer({
-  server: httpServer, // Node.js HTTP server
-  singletonServices,
-  createWireServices,
-  channelStore,
-})
-
-await wsServer.init()
-```
-
-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.