@pikku/cli 0.12.91 → 0.12.92

package/skills/pikku-realtime/SKILL.md

@@ -1,236 +0,0 @@
----
-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).'
-installGroups: [core]
----
-
-# Pikku Realtime
-
-## 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.
-
-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 when WebSocket is blocked or for trivially streaming one topic.
-
-## 1. Declare your topics
-
-In your project's types file (e.g. `types/eventhub-topics.d.ts`):
-
-```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> {
-  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.
-
-## 2. Enable the server side
-
-```bash
-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, 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
-
-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). The generated
-file exports two surfaces:
-
-```ts
-export class PikkuRealtime {
-  constructor(options: { url: string; reconnect?: boolean; ... })
-  subscribe<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): () => void
-  unsubscribe<K extends keyof EventHubTopics>(topic: K, handler?: ...): void
-  close(): void
-}
-
-export function subscribeToTopicViaSSE<K extends keyof EventHubTopics>(
-  baseUrl: string, topic: K, handler: (data: EventHubTopics[K]) => void
-): { close: () => void }
-```
-
-Without `realtimeEventHubTopicsImport`, the client falls back to
-`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. 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'
-
-export const createTodo = pikkuFunc({
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  func: async ({ kysely, eventHub }, data) => {
-    const todo = await kysely
-      .insertInto('todos').values(data).returningAll()
-      .executeTakeFirstOrThrow()
-
-    if (eventHub) {
-      await eventHub.publish('todo-created', null, {
-        topic: 'todo-created',
-        data: { todo },
-      })
-    }
-    return { id: todo.id }
-  },
-})
-```
-
-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
-```
-
-## 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() // 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>
-}
-```
-
-## 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              | **PikkuRealtime** (WebSocket) |
-| Single live stream, simple cleanup         | **subscribeToTopicViaSSE**    |
-| 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.
-
-## 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.

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

@@ -1,23 +0,0 @@
-# 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.

package/skills/pikku-redis/SKILL.md

@@ -1,90 +0,0 @@
----
-name: pikku-redis
-description: >-
-  Use when setting up Redis-backed services in a Pikku app. Covers channel stores, workflow
-  services, secret services, event hubs, agent runs, and deployment services backed by Redis.
-  TRIGGER when: code uses RedisChannelStore, RedisWorkflowService, RedisSecretService, or user
-  asks about Redis setup with Pikku. DO NOT TRIGGER when: user asks about BullMQ queues (use
-  pikku-queue) or SQL databases (use pikku-kysely).
----
-
-# Pikku Redis
-
-## 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/redis` provides Redis-backed implementations of Pikku's core service interfaces using [ioredis](https://github.com/redis/ioredis).
-
-## Installation
-
-```bash
-yarn add @pikku/redis
-```
-
-## API Reference
-
-### Available Services
-
-All services accept a Redis connection (ioredis `Redis` instance, `RedisOptions`, or connection string) in their constructor.
-
-| Service                   | Interface              | Purpose                                        |
-| ------------------------- | ---------------------- | ---------------------------------------------- |
-| `RedisChannelStore`       | `ChannelStore`         | WebSocket channel state persistence            |
-| `RedisEventHubStore`      | `EventHubStore`        | Event hub state persistence                    |
-| `RedisWorkflowService`    | `PikkuWorkflowService` | Workflow definition storage                    |
-| `RedisWorkflowRunService` | `WorkflowRunService`   | Workflow execution tracking                    |
-| `RedisDeploymentService`  | `DeploymentService`    | Deployment state management                    |
-| `RedisAgentRunService`    | `AgentRunService`      | Agent execution tracking                       |
-| `RedisSecretService`      | `SecretService`        | Encrypted secret storage (envelope encryption) |
-
-### Secret Service
-
-```typescript
-import { RedisSecretService } from '@pikku/redis'
-
-const secrets = new RedisSecretService(
-  connectionOrConfig: Redis | RedisOptions | string,
-  config: { kekSecret: string; salt: string }
-)
-
-await secrets.getSecret<T = string>(key: string): Promise<T>
-await secrets.getSecrets<T>(keys: (keyof T & string)[]): Promise<Partial<T>>
-await secrets.hasSecret(key: string): Promise<boolean>
-await secrets.setSecret(key: string, value: unknown): Promise<void>
-await secrets.deleteSecret(key: string): Promise<void>
-await secrets.rotateKEK(): Promise<number>
-await secrets.close(): Promise<void>
-```
-
-## Usage Patterns
-
-### Full Setup
-
-```typescript
-import {
-  RedisChannelStore,
-  RedisWorkflowService,
-  RedisSecretService,
-} from '@pikku/redis'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-
-  const channelStore = new RedisChannelStore(config.redisUrl)
-  const workflowService = new RedisWorkflowService(config.redisUrl)
-
-  const secrets = new RedisSecretService(config.redisUrl, {
-    kekSecret: config.kekSecret,
-    salt: config.salt,
-  })
-
-  return { config, logger, channelStore, workflowService, secrets }
-})
-```

package/skills/pikku-rpc/SKILL.md

@@ -1,171 +0,0 @@
----
-name: pikku-rpc
-description: >-
-  Use when making internal function-to-function calls within a Pikku app, composing functions, or
-  exposing RPC endpoints. Covers rpc.invoke, rpc.remote, rpc.exposed, and generated RPC client.
-  TRIGGER when: code uses wire.rpc or expose: true, user asks about calling one Pikku function
-  from another, function composition, or RPC endpoints. DO NOT TRIGGER when: user asks about HTTP
-  routes (use pikku-http) or addon cross-package calls (use pikku-addon).
-installGroups: [core]
----
-
-# Pikku RPC 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.
-
-Call Pikku functions from other Pikku functions internally with full type safety. Use RPC to compose business logic without importing functions directly.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and which could be called via RPC
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### RPC Methods (on `wire.rpc`)
-
-Four ways to call functions via RPC:
-
-| Method                           | Purpose                                   |
-| -------------------------------- | ----------------------------------------- |
-| `rpc.invoke(name, data)`         | Internal call to any wired function       |
-| `rpc.remote(name, data)`         | Remote call via DeploymentService         |
-| `rpc.exposed(name, data)`        | Call functions marked with `expose: true` |
-| `rpc.startWorkflow(name, input)` | Start a workflow                          |
-
-### Exposed Functions
-
-Mark a function as externally callable via RPC:
-
-```typescript
-const greet = pikkuSessionlessFunc({
-  title: 'Greet',
-  expose: true, // ← callable via rpc.exposed()
-  func: async ({}, { name }) => {
-    return { message: `Hello, ${name}!` }
-  },
-})
-```
-
-### HTTP RPC Endpoint
-
-Expose all `expose: true` functions over HTTP:
-
-```typescript
-wireHTTP({
-  route: '/rpc/:rpcName',
-  method: 'post',
-  auth: false,
-  func: rpcCaller,
-})
-```
-
-## Usage Patterns
-
-### Internal Function Composition
-
-```typescript
-const calculateTax = pikkuSessionlessFunc({
-  title: 'Calculate Tax',
-  func: async ({}, { amount, rate }) => {
-    return { tax: amount * rate }
-  },
-})
-
-const processOrder = pikkuFunc({
-  title: 'Process Order',
-  func: async ({ db }, { orderId }, { rpc }) => {
-    const order = await db.getOrder(orderId)
-
-    // Call another pikku function internally — fully typed
-    const { tax } = await rpc.invoke('calculateTax', {
-      amount: order.total,
-      rate: 0.08,
-    })
-
-    return { orderId, total: order.total + tax }
-  },
-})
-```
-
-### When to Use RPC vs Direct Imports
-
-| Approach       | Use When                                                                                     |
-| -------------- | -------------------------------------------------------------------------------------------- |
-| `rpc.invoke()` | Cross-domain calls, maintaining separation of concerns, function may be in different package |
-| Direct import  | Same module, tightly coupled logic, performance critical                                     |
-
-RPC calls go through Pikku's middleware and permission pipeline. Direct imports skip them.
-
-### Generated RPC Client
-
-After `npx pikku all`:
-
-```typescript
-import { pikkuRPC } from '.pikku/pikku-rpc.gen.js'
-
-pikkuRPC.setServerUrl('http://localhost:4002')
-
-const result = await pikkuRPC.invoke('calculateTax', {
-  amount: 100,
-  rate: 0.08,
-})
-
-pikkuRPC.setAuthorizationJWT(token)
-```
-
-## Complete Example
-
-```typescript
-// functions/billing.functions.ts
-export const calculateTax = pikkuSessionlessFunc({
-  title: 'Calculate Tax',
-  func: async ({}, { amount, region }) => {
-    const rates = { US: 0.08, EU: 0.2, UK: 0.2 }
-    return { tax: amount * (rates[region] || 0) }
-  },
-})
-
-export const calculateShipping = pikkuSessionlessFunc({
-  title: 'Calculate Shipping',
-  func: async ({}, { weight, region }) => {
-    const base = region === 'US' ? 5 : 15
-    return { shipping: base + weight * 0.5 }
-  },
-})
-
-// functions/orders.functions.ts
-export const processOrder = pikkuFunc({
-  title: 'Process Order',
-  func: async ({ db }, { orderId }, { rpc }) => {
-    const order = await db.getOrder(orderId)
-
-    const { tax } = await rpc.invoke('calculateTax', {
-      amount: order.total,
-      region: order.region,
-    })
-
-    const { shipping } = await rpc.invoke('calculateShipping', {
-      weight: order.totalWeight,
-      region: order.region,
-    })
-
-    const finalTotal = order.total + tax + shipping
-    await db.updateOrder(orderId, { tax, shipping, finalTotal })
-
-    return { orderId, total: finalTotal, tax, shipping }
-  },
-})
-```