@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-trigger/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: pikku-trigger
+description: 'Use when adding event-driven functions that respond to system events like Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and pikkuTriggerFunc.
+TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to external events.
+DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-cron) or background job queues (use pikku-queue).'
+installGroups: [core]
+---
+
+# Pikku Trigger 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 fire when external events occur. Triggers connect event sources (Redis pub/sub, PostgreSQL LISTEN/NOTIFY, polling, webhooks) to Pikku functions.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions and their types
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `wireTrigger(config)`
+
+Define the target function that handles trigger events:
+
+```typescript
+import { wireTrigger } from '@pikku/core/trigger'
+
+wireTrigger({
+  name: string, // Trigger name (matches source)
+  func: PikkuFunc, // Function to call when event fires
+})
+```
+
+### `wireTriggerSource(config)`
+
+Define the event source that fires triggers:
+
+```typescript
+import { wireTriggerSource } from '@pikku/core/trigger'
+
+wireTriggerSource({
+  name: string, // Must match wireTrigger name
+  func: PikkuTriggerFunc, // Source function (sets up listener)
+  input: object, // Configuration for the source
+})
+```
+
+### `pikkuTriggerFunc<TInput, TEvent>`
+
+Define a trigger source function. Returns a cleanup function.
+
+```typescript
+import { pikkuTriggerFunc } from '#pikku'
+
+const source = pikkuTriggerFunc<
+  InputType, // Configuration input
+  EventType // Shape of events it emits
+>(async (services, input, { trigger }) => {
+  // Set up listener...
+  trigger.invoke(eventData) // Fire the trigger
+
+  // Return cleanup function
+  return async () => {
+    /* teardown */
+  }
+})
+```
+
+## Usage Patterns
+
+### Redis Pub/Sub Source
+
+```typescript
+const redisSubscribe = pikkuTriggerFunc<
+  { channels: string[] },
+  { channel: string; message: any }
+>(async ({ redis }, { channels }, { trigger }) => {
+  const subscriber = redis.duplicate()
+
+  subscriber.on('message', (channel, message) => {
+    trigger.invoke({ channel, message: JSON.parse(message) })
+  })
+
+  await subscriber.subscribe(...channels)
+
+  return async () => {
+    await subscriber.unsubscribe()
+    await subscriber.quit()
+  }
+})
+
+// Target function
+const onOrderEvent = pikkuSessionlessFunc({
+  title: 'On Order Event',
+  func: async ({ db, logger }, { channel, message }) => {
+    logger.info(`Order event on ${channel}`, message)
+    await db.processOrderEvent(message)
+  },
+})
+
+// Wire them together
+wireTrigger({
+  name: 'order-events',
+  func: onOrderEvent,
+})
+
+wireTriggerSource({
+  name: 'order-events',
+  func: redisSubscribe,
+  input: { channels: ['orders:created', 'orders:updated'] },
+})
+```
+
+### Triggers vs Queues
+
+| Feature     | Trigger                            | Queue                          |
+| ----------- | ---------------------------------- | ------------------------------ |
+| Execution   | Synchronous, in-process            | Async, distributed             |
+| Reliability | At-most-once                       | At-least-once (with retries)   |
+| Use case    | React to events immediately        | Reliable background processing |
+| Source      | External systems (Redis, PG, etc.) | Enqueued programmatically      |
+
+Use triggers for real-time reactions. Use queues for reliable, retryable background work.
+
+## Complete Example
+
+```typescript
+// functions/triggers.functions.ts
+const pgListen = pikkuTriggerFunc<{ channel: string }, { payload: any }>(
+  async ({ db }, { channel }, { trigger }) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(channel)) {
+      throw new Error(`Invalid channel name: ${channel}`)
+    }
+    const client = await db.pool.connect()
+
+    client.on('notification', (msg) => {
+      trigger.invoke({ payload: JSON.parse(msg.payload) })
+    })
+
+    await client.query(`LISTEN ${channel}`)
+
+    return async () => {
+      await client.query(`UNLISTEN ${channel}`)
+      client.release()
+    }
+  }
+)
+
+const onUserCreated = pikkuSessionlessFunc({
+  title: 'On User Created',
+  func: async ({ emailService, logger }, { payload }) => {
+    logger.info('New user created', { userId: payload.id })
+    await emailService.sendWelcome(payload.email)
+  },
+})
+
+// wirings/triggers.wiring.ts
+wireTrigger({ name: 'user-created', func: onUserCreated })
+wireTriggerSource({
+  name: 'user-created',
+  func: pgListen,
+  input: { channel: 'user_created' },
+})
+```

package/skills/pikku-versioning/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: pikku-versioning
+description: 'Use when versioning Pikku function contracts, detecting breaking changes, or managing API backward compatibility. Covers the version property, versions.pikku.json manifest, contract hashing, and CI integration.
+TRIGGER when: code uses version: on a pikkuFunc, user asks about API versioning, breaking changes, contract hashes, backward compatibility, or "pikku versions" CLI commands.
+DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config) or general function definitions (use pikku-concepts).'
+installGroups: [core]
+---
+
+# Pikku Function Versioning
+
+## 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.
+
+Track and protect function contracts across releases. Pikku hashes each function's input/output schema into a manifest so you can detect breaking changes before they ship.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions and their versions
+```
+
+See `pikku-concepts` for the core mental model.
+
+## Function Versioning
+
+When you need to introduce a breaking change, keep the old function as a pinned version and let the new one become the latest.
+
+**The pattern:**
+
+1. Create a new file `my-function-v1.function.ts` — export a variable with the `V1` suffix
+2. Set `override: 'myFunction'` — this is the contract key the manifest groups under
+3. Set `version: 1` — pins this as version 1 of the contract
+4. The existing `my-function.function.ts` (no `version:` field) automatically becomes the latest version
+
+```typescript
+// my-function-v1.function.ts — old contract, kept for running workflows/agents
+export const getBookV1 = pikkuFunc({
+  override: 'getBook', // REQUIRED — links this to the 'getBook' contract family
+  version: 1,
+  input: z.object({ bookId: z.string() }),
+  output: z.object({ title: z.string() }),
+  func: async ({ db }, { bookId }) => {
+    return db.getBook(bookId)
+  },
+})
+
+// my-function.function.ts — latest contract, no version: field
+export const getBook = pikkuFunc({
+  input: z.object({
+    bookId: z.string(),
+    format: z.enum(['full', 'summary']),
+  }),
+  output: z.object({
+    title: z.string(),
+    author: z.string(),
+    isbn: z.string(),
+  }),
+  func: async ({ db }, { bookId, format }) => {
+    return db.getBook(bookId, format)
+  },
+})
+```
+
+**Why `override` is required:** The manifest groups functions by a shared contract key. Without `override: 'getBook'`, `getBookV1` is stored internally as `getBookV1@v1` (key: `getBookV1`), which is a different contract family from `getBook`. With `override: 'getBook'`, it becomes `getBook@v1` (key: `getBook`), which groups with the unversioned `getBook` — and the unversioned one is automatically promoted to `getBook@v2`.
+
+## Version Manifest (`versions.pikku.json`)
+
+Pikku tracks contract hashes to detect breaking changes:
+
+```json
+{
+  "manifestVersion": 1,
+  "contracts": {
+    "createTodo": {
+      "latest": 1,
+      "versions": {
+        "1": { "inputHash": "a1b2c3d4", "outputHash": "e5f6a7b8" }
+      }
+    },
+    "getTodos": {
+      "latest": 2,
+      "versions": {
+        "1": { "inputHash": "i9j0k1l2", "outputHash": "m3n4o5p6" },
+        "2": { "inputHash": "q7r8s9t0", "outputHash": "u1v2w3x4" }
+      }
+    }
+  }
+}
+```
+
+Each hash is derived from the function's input and output schemas plus the contract key. If a schema changes without a version bump, `pikku versions check` will fail.
+
+## CLI Commands
+
+```bash
+npx pikku versions init     # Initialize versioning manifest (run once)
+npx pikku versions check    # Detect contract changes (use in CI)
+npx pikku versions update   # Update contract hashes after version bump
+```
+
+**Workflow:**
+
+1. `pikku versions init` — run once to create `versions.pikku.json`
+2. Develop normally — add/modify functions
+3. `pikku versions check` — CI catches unversioned breaking changes
+4. If intentional: create `my-function-v1.function.ts` with `override` + `version: 1`, then `pikku versions update`
+
+## CI Integration
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npx pikku versions check
+```
+
+## Complete Example
+
+```typescript
+// create-todo-v1.function.ts — v1 locked contract
+export const createTodoV1 = pikkuSessionlessFunc({
+  override: 'createTodo', // groups under 'createTodo' contract family
+  version: 1,
+  input: z.object({ title: z.string() }),
+  output: z.object({ id: z.string(), title: z.string() }),
+  func: async ({ todoStore }, { title }) => todoStore.add(title),
+})
+
+// create-todo.function.ts — v2 (latest), called by default
+export const createTodo = pikkuSessionlessFunc({
+  input: z.object({
+    title: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  output: z.object({
+    id: z.string(),
+    title: z.string(),
+    priority: z.string(),
+  }),
+  func: async ({ todoStore }, { title, priority }) =>
+    todoStore.add(title, priority),
+})
+```
+
+Result in manifest:
+
+```json
+"createTodo": {
+  "latest": 2,
+  "versions": {
+    "1": { "inputHash": "...", "outputHash": "..." },
+    "2": { "inputHash": "...", "outputHash": "..." }
+  }
+}
+```

package/skills/pikku-websocket/SKILL.md

@@ -0,0 +1,239 @@
+---
+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 prebuild`:
+
+```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 },
+  },
+})
+```