@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-wiring/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: pikku-wiring
+description: >-
+  Use when exposing a Pikku function over a transport — HTTP routes and SSE, WebSocket channels,
+  typed realtime pub/sub, internal and exposed RPC, queue workers, cron schedules, event triggers,
+  MCP tools/resources/prompts, CLI commands, or a Slack gateway. Covers choosing the wiring, the
+  model every wiring shares, and what differs: which function type each needs, where a session
+  comes from, and which calls throw instead of returning. TRIGGER when: code uses wireHTTP,
+  defineHTTPRoutes, wireChannel, wireQueueWorker, wireScheduler, wireTrigger, wireTriggerSource,
+  wireCLI, wireMCPResource, wireMCPPrompt, `mcp: true`, `sse: true`, `expose: true`, rpc.invoke,
+  SlackGatewayAdapter, or the user asks how to expose, route, schedule, queue, stream or publish a
+  function. DO NOT TRIGGER when: writing the function body itself (use pikku-concepts), declaring
+  authorization (use pikku-auth), or serving the app on a runtime (use pikku-deploy).
+installGroups: [core]
+---
+
+# Pikku Wiring
+
+## 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.
+
+## Before you start
+
+```bash
+pikku info functions --verbose   # existing functions, their types, tags, middleware
+pikku info tags --verbose        # project organisation and naming conventions
+pikku info middleware --verbose  # what middleware is already applied
+```
+
+Follow the patterns you find. Option tables and exact signatures come from
+`pikku doc` — run `pikku doc --ai` for the installed surface. This skill is what
+the compiler cannot tell you: which wiring to reach for, and what changes when
+you move a function from one to another.
+
+## What a wiring is
+
+A **function** owns behaviour, its `input`/`output` schemas, and its
+authorization. A **wiring** owns only the transport: how a caller reaches that
+function. The same function can be wired to several transports at once, which is
+why nothing transport-specific belongs in its body.
+
+Three consequences that hold for every wiring below:
+
+- **Input and output types are never declared on the wiring.** They come from the
+  function's own `input:`/`output:` schemas. Route params, query params and body
+  are merged into the function's `data` argument.
+- **Permissions are never declared on the wiring.** Wire-level permissions were
+  removed in #972 — declare them on the function (`pikkuFunc({ permissions })`,
+  see `pikku-auth`) or app-wide via `addGlobalPermission`. Tags and
+  patterns now target *middleware* only.
+- **The wire is the third argument**, not a service. `channel`, `rpc`, `session`,
+  `setSession`, `mcp`, `queue`, `scheduledTask` and `cli` all live there.
+
+## Import from `#pikku/*`, never `@pikku/core/*`
+
+Every wiring factory has two versions. The generated `#pikku/*` entrypoint binds
+it to your project's service, session and middleware types; the `@pikku/core/*`
+export is the unbound generic. **Both compile.** Importing from core costs you
+exactly the typing that makes the wiring worth having, silently.
+
+| Wiring | Import from |
+| --- | --- |
+| `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes` | `#pikku/http` |
+| `wireChannel`, `defineChannelRoutes` | `#pikku/channel` |
+| `wireQueueWorker` | `#pikku/queue` |
+| `wireScheduler` | `#pikku/scheduler` |
+| `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc` | `#pikku/trigger` |
+| `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender` | `#pikku/cli` |
+| `pikkuMCPToolFunc`, `pikkuMCPResourceFunc`, `pikkuMCPPromptFunc`, `wireMCPResource`, `wireMCPPrompt` | `#pikku/mcp` |
+
+## Pick a wiring
+
+| Reach for | When | Reference |
+| --- | --- | --- |
+| **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md` |
+| **Channel** | A hand-designed WebSocket protocol with your own action routing | `references/channel.md` |
+| **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics | `references/realtime.md` |
+| **RPC** | One function calling another, or dispatching a name from outside | `references/rpc.md` |
+| **Queue** | Reliable background work that must survive a crash and retry | `references/queue.md` |
+| **Scheduler** | Recurring work on a cron expression | `references/scheduler.md` |
+| **Trigger** | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN) | `references/trigger.md` |
+| **MCP** | Exposing functions to an AI assistant as tools, resources or prompts | `references/mcp.md` |
+| **CLI** | A terminal program with commands, subcommands and options | `references/cli.md` |
+| **Gateway** | An inbound integration from a third-party product — Slack is the shipped adapter | `references/gateway-slack.md` |
+
+Realtime and Channel are the pair most often confused. If the shape is "server
+pushes typed events to subscribers", use Realtime — `pikku enable events`
+generates the channel, the SSE route and the cleanup for you. Reach for Channel
+only when the client also sends structured messages you need to route on.
+
+## What differs, and where it bites
+
+### Each wiring demands a particular function type
+
+| Wiring | Function type | Why |
+| --- | --- | --- |
+| HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response |
+| Scheduler | **`pikkuVoidFunc`** | A cron has no input and no caller to return to |
+| Trigger *source* | **`pikkuTriggerFunc`** | Runs **once at startup**, not once per event |
+
+A trigger source is the one that surprises people: it sets up a listener, calls
+`trigger.invoke(...)` per event, and returns a teardown function. It receives
+**singleton services only** — no session, no request, no per-wire services,
+because the listener outlives every event it emits.
+
+### Where a session comes from is not uniform
+
+An HTTP or channel caller arrives with credentials and middleware mints a
+session. Nothing else does.
+
+- **A cron runs with no session at all.** It cannot invoke a permission- or
+  scope-gated RPC, and nothing it writes can be attributed. A scheduled task is a
+  machine principal — give it one in the task's own `middleware`, exactly as a
+  bearer-authenticated caller gets one. See the machine-auth section of
+  `pikku-middleware`.
+- **A queue worker and a trigger handler are the same case.** Whatever identity
+  they need is minted in middleware, not inherited.
+- **A channel authenticates per action.** `setSession` is on the wire, and an
+  `auth: false` action (conventionally `authenticate`) is how the session is
+  established mid-connection.
+- **`auth` on `wireCLI` guards only the generated websocket channel.** A locally
+  executed CLI has no connection to authenticate, so it is not a way to require a
+  session for local runs.
+
+### Some control-flow calls throw instead of returning
+
+`wire.scheduledTask.skip(reason)` and `wire.queue.discard(reason)` both read like
+an early return and are not — they throw, so nothing after the call runs and no
+`return` is needed. The consequence lands in middleware: a `try/catch` around
+`await next()` catches a skip or a discard and reports it as a failure. If your
+middleware distinguishes success from failure, let those pass through rather than
+logging them as errors.
+
+### Delivery semantics differ, and that is usually the real choice
+
+| Wiring | Delivery | Runs where |
+| --- | --- | --- |
+| Trigger | **At-most-once**, synchronous | In-process, alongside the listener |
+| Queue | **At-least-once** with retries and a dead-letter queue | Distributed workers |
+| Scheduler | Depends on the runtime — see below | Wherever the scheduler service runs |
+
+Reach for a trigger to react immediately, and a queue when the work must not be
+lost. A trigger that must not drop events is a queue with extra steps.
+
+Scheduled tasks are the trap: on serverless runtimes the same `wireScheduler`
+declaration behaves three different ways, and the deployment unit rather than the
+cron expression can decide which tasks fire. `pikku-deploy` has the comparison.
+
+### Codegen owns several wirings — do not hand-write them
+
+| Turn it on | Codegen writes | Never hand-write |
+| --- | --- | --- |
+| `pikku enable rpc` | `rpc-public.gen.ts` — the `POST /rpc/:rpcName` route | A second route on the same path collides |
+| `pikku enable events` | `events.gen.ts` — the `/events` channel and `GET /events/:topic` | A hand-rolled `/events` misses disconnect cleanup |
+| `wireCLI` | `<program>-channel.gen.ts` — the same commands over a channel | It is regenerated on every build |
+
+Enabling the RPC endpoint says the endpoint exists, not who may call it — each
+`expose: true` function is still gated by its own `auth`, permissions and scopes.
+
+## What NOT to do
+
+- Do not import a wiring factory from `@pikku/core/*`. It compiles and silently
+  drops your project's types; use the `#pikku/*` entrypoint.
+- Do not put `permissions` on a wiring. They were removed in #972 and belong on
+  the function.
+- Do not declare input or output types on a wiring — they come from the
+  function's schemas.
+- Do not `return` after `skip()` or `discard()`, and do not let middleware
+  report them as failures.
+- Do not hand-write `/rpc/:rpcName`, `/events`, or a CLI's channel file.
+- Do not reach for a trigger when losing an event matters — use a queue.
+- Do not put `sse: true` on anything but a `get`, or `query` on anything but a
+  `post`; the config union rejects both rather than failing at runtime.

package/skills/{pikku-websocket/SKILL.md → pikku-wiring/references/channel.md}

@@ -1,44 +1,11 @@
----
-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), or typed pub/sub events (use pikku-realtime).
-installGroups: [core]
----
-
 # Pikku WebSocket Wiring
 
-## 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.
-
-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'
+import { wireChannel } from '#pikku/channel'
 
 wireChannel({
   name: string,                      // Channel name (e.g. 'todos')
@@ -66,7 +33,7 @@ wireChannel({
 
 Note there is **no `permissions` key on a message wiring** — wire-level
 permissions were removed in #972. Authorization lives on the function's own
-`permissions` field (see `pikku-permissions`).
+`permissions` field (see `pikku-auth`).
 
 ### `pikkuChannelMiddleware(fn)`
 

package/skills/{pikku-cli/SKILL.md → pikku-wiring/references/cli.md}

@@ -1,37 +1,5 @@
----
-name: pikku-cli
-description: >-
-  Use when building CLI commands with Pikku. Covers wireCLI, pikkuCLICommand, subcommands,
-  options, parameters, custom renderers, and nested command groups. TRIGGER when: code uses
-  wireCLI/pikkuCLICommand, user asks about CLI commands, terminal tools, command-line interface,
-  or adding subcommands. DO NOT TRIGGER when: user asks about the pikku CLI tool itself (use
-  pikku-meta) or HTTP endpoints (use pikku-http).
-installGroups: [core]
----
-
 # Pikku CLI Wiring
 
-## 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.
-
-Wire Pikku functions as CLI commands with parameters, options, subcommands, and custom terminal renderers.
-
-## 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
 
 ### `wireCLI(config)`
@@ -244,4 +212,4 @@ session for local runs. Don't hand-write or edit the generated channel file.
 
 ## Complete Example
 
-For a full functions + renderers + nested-subcommand wiring walkthrough, see `references/complete-example.md`.
+For a full functions + renderers + nested-subcommand wiring walkthrough, see `cli-complete-example.md`.

package/skills/{pikku-gateway-slack/SKILL.md → pikku-wiring/references/gateway-slack.md}

@@ -1,28 +1,5 @@
----
-name: pikku-gateway-slack
-description: >-
-  Use when integrating Slack with a Pikku app. Covers SlackGatewayAdapter, slash commands, OAuth
-  flow, message handling, and signature verification. TRIGGER when: code uses SlackGatewayAdapter,
-  parseSlashCommand, buildSlackInstallUrl, or user asks about Slack integration, Slack bots, or
-  @pikku/gateway-slack. DO NOT TRIGGER when: user asks about general gateway/webhook patterns (use
-  pikku-trigger).
-installGroups: [core]
----
-
 # Pikku Gateway Slack
 
-## 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/gateway-slack` provides a Slack Events API gateway adapter, slash command handling, OAuth installation flow, and message utilities.
-
 ## Installation
 
 ```bash

package/skills/{pikku-http/SKILL.md → pikku-wiring/references/http.md}

@@ -1,41 +1,5 @@
----
-name: pikku-http
-description: >-
-  Use when adding HTTP routes, REST APIs, web endpoints, or SSE streams to a Pikku app. Covers
-  wireHTTP, defineHTTPRoutes, route groups, auth, middleware, SSE, and generated
-  fetch client. TRIGGER when: code uses wireHTTP/defineHTTPRoutes/wireHTTPRoutes, user asks about
-  REST endpoints, API routes, SSE, or the generated fetch client. DO NOT TRIGGER when: user asks
-  about WebSocket (use pikku-websocket), queue workers (use pikku-queue), or deployment (use
-  pikku-deploy-*).
-installGroups: [core]
----
-
 # Pikku HTTP Wiring
 
-## 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.
-
-Wire Pikku functions to HTTP endpoints. Supports single routes, composable route groups, auth, middleware, SSE, and auto-generated type-safe clients. (Authorization lives on the function, not the wiring — see `pikku-permissions`.)
-
-## Before You Start
-
-Run these commands to understand the current project:
-
-```bash
-pikku info functions --verbose   # See existing functions, their types, tags, middleware
-pikku info tags --verbose        # Understand project organization and naming conventions
-pikku info middleware --verbose  # See what middleware is already applied
-```
-
-Follow existing patterns you find (naming, tag usage, file organization). See `pikku-concepts` for the core mental model.
-
 ## API Reference
 
 All three come from `#pikku/http` (the generated `.pikku/http/index.ts`), which
@@ -50,7 +14,7 @@ Function input/output types come from the function's own `input:`/`output:` zod
 
 Config cascading across groups: `basePath` concatenates down the chain, `tags` merge (union), `auth` child overrides parent.
 
-For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read `references/http-options.md`.
+For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read `http-options.md`.
 
 ### `addHTTPMiddleware(pattern, middlewares)`
 
@@ -59,7 +23,7 @@ addHTTPMiddleware('*', [authBearer()]) // All routes
 addHTTPMiddleware('/api/*', [rateLimit()]) // Pattern match
 ```
 
-> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
+> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-auth`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
 
 ## Data Flow
 
@@ -122,7 +86,7 @@ wireHTTP({ method: 'get', route: '/books', func: listBooks, auth: false })
 wireHTTP({ method: 'delete', route: '/books/:bookId', func: deleteBook })
 ```
 
-Authorization is not a wiring concern — declare it on the function via `permissions` (see `pikku-permissions`), or app-wide via `addGlobalPermission`.
+Authorization is not a wiring concern — declare it on the function via `permissions` (see `pikku-auth`), or app-wide via `addGlobalPermission`.
 
 ### Middleware
 

package/skills/{pikku-mcp/SKILL.md → pikku-wiring/references/mcp.md}

@@ -1,38 +1,5 @@
----
-name: pikku-mcp
-description: >-
-  Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers
-  mcp: true, pikkuMCPToolFunc, pikkuMCPResourceFunc, pikkuMCPPromptFunc, wireMCPResource,
-  wireMCPPrompt, the MCP wire object and PikkuMCPServer. TRIGGER when: code uses mcp: true or any
-  pikkuMCP*Func/wireMCP* helper, user asks about MCP, Model Context Protocol, AI tool integration,
-  or exposing functions to Claude/ChatGPT. DO NOT TRIGGER when: user asks about AI agents (use
-  pikku-agent) or general function definitions (use pikku-concepts).
-installGroups: [core]
----
-
 # Pikku MCP Wiring
 
-## 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.
-
-Expose Pikku functions as Model Context Protocol (MCP) tools, resources, and prompts for AI assistants like Claude, ChatGPT, and others.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions that could become MCP tools
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
 ## The shape of MCP in Pikku
 
 MCP has three surfaces, and Pikku wires them differently:

package/skills/{pikku-queue/SKILL.md → pikku-wiring/references/queue.md}

@@ -1,43 +1,11 @@
----
-name: pikku-queue
-description: >-
-  Use when adding background job processing, async task queues, or distributed workers to a Pikku
-  app. Covers wireQueueWorker, job enqueuing, progress tracking, retries, BullMQ and PgBoss
-  adapters. TRIGGER when: code uses wireQueueWorker, user asks about background jobs, task queues,
-  async processing, BullMQ, PgBoss, or job retries. DO NOT TRIGGER when: user asks about scheduled
-  cron tasks (use pikku-schedule) or event-driven triggers (use pikku-trigger).
-installGroups: [core]
----
-
 # Pikku Queue Wiring
 
-## 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.
-
-Wire Pikku functions as background queue workers. Supports job control (progress, retry, discard), configurable concurrency, and type-safe job publishing.
-
-## 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
 
 ### `wireQueueWorker(config)`
 
 ```typescript
-import { wireQueueWorker } from '@pikku/core/queue'
+import { wireQueueWorker } from '#pikku/queue'
 
 wireQueueWorker({
   name: string,            // Queue name (unique identifier)