@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-redis/SKILL.md

@@ -1,99 +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. 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) |
-| `RedisSessionStore`       | `SessionStore`         | Persisted user sessions                        |
-
-### Secret Service
-
-Envelope encryption: `key` derives the KEK that wraps each secret's own DEK.
-Keeping `previousKey` set is what makes `rotateKEK()` possible — it re-wraps
-every secret onto the current key and returns the new version.
-
-```typescript
-import { RedisSecretService } from '@pikku/redis'
-
-const secrets = new RedisSecretService(
-  connectionOrConfig: Redis | RedisOptions | string,
-  config: {
-    key: string          // the KEK passphrase
-    keyVersion?: number  // defaults to 1
-    previousKey?: string // required to rotate
-    keyPrefix?: string   // namespaces the redis keys
-  }
-)
-
-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, {
-    key: config.kekPassphrase,
-  })
-
-  return { config, logger, channelStore, workflowService, secrets }
-})
-```

package/skills/pikku-schema-ajv/SKILL.md

@@ -1,83 +0,0 @@
----
-name: pikku-schema-ajv
-description: >-
-  Use when setting up JSON schema validation with AJV in a Pikku app. Covers AjvSchemaService for
-  request/response validation. TRIGGER when: code uses AjvSchemaService, user asks about AJV, JSON
-  schema validation, or @pikku/schema-ajv. DO NOT TRIGGER when: user asks about Cloudflare Workers
-  schema validation (use pikku-schema-cfworker).
----
-
-# Pikku Schema AJV (JSON Schema Validation)
-
-## 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/schema-ajv` provides JSON schema validation using [AJV](https://ajv.js.org/). Implements the `SchemaService` interface from `@pikku/core`. This is the default schema validator for Node.js environments.
-
-## Installation
-
-```bash
-yarn add @pikku/schema-ajv
-```
-
-## API Reference
-
-### `AjvSchemaService`
-
-```typescript
-import { AjvSchemaService } from '@pikku/schema-ajv'
-
-const schema = new AjvSchemaService(logger: Logger)
-```
-
-**Methods:**
-
-- `compileSchema(name: string, schema: any): void` — Compile and register a JSON schema under `name`
-- `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
-- `getSchemaNames(): Set<string>` — Get all registered schema names
-- `getSchemaKeys(schemaName: string): string[]` — Top-level property keys, or `[]` if the schema has no `properties`
-
-The first argument is the **name**, the second the schema — the parameter is
-called `schema` in the source, which reads backwards.
-
-### Behaviour that matters
-
-- **Registration is name-keyed and never re-compiles.** A second
-  `compileSchema('X', …)` with a different schema is a no-op; the first one wins
-  for the process lifetime. `@pikku/schema-cfworker` _does_ recompile on a
-  changed value, so a dev hot-reload after codegen picks up a changed schema
-  there but not here — restart the process instead.
-- **AJV is a module-level singleton**, shared by every `AjvSchemaService` you
-  construct, so compiled schema names are global to the process.
-- **`useDefaults: true` mutates the validated object**, filling in schema
-  defaults in place. `coerceTypes: false`, so a query-string `"1"` will not
-  become `1` — the wiring layer is what coerces, not this service.
-- `ajv-formats` is registered, so `format` keywords (`email`, `uuid`, `date-time`)
-  are enforced.
-- A failed validation throws `UnprocessableContentError` (a 422). A _missing_
-  schema throws a bare string, `Missing validator for <name>` — not an `Error`,
-  so `catch (e) { e.message }` reads `undefined`. That normally means codegen
-  didn't run.
-
-## Usage Patterns
-
-### With Pikku Services
-
-```typescript
-import { AjvSchemaService } from '@pikku/schema-ajv'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new ConsoleLogger()
-  const schema = new AjvSchemaService(logger)
-  return { config, logger, schema }
-})
-```
-
-Pikku automatically uses the schema service to validate function inputs and outputs when schemas are defined in your function definitions.

package/skills/pikku-schema-cfworker/SKILL.md

@@ -1,82 +0,0 @@
----
-name: pikku-schema-cfworker
-description: >-
-  Use when setting up JSON schema validation for Cloudflare Workers in a Pikku app. Covers
-  CFWorkerSchemaService as a lightweight alternative to AJV. TRIGGER when: code uses
-  CFWorkerSchemaService, user asks about schema validation on Cloudflare Workers, or
-  @pikku/schema-cfworker. DO NOT TRIGGER when: user asks about AJV schema validation (use
-  pikku-schema-ajv).
----
-
-# Pikku Schema CFWorker (Cloudflare Workers Validation)
-
-## 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/schema-cfworker` provides JSON schema validation using [@cfworker/json-schema](https://github.com/cfworker/cfworker), a lightweight validator compatible with Cloudflare Workers (no `eval` or `new Function`). Implements the `SchemaService` interface from `@pikku/core`.
-
-## Installation
-
-```bash
-yarn add @pikku/schema-cfworker
-```
-
-## API Reference
-
-### `CFWorkerSchemaService`
-
-```typescript
-import { CFWorkerSchemaService } from '@pikku/schema-cfworker'
-
-const schema = new CFWorkerSchemaService(logger: Logger)
-```
-
-**Methods:**
-
-- `compileSchema(name: string, schema: any): void` — Compile and register a JSON schema under `name`
-- `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
-- `getSchemaNames(): Set<string>` — Get all registered schema names
-- `getSchemaKeys(schemaName: string): string[]` — Top-level property keys, or `[]` if the schema has no `properties`
-
-### Where it differs from AJV
-
-These two are not drop-in equivalents, and the differences are the kind that
-surface as behaviour changes rather than compile errors:
-
-- **No `useDefaults`.** AJV fills schema defaults into the validated object in
-  place; this validator does not. A field you relied on being defaulted arrives
-  `undefined` on Workers.
-- **It re-compiles when the schema value changes.** AJV caches by name forever;
-  here a `compileSchema` with a different value for the same name replaces the
-  validator, which is what lets a dev hot-reload pick up regenerated schemas.
-- **Each validator gets a deep clone of the schema** (`@cfworker/json-schema`
-  mutates what it is given, which throws on a frozen generated object).
-- A compile failure throws `Error('Failed to compile schema: <name>')` with the
-  underlying cause swallowed — check the schema by hand when you see it.
-
-A failed validation throws `UnprocessableContentError` (422) with the validator
-errors joined; a _missing_ schema throws a bare string, `Missing validator for
-<name>`, not an `Error`.
-
-## Usage Patterns
-
-### With Cloudflare Workers
-
-```typescript
-import { CFWorkerSchemaService } from '@pikku/schema-cfworker'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new ConsoleLogger()
-  const schema = new CFWorkerSchemaService(logger)
-  return { config, logger, schema }
-})
-```
-
-Use this instead of `@pikku/schema-ajv` when deploying to Cloudflare Workers, as AJV uses `eval` which is not permitted in the Workers runtime.

package/skills/pikku-ws/SKILL.md

@@ -1,87 +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).
-installGroups: [fabric]
----
-
-# Pikku WS (WebSocket Server Runtime)
-
-## 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/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
-
-The package exports one function, `pikkuWebsocketHandler` — there is no server
-class. You own the `http.Server` and the `WebSocketServer`; the handler attaches
-the upgrade and message plumbing to them.
-
-```typescript
-import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
-import { stopSingletonServices } from '@pikku/core'
-import { Server } from 'http'
-import { WebSocketServer } from 'ws'
-
-import '../.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const server = new Server()
-const wss = new WebSocketServer({
-  noServer: true,
-  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
-})
-
-pikkuWebsocketHandler({
-  server,
-  wss,
-  logger: singletonServices.logger,
-  logRoutes: true, // print the wired channels at startup
-  loadSchemas: true, // compile input schemas up front
-})
-
-server.listen(4002, 'localhost')
-```
-
-`noServer: true` is not optional decoration — the handler performs the upgrade
-itself so it can run pikku's HTTP middleware chain (auth, cors) against the
-upgrade request before a channel exists. Letting `ws` bind the server directly
-would skip that.
-
-Services come from the bootstrap import and the global singleton registry, which
-is why nothing is passed in. The event hub is taken from
-`singletonServices.eventHub` when it is a `LocalEventHubService`, and a local one
-is created otherwise — so a single-process app gets pub/sub for free, while a
-multi-instance deployment must register a distributed hub (see `pikku-realtime`).
-
-The options type also extends `RunHTTPWiringOptions`, so per-request settings
-such as `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` are accepted
-here too.
-
-On shutdown, call `stopSingletonServices()` then close `wss` and `server`.
-
-See `pikku-websocket` for channel wiring details, and
-`pikku-deploy-fastify`/`pikku-deploy-express` when the WebSocket server shares a
-port with an HTTP app.