@pikku/skills 0.12.22 → 0.12.25

package/skills/pikku-mongodb/SKILL.md

@@ -1,113 +0,0 @@
----
-name: pikku-mongodb
-description: >-
-  Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection,
-  channel stores, workflow services, secret services, AI storage, agent runs, and deployment
-  services. TRIGGER when: code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService,
-  MongoDBSecretService, or user asks about MongoDB setup with Pikku. DO NOT TRIGGER when: user
-  asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).
----
-
-# Pikku MongoDB
-
-## 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/mongodb` provides MongoDB-backed implementations of Pikku's core service interfaces.
-
-## Installation
-
-```bash
-yarn add @pikku/mongodb
-```
-
-## API Reference
-
-### `PikkuMongoDB` (Connection Wrapper)
-
-```typescript
-import { PikkuMongoDB } from '@pikku/mongodb'
-
-const mongo = new PikkuMongoDB(
-  logger: Logger,
-  clientOrUri: MongoClient | string,
-  dbName: string,
-  options?: MongoClientOptions
-)
-
-await mongo.init()
-mongo.db  // Db instance for queries
-await mongo.close()
-```
-
-### Available Services
-
-| Service                      | Interface                                   | Purpose                                        |
-| ---------------------------- | ------------------------------------------- | ---------------------------------------------- |
-| `MongoDBChannelStore`        | `ChannelStore`                              | WebSocket channel state persistence            |
-| `MongoDBEventHubStore`       | `EventHubStore`                             | Event hub state persistence                    |
-| `MongoDBWorkflowService`     | `PikkuWorkflowService`                      | Workflow definition storage                    |
-| `MongoDBWorkflowRunService`  | `WorkflowRunService`                        | Workflow execution tracking                    |
-| `MongoDBDeploymentService`   | `DeploymentService`                         | Deployment state management                    |
-| `MongoDBAgentStorageService` | `AgentStorageService, AgentRunStateService` | AI conversation/run storage                    |
-| `MongoDBAgentRunService`     | `AgentRunService`                           | Agent execution tracking                       |
-| `MongoDBSecretService`       | `SecretService`                             | Encrypted secret storage (envelope encryption) |
-| `MongoDBSessionStore`        | `SessionStore`                              | Persisted user sessions                        |
-
-All services take a `Db` instance in their constructor and have an `init()` method that creates collections/indexes.
-
-### 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 { MongoDBSecretService } from '@pikku/mongodb'
-
-const secrets = new MongoDBSecretService(mongo.db, {
-  key: 'your-key-encryption-passphrase',
-  keyVersion: 2, // defaults to 1
-  previousKey: 'the-passphrase-you-are-rotating-away-from',
-  audit: true, // log write/delete/rotate through the audit sink
-  auditReads: false, // reads too — noisy, off by default
-})
-await secrets.init()
-
-await secrets.setSecret('api-key', { key: 'sk-...' })
-const value = await secrets.getSecret<{ key: string }>('api-key')
-await secrets.rotateKEK()
-```
-
-## Usage Patterns
-
-### Full Setup
-
-```typescript
-import {
-  PikkuMongoDB,
-  MongoDBChannelStore,
-  MongoDBWorkflowService,
-} from '@pikku/mongodb'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-  const mongo = new PikkuMongoDB(logger, config.mongoUri, 'myapp')
-  await mongo.init()
-
-  const channelStore = new MongoDBChannelStore(mongo.db)
-  await channelStore.init()
-
-  const workflowService = new MongoDBWorkflowService(mongo.db)
-  await workflowService.init()
-
-  return { config, logger, database: mongo, channelStore, workflowService }
-})
-```

package/skills/pikku-product-second-opinion/README.md

@@ -1,43 +0,0 @@
-# pikku-product-second-opinion
-
-Turns a `pikku-software-archaeology` blueprint into a **plain-language report for a
-non-technical owner** — a founder/PM stuck with an app they didn't build.
-Explains how it works and how it could be better, in business terms.
-
-```
-Existing repo → pikku-software-archaeology → .knowledge/ blueprint → pikku-product-second-opinion → founder report
-   (facts)              (extract)          (machine-readable)         (translate + advise)   (markdown + web page)
-```
-
-## The split from pikku-software-archaeology
-
-- **pikku-software-archaeology** extracts _facts_ into `.knowledge/` for a machine (Pikku) to rebuild from. Engineer/generator audience.
-- **pikku-product-second-opinion** reads that blueprint and writes an _opinionated report_ for a human to decide from. Non-technical audience.
-
-One extracts; one advises. This skill consumes the other's output — it doesn't re-read the code.
-
-## What the report is calibrated to (locked by the author)
-
-- **Layered depth** — a one-page executive summary, then a section per major area for anyone who wants detail.
-- **Direct but fair tone** — names problems plainly, always with why-it-matters and credit for what's good.
-- **Both formats** — a markdown copy in the repo plus a clean, shareable web page (rendered via the `artifact-design` skill).
-
-## The rules that make it work
-
-1. **Translate, don't dump.** Every technical concept becomes a business outcome or a plain description. The jargon→plain table is in `SKILL.md`.
-2. **Every problem carries impact + severity + effort.** A problem with no "what it means for you" doesn't ship.
-3. **Always credit what works.** All-criticism reports get dismissed.
-4. **Argue improvements in business outcomes** (more reliable / faster / cheaper / safer / easier to hand off), and say whether each is a cheap **rewire** or an expensive **rebuild** — never recommend a rewrite just because the code is messy.
-5. **Mark confidence.** Certain and "I'd need to check" are different sentences.
-6. **Cover the frontend and the other ways the app is used** when the blueprint has them — walk the screens as a journey, call out consistency, and flag the custom-logic pieces (charts/tables/editors) as the real work vs the cheap standard pieces. Name the ways the product can be driven (people/web, developers/API+SDK, AI agents/MCP, power users/CLI) — often a genuine strength.
-7. **Give honest technology tradeoffs — both sides.** Every stack bet (framework, auth, hosting, key libraries) gets what-it-buys AND what-it-costs in business terms, tied to the founder's stage/goals. Don't cheerlead, don't trash, and **don't soften the disadvantages**. The app's own bets are derived from the blueprint (`architecture.json`/`integrations.json`/`frontend.json` + the repo's manifest) — never from a list in the skill, because a verdict you could write before reading the blueprint isn't a second opinion. Separately, and only when a rebuild is actually being recommended, the target stack (Pikku, Better Auth, TanStack Start) gets the _same_ both-sides treatment with cons first-class — pinning someone's dependency for being pre-1.0 while staying quiet about the replacement being pre-1.0 too is a pitch, not an opinion.
-
-## Files
-
-```
-pikku-product-second-opinion/
-├── SKILL.md                      # method + voice rules + red flags
-├── README.md                     # this file
-├── references/report-template.md # the layered structure to fill in
-└── example/sample-report.md      # worked example (competitor-tracking area, founder voice)
-```

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.