@pikku/cli 0.12.91 → 0.12.93

package/skills/pikku-mcp/SKILL.md

@@ -1,241 +0,0 @@
----
-name: pikku-mcp
-description: >-
-  Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers
-  mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object. TRIGGER when:
-  code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, 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-ai-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. 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.
-
-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.
-
-## API Reference
-
-### MCP Tools (simplest approach)
-
-Add `mcp: true` to any existing `pikkuFunc` to expose it as an MCP tool:
-
-```typescript
-const myFunc = pikkuFunc({
-  description: string,      // Used as MCP tool description
-  input: ZodSchema,         // Becomes MCP tool input schema
-  output: ZodSchema,        // Return type
-  mcp: true,                // ← Expose as MCP tool
-  func: async (services, data) => { ... },
-})
-```
-
-### MCP Resources (`pikkuMCPResourceFunc`)
-
-```typescript
-import { pikkuMCPResourceFunc } from '#pikku'
-
-const resource = pikkuMCPResourceFunc({
-  uri: string,              // URI template, e.g. 'todos/{id}'
-  title: string,            // Human-readable title
-  description?: string,
-  func: async (services, data, { mcp }) => {
-    // Must return array of { uri, text } or { uri, blob, mimeType }
-    return [{ uri: mcp.uri!, text: JSON.stringify(result) }]
-  },
-})
-```
-
-### MCP Prompts (`pikkuMCPPromptFunc`)
-
-```typescript
-import { pikkuMCPPromptFunc } from '#pikku'
-
-const prompt = pikkuMCPPromptFunc({
-  name: string,
-  description: string,
-  func: async (services, data) => {
-    // Must return array of MCP messages
-    return [
-      {
-        role: 'user',
-        content: { type: 'text', text: '...' },
-      },
-    ]
-  },
-})
-```
-
-### MCP Wire Object
-
-Inside MCP-enabled functions, `wire.mcp` provides:
-
-```typescript
-mcp.uri // Current resource URI (for resources)
-mcp.sendResourceUpdated(uri) // Notify clients a resource changed
-mcp.enableTools({ toolName: true }) // Dynamically enable/disable tools
-```
-
-## Usage Patterns
-
-### Expose Existing Functions as MCP Tools
-
-The simplest path — add `mcp: true` to any function:
-
-```typescript
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
-```
-
-### MCP Resources with URI Templates
-
-```typescript
-export const getTodo = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
-  title: 'Todo Details',
-  description: 'Get a todo by ID',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
-})
-```
-
-### MCP Prompts
-
-```typescript
-export const codeReview = pikkuMCPPromptFunc({
-  name: 'codeReview',
-  description: 'Generate a code review prompt',
-  func: async ({}, { filePath, context }) => {
-    return [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Review ${filePath}. Context: ${context}`,
-        },
-      },
-    ]
-  },
-})
-```
-
-### Dynamic Tool Control
-
-```typescript
-export const manageTodos = pikkuFunc({
-  description: 'Manage todo items',
-  input: ManageTodosInput,
-  output: ManageTodosOutput,
-  mcp: true,
-  func: async ({ db }, { action, id }, { mcp }) => {
-    if (action === 'delete') {
-      await db.deleteTodo(id)
-      mcp.sendResourceUpdated(`todos/${id}`)
-      await mcp.enableTools({ archiveTodos: true })
-      return { deleted: true }
-    }
-  },
-})
-```
-
-### MCP Server Setup
-
-```typescript
-// start.ts
-import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
-
-const server = new PikkuMCPServer(config, singletonServices, createWireServices)
-await server.init()
-await server.start()
-```
-
-## Complete Example
-
-```typescript
-// functions/todos.functions.ts
-export const listTodos = pikkuSessionlessFunc({
-  description: 'List all todo items',
-  input: ListTodosInput,
-  output: ListTodosOutput,
-  mcp: true,
-  func: async ({ db }, { status }) => {
-    return { todos: await db.listTodos(status) }
-  },
-})
-
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
-
-export const completeTodo = pikkuFunc({
-  description: 'Mark a todo as complete',
-  input: CompleteTodoInput,
-  output: CompleteTodoOutput,
-  mcp: true,
-  func: async ({ db }, { todoId }) => {
-    return await db.completeTodo(todoId)
-  },
-})
-
-// functions/todos.mcp.ts
-export const getTodoResource = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
-  title: 'Todo Details',
-  description: 'Get details of a specific todo',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
-})
-
-export const planDayPrompt = pikkuMCPPromptFunc({
-  name: 'planDay',
-  description: 'Create a daily plan based on pending todos',
-  func: async ({ db }, {}) => {
-    const { todos } = await db.listTodos('pending')
-    return [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Plan my day. Here are my pending todos:\n${todos.map((t) => `- ${t.text} (${t.priority})`).join('\n')}`,
-        },
-      },
-    ]
-  },
-})
-```

package/skills/pikku-middleware/SKILL.md

@@ -1,231 +0,0 @@
----
-name: pikku-middleware
-description: >-
-  Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware
-  (including service-to-service bearer auth), per-route middleware, session-setting middleware, or
-  understanding middleware execution order and priority. TRIGGER when: user wants middleware on
-  some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global
-  interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about
-  permissions/authorization checks (use pikku-permissions), auth strategies like
-  authBearer/authCookie (use pikku-security), or deployment.
-installGroups: [core]
----
-
-# Pikku Middleware
-
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info tags --json` to understand the existing middleware and tag landscape.
-2. Identify the source files that own the behavior — wirings files, not generated output.
-3. Register middleware at module load time — in a `wirings/*.ts` file, never inside a function body.
-4. Validate: run `pikku all --tsc` after adding or changing middleware — it regenerates and then confirms type safety in one pass.
-
-## The `pikkuMiddleware` Factory
-
-```typescript
-import { pikkuMiddleware } from '#pikku'
-
-// Simple: just a function
-const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
-  // runs before the function
-  await next()
-  // runs after the function (optional)
-})
-
-// With metadata (name + priority)
-const telemetryMiddleware = pikkuMiddleware({
-  name: 'my-telemetry',
-  priority: 'highest',
-  func: async (services, wire, next) => {
-    const start = performance.now()
-    try {
-      await next()
-    } finally {
-      services.logger.info({ duration: Math.round(performance.now() - start) })
-    }
-  },
-})
-```
-
-The `wire` object gives you:
-- `wire.http` — inbound HTTP context (headers, URL, cookies)
-- `wire.setSession(session)` — set the session for this request
-- `wire.getSession()` — read the current session
-- `wire.session` — the session set so far (may be undefined)
-
-Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `@pikku/core/errors`.
-
-## Scoping: Five Levels
-
-From broadest to narrowest:
-
-```typescript
-// 1. Wire-agnostic global: all wire types (HTTP, Queue, Channel, Trigger, Workflow, ...)
-addGlobalMiddleware([telemetryOuter()])
-
-// 2. HTTP global: all HTTP routes
-addHTTPMiddleware('*', [cors(), authBearer()])
-
-// 3. Prefix-based: URL pattern
-addHTTPMiddleware('/admin/*', [auditLog])
-
-// 4. Tag-based: any wiring with matching tag
-addTagMiddleware('machine-agent', [bearerAuth])  // tag on function or wire
-
-// 5. Inline: per-wiring
-wireHTTP({
-  route: '/books/:id',
-  func: getBook,
-  middleware: [cacheControl],
-})
-```
-
-## Global Middleware (`addGlobalMiddleware`)
-
-Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
-
-```typescript
-import { addGlobalMiddleware } from '@pikku/core'
-import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
-
-addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])  // wraps the full call
-addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])  // closest to the function body
-```
-
-`telemetryOuter` ships with `priority: 'highest'`, `telemetryInner` with `priority: 'lowest'` — so priority sorting places outer first regardless of array/call order.
-
-## HTTP & Prefix Middleware (`addHTTPMiddleware`)
-
-```typescript
-import { addHTTPMiddleware } from '@pikku/core/http'
-import { cors, authBearer } from '@pikku/core/middleware'
-
-// All routes
-addHTTPMiddleware('*', [cors({ origin: 'https://app.example.com', credentials: true })])
-
-// Scoped to /api/* prefix
-addHTTPMiddleware('/api/*', [rateLimit({ maxRequests: 100, windowMs: 60_000 })])
-```
-
-## Tag Middleware (`addTagMiddleware`)
-
-Tag middleware fires for any wiring (function or wire object) that carries a matching tag. This is the canonical approach for service-to-service bearer auth, rate limiting a group, or any cross-cutting concern scoped to a subset of routes.
-
-### Setting Tags
-
-```typescript
-// On the function definition
-export const myFunc = pikkuSessionlessFunc({
-  auth: false,
-  tags: ['machine-agent'],
-  func: async (services, input) => { ... },
-})
-
-// On the wire object
-wireHTTP({
-  route: '/internal/action',
-  method: 'post',
-  auth: false,
-  tags: ['internal'],
-  func: myFunc,
-})
-```
-
-Tags from the function definition and the wire object are merged — middleware from both tag sets runs.
-
-### Registering Tag Middleware
-
-```typescript
-import { addTagMiddleware } from '.pikku/pikku-types.gen.js'
-
-addTagMiddleware('machine-agent', [machineAgentBearerAuth])
-```
-
-Call at module load time — typically in the same `wirings/*.ts` file as the `wireHTTP` calls that use the tag.
-
-## Middleware Execution Order
-
-**Scope resolution order (broadest → narrowest):**
-
-```text
-global → httpGroup/* → httpGroup/prefix → wiringTags → wiringMiddleware → funcTags → funcMiddleware → function body
-```
-
-**Within each scope, sorted by priority:**
-
-```text
-highest → high → medium (default) → low → lowest
-```
-
-Set priority using the config-object form of `pikkuMiddleware`:
-
-```typescript
-const earlyMiddleware = pikkuMiddleware({
-  name: 'early',
-  priority: 'highest',   // 'highest' | 'high' | 'medium' | 'low' | 'lowest'
-  func: async (services, wire, next) => { ... },
-})
-```
-
-Priority is the primary sort key; within the same level, registration order is preserved. Use priority when a middleware must run before/after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
-
-## Service-to-Service Bearer Auth (canonical pattern)
-
-A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
-
-**On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
-
-```typescript
-// lib/host-token.ts
-let _token: string | null = null
-export const setToken = (t: string) => { _token = t }
-export const getToken = () => _token
-```
-
-```typescript
-// wirings/http.wiring.ts
-import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '../../.pikku/pikku-types.gen.js'
-import { UnauthorizedError } from '@pikku/core/errors'
-import { getToken } from '../lib/host-token.js'
-
-const bearerAuth = pikkuMiddleware(async (_services, { http }, next) => {
-  const authHeader = http?.request?.header?.('authorization') || http?.request?.header?.('Authorization')
-  const token = getToken()
-  const expected = token ? `Bearer ${token}` : null
-  if (
-    !expected ||
-    !authHeader ||
-    authHeader.length !== expected.length ||
-    !timingSafeEqual(Buffer.from(authHeader), Buffer.from(expected))
-  ) {
-    throw new UnauthorizedError()
-  }
-  return next()
-})
-
-addTagMiddleware('machine-agent', [bearerAuth])
-```
-
-```typescript
-// functions/my.function.ts
-export const myFunc = pikkuSessionlessFunc({
-  expose: true,
-  auth: false,
-  tags: ['machine-agent'],
-  func: async (services, input) => { ... },
-})
-```
-
-**On the client (the caller):** use the generated `RPCInvoke` type — never hand-write a `fetch` wrapper's types. See `references/middleware-patterns.md`.
-
-## More patterns
-
-`references/middleware-patterns.md` covers the client-side `RPCInvoke` caller, session-setting middleware (set a session from an API key), and request logging / audit middleware.
-
-## After Changes
-
-```bash
-pikku all              # regenerate metadata so new tags are picked up
-pikku all --tsc        # regenerate, then type-check (fails on type errors)
-```

package/skills/pikku-middleware/references/middleware-patterns.md

@@ -1,61 +0,0 @@
-# Middleware Patterns (extended)
-
-Detailed, less-common middleware recipes. The common-path bearer-auth pattern lives inline in SKILL.md; this file holds the client-side caller, session-setting, and audit recipes.
-
-## Service-to-Service: the client (caller) side
-
-Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
-
-```typescript
-import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
-
-export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
-  return async (name: string, data?: unknown) => {
-    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ data: data ?? {} }),
-    })
-    if (!res.ok) {
-      const text = await res.text().catch(() => '')
-      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
-    }
-    return res.json()
-  } as RPCInvoke
-}
-```
-
-## Session-Setting Middleware
-
-```typescript
-const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
-  if (session) return next()  // already authenticated
-
-  const header = http?.request?.header?.('x-api-key')
-  if (!header) return next()
-
-  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
-  if (row) setSession?.({ userId: row.userId })
-
-  return next()
-})
-
-addTagMiddleware('api-key-auth', [apiKeyAuth])
-```
-
-Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
-
-## Request Logging / Audit
-
-```typescript
-const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
-  const start = Date.now()
-  await next()
-  await db.createAuditLog({ duration: Date.now() - start })
-})
-
-addHTTPMiddleware('/admin/*', [auditLog])
-```

package/skills/pikku-mongodb/SKILL.md

@@ -1,105 +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. 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/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                    |
-| `MongoDBAIStorageService`   | `AIStorageService, AIRunStateService` | AI conversation/run storage                    |
-| `MongoDBAgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
-| `MongoDBSecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
-
-All services take a `Db` instance in their constructor and have an `init()` method that creates collections/indexes.
-
-### Secret Service
-
-```typescript
-import { MongoDBSecretService } from '@pikku/mongodb'
-
-const secrets = new MongoDBSecretService(mongo.db, {
-  kekSecret: 'your-key-encryption-key',
-  salt: 'your-salt',
-})
-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 }
-})
-```