@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-services/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: pikku-services
+description: 'Use when setting up dependency injection, creating custom services, or configuring the service layer in a Pikku app. Covers pikkuServices (singleton), pikkuWireServices (per-request), service typing, built-in services, and tree-shaking.
+TRIGGER when: code uses pikkuServices/pikkuWireServices, user asks about services.ts, dependency injection, service factories, or built-in services (ConsoleLogger, JoseJWTService).
+DO NOT TRIGGER when: user asks about auth middleware (use pikku-security) or secrets/variables (use pikku-config).'
+installGroups: [core]
+---
+
+# Pikku Services (Dependency Injection)
+
+## 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 uses factory functions for dependency injection. Singleton services are created once at startup. Wire services are created fresh per request/job/command.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See which services existing functions use
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `pikkuServices(factory)`
+
+Create singleton services — instantiated once at server startup.
+
+```typescript
+import { pikkuServices } from '#pikku'
+
+const createSingletonServices = pikkuServices(
+  async (config, existingServices?) => {
+    // config: your CoreConfig object
+    // existingServices: optional, for chaining factories
+    return {
+      config,
+      logger: Logger,
+      jwt: JWTService,
+      database: DatabasePool,
+      // ...any custom services
+    }
+  }
+)
+```
+
+### `pikkuWireServices(factory)`
+
+Create per-request services — fresh instance for each HTTP request, queue job, CLI command, etc.
+
+```typescript
+import { pikkuWireServices } from '#pikku'
+
+const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => {
+    // singletonServices: all singleton services
+    // wire: transport context (session, channel, etc.)
+    // Pikku merges these with singleton services automatically
+    return {
+      userSession: UserSessionService,
+      dbTransaction: DatabaseTransaction,
+    }
+  }
+)
+```
+
+### Auto-Generated Service Manifest
+
+After `npx pikku prebuild`, Pikku generates a manifest of which services are actually used:
+
+```typescript
+// .pikku/pikku-services.gen.ts (auto-generated)
+export const requiredSingletonServices = {
+  database: true, // used by getUser, deleteUser
+  audit: true, // used by deleteUser
+  cache: false, // not used by any wired function
+  jwt: true, // used by auth middleware
+} as const
+
+export type RequiredSingletonServices = Pick<
+  SingletonServices,
+  'database' | 'audit' | 'jwt'
+> &
+  Partial<Omit<SingletonServices, 'database' | 'audit' | 'jwt'>>
+```
+
+## Usage Patterns
+
+### Basic Singleton Services
+
+```typescript
+const createSingletonServices = pikkuServices(
+  async (config, existingServices) => {
+    const logger = new ConsoleLogger()
+    const database = new DatabasePool(config.database)
+    await database.connect()
+
+    const jwt = new JoseJWTService(
+      async () => [{ id: 'my-key', value: JWT_SECRET }],
+      logger
+    )
+
+    return {
+      config,
+      logger,
+      database,
+      jwt,
+      books: new BookService(),
+    }
+  }
+)
+```
+
+### Per-Request Wire Services
+
+```typescript
+const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => {
+    return {
+      userSession: createUserSessionService(wire),
+      dbTransaction: new DatabaseTransaction(singletonServices.database),
+    }
+  }
+)
+```
+
+### Using Services in Functions
+
+Functions destructure services from the first parameter:
+
+```typescript
+const getUser = pikkuFunc({
+  title: 'Get User',
+  func: async ({ db, logger, jwt }, { userId }) => {
+    logger.info('Fetching user', { userId })
+    const user = await db.getUser(userId)
+    return { user }
+  },
+})
+```
+
+### Dynamic Import Optimization
+
+Use the generated manifest to conditionally import heavy dependencies:
+
+```typescript
+import { requiredSingletonServices } from '.pikku/pikku-services.gen.js'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+
+  let jwt: JWTService | undefined
+  if (requiredSingletonServices.jwt) {
+    const { JoseJWTService } = await import('@pikku/jose')
+    jwt = new JoseJWTService(keys, logger)
+  }
+
+  let database: Database | undefined
+  if (requiredSingletonServices.database) {
+    database = await createDatabase(config.databaseUrl)
+  }
+
+  return { config, logger, jwt, database }
+})
+```
+
+### Built-in Services
+
+| Service                 | Package                | Purpose                     |
+| ----------------------- | ---------------------- | --------------------------- |
+| `ConsoleLogger`         | `@pikku/core/services` | Console-based logging       |
+| `JoseJWTService`        | `@pikku/jose`          | JWT sign/verify via jose    |
+| `LocalSecretService`    | `@pikku/core/services` | Local development secrets   |
+| `LocalVariablesService` | `@pikku/core/services` | Local environment variables |
+| `PinoLogger`            | `@pikku/pino`          | Structured logging via Pino |
+
+## Complete Example
+
+```typescript
+// services.ts
+import { pikkuServices, pikkuWireServices } from '#pikku'
+import { ConsoleLogger } from '@pikku/core/services'
+import { JoseJWTService } from '@pikku/jose'
+
+// Custom service
+class TodoStore {
+  private todos: Map<string, Todo> = new Map()
+
+  async create(title: string, priority: string) {
+    const todo = { id: crypto.randomUUID(), title, priority, completed: false }
+    this.todos.set(todo.id, todo)
+    return todo
+  }
+
+  async get(id: string) {
+    return this.todos.get(id)
+  }
+  async list() {
+    return [...this.todos.values()]
+  }
+  async delete(id: string) {
+    this.todos.delete(id)
+  }
+}
+
+export const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const jwt = new JoseJWTService(
+    async () => [{ id: 'my-key', value: config.jwtSecret }],
+    logger
+  )
+
+  return {
+    config,
+    logger,
+    jwt,
+    secrets: new LocalSecretService(),
+    variables: new LocalVariablesService(),
+    todoStore: new TodoStore(),
+  }
+})
+
+export const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => ({
+    scopedLogger: new ScopedLogger(wire.session?.initial?.userId),
+  })
+)
+
+// functions/todos.functions.ts — services are auto-injected
+export const createTodo = pikkuFunc({
+  title: 'Create Todo',
+  func: async ({ todoStore, logger }, { title, priority }) => {
+    const todo = await todoStore.create(title, priority)
+    logger.info('Created todo', { id: todo.id })
+    return { todo }
+  },
+})
+```

package/skills/pikku-template-clone/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pikku-template-clone
+description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `pikku create`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
+allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
+---
+
+# Pikku Template Post-Clone Cleanup
+
+## Agent Operating Procedure
+
+Run this **once**, right after a template is cloned or scaffolded into a new
+project. The goal is to turn template scaffolding into a real project. Make the
+smallest changes and land them as one focused `chore: post-clone cleanup`
+commit, separate from any feature work.
+
+1. **Replace the template README.** The shipped `README.md` describes the
+   _template_, not the user's project — leaving it in place is misleading.
+   Either delete it (`git rm README.md`) or rewrite it with the new project's
+   name and purpose. Never ship a clone with the generic template README.
+2. **Keep the lockfile committed.** Templates ship a committed `yarn.lock`; do
+   NOT re-add `yarn.lock` to `.gitignore`. A real project commits its lockfile
+   for reproducible installs. The correct pattern is `yarn.lock` followed by
+   `!/yarn.lock`, which commits the root lockfile while keeping generated
+   per-unit lockfiles under `.deploy/` (and `e2e/`) ignored.
+3. **Rename template identifiers.** Update `name` in the root `package.json`
+   (and any `@project/*` or other placeholder names) to the real project.
+4. **Drop template-only artifacts.** Remove any `TEMPLATE.md`, demo docs, or
+   placeholder content that only made sense for the template.
+
+Do not touch generated files (`.pikku/`, `*.gen.*`) or run a full reinstall as
+part of cleanup — this step is project hygiene, not a build.
+
+## Why this exists
+
+Templates are structure-only starting points. Without this pass, clones carry a
+misleading README, a placeholder package name, and (historically) a gitignored
+lockfile — all of which leak template assumptions into a real project. Running
+it immediately after clone keeps every Pikku project, OSS or Fabric, starting
+from a clean, honest baseline.

package/skills/pikku-testing/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: pikku-testing
+description: 'Use when writing tests for Pikku functions, middleware, permissions, or services. Covers unit testing with direct invocation, runPikkuFunc, service mocking, and integration testing with the HTTP runner.
+TRIGGER when: user asks about testing, writing tests, test setup, mocking services, or integration testing Pikku functions.
+DO NOT TRIGGER when: user asks about running the existing test suite (use Bash) or CI configuration (not a Pikku skill).'
+installGroups: [core]
+---
+
+# Pikku Testing
+
+## 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 functions are pure business logic — no HTTP, no framework — making them easy to test. Test at three levels: direct function calls, `runPikkuFunc` (with middleware/permissions), and integration tests (full HTTP stack).
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions and their middleware/permissions
+pikku info middleware --verbose  # See middleware applied
+```
+
+See `pikku-concepts` for the core mental model.
+
+## Test Runner Setup
+
+Pikku uses Node.js built-in test runner with tsx for TypeScript:
+
+```bash
+node --import tsx --test src/**/*.test.ts
+```
+
+Standard test file:
+
+```typescript
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+```
+
+## Level 1: Direct Function Invocation
+
+The simplest approach — call `func` directly with mock services:
+
+```typescript
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+
+describe('createTodo', () => {
+  test('should create a todo', async () => {
+    const mockServices = {
+      todoStore: {
+        add: async (title: string) => ({
+          id: '1',
+          title,
+          completed: false,
+        }),
+      },
+    }
+
+    const result = await createTodo.func(mockServices as any, {
+      title: 'Buy milk',
+    })
+
+    assert.equal(result.title, 'Buy milk')
+    assert.equal(result.completed, false)
+  })
+})
+```
+
+This tests pure business logic — no middleware, no permissions, no validation.
+
+## Level 2: `runPikkuFunc` (Full Pipeline)
+
+Tests the function through Pikku's middleware, permissions, and schema validation pipeline:
+
+```typescript
+import { runPikkuFunc } from '@pikku/core'
+import { addFunction, addMiddleware, addPermission } from '@pikku/core'
+import { resetPikkuState, pikkuState } from '@pikku/core'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+test('should run function with middleware', async () => {
+  const mockSingletonServices = {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+  } as any
+
+  // Register function metadata
+  pikkuState(null, 'function', 'meta')['myFunc'] = {
+    pikkuFuncId: 'myFunc',
+    inputSchemaName: null,
+    outputSchemaName: null,
+  }
+
+  // Register the function
+  addFunction('myFunc', {
+    func: async (services, data) => {
+      return { greeting: `Hello ${data.name}` }
+    },
+  })
+
+  const result = await runPikkuFunc('rpc', 'test-wire', 'myFunc', {
+    singletonServices: mockSingletonServices,
+    getAllServices: () => mockSingletonServices,
+    data: () => ({ name: 'World' }),
+    auth: false,
+    wire: {},
+  })
+
+  assert.deepEqual(result, { greeting: 'Hello World' })
+})
+```
+
+### Testing Middleware Execution Order
+
+```typescript
+test('middleware runs in order: wiring tags -> wiring -> func tags -> func', async () => {
+  const mockSingletonServices = {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+  } as any
+
+  const order: string[] = []
+
+  const createMiddleware =
+    (name: string) => async (services: any, wire: any, next: Function) => {
+      order.push(name)
+      await next()
+    }
+
+  addMiddleware('apiTag', [createMiddleware('apiTag')])
+  addMiddleware('funcTag', [createMiddleware('funcTag')])
+
+  pikkuState(null, 'function', 'meta')['myFunc'] = {
+    pikkuFuncId: 'myFunc',
+    inputSchemaName: null,
+    outputSchemaName: null,
+    middleware: [{ type: 'tag', tag: 'funcTag' }],
+  }
+
+  addFunction('myFunc', {
+    func: async () => {
+      order.push('main')
+      return 'ok'
+    },
+    middleware: [createMiddleware('funcMiddleware')],
+    tags: ['funcTag'],
+  })
+
+  await runPikkuFunc('rpc', 'test', 'myFunc', {
+    singletonServices: mockSingletonServices,
+    getAllServices: () => mockSingletonServices,
+    data: () => ({}),
+    wireMiddleware: [createMiddleware('wiringMiddleware')],
+    inheritedMiddleware: [{ type: 'tag', tag: 'apiTag' }],
+    auth: false,
+    wire: {},
+  })
+
+  assert.deepEqual(order, [
+    'apiTag',
+    'wiringMiddleware',
+    'funcTag',
+    'funcMiddleware',
+    'main',
+  ])
+})
+```
+
+### Testing Permissions
+
+```typescript
+test('should reject when permission fails', async () => {
+  const mockSingletonServices = {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+  } as any
+
+  addPermission('admin', [
+    async () => false, // Always deny
+  ])
+
+  pikkuState(null, 'function', 'meta')['adminFunc'] = {
+    pikkuFuncId: 'adminFunc',
+    inputSchemaName: null,
+    outputSchemaName: null,
+    permissions: [{ type: 'tag', tag: 'admin' }],
+  }
+
+  addFunction('adminFunc', { func: async () => 'secret' })
+
+  await assert.rejects(
+    runPikkuFunc('rpc', 'test', 'adminFunc', {
+      singletonServices: mockSingletonServices,
+      getAllServices: () => mockSingletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+    }),
+    /Permission/
+  )
+})
+```
+
+## Level 3: Integration Testing (HTTP)
+
+Test the full HTTP stack using the `fetch` export:
+
+```typescript
+import { fetch, wireHTTP } from '@pikku/core/http'
+import { resetPikkuState, pikkuState, addFunction } from '@pikku/core'
+
+const mockSingletonServices = {
+  logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+} as any
+
+const listTodos = {
+  func: async () => ({ todos: [{ id: '1', title: 'Test todo' }] }),
+}
+
+beforeEach(() => {
+  resetPikkuState()
+
+  // Set up singleton services in state
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: async () => ({}),
+  })
+})
+
+test('GET /todos returns todo list', async () => {
+  // Register route metadata and function
+  pikkuState(null, 'http', 'meta')['get'] =
+    pikkuState(null, 'http', 'meta')['get'] || {}
+  pikkuState(null, 'http', 'meta')['get']['/todos'] = {
+    pikkuFuncId: 'listTodos',
+    method: 'get',
+    route: '/todos',
+  }
+  addFunction('listTodos', listTodos)
+  wireHTTP({ method: 'get', route: '/todos', func: listTodos })
+
+  const request = new Request('http://localhost/todos')
+  const response = await fetch(request)
+  const data = await response.json()
+
+  assert.equal(response.status, 200)
+  assert.ok(Array.isArray(data.todos))
+})
+```
+
+## Testing Services
+
+Test custom services in isolation:
+
+```typescript
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { LocalVariablesService } from '@pikku/core/services'
+
+describe('LocalVariablesService', () => {
+  test('should get and set variables', () => {
+    const service = new LocalVariablesService({ API_KEY: 'test-key' })
+    assert.equal(service.get('API_KEY'), 'test-key')
+
+    service.set('NEW_KEY', 'value')
+    assert.equal(service.get('NEW_KEY'), 'value')
+  })
+})
+```
+
+## Testing with Real Services (Verifier Pattern)
+
+For integration testing with a running server:
+
+```typescript
+// services.ts — real service setup for tests
+import { pikkuServices, pikkuWireServices } from '#pikku'
+import { LocalSecretService, LocalVariablesService } from '@pikku/core/services'
+
+export const createSingletonServices = pikkuServices(async (config) => {
+  const variables = new LocalVariablesService()
+  const secrets = new LocalSecretService(variables)
+  return { config, variables, secrets, logger: new ConsoleLogger() }
+})
+
+export const createWireServices = pikkuWireServices(async () => ({}))
+```
+
+```typescript
+// start.ts — bootstrap server for tests
+import './.pikku/pikku-bootstrap.gen.js'
+import { createSingletonServices, createWireServices } from './services.js'
+
+const config = {}
+const singletonServices = await createSingletonServices(config)
+const server = new PikkuFastifyServer(
+  config,
+  singletonServices,
+  createWireServices
+)
+await server.init()
+await server.start()
+```
+
+## Common Patterns
+
+### Mock Logger
+
+```typescript
+const mockLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}
+```
+
+### Mock Singleton Services
+
+```typescript
+const mockSingletonServices = {
+  logger: mockLogger,
+  todoStore: new InMemoryTodoStore(),
+  // Add whatever services your functions need
+} as any
+```
+
+### Reset State Between Tests
+
+Always reset pikku state in `beforeEach` to isolate tests:
+
+```typescript
+import { resetPikkuState } from '@pikku/core'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+```
+
+### Async Error Assertions
+
+```typescript
+await assert.rejects(
+  async () => await myFunc.func(services, { id: 'nonexistent' }),
+  { message: 'Not found' }
+)
+```
+
+## Complete Example
+
+```typescript
+// functions/todos.functions.ts
+export const createTodo = pikkuSessionlessFunc({
+  description: 'Create a todo',
+  input: z.object({ title: z.string().min(1) }),
+  output: z.object({ id: z.string(), title: z.string() }),
+  func: async ({ todoStore }, { title }) => {
+    return todoStore.add(title)
+  },
+})
+
+// functions/todos.test.ts
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+
+class MockTodoStore {
+  private todos: any[] = []
+
+  async add(title: string) {
+    const todo = { id: String(this.todos.length + 1), title, completed: false }
+    this.todos.push(todo)
+    return todo
+  }
+
+  async list() {
+    return this.todos
+  }
+}
+
+describe('createTodo', () => {
+  let todoStore: MockTodoStore
+
+  beforeEach(() => {
+    todoStore = new MockTodoStore()
+  })
+
+  test('creates a todo with the given title', async () => {
+    const result = await createTodo.func({ todoStore } as any, {
+      title: 'Buy milk',
+    })
+
+    assert.equal(result.id, '1')
+    assert.equal(result.title, 'Buy milk')
+  })
+
+  test('increments IDs', async () => {
+    await createTodo.func({ todoStore } as any, { title: 'First' })
+    const second = await createTodo.func({ todoStore } as any, {
+      title: 'Second',
+    })
+
+    assert.equal(second.id, '2')
+  })
+})
+```