@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-config/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: pikku-config
+description: 'Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app. Covers wireSecret, wireVariable, wireOAuth2Credential, and typed config access.
+TRIGGER when: code uses wireSecret/wireVariable/wireOAuth2Credential, user asks about env vars, secrets, config, OAuth2, or "how do I access environment variables".
+DO NOT TRIGGER when: user asks about API versioning/breaking changes (use pikku-versioning), service factories (use pikku-services), or auth middleware (use pikku-security).'
+installGroups: [core]
+---
+
+# Pikku Config, Secrets & OAuth2
+
+## 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.
+
+Manage secrets, variables, and OAuth2 credentials. Never use `process.env` in Pikku functions — use typed services instead.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions and their versions
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## Secrets & Variables
+
+### `wireSecret(config)`
+
+Declare a secret with a Zod schema for type-safe access:
+
+```typescript
+wireSecret({
+  name: string, // Secret identifier
+  schema: ZodSchema, // Shape and validation
+})
+```
+
+### `wireVariable(config)`
+
+Declare a variable (non-sensitive config) with a Zod schema:
+
+```typescript
+wireVariable({
+  name: string,
+  schema: ZodSchema,
+})
+```
+
+### Accessing in Functions
+
+```typescript
+// Secrets — encrypted, sensitive values
+const config = await services.secrets.getSecretJSON('SECRET_NAME')
+
+// Variables — plain-text configuration
+const flags = await services.variables.getVariableJSON('VARIABLE_NAME')
+
+// Simple string access
+const apiKey = services.variables.get('API_KEY')
+```
+
+### Local Development Services
+
+```typescript
+import { LocalSecretService, LocalVariablesService } from '@pikku/core/services'
+
+const createSingletonServices = pikkuServices(async (config) => ({
+  secrets: new LocalSecretService(), // Reads from .env or local files
+  variables: new LocalVariablesService(), // Reads from environment
+}))
+```
+
+### Usage Patterns
+
+```typescript
+// Declare secrets with typed schemas
+wireSecret({
+  name: 'STRIPE_CONFIG',
+  schema: z.object({
+    apiKey: z.string().startsWith('sk_'),
+    webhookSecret: z.string(),
+  }),
+})
+
+// In your function — fully typed
+const config = await secrets.getSecretJSON('STRIPE_CONFIG')
+// config.apiKey       → string (autocompleted)
+// config.webhookSecret → string (autocompleted)
+
+// Declare variables
+wireVariable({
+  name: 'FEATURE_FLAGS',
+  schema: z.object({
+    darkMode: z.boolean(),
+    maxUploadMB: z.number().default(10),
+  }),
+})
+
+// Read it — typed and validated
+const flags = await variables.getVariableJSON('FEATURE_FLAGS')
+// flags.darkMode    → boolean
+// flags.maxUploadMB → number
+```
+
+## OAuth2 Credentials
+
+### `wireOAuth2Credential(config)`
+
+```typescript
+wireOAuth2Credential({
+  name: string,              // Credential identifier
+  displayName: string,       // Human-readable name
+  secretId: string,          // Secret holding { clientId, clientSecret }
+  tokenSecretId: string,     // Secret for token storage (auto-refreshed)
+  authorizationUrl: string,  // OAuth2 authorization endpoint
+  tokenUrl: string,          // OAuth2 token endpoint
+  scopes: string[],          // Required OAuth2 scopes
+})
+```
+
+### Usage
+
+```typescript
+wireOAuth2Credential({
+  name: 'slackOAuth',
+  displayName: 'Slack OAuth',
+  secretId: 'SLACK_OAUTH_APP',
+  tokenSecretId: 'SLACK_OAUTH_TOKENS',
+  authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+  tokenUrl: 'https://slack.com/api/oauth.v2.access',
+  scopes: ['chat:write', 'channels:read'],
+})
+
+// In your function — tokens refresh automatically
+const response = await slackOAuth.request(
+  'https://slack.com/api/chat.postMessage',
+  {
+    method: 'POST',
+    body: JSON.stringify({ channel, text }),
+  }
+)
+const data = await response.json()
+```
+
+## Key Rule
+
+**Never use `process.env` inside Pikku functions.** Use the `variables` or `secrets` service:
+
+```typescript
+// ❌ Wrong
+const apiKey = process.env.API_KEY
+
+// ✅ Correct
+const apiKey = services.variables.get('API_KEY')
+```
+
+`process.env` belongs only in server bootstrap code (`start.ts`).
+
+## Complete Example
+
+```typescript
+// schemas/config.ts
+wireSecret({
+  name: 'DATABASE_CONFIG',
+  schema: z.object({
+    connectionString: z.string().url(),
+    maxPoolSize: z.number().default(10),
+  }),
+})
+
+wireVariable({
+  name: 'APP_CONFIG',
+  schema: z.object({
+    appName: z.string(),
+    maxUploadSizeMB: z.number().default(10),
+    maintenanceMode: z.boolean().default(false),
+  }),
+})
+
+wireOAuth2Credential({
+  name: 'githubOAuth',
+  displayName: 'GitHub OAuth',
+  secretId: 'GITHUB_OAUTH_APP',
+  tokenSecretId: 'GITHUB_OAUTH_TOKENS',
+  authorizationUrl: 'https://github.com/login/oauth/authorize',
+  tokenUrl: 'https://github.com/login/oauth/access_token',
+  scopes: ['read:user', 'repo'],
+})
+
+// functions/admin.functions.ts
+export const getAppStatus = pikkuSessionlessFunc({
+  title: 'Get App Status',
+  func: async ({ variables, secrets }) => {
+    const appConfig = await variables.getVariableJSON('APP_CONFIG')
+    return {
+      appName: appConfig.appName,
+      maintenanceMode: appConfig.maintenanceMode,
+    }
+  },
+})
+```

package/skills/pikku-cron/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: pikku-cron
+description: 'Use when adding scheduled tasks, recurring jobs, or cron-based automation to a Pikku app. Covers wireScheduler, cron expressions, scheduled task wire object, and scheduler middleware.
+TRIGGER when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or "run every X minutes/hours".
+DO NOT TRIGGER when: user asks about background jobs with retries (use pikku-queue) or event-driven triggers (use pikku-trigger).'
+---
+
+# Pikku Cron/Scheduler 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.
+
+Wire Pikku functions to run on a schedule using cron expressions. Uses `pikkuVoidFunc` (no input/output).
+
+## 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
+
+### `wireScheduler(config)`
+
+```typescript
+import { wireScheduler } from '@pikku/core/scheduler'
+
+wireScheduler({
+  name: string,            // Unique scheduler name
+  schedule: string,        // Cron expression
+  func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
+  middleware?: PikkuMiddleware[],
+})
+```
+
+### Wire Object (`wire.scheduledTask`)
+
+Inside scheduled functions:
+
+```typescript
+wire.scheduledTask.name // Scheduler name
+wire.scheduledTask.schedule // Cron expression string
+wire.scheduledTask.executionTime // When this execution was triggered
+wire.scheduledTask.skip(reason) // Skip this execution (no error)
+```
+
+### Cron Expression Reference
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Common patterns:
+
+| Expression    | Meaning                    |
+| ------------- | -------------------------- |
+| `*/5 * * * *` | Every 5 minutes            |
+| `0 9 * * *`   | Daily at 9:00 AM           |
+| `0 9 * * 1`   | Every Monday at 9:00 AM    |
+| `0 0 1 * *`   | First of month at midnight |
+| `0 */6 * * *` | Every 6 hours              |
+| `30 2 * * 0`  | Sundays at 2:30 AM         |
+
+## Usage Patterns
+
+### Basic Scheduled Task
+
+```typescript
+const dailySummary = pikkuVoidFunc({
+  title: 'Daily Summary',
+  func: async ({ db, emailService, logger }) => {
+    logger.info('Generating daily summary')
+    const stats = await db.getDailyStats()
+    await emailService.sendSummary(stats)
+  },
+})
+
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+})
+```
+
+### Using the Wire Object
+
+```typescript
+const weeklyCleanup = pikkuVoidFunc({
+  title: 'Weekly Cleanup',
+  func: async ({ db, logger }, _input, wire) => {
+    logger.info(`Running: ${wire.scheduledTask.name}`)
+    logger.info(`Schedule: ${wire.scheduledTask.schedule}`)
+    logger.info(`Execution time: ${wire.scheduledTask.executionTime}`)
+
+    const staleCount = await db.countStaleTodos()
+    if (staleCount === 0) {
+      wire.scheduledTask.skip('No stale todos found')
+      return
+    }
+
+    await db.deleteCompletedTodos({ olderThan: '30d' })
+    logger.info(`Cleaned ${staleCount} stale todos`)
+  },
+})
+
+wireScheduler({
+  name: 'weeklyCleanup',
+  schedule: '0 0 * * 0',
+  func: weeklyCleanup,
+})
+```
+
+### Scheduler Middleware
+
+```typescript
+const schedulerMetrics = pikkuMiddleware(
+  async ({ logger }, { scheduledTask }, next) => {
+    const start = Date.now()
+    logger.info(`Task started: ${scheduledTask.name}`)
+
+    try {
+      await next()
+      logger.info(`Task completed: ${scheduledTask.name}`, {
+        duration: Date.now() - start,
+      })
+    } catch (error) {
+      logger.error(`Task failed: ${scheduledTask.name}`, {
+        error: error.message,
+        duration: Date.now() - start,
+      })
+      throw error
+    }
+  }
+)
+
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+  middleware: [schedulerMetrics],
+})
+```
+
+## Complete Example
+
+```typescript
+// functions/scheduled.functions.ts
+export const dailySummary = pikkuVoidFunc({
+  title: 'Daily Summary',
+  func: async ({ db, emailService, logger }) => {
+    const stats = await db.getDailyStats()
+    await emailService.sendSummary(stats)
+    logger.info('Daily summary sent', { stats })
+  },
+})
+
+export const cleanupExpired = pikkuVoidFunc({
+  title: 'Cleanup Expired',
+  func: async ({ db, logger }, _input, wire) => {
+    const count = await db.countExpiredSessions()
+    if (count === 0) {
+      wire.scheduledTask.skip('No expired sessions')
+      return
+    }
+    await db.deleteExpiredSessions()
+    logger.info(`Cleaned ${count} expired sessions`)
+  },
+})
+
+export const syncInventory = pikkuVoidFunc({
+  title: 'Sync Inventory',
+  func: async ({ inventoryApi, db, logger }) => {
+    const updates = await inventoryApi.getChanges()
+    await db.applyInventoryUpdates(updates)
+    logger.info(`Synced ${updates.length} inventory changes`)
+  },
+})
+
+// wirings/scheduler.wiring.ts
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+})
+wireScheduler({
+  name: 'cleanupExpired',
+  schedule: '0 */6 * * *',
+  func: cleanupExpired,
+})
+wireScheduler({
+  name: 'syncInventory',
+  schedule: '*/15 * * * *',
+  func: syncInventory,
+})
+```

package/skills/pikku-deploy-azure/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: pikku-deploy-azure
+description: 'Use when deploying a Pikku app to Azure Functions. Covers PikkuAzFunctionsLogger and PikkuAzTimerRequest for Azure Functions runtime.
+TRIGGER when: user asks about Azure Functions, Azure deployment, or @pikku/azure-functions.
+DO NOT TRIGGER when: user asks about AWS Lambda (use pikku-deploy-lambda) or Cloudflare Workers (use pikku-deploy-cloudflare).'
+---
+
+# Pikku Azure Functions Deployment
+
+## 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/azure-functions` provides Azure Functions runtime adapters for Pikku.
+
+## Installation
+
+```bash
+yarn add @pikku/azure-functions @azure/functions
+```
+
+## API Reference
+
+### `PikkuAzFunctionsLogger`
+
+Logger implementation that integrates with Azure Functions' built-in logging context.
+
+### `PikkuAzTimerRequest`
+
+Timer trigger request handler for running Pikku scheduled functions as Azure Timer Triggers.
+
+## Usage Patterns
+
+### HTTP Function
+
+```typescript
+import { app } from '@azure/functions'
+import { PikkuAzFunctionsLogger } from '@pikku/azure-functions'
+
+app.http('api', {
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  route: '{*path}',
+  handler: async (request, context) => {
+    const logger = new PikkuAzFunctionsLogger(context)
+    // Wire Pikku HTTP runner with Azure request/response
+  },
+})
+```
+
+### Timer Trigger
+
+```typescript
+import { app } from '@azure/functions'
+import { PikkuAzTimerRequest } from '@pikku/azure-functions'
+
+app.timer('scheduler', {
+  schedule: '0 */5 * * * *',
+  handler: async (timer, context) => {
+    const request = new PikkuAzTimerRequest(timer)
+    // Process scheduled Pikku functions
+  },
+})
+```

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pikku-deploy-cloudflare
+description: 'Use when deploying a Pikku app to Cloudflare Workers. Covers HTTP fetch handler, scheduled tasks, and WebSocket via Durable Objects.
+TRIGGER when: code imports @pikku/cloudflare, user mentions Cloudflare Workers deployment, or worker entry uses ExportedHandler/wrangler.toml.
+DO NOT TRIGGER when: just defining functions/wirings without Cloudflare-specific code.'
+installGroups: [fabric]
+---
+
+# Pikku Cloudflare Workers Deployment
+
+## 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.
+
+```bash
+yarn add @pikku/cloudflare
+```
+
+## Worker Entry
+
+```typescript
+import { runFetch, runScheduled } from '@pikku/cloudflare'
+import { setupServices } from './setup-services.js'
+import './.pikku/pikku-bootstrap.gen.js'
+
+export default {
+  async scheduled(controller, env) {
+    await setupServices(env)
+    await runScheduled(controller)
+  },
+
+  async fetch(request, env): Promise<Response> {
+    await setupServices(env)
+    return await runFetch(request as unknown as Request)
+  },
+} satisfies ExportedHandler<Record<string, string>>
+```
+
+## Service Setup
+
+Cloudflare passes env variables per-request — wrap them with Pikku services:
+
+```typescript
+// setup-services.ts
+import { LocalVariablesService, LocalSecretService } from '@pikku/core/services'
+import { createConfig, createSingletonServices } from './services.js'
+
+export const setupServices = async (
+  env: Record<string, string | undefined>
+) => {
+  const localVariables = new LocalVariablesService(env)
+  const config = await createConfig(localVariables)
+  const localSecrets = new LocalSecretService(localVariables)
+  return await createSingletonServices(config, {
+    variables: localVariables,
+    secrets: localSecrets,
+  })
+}
+```
+
+## WebSocket (Durable Objects)
+
+```typescript
+import { CloudflareWebSocketHibernationServer } from '@pikku/cloudflare'
+
+export class WebSocketHibernationServer extends CloudflareWebSocketHibernationServer {
+  protected async getParams() {
+    const singletonServices = await setupServices(this.env)
+    return { singletonServices }
+  }
+}
+```
+
+Register the Durable Object in `wrangler.toml` and export from the worker entry.

package/skills/pikku-deploy-express/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pikku-deploy-express
+description: 'Use when deploying a Pikku app with Express. Covers PikkuExpressServer standalone and pikkuExpressMiddleware for existing Express apps.
+TRIGGER when: code imports @pikku/express or @pikku/express-middleware, user mentions Express deployment, or start.ts creates a PikkuExpressServer.
+DO NOT TRIGGER when: just defining functions/wirings without Express-specific code.'
+---
+
+# Pikku Express Deployment
+
+## 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.
+
+## Standalone Server
+
+```bash
+yarn add @pikku/express
+```
+
+```typescript
+import { PikkuExpressServer } from '@pikku/express'
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const appServer = new PikkuExpressServer(
+  { ...config, port: 4002, hostname: 'localhost' },
+  singletonServices.logger
+)
+appServer.enableExitOnSigInt()
+await appServer.init()
+await appServer.start()
+```
+
+**Constructor:** `new PikkuExpressServer(config, logger)`
+
+**Config extends CoreConfig with:**
+
+- `port: number`
+- `hostname: string`
+- `healthCheckPath?: string`
+- `limits?: Partial<Record<string, string>>`
+- `content?: LocalContentConfig` (for static assets / file uploads)
+
+**Methods:**
+
+- `init(httpOptions?): Promise<void>` — Register middleware and routes
+- `start(): Promise<void>` — Start listening
+- `stop(): Promise<void>` — Graceful shutdown
+- `enableExitOnSigInt(): Promise<void>` — SIGINT handler
+- `enableCors(options): void` — Enable CORS
+- `enableStaticAssets(): void` — Serve static files (requires `content` config)
+
+**Property:** `app: Express` — Direct access to Express instance for custom middleware.
+
+## Middleware (existing Express app)
+
+```bash
+yarn add @pikku/express-middleware
+```
+
+```typescript
+import express from 'express'
+import { pikkuExpressMiddleware } from '@pikku/express-middleware'
+import './.pikku/pikku-bootstrap.gen.js'
+
+const app = express()
+app.use(
+  pikkuExpressMiddleware({
+    logger: singletonServices.logger,
+    logRoutes: true,
+    loadSchemas: true,
+  })
+)
+```