@pikku/cli 0.12.91 → 0.12.93

package/skills/pikku-config/SKILL.md

@@ -1,212 +0,0 @@
----
-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.getSecret('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.getSecret('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

@@ -1,214 +0,0 @@
----
-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

@@ -1,71 +0,0 @@
----
-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

@@ -1,82 +0,0 @@
----
-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

@@ -1,86 +0,0 @@
----
-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,
-  })
-)
-```