@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-ai-voice/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: pikku-ai-voice
+description: 'Use when adding voice input (speech-to-text) or voice output (text-to-speech) to AI agents in a Pikku app. Covers voiceInput/voiceOutput middleware hooks and STT/TTS service interfaces.
+TRIGGER when: code uses voiceInput, voiceOutput, STTService, TTSService, or user asks about voice, speech-to-text, text-to-speech, or @pikku/ai-voice.
+DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or Vercel AI SDK (use pikku-ai-vercel).'
+---
+
+# Pikku AI Voice (Speech I/O)
+
+## 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/ai-voice` provides speech-to-text and text-to-speech middleware hooks for Pikku AI agents.
+
+## Installation
+
+```bash
+yarn add @pikku/ai-voice
+```
+
+## API Reference
+
+### Service Interfaces
+
+```typescript
+interface STTService {
+  transcribe(
+    audio: Uint8Array,
+    options?: { language?: string; format?: string }
+  ): Promise<string>
+}
+
+interface TTSService {
+  synthesize(
+    text: string,
+    options?: { voice?: string; format?: string }
+  ): Promise<Uint8Array>
+  synthesizeStream?(
+    text: string,
+    options?: { voice?: string; format?: string }
+  ): AsyncIterable<Uint8Array>
+}
+```
+
+### Middleware Hooks
+
+```typescript
+import { voiceInput, voiceOutput } from '@pikku/ai-voice'
+
+voiceInput(config?: { language?: string }): PikkuAIMiddlewareHooks
+voiceOutput(config?: { format?: string; voice?: string }): PikkuAIMiddlewareHooks
+```
+
+These return middleware hooks that can be attached to AI agent wirings to automatically transcribe audio input and synthesize audio output.
+
+## Usage Patterns
+
+### Voice-Enabled Agent
+
+```typescript
+import { voiceInput, voiceOutput } from '@pikku/ai-voice'
+import { wireAIAgent } from '@pikku/core/ai-agent'
+
+wireAIAgent({
+  name: 'voice-assistant',
+  model: 'openai:gpt-4o',
+  systemPrompt: 'You are a voice assistant.',
+  middlewareHooks: [
+    voiceInput({ language: 'en' }),
+    voiceOutput({ voice: 'alloy', format: 'mp3' }),
+  ],
+  func: myAgentFunc,
+})
+```
+
+### Custom STT/TTS Services
+
+Implement the `STTService` and `TTSService` interfaces with your provider (OpenAI Whisper, ElevenLabs, etc.) and register them as singleton services.

package/skills/pikku-auth-js/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pikku-auth-js
+description: 'Use when integrating Auth.js (NextAuth) with a Pikku app. Covers createAuthHandler, createAuthRoutes, and Auth.js configuration.
+TRIGGER when: code uses createAuthHandler, createAuthRoutes, user asks about Auth.js, NextAuth, OAuth providers, or @pikku/auth-js.
+DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security) or custom session services (use pikku-services).'
+---
+
+# Pikku Auth.js Integration
+
+## 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/auth-js` provides [Auth.js](https://authjs.dev/) integration for Pikku apps, handling OAuth providers, session management, and auth routes.
+
+## Installation
+
+```bash
+yarn add @pikku/auth-js @auth/core
+```
+
+## API Reference
+
+### `createAuthHandler(config)`
+
+Creates a Pikku function that handles all Auth.js routes (signin, signout, callback, etc.):
+
+```typescript
+import { createAuthHandler } from '@pikku/auth-js'
+
+const authHandler = createAuthHandler(
+  config: AuthConfig | ((services: CoreSingletonServices) => AuthConfig | Promise<AuthConfig>)
+)
+// Returns: { func: CorePikkuFunctionSessionless }
+```
+
+The config can be static or a factory function that receives singleton services (useful for dynamic provider configuration).
+
+### `createAuthRoutes(config, basePath?)`
+
+Creates HTTP route contracts for Auth.js endpoints:
+
+```typescript
+import { createAuthRoutes } from '@pikku/auth-js'
+
+const authRoutes = createAuthRoutes(
+  config: AuthConfig | ((services) => AuthConfig | Promise<AuthConfig>),
+  basePath?: string  // default: '/auth'
+)
+// Returns: HTTPRouteContract<HTTPRouteMap>
+```
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { createAuthHandler, createAuthRoutes } from '@pikku/auth-js'
+import GitHub from '@auth/core/providers/github'
+
+const authConfig = {
+  providers: [
+    GitHub({
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    }),
+  ],
+}
+
+const authHandler = createAuthHandler(authConfig)
+const authRoutes = createAuthRoutes(authConfig)
+```
+
+### Dynamic Config with Services
+
+```typescript
+const authHandler = createAuthHandler(async (services) => {
+  const githubSecret = await services.secrets.getSecretJSON('github-oauth')
+  return {
+    providers: [
+      GitHub({
+        clientId: githubSecret.clientId,
+        clientSecret: githubSecret.clientSecret,
+      }),
+    ],
+  }
+})
+```
+
+### Wiring Auth Routes
+
+```typescript
+import { wireHTTPRoute } from '@pikku/core/http'
+
+// Auth routes are automatically wired when passed to your HTTP runner
+const routes = [
+  ...authRoutes,
+  // ...your other routes
+]
+```

package/skills/pikku-aws/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: pikku-aws
+description: 'Use when setting up AWS services (S3, SQS, Secrets Manager) in a Pikku app. Covers S3Content for file storage, SQSQueueService for queues, and AWSSecrets for secret management.
+TRIGGER when: code uses S3Content, SQSQueueService, AWSSecrets, or user asks about AWS integration, S3 uploads, SQS queues, or AWS Secrets Manager with Pikku.
+DO NOT TRIGGER when: user asks about AWS Lambda runtime (use pikku-deploy-lambda).'
+---
+
+# Pikku AWS Services
+
+## 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/aws-services` provides AWS-backed implementations of Pikku's content, queue, and secret service interfaces.
+
+## Installation
+
+```bash
+yarn add @pikku/aws-services
+```
+
+## API Reference
+
+### `S3Content` (File Storage)
+
+```typescript
+import { S3Content } from '@pikku/aws-services'
+
+const content = new S3Content(
+  config: S3ContentConfig,
+  logger: Logger,
+  signConfig: { keyPairId: string; privateKey: string }
+)
+```
+
+**Methods:**
+
+- `signURL(url: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>` — Sign a CloudFront URL
+- `signContentKey(key: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>` — Sign a content key
+- `getUploadURL(Key: string, ContentType: string): Promise<{ uploadUrl, assetKey }>` — Get presigned upload URL
+- `readFile(Key: string): Promise<ReadableStream>` — Read file as stream
+- `readFileAsBuffer(Key: string): Promise<Buffer>` — Read file as buffer
+- `writeFile(Key: string, stream: ReadableStream): Promise<boolean>` — Write file from stream
+- `copyFile(Key: string, fromAbsolutePath: string): Promise<boolean>` — Copy local file to S3
+- `deleteFile(Key: string): Promise<boolean>` — Delete file
+
+### `SQSQueueService` (Queue)
+
+```typescript
+import { SQSQueueService } from '@pikku/aws-services'
+
+const queue = new SQSQueueService(config: SQSQueueServiceConfig)
+```
+
+Implements `QueueService`. Note: `supportsResults = false` — job status tracking is not supported.
+
+**Methods:**
+
+- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — Enqueue a message
+
+### `AWSSecrets` (Secrets Manager)
+
+```typescript
+import { AWSSecrets } from '@pikku/aws-services'
+
+const secrets = new AWSSecrets(config: AWSConfig)
+```
+
+**Methods:**
+
+- `getSecret<R>(SecretId: string): Promise<R>` — Get a secret value
+- `getSecretJSON<R>(SecretId: string): Promise<R>` — Get and parse a JSON secret
+- `hasSecret(SecretId: string): Promise<boolean>` — Check if secret exists
+
+## Usage Patterns
+
+### S3 Content Service
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new S3Content(
+    { bucket: config.s3Bucket, region: config.awsRegion },
+    logger,
+    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
+  )
+  return { config, logger, content }
+})
+```
+
+### SQS Queue
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const queue = new SQSQueueService({
+    region: config.awsRegion,
+    queueUrlPrefix: config.sqsUrlPrefix,
+  })
+  return { config, queue }
+})
+```

package/skills/pikku-backblaze/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pikku-backblaze
+description: 'Use when setting up Backblaze B2 file storage in a Pikku app. Covers B2Content for file uploads, downloads, and signed URLs.
+TRIGGER when: code uses B2Content, user asks about Backblaze B2, or @pikku/backblaze.
+DO NOT TRIGGER when: user asks about S3 storage (use pikku-aws).'
+---
+
+# Pikku Backblaze (B2 Content Storage)
+
+## 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/backblaze` provides Backblaze B2-backed file storage implementing the `ContentService` interface.
+
+## Installation
+
+```bash
+yarn add @pikku/backblaze
+```
+
+## API Reference
+
+### `B2Content`
+
+```typescript
+import { B2Content } from '@pikku/backblaze'
+
+const content = new B2Content(
+  config: B2ContentConfig,
+  logger: Logger
+)
+```
+
+**Methods:**
+
+- `signContentKey(key: string, dateLessThan: Date): Promise<string>` — Sign a content key
+- `signURL(url: string, dateLessThan: Date): Promise<string>` — Sign a URL
+- `getUploadURL(fileKey: string, contentType: string): Promise<{ uploadUrl, assetKey, uploadMethod?, uploadHeaders? }>` — Get upload URL
+- `writeFile(assetKey: string, stream: ReadableStream): Promise<boolean>` — Write file
+- `copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>` — Copy local file to B2
+- `readFile(assetKey: string): Promise<ReadableStream>` — Read file as stream
+- `readFileAsBuffer(assetKey: string): Promise<Buffer>` — Read file as buffer
+- `deleteFile(fileName: string): Promise<boolean>` — Delete file
+
+## Usage Patterns
+
+```typescript
+import { B2Content } from '@pikku/backblaze'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new B2Content(
+    {
+      applicationKeyId: config.b2KeyId,
+      applicationKey: config.b2AppKey,
+      bucketId: config.b2BucketId,
+      cdnUrl: config.b2CdnUrl,
+    },
+    logger
+  )
+  return { config, logger, content }
+})
+```

package/skills/pikku-cli/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: pikku-cli
+description: 'Use when building CLI commands with Pikku. Covers wireCLI, pikkuCLICommand, subcommands, options, parameters, custom renderers, and nested command groups.
+TRIGGER when: code uses wireCLI/pikkuCLICommand, user asks about CLI commands, terminal tools, command-line interface, or adding subcommands.
+DO NOT TRIGGER when: user asks about the pikku CLI tool itself (use pikku-info) or HTTP endpoints (use pikku-http).'
+installGroups: [core]
+---
+
+# Pikku CLI 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 as CLI commands with parameters, options, subcommands, and custom terminal renderers.
+
+## 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
+
+### `wireCLI(config)`
+
+```typescript
+import { wireCLI } from '@pikku/core/cli'
+
+wireCLI({
+  program: string,              // Program name (e.g. 'todos')
+  options?: {                   // Global options
+    [key: string]: {
+      description: string,
+      short?: string,           // Single char alias (e.g. 'v')
+      default?: any,
+    }
+  },
+  render?: PikkuCLIRender,      // Default renderer for all commands
+  commands: {
+    [name: string]: PikkuCLICommand | {
+      description: string,
+      subcommands: { [name: string]: PikkuCLICommand }
+    }
+  },
+})
+```
+
+### `pikkuCLICommand(config)`
+
+```typescript
+import { pikkuCLICommand } from '#pikku'
+
+pikkuCLICommand({
+  parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
+  func: PikkuFunc,              // Business logic function
+  description?: string,
+  render?: PikkuCLIRender,      // Custom output renderer
+  options?: {
+    [key: string]: {
+      description: string,
+      short?: string,
+      default?: any,
+      choices?: string[],       // Restrict to values
+    }
+  },
+})
+```
+
+### `pikkuCLIRender(fn)`
+
+```typescript
+import { pikkuCLIRender } from '@pikku/core/cli'
+
+const renderer = pikkuCLIRender<OutputType>((services, data) => {
+  // Format and print output to terminal
+  console.log(data)
+})
+```
+
+## Usage Patterns
+
+### Basic Commands
+
+```typescript
+wireCLI({
+  program: 'todos',
+  commands: {
+    add: pikkuCLICommand({
+      parameters: '<text>',
+      func: createTodo,
+      description: 'Add a new todo',
+      render: todoRenderer,
+      options: {
+        priority: {
+          description: 'Set priority',
+          short: 'p',
+          default: 'normal',
+          choices: ['low', 'normal', 'high'],
+        },
+      },
+    }),
+    list: pikkuCLICommand({
+      func: listTodos,
+      description: 'List all todos',
+      render: todosRenderer,
+      options: {
+        completed: {
+          description: 'Show completed only',
+          short: 'c',
+          default: false,
+        },
+      },
+    }),
+  },
+})
+// Usage: todos add "Buy milk" -p high
+// Usage: todos list -c
+```
+
+### Nested Subcommands
+
+```typescript
+wireCLI({
+  program: 'app',
+  options: {
+    verbose: { description: 'Verbose output', short: 'v', default: false },
+  },
+  commands: {
+    greet: pikkuCLICommand({
+      parameters: '<name>',
+      func: greetUser,
+      render: greetRenderer,
+    }),
+
+    user: {
+      description: 'User management',
+      subcommands: {
+        create: pikkuCLICommand({
+          parameters: '<username> <email>',
+          func: createUser,
+          render: userRenderer,
+          options: {
+            admin: { description: 'Admin role', short: 'a', default: false },
+          },
+        }),
+        list: pikkuCLICommand({
+          func: listUsers,
+          render: usersRenderer,
+          options: {
+            limit: { description: 'Max results', short: 'l' },
+          },
+        }),
+      },
+    },
+  },
+})
+// Usage: app greet Alice
+// Usage: app user create bob bob@example.com -a
+// Usage: app user list -l 10
+// Usage: app -v user list
+```
+
+### Custom Renderers
+
+```typescript
+const todoRenderer = pikkuCLIRender<{ todo: Todo }>((_services, { todo }) => {
+  console.log(`✓ Created: ${todo.text} (priority: ${todo.priority})`)
+})
+
+const todosRenderer = pikkuCLIRender<{ todos: Todo[] }>(
+  (_services, { todos }) => {
+    todos.forEach((t, i) => {
+      const check = t.completed ? '✓' : ' '
+      console.log(`  ${i + 1}. ${t.text}  ${check}`)
+    })
+  }
+)
+
+// Default renderer for program, override per-command
+wireCLI({
+  program: 'todos',
+  render: jsonRenderer,
+  commands: {
+    add: pikkuCLICommand({
+      func: createTodo,
+      render: todoRenderer, // Overrides jsonRenderer
+    }),
+  },
+})
+```
+
+## Complete Example
+
+```typescript
+// functions/admin.functions.ts
+export const createUser = pikkuFunc({
+  title: 'Create User',
+  func: async ({ db }, { username, email, admin }) => {
+    const user = await db.createUser({
+      username,
+      email,
+      role: admin ? 'admin' : 'user',
+    })
+    return { user }
+  },
+})
+
+export const listUsers = pikkuSessionlessFunc({
+  title: 'List Users',
+  func: async ({ db }, { limit }) => {
+    return { users: await db.listUsers(limit || 50) }
+  },
+})
+
+export const deleteUser = pikkuFunc({
+  title: 'Delete User',
+  func: async ({ db }, { username }) => {
+    await db.deleteUser(username)
+    return { deleted: username }
+  },
+})
+
+// wirings/cli.wiring.ts
+const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
+  console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)
+})
+
+const usersRenderer = pikkuCLIRender<{ users: User[] }>(
+  (_services, { users }) => {
+    console.log(`Users (${users.length}):`)
+    users.forEach((u) =>
+      console.log(`  ${u.username} <${u.email}> [${u.role}]`)
+    )
+  }
+)
+
+wireCLI({
+  program: 'admin',
+  commands: {
+    user: {
+      description: 'User management',
+      subcommands: {
+        create: pikkuCLICommand({
+          parameters: '<username> <email>',
+          func: createUser,
+          render: userRenderer,
+          options: {
+            admin: {
+              description: 'Create as admin',
+              short: 'a',
+              default: false,
+            },
+          },
+        }),
+        list: pikkuCLICommand({
+          func: listUsers,
+          render: usersRenderer,
+          options: {
+            limit: { description: 'Max results', short: 'l' },
+          },
+        }),
+        delete: pikkuCLICommand({
+          parameters: '<username>',
+          func: deleteUser,
+          description: 'Delete a user',
+        }),
+      },
+    },
+  },
+})
+```