@pikku/cli 0.12.91 → 0.12.93

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

@@ -1,82 +0,0 @@
----
-name: pikku-ai-vercel
-description: >-
-  Use when setting up AI agent execution with the Vercel AI SDK in a Pikku app. Covers
-  VercelAIAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses
-  VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
-  @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or
-  voice I/O (use pikku-ai-voice).
-installGroups: [core]
----
-
-# Pikku AI Vercel (Agent Runner)
-
-## 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-vercel` provides an AI agent runner backed by the [Vercel AI SDK](https://sdk.vercel.ai/). Implements `AIAgentRunnerService` from `@pikku/core`.
-
-## Installation
-
-```bash
-yarn add @pikku/ai-vercel ai @ai-sdk/openai  # or any AI SDK provider
-```
-
-## API Reference
-
-### `VercelAIAgentRunner`
-
-```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
-
-const runner = new VercelAIAgentRunner(
-  providers: Record<string, any>  // Map of provider name → Vercel AI SDK provider instance
-)
-```
-
-**Methods:**
-
-- `stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>` — Stream AI responses with tool calls
-- `run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>` — Execute a single AI step (non-streaming)
-
-The `providers` map lets you register multiple AI providers. Model strings use `provider:model` format (e.g., `"openai:gpt-4o"`).
-
-## Usage Patterns
-
-### Basic Setup
-
-```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
-import { openai } from '@ai-sdk/openai'
-import { anthropic } from '@ai-sdk/anthropic'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const aiRunner = new VercelAIAgentRunner({
-    openai: openai,
-    anthropic: anthropic,
-  })
-  return { config, aiRunner }
-})
-```
-
-### With AI Agent Wiring
-
-```typescript
-import { wireAIAgent } from '@pikku/core/ai-agent'
-
-wireAIAgent({
-  name: 'assistant',
-  model: 'openai:gpt-4o',
-  systemPrompt: 'You are a helpful assistant.',
-  func: myAgentFunc,
-})
-```
-
-The `VercelAIAgentRunner` is used internally by Pikku's AI agent wiring to execute model calls. See `pikku-ai-agent` for wiring details.

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

@@ -1,88 +0,0 @@
----
-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-audit/SKILL.md

@@ -1,175 +0,0 @@
----
-name: pikku-audit
-description: >-
-  Use when adding audit / activity-history / change-tracking to a Pikku app, or when a function
-  needs to record who changed what. Covers the built-in AuditService sink, the per-invocation
-  auditLog buffer (createInvocationAudit / pikkuWireServices), the `audit: true` function flag,
-  explicit `auditLog.write()` domain events, automatic query-level capture via
-  createAuditedKysely, and the durable KyselyAuditService sink. TRIGGER when: user asks for an
-  audit log, change history, activity feed, "who did this", or a custom audit/history table; code
-  uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when:
-  user wants app logging/telemetry (use the logger) or DB migrations in general (use
-  pikku-kysely).
-installGroups: [core]
----
-
-# Pikku Audit
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Check how services are wired (`services.ts`) and whether an `audit` table migration exists before adding audit calls.
-2. NEVER hand-roll a custom `audit_log` / history table with direct `insertInto('audit_log')` calls. The framework owns audit. A bespoke table drifts from the runtime (missing actor/trace/wire context, hand-written CHECK constraints that reject valid events, no prod sink). Use the built-in path below.
-3. Make the smallest source change: mark the function `audit: true`, inject `auditLog`, call `auditLog.write(...)`. Do not invent a new service.
-4. Validate with `pikku all` (regenerates the service flags) then run the app / e2e.
-
-## Mental model — two layers
-
-- **`audit` (singleton `AuditService`)** — the durable **sink**. Write-only: `audit(event)` + optional `write(batch)`. Defaults to `NoopAuditService` (discards). Swap in a real sink to persist (see Sinks).
-- **`auditLog` (wire service `AuditLog`)** — a per-invocation **buffer** built from the sink via `createInvocationAudit(audit, wire)`. `auditLog.write(input)` enriches each event with `functionId`, `wireType`, `traceId`, `occurredAt`, and `actor` (from the wire session) automatically, then flushes to the sink when the invocation ends.
-
-An event only persists when the function opts in with **`audit: true`** — otherwise `auditLog` is a no-op that warns.
-
-## Wiring (services.ts)
-
-```typescript
-import { NoopAuditService, createInvocationAudit } from '@pikku/core/services'
-
-export const createSingletonServices = pikkuServices(async (config, existing) => {
-  // Prod platforms may inject a queue-backed sink as existing.audit.
-  const audit = existing?.audit ?? new NoopAuditService()
-  return { ...existing, config, /* ... */ audit }
-})
-
-// auditLog is created per invocation from the sink. Returned unconditionally so
-// a write from a function that forgot `audit: true` warns instead of vanishing.
-export const createWireServices = pikkuWireServices(async (services, wire) => {
-  if (!services.audit) return {}
-  return { auditLog: createInvocationAudit(services.audit, wire) }
-})
-```
-
-`audit` and `auditLog` are already declared on `CoreSingletonServices` / `CoreServices`, so no type change is needed to inject them.
-
-## Recording events — explicit domain events (default)
-
-Mark the function `audit: true` and call `auditLog?.write(...)`. Domain history goes in `metadata`; the actor is derived from the session, so do NOT pass it manually.
-
-```typescript
-export const cancelInvoice = pikkuFunc({
-  audit: true,                       // REQUIRED — else write() is a no-op
-  input: CancelInvoiceInput,
-  output: CancelInvoiceOutput,
-  func: async ({ kysely, auditLog }, { invoiceId }, { session }) => {
-    const inv = await kysely.selectFrom('invoice')/* ... */.executeTakeFirstOrThrow()
-    await kysely.updateTable('invoice').set({ status: 'cancelled' })/* ... */.execute()
-
-    await auditLog?.write({
-      type: 'invoice.update',
-      source: 'explicit',
-      metadata: {
-        entity: 'invoice',
-        entityId: invoiceId,
-        action: 'update',
-        field: 'status',
-        before: inv.status,
-        after: 'cancelled',
-      },
-    })
-    return { ok: true }
-  },
-})
-```
-
-For a **system/cron** function there is no session, so `actor` is simply absent (nulls out `actor_user_id`). Use `pikkuVoidFunc({ audit: true, func: async ({ auditLog }) => { ... } })` — the void/config form accepts `audit`.
-
-Helper functions (in `lib/`) that record audit take `auditLog?: AuditLog` in their services arg and are passed it from a `audit: true` caller — never import a service.
-
-Note: events buffer and flush on invocation close. For a write inside a DB transaction, call `auditLog.write()` **after** the transaction commits — the sink is not part of your `trx`, so only record committed state.
-
-## Recording events — automatic query capture (optional)
-
-To audit every DB mutation without explicit calls, wrap kysely so each query emits an event. Note this captures table/column changes only — it cannot see semantic events that do no DB write (e.g. "email sent"), so combine with explicit writes when you need those.
-
-```typescript
-import { createAuditedKysely } from '@pikku/kysely'
-export const createWireServices = pikkuWireServices(async (services, wire) => {
-  if (!services.audit) return {}
-  const auditLog = createInvocationAudit(services.audit, wire)
-  return { auditLog, kysely: createAuditedKysely(services.kysely, { audit: auditLog }) }
-})
-```
-
-## Sinks
-
-- **`NoopAuditService`** (`@pikku/core/services`) — default; discards events. Fine when audit isn't needed.
-- **`KyselyAuditService`** (`@pikku/kysely`) — durable: persists events to an `audit` table via kysely. Use as the local/dev sink so events are queryable without a platform queue: `new KyselyAuditService(kysely)`.
-- **Platform-injected sink** — a deploy platform may inject its own queue-backed `audit` (hence the `existing?.audit ??` fallback above). Its rows land in the same `audit` table shape.
-
-### The `audit` table (add this migration if you persist audit)
-
-```sql
-CREATE TABLE IF NOT EXISTS audit (
-  audit_id       TEXT NOT NULL PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
-  occurred_at    TEXT NOT NULL DEFAULT (datetime('now')),
-  type           TEXT NOT NULL,
-  source         TEXT NOT NULL DEFAULT 'auto',
-  outcome        TEXT,
-  function_id    TEXT,
-  wire_type      TEXT,
-  trace_id       TEXT,
-  transaction_id TEXT,
-  query_id       TEXT,
-  actor_user_id  TEXT,
-  actor_org_id   TEXT,
-  tables         TEXT,  -- JSON: table names touched (auto capture)
-  changed_cols   TEXT,  -- JSON: changed column names (auto capture)
-  event          TEXT,  -- custom event label
-  old            TEXT,  -- JSON: previous values
-  data           TEXT   -- JSON: metadata / new values / event payload
-);
-```
-
-`auditLog.write({ metadata })` lands in the `data` column. Read history back by filtering it (SQLite `json_extract`, Postgres `->>`):
-
-```typescript
-const rows = await kysely
-  .selectFrom('audit')
-  .leftJoin('user', 'user.id', 'audit.actorUserId')
-  .where(sql<boolean>`json_extract(audit.data, '$.entity') = 'invoice'`)
-  .where(sql<boolean>`json_extract(audit.data, '$.entityId') = ${invoiceId}`)
-  .orderBy('audit.occurredAt', 'desc')
-  .select([
-    'audit.auditId',
-    sql<string>`json_extract(audit.data, '$.action')`.as('action'),
-    'audit.occurredAt as at',
-    'user.name as userName',
-  ])
-  .execute()
-```
-
-## AuditEvent shape
-
-```typescript
-type AuditEvent = {
-  type: string                          // e.g. 'invoice.update'
-  source: 'auto' | 'explicit'
-  occurredAt: string                    // auto-filled by auditLog
-  outcome?: string
-  functionId?; wireType?; wireId?; traceId?; transactionId?; queryId?  // auto
-  actor?: { userId?; orgId? }           // auto from wire session
-  input?: unknown
-  metadata?: Record<string, unknown>    // your domain payload
-}
-```
-
-`auditLog.write()` takes `Omit<AuditEvent, 'occurredAt'>` — you only supply `type`, `source`, and `metadata` (and `actor` if overriding the session default).
-
-## Do / Don't
-
-- DO mark recording functions `audit: true`, inject `auditLog`, and call `auditLog.write({ type, source: 'explicit', metadata })`.
-- DO let the actor come from the session — don't thread `userId` into metadata for the actor.
-- DON'T create a custom `audit_log`/history table or `insertInto('audit_log')` by hand.
-- DON'T annotate the function's I/O from audit; audit is a side channel, not part of `input`/`output`.
-- DON'T write audit inside a DB transaction expecting rollback — record after commit.

package/skills/pikku-aws/SKILL.md

@@ -1,111 +0,0 @@
----
-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<T = string>(SecretId: string): Promise<T>` — Get a secret value; a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string)
-- `getSecrets<T>(SecretIds: (keyof T & string)[]): Promise<Partial<T>>` — Batch fetch; missing keys are omitted rather than thrown
-- `hasSecret(SecretId: string): Promise<boolean>` — Check if secret exists
-- `setSecret` / `deleteSecret` — **not implemented** for `AWSSecrets`; it throws. Manage AWS secrets out of band.
-
-## 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

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