@pikku/cli 0.12.21 → 0.12.23

package/skills/pikku-i18n/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: pikku-i18n
+description: 'Wire i18n into a Pikku frontend (Vite SPA, Vite SSR, or Next.js app-router) with react-i18next + i18next. English by default, every user-facing string goes through a `t()` token, and additional languages are served under `/de` `/es` URL prefixes. TRIGGER when: scaffolding or editing a frontend and writing user-facing text, adding a second language, or asked to "make this translatable / use tokens / add i18n". DO NOT TRIGGER for backend functions, error messages thrown from functions, or log output.'
+installGroups: [core]
+---
+
+# Pikku i18n
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Every user-facing string in a frontend is a token. Never hardcode display text — write `t('some.token')` and put the English copy in `i18n/en.json`. This holds even when the app ships only English; the tokens are the seam a second language slots into later.
+2. One `i18n/<lang>.json` file per language per app, sitting next to the i18n config in a single `i18n/` folder. English (`en`) is the default and is the only locale registered until someone adds another.
+3. Pick the delivery pattern by framework (see below). The token files and config shape are identical across frameworks; only _how the active locale reaches the renderer_ differs.
+4. Validate with the app's own `tsc` then its `build`. For Next.js, a clean `dev` is not enough — run `build`, because the RSC page-data collection step is where i18n wiring mistakes surface.
+
+## The rules that don't change
+
+- Library: `react-i18next` + `i18next`. Nothing else.
+- Locale files live next to the config in an `i18n/` folder — `src/i18n/<lang>.json` (Vite) or `app/i18n/<lang>.json` (Next.js) — imported statically. **Do not** put them under `public/` — Vite cannot `import` from `public/`, and a runtime fetch is unnecessary: UI-string files are a few KB, so static-import every locale and move on. Do not reach for `i18next-http-backend`, lazy `import()`, or per-locale code-splitting.
+- Default locale is `en`. Adding a language = drop `i18n/<lang>.json`, import + register it in the config, done. Its content is then served under the `/<lang>` URL prefix; the default locale needs no prefix.
+- Keys are namespaced by area (`auth.login.title`, `board.createCta`). Interpolate with `{{name}}` and pass `t('key', { name })`.
+
+## Type safety — and why deploys block on i18n
+
+Tokens are **typed**, not stringly-typed. Each config augments i18next's
+`CustomTypeOptions` with `resources: { translation: typeof en }` (the block is in
+every config shape below). i18next flattens `typeof en` into a union of dot-path
+keys, so:
+
+- `t('auth.login.titel')` (typo) or `t('auth.removed')` (deleted key) is a **TypeScript error**, not a silent runtime `auth.removed` string.
+- An added locale registered as `de satisfies typeof en` fails to compile if `de.json` is missing keys or has drifted from `en.json`.
+
+This is enforced at deploy: the build pipeline runs each frontend's `tsc`
+(`yarn tsc` / `tsc --noEmit`) **before** building it, and a type error aborts the
+deploy. `vite build` does not type-check on its own, so this gate is the only
+thing standing between a broken/missing token and production. Keep a `"tsc":
+"tsc --noEmit"` script in every frontend's `package.json` so the gate uses it.
+
+The type gate catches _invalid_ tokens but not _inlined_ strings — a hardcoded
+`<h1>Welcome</h1>` compiles fine. Catching those is best-effort (the builder
+agent is told never to inline) plus the debug mode below.
+
+## i18n debug mode (find inlined strings)
+
+Each config registers an i18next `postProcessor` named `i18nDebug` that, when
+enabled, masks every _translated_ string to block glyphs (`█`). The trick: with
+it on, anything still readable on screen is text that **never went through a
+token** — i.e. a hardcoded/inlined string. It's a visual leak detector for
+missing i18n, not a runtime feature, so it ships **off by default**.
+
+```ts
+export function isI18nDebug(): boolean {
+  if (typeof process !== 'undefined' && process.env?.I18N_DEBUG === '1')
+    return true
+  if (typeof window === 'undefined') return false
+  const params = new URLSearchParams(window.location.search)
+  if (params.has('i18n-debug')) return params.get('i18n-debug') !== '0'
+  return window.localStorage?.getItem('i18n-debug') === '1'
+}
+
+const i18nDebugPostProcessor = {
+  type: 'postProcessor' as const,
+  name: 'i18nDebug',
+  process: (value: string) =>
+    isI18nDebug() ? value.replace(/\S/g, '█') : value,
+}
+// register on the instance: `.use(i18nDebugPostProcessor)` and add
+// `postProcess: ['i18nDebug']` to `.init({ ... })`.
+```
+
+- **Client (Vite SPA/SSR):** toggle with `?i18n-debug` in the URL or `localStorage['i18n-debug'] = '1'`.
+- **Server (Next.js server components):** there is no per-request URL toggle — enable for a build with `I18N_DEBUG=1` (the helper only checks the env var server-side).
+
+All the bundled templates already wire this; mirror it when hand-wiring i18n in a new app. (A future e2e check can flip the flag and assert no unmasked text renders.)
+
+## Config shape (client / SPA)
+
+`src/i18n/config.ts`:
+
+```ts
+import i18n from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import en from './en.json'
+
+// Typed tokens. i18next flattens this resource type into dot-path keys, so
+// `t('auth.login.title')` is checked and a typo/removed key is a compile error.
+declare module 'i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'translation'
+    resources: {
+      translation: typeof en
+    }
+  }
+}
+
+export const supportedLocales = ['en'] as const
+export type Locale = (typeof supportedLocales)[number]
+export const defaultLocale: Locale = 'en'
+
+export function detectLocale(pathname: string): Locale {
+  const segment = pathname.split('/')[1]
+  if (supportedLocales.includes(segment as Locale)) return segment as Locale
+  if (typeof navigator !== 'undefined') {
+    const lang = navigator.language?.split('-')[0]
+    if (supportedLocales.includes(lang as Locale)) return lang as Locale
+  }
+  return defaultLocale
+}
+
+i18n.use(initReactI18next).init({
+  resources: { en: { translation: en } },
+  lng:
+    typeof window !== 'undefined'
+      ? detectLocale(window.location.pathname)
+      : defaultLocale,
+  fallbackLng: defaultLocale,
+  interpolation: { escapeValue: false },
+})
+
+export default i18n
+```
+
+Import it once for its side effect at the app entry (`import './i18n/config'` in `main.tsx`), then use the hook in components:
+
+```tsx
+import { useTranslation } from 'react-i18next'
+function Page() {
+  const { t } = useTranslation()
+  return <h1>{t('landing.title')}</h1>
+}
+```
+
+Non-component helpers (formatters, status maps) can't use the hook — import the instance and call it directly:
+
+```ts
+import i18n from '../i18n/config'
+export const prettyStatus = (s: string) => i18n.t(`status.${s}`)
+```
+
+## Per-framework delivery
+
+### Vite SPA
+
+The config above is the whole story. `import './i18n/config'` in `main.tsx`; `useTranslation` everywhere.
+
+### Vite SSR (`@cloudflare/vite-plugin` / Worker)
+
+Same config, but `import './i18n/config'` in **both** the worker entry (`worker.tsx`) and the client entry (`client.tsx`) so the global i18next instance is initialised on each side before `<App/>` renders. The locale JSON is bundled into the Worker (a static import, not a fetch — the Worker never has to fetch its own assets). The shared `<App/>` uses `useTranslation` normally.
+
+### Next.js app-router — server components
+
+Server components **cannot** call `useTranslation`, and they **must not** import `initReactI18next`: it calls React's `createContext`, which throws during RSC page-data collection (`(0 , Y.createContext) is not a function` at build). Use a plain i18next instance and a fixed translator instead.
+
+`app/i18n/config.ts`:
+
+```ts
+import { createInstance } from 'i18next'
+import en from './en.json'
+
+// Typed tokens — same augmentation as the SPA config; `getT()('key')` is
+// checked against en.json's flattened dot-path keys.
+declare module 'i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'translation'
+    resources: {
+      translation: typeof en
+    }
+  }
+}
+
+export const supportedLocales = ['en'] as const
+export type Locale = (typeof supportedLocales)[number]
+export const defaultLocale: Locale = 'en'
+
+const i18n = createInstance()
+i18n.init({
+  resources: { en: { translation: en } },
+  lng: defaultLocale,
+  fallbackLng: defaultLocale,
+  interpolation: { escapeValue: false },
+})
+
+export function getT(locale: Locale = defaultLocale) {
+  return i18n.getFixedT(locale)
+}
+
+export default i18n
+```
+
+```tsx
+import { getT } from './i18n/config'
+export default function Page() {
+  const t = getT()
+  return <h1>{t('page.title')}</h1>
+}
+```
+
+This works in both `output: 'export'` (static) and dynamic SSR — the static export pre-renders translated HTML at build time.
+
+### Next.js app-router — client components
+
+A `'use client'` component that needs the hook uses the standard `initReactI18next` instance behind an `I18nextProvider`, kept separate from the server `app/i18n/config.ts`. Most starter pages are server components and never need this.
+
+## Adding a second language
+
+1. `i18n/de.json` mirroring `en.json`'s keys.
+2. In the config: `import de from './de.json'`, add `'de'` to `supportedLocales`, and register it as `de: { translation: de satisfies typeof en }`. The `satisfies typeof en` makes an incomplete or drifted `de.json` a **compile error** — which is what blocks a deploy on missing i18n (see below).
+3. `detectLocale` already resolves `/de/...`; wire the locale segment into routing so `/de` renders the German tree (the default locale stays prefix-free).
+
+## What NOT to do
+
+- Don't hardcode display strings "just for now" — that defeats the point; the token is the work.
+- Don't put locale files under `public/` or fetch them at runtime.
+- Don't wire `initReactI18next` into a Next.js server component or any module a server component imports.
+- Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/pikku-info/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: pikku-info
+description: 'Discover what exists in a Pikku project — functions, tags, middleware, permissions, HTTP routes, channels, schedulers, queues, and more. Use when you need to understand the project structure, find existing functions, or check what middleware and permissions are defined.
+TRIGGER when: user asks "what functions exist?", "show me the project structure", "list routes/middleware/permissions", or needs to understand an existing Pikku codebase.
+DO NOT TRIGGER when: user is writing new code (use the specific wiring skill) or asking about Pikku concepts (use pikku-concepts).'
+installGroups: [core]
+allowed-tools: Bash(yarn pikku info *)
+argument-hint: '[functions|tags|middleware|permissions] [--verbose] [--limit N]'
+---
+
+# Pikku Project Discovery
+
+## 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.
+
+Use the `pikku info` CLI commands to inspect this Pikku project. Run the commands below and present the results to the user in a clear summary.
+
+## Available Commands
+
+Always use `--silent` to suppress the banner and inspector logs.
+
+### Functions
+
+List all registered pikku functions:
+
+```bash
+yarn pikku info functions --silent
+```
+
+For full details including transport type (http/channel/scheduler/queue/workflow/mcp/cli/trigger), middleware, permissions, and source file:
+
+```bash
+yarn pikku info functions --verbose --silent
+```
+
+### Tags
+
+List all tags with counts of associated functions, middleware, and permissions:
+
+```bash
+yarn pikku info tags --silent
+```
+
+For full names instead of counts:
+
+```bash
+yarn pikku info tags --verbose --silent
+```
+
+### Middleware
+
+List all middleware definitions:
+
+```bash
+yarn pikku info middleware --silent
+```
+
+For full details including source file, required services, and description:
+
+```bash
+yarn pikku info middleware --verbose --silent
+```
+
+### Permissions
+
+List all permission definitions:
+
+```bash
+yarn pikku info permissions --silent
+```
+
+For full details including source file, required services, and description:
+
+```bash
+yarn pikku info permissions --verbose --silent
+```
+
+## Instructions
+
+1. If the user specifies a subcommand (e.g., `/pikku-info functions`), run only that command.
+2. If no subcommand is specified, run all four commands to give a complete project overview.
+3. Always use `--silent` to suppress the Pikku banner and inspector logs.
+4. Use `--verbose` when the user asks for details, file paths, or "more info".
+5. Use `--limit N` to control output size (default is 50 rows).
+6. After running the commands, summarize the findings concisely:
+   - Total count of functions, tags, middleware, and permissions
+   - Notable patterns (e.g., which transport types are in use, which tags group the most functions)
+   - Any functions without tags or transport types (potential issues)

package/skills/pikku-jose/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pikku-jose
+description: 'Use when setting up JWT authentication with the jose library in a Pikku app. Covers JoseJWTService constructor, secret rotation, token encoding/decoding/verification.
+TRIGGER when: code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or @pikku/jose.
+DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or general service setup (use pikku-services).'
+---
+
+# Pikku Jose (JWT Service)
+
+## 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/jose` provides JWT signing, verification, and decoding using the [jose](https://github.com/panva/jose) library. Implements the `JWTService` interface from `@pikku/core`.
+
+## Installation
+
+```bash
+yarn add @pikku/jose
+```
+
+## API Reference
+
+### `JoseJWTService`
+
+```typescript
+import { JoseJWTService } from '@pikku/jose'
+
+const jwt = new JoseJWTService(
+  getSecrets: () => Promise<Array<{ id: string; value: string }>>,
+  logger?: Logger
+)
+
+await jwt.init()
+```
+
+**Constructor Parameters:**
+
+- `getSecrets` — Async function returning an array of `{ id, value }` key pairs. First key is used for signing; all keys are tried for verification (supports rotation).
+- `logger` — Optional logger instance.
+
+**Methods:**
+
+- `init(): Promise<void>` — Fetch and cache secrets. Call at startup.
+- `encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string>` — Create a signed JWT.
+- `decode<T>(token: string): Promise<T>` — Decode a JWT payload without verification.
+- `verify(token: string): Promise<void>` — Verify a JWT signature and expiry.
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { JoseJWTService } from '@pikku/jose'
+
+const jwt = new JoseJWTService(
+  async () => [{ id: 'key-1', value: process.env.JWT_SECRET! }],
+  logger
+)
+await jwt.init()
+```
+
+### Secret Rotation
+
+Supply multiple keys. The first is used for signing; all are tried for verification:
+
+```typescript
+const jwt = new JoseJWTService(async () => [
+  { id: 'key-2', value: NEW_SECRET }, // signs with this
+  { id: 'key-1', value: OLD_SECRET }, // still verifies tokens signed with this
+])
+```
+
+### With Pikku Services
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const jwt = new JoseJWTService(
+    async () => [{ id: 'my-key', value: config.jwtSecret }],
+    logger
+  )
+  await jwt.init()
+  return { config, logger, jwt }
+})
+```
+
+### Encoding & Verifying Tokens
+
+```typescript
+const token = await jwt.encode('1h', { userId: 'abc', role: 'admin' })
+
+await jwt.verify(token) // throws if invalid/expired
+
+const payload = await jwt.decode<{ userId: string; role: string }>(token)
+```

package/skills/pikku-kysely/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: pikku-kysely
+description: 'Use when setting up SQL database services with Kysely in a Pikku app. Covers @pikku/kysely (base), @pikku/kysely-postgres, @pikku/kysely-mysql, @pikku/kysely-sqlite — channel stores, workflow services, secret services, AI storage, agent runs, and deployment services.
+TRIGGER when: code uses Kysely, PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or user asks about SQL database setup, Postgres/MySQL/SQLite with Pikku.
+DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or Redis (use pikku-redis).'
+installGroups: [core]
+---
+
+# Pikku Kysely (SQL Database 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 provides SQL database services through four packages:
+
+- `@pikku/kysely` — Base service implementations (database-agnostic)
+- `@pikku/kysely-postgres` — PostgreSQL-specific implementations + `PikkuKysely` connection wrapper
+- `@pikku/kysely-mysql` — MySQL-specific implementations
+- `@pikku/kysely-sqlite` — SQLite-specific implementations + `createSQLiteKysely` factory
+
+All implement standard Pikku interfaces from `@pikku/core`.
+
+## Installation
+
+```bash
+# Pick your database
+yarn add @pikku/kysely @pikku/kysely-postgres   # PostgreSQL
+yarn add @pikku/kysely @pikku/kysely-mysql      # MySQL
+yarn add @pikku/kysely @pikku/kysely-sqlite     # SQLite
+```
+
+## API Reference
+
+### PostgreSQL Connection — `PikkuKysely`
+
+```typescript
+import { PikkuKysely } from '@pikku/kysely-postgres'
+
+const db = new PikkuKysely<DB>(
+  logger: Logger,
+  connectionOrConfig: postgres.Sql | postgres.Options | string,
+  defaultSchemaName?: string
+)
+
+await db.init()
+db.kysely  // Kysely<DB> instance for queries
+await db.close()
+```
+
+### SQLite Factory — `createSQLiteKysely`
+
+```typescript
+import { createSQLiteKysely } from '@pikku/kysely-sqlite'
+
+const kysely = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
+```
+
+### Available Services
+
+Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLite`, or base `Kysely`):
+
+| Service               | Interface                             | Purpose                                        |
+| --------------------- | ------------------------------------- | ---------------------------------------------- |
+| `*ChannelStore`       | `ChannelStore`                        | WebSocket channel state persistence            |
+| `*EventHubStore`      | `EventHubStore`                       | Event hub state persistence                    |
+| `*WorkflowService`    | `PikkuWorkflowService`                | Workflow definition storage                    |
+| `*WorkflowRunService` | `WorkflowRunService`                  | Workflow execution tracking                    |
+| `*DeploymentService`  | `DeploymentService`                   | Deployment state management                    |
+| `*AIStorageService`   | `AIStorageService, AIRunStateService` | AI conversation/run storage                    |
+| `*AgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
+| `*SecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
+
+All services take a `Kysely<KyselyPikkuDB>` instance in their constructor and have an `init()` method that creates tables if needed.
+
+### Secret Service
+
+```typescript
+import { PgKyselySecretService } from '@pikku/kysely-postgres'
+
+const secrets = new PgKyselySecretService(db.kysely, {
+  kekSecret: 'your-key-encryption-key',
+  salt: 'your-salt',
+})
+await secrets.init()
+
+await secrets.setSecretJSON('api-key', { key: 'sk-...' })
+const value = await secrets.getSecretJSON<{ key: string }>('api-key')
+await secrets.rotateKEK() // Re-encrypt all secrets with new KEK
+```
+
+## Usage Patterns
+
+### PostgreSQL Setup
+
+```typescript
+import {
+  PikkuKysely,
+  PgKyselyChannelStore,
+  PgKyselyWorkflowService,
+} from '@pikku/kysely-postgres'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const db = new PikkuKysely(logger, config.databaseUrl)
+  await db.init()
+
+  const channelStore = new PgKyselyChannelStore(db.kysely)
+  await channelStore.init()
+
+  const workflowService = new PgKyselyWorkflowService(db.kysely)
+  await workflowService.init()
+
+  return { config, logger, database: db, channelStore, workflowService }
+})
+```
+
+### SQLite Setup
+
+```typescript
+import {
+  createSQLiteKysely,
+  SQLiteKyselyChannelStore,
+} from '@pikku/kysely-sqlite'
+import Database from 'better-sqlite3'
+
+const kysely = createSQLiteKysely(new Database('app.db'))
+const channelStore = new SQLiteKyselyChannelStore(kysely)
+await channelStore.init()
+```
+
+### MySQL Setup
+
+```typescript
+import { MySQLKyselyWorkflowService } from '@pikku/kysely-mysql'
+
+const workflowService = new MySQLKyselyWorkflowService(kyselyInstance)
+await workflowService.init()
+```