@pikku/cli 0.12.91 → 0.12.92

package/skills/pikku-jose/SKILL.md

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

@@ -1,219 +0,0 @@
----
-name: pikku-kysely
-description: >-
-  Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
-  function body, or when setting up SQL database services with Kysely. Covers the query builder
-  API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores,
-  workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
-  non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
-  conditional query), the injected `kysely` service is used in a function body, or code uses
-  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
-  about SQL setup 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.
-
-## Writing Queries — the Kysely query builder
-
-In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Pikku wires the **CamelCasePlugin**, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a `` sql`` `` literal**. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).
-
-```typescript
-import { sql } from 'kysely'
-// Relation helpers are ENGINE-SPECIFIC — import the matching path:
-import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/sqlite'   // SQLite / libSQL
-// import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres' // Postgres
-```
-
-```typescript
-// SELECT + where/orderBy/limit/offset. Terminals: .execute() | .executeTakeFirst()
-// | .executeTakeFirstOrThrow(() => new NotFoundError()) — pass an error factory.
-const rows = await kysely.selectFrom('item')
-  .select(['id', 'name', 'quantity'])
-  .where('warehouseId', '=', warehouseId)
-  .orderBy('name').limit(50).execute()
-
-// JOINS + aliased selects (qualify columns once a join exists)
-await kysely.selectFrom('stock')
-  .innerJoin('item', 'item.id', 'stock.itemId')
-  .leftJoin('bin as b', 'b.id', 'stock.binId')
-  .select(['stock.id', 'item.name as itemName', 'b.code as binCode'])
-  .execute()
-
-// AGGREGATES via the fn helper + groupBy/having. eb.fn.count returns string|number —
-// cast if you need a JS number (SQLite: CAST(... AS INTEGER)).
-await kysely.selectFrom('stock')
-  .select((eb) => ['itemId', eb.fn.sum<number>('quantity').as('onHand')])
-  .groupBy('itemId')
-  .having((eb) => eb.fn.sum('quantity'), '<', 10)   // low-stock
-  .execute()
-
-// INSERT + RETURNING (one round-trip; works on SQLite & Postgres)
-const created = await kysely.insertInto('item')
-  .values({ name: input.name, warehouseId })
-  .returning(['id', 'name']).executeTakeFirstOrThrow()
-
-// UPDATE + RETURNING, DELETE
-await kysely.updateTable('item').set({ quantity: input.quantity })
-  .where('id', '=', input.id).returning(['id', 'quantity']).executeTakeFirstOrThrow()
-await kysely.deleteFrom('item').where('id', '=', input.id).execute()
-
-// EXPRESSION BUILDER for and/or; $if for conditional building; sql for raw fragments
-await kysely.selectFrom('item')
-  .selectAll()
-  .where((eb) => eb.or([eb('quantity', '=', 0), eb('discontinued', '=', true)]))
-  .$if(!!input.search, (qb) => qb.where('name', 'like', `%${input.search}%`))
-  .select(sql<number>`quantity * unit_cost`.as('value'))   // snake_case ok inside sql``
-  .execute()
-
-// NESTED DATA (no relations) — jsonObjectFrom (one) / jsonArrayFrom (many)
-await kysely.selectFrom('warehouse')
-  .select((eb) => ['warehouse.id', 'warehouse.name',
-    jsonArrayFrom(eb.selectFrom('bin').select(['bin.id', 'bin.code'])
-      .whereRef('bin.warehouseId', '=', 'warehouse.id')).as('bins')])
-  .execute()
-
-// TRANSACTION — multi-write atomicity. Use trx (not kysely) inside.
-await kysely.transaction().execute(async (trx) => {
-  await trx.updateTable('stock').set({ quantity: 0 }).where('itemId', '=', id).execute()
-  await trx.insertInto('stockMove').values({ itemId: id, delta: -qty }).execute()
-})
-```
-
-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.setSecret('api-key', { key: 'sk-...' })
-const value = await secrets.getSecret<{ 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()
-```

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

@@ -1,183 +0,0 @@
----
-name: pikku-machine-auth
-description: >-
-  Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine
-  (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions
-  into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key
-  plugin, machine identities, and `betterAuthSession` with the api-key branch. TRIGGER when: user
-  asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client
-  credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
-  NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
-  app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
----
-
-# Pikku Machine Auth
-
-Unified authentication for humans **and** machines against a Pikku + better-auth
-server. Two paths, two headers, one resolver:
-
-| Caller | Credential | Header | Obtained by |
-|---|---|---|---|
-| **Human** (CLI, dev) | better-auth session token | `Authorization: Bearer <token>` | `pikku login` (device flow) → `~/.pikku/session.json` |
-| **Machine** (agent, sandbox, worker) | scoped API key | `x-api-key: <key>` | `createApiKey` (server-side, at provision/spawn) |
-
-Both resolve to a Pikku `UserSession` through one middleware:
-`betterAuthSession({ mapSession, apiKey: { mapKey } })`.
-
-> The literal OAuth `client_credentials` grant is **not** implemented in
-> better-auth's oidc-provider. The API Key plugin gives the same capability (a
-> baked secret a service presents for scoped access), not the wire protocol.
-
-## Agent Operating Procedure
-
-1. Discover before editing — inspect the app's `betterAuth({ plugins: [...] })`
-   config and existing middleware wiring before adding anything.
-2. Server changes go in the auth factory + a middleware wiring file; never put
-   auth checks in a function body (use `permissions`).
-3. The API Key plugin contributes an `apikey` table — add the matching SQL
-   migration and regenerate DB types before relying on it.
-4. Validate with the narrowest command, then `pikku all`.
-
-## Human path — `pikku login`
-
-```bash
-pikku login --url https://app.example.com   # device-authorization flow
-pikku whoami                                  # show current session + expiry
-pikku logout                                  # remove stored session
-```
-
-`pikku login` runs the RFC 8628 device flow: it requests a code, opens the
-browser to the verification URL, polls until you approve, then stores the
-session token (keyed by base URL) at `~/.pikku/session.json` with its expiry.
-
-**Server requirement** — enable the `deviceAuthorization` and `bearer` plugins:
-
-```typescript
-import { deviceAuthorization, bearer } from 'better-auth/plugins'
-
-betterAuth({
-  // ...
-  plugins: [
-    deviceAuthorization({ expiresIn: '5min', interval: '5s', schema: {} }),
-    bearer(), // lets `Authorization: Bearer <session-token>` resolve a session
-  ],
-})
-```
-
-The browser approval is two steps the user's browser does automatically:
-`GET /auth/device?user_code=XXXX` (claims the code while signed in) then
-`POST /auth/device/approve`. The CLI only requests the code and polls
-`POST /auth/device/token`.
-
-## Machine path — API keys
-
-Install the plugin (separate official package) and enable it:
-
-```bash
-yarn add @better-auth/api-key   # peer: better-auth ^1.6.19
-```
-
-```typescript
-import { apiKey } from '@better-auth/api-key'
-
-betterAuth({
-  plugins: [
-    apiKey({
-      enableMetadata: true,          // REQUIRED to store scope on the key
-      enableSessionForAPIKeys: true, // lets a key resolve via getSession too
-    }),
-  ],
-})
-```
-
-### Identity model
-
-A **machine is an API key, not a throwaway user.** Keys are owned by a small set
-of stable **service-user** identities you provision once (e.g. `orchestrator`,
-`machine-agent`, `builder`, `sandbox-runtime`). Per-machine scope rides on the
-key's `metadata`/`permissions`. A key requires a real owning user row — minting
-one for a non-existent `userId` is created but will not resolve.
-
-### Mint a scoped key (server-side, at spawn/provision)
-
-```typescript
-// `auth` is the better-auth instance (injected service)
-const { key } = await auth.api.createApiKey({
-  body: {
-    userId: sandboxRuntimeUserId,        // a stable service user
-    name: `sandbox:${sandboxId}`,
-    expiresIn: 60 * 60,                   // seconds
-    metadata: { sandboxId },             // keep only STABLE ids here
-    permissions: { sandbox: ['read', 'write'] },
-  },
-})
-// inject `key` into the machine's env; it sends it as `x-api-key`.
-```
-
-Rotate by minting a new key and expiring/deleting the old (`deleteApiKey`);
-multiple active keys per identity allow zero-downtime rotation.
-
-### Resolve scope — `verifyApiKey`, not `getSession`
-
-`getSession(x-api-key)` returns only a bare mock session **without** the
-metadata. Scope must come from `verifyApiKey`, which returns
-`{ valid, key: { userId, metadata, permissions } }`. The
-`betterAuthSession` api-key branch does this for you:
-
-```typescript
-import { betterAuthSession } from '@pikku/better-auth'
-import { addHTTPMiddleware } from '@pikku/core/http'
-
-addHTTPMiddleware([
-  betterAuthSession({
-    // human path: getSession result -> app session
-    mapSession: ({ user }) => ({ userId: user.id }),
-    // machine path: verified key -> app session. `services` lets you resolve
-    // CURRENT scope (e.g. look up the owning row) instead of trusting only the
-    // baked metadata.
-    apiKey: {
-      header: 'x-api-key', // default
-      mapKey: async (key, services) => {
-        const sandboxId = key.metadata?.sandboxId
-        if (!sandboxId) return null // reject
-        const row = await services.kysely
-          .selectFrom('sandboxInstance')
-          .innerJoin('sandbox', 'sandbox.id', 'sandboxInstance.sandboxId')
-          .select(['sandbox.orgId', 'sandbox.projectId'])
-          .where('sandboxInstance.sandboxId', '=', sandboxId)
-          .where('sandboxInstance.stoppedAt', 'is', null)
-          .executeTakeFirst()
-        if (!row) return null
-        return { userId: sandboxId, orgId: row.orgId, role: 'sandbox' }
-      },
-    },
-  }),
-])
-```
-
-When the api-key header is present it is authoritative — the middleware never
-falls through to `getSession` (a bare mock session would shadow the scoped one).
-When it is absent, the human `getSession` path runs as normal.
-
-### WebSocket channels authenticate on the upgrade handshake
-
-Generated channel CLI clients attach the credential as a connection header
-(`x-api-key` for `PIKKU_API_KEY`, else `Authorization: Bearer` from
-`~/.pikku/session.json`). The `@pikku/ws` server copies the upgrade-request
-headers into the channel's `http.request` and runs the inherited HTTP `*`
-middleware during `runUpgradeMiddleware`, so `betterAuthSession` resolves the
-session before the channel opens. For this to work the app must register
-`betterAuthSession` via `addHTTPMiddleware([...])` (the `*` group) — not only on
-specific routes — so it is inherited into the channel upgrade. Browser clients
-cannot set WebSocket headers, so header-auth only covers the Node CLI path; a
-browser channel needs a query-param/subprotocol vector instead.
-
-## Gotchas
-
-- `apiKey()` rejects `metadata` unless `enableMetadata: true`.
-- `deviceAuthorization()` requires a `schema` option (pass `schema: {}`).
-- Keep the two paths on **different headers** — `x-api-key` (machine) vs
-  `Authorization: Bearer` (human). One header for both reintroduces ambiguity.
-- The `apikey` table is plugin-contributed — add the SQL migration + regen types.
-- `~/.pikku/session.json` is written `0600` and stores the token + expiry; the
-  CLI uses the expiry to detect when a re-login is needed.