@pikku/skills 0.12.4 → 0.12.8

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

@@ -128,18 +128,24 @@ In both cases a **route-scoped** registration (`addHTTPMiddleware('/some/path',
 
 ### Admin capabilities are scopes, not a role
 
-Pikku does **not** use better-auth's `admin()` plugin, and nothing in this
-package reads a `role` column. A role is not a permission: "who may impersonate"
-and "who may rebind a shared credential" are different capabilities one user can
-hold independently, which a single `role` string cannot express. Every gate the
-package owns therefore resolves the caller's scopes through the registered
-`ScopeService` and checks the `admin:*` tree:
+Scopes are the source of truth for what an admin may do; nothing in pikku reads
+a `role`. A role is not a permission: "who may impersonate" and "who may rebind a
+shared credential" are different capabilities one user can hold independently,
+which a single `role` string cannot express. Every gate the package owns
+resolves the caller's scopes through the registered `ScopeService` and checks the
+`admin:*` tree (`ADMIN_SCOPES` exports the ids so you never spell them as bare
+strings):
 
 | Gate                                                                 | Scope required           |
 | -------------------------------------------------------------------- | ------------------------ |
 | `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`      |
 | `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link` |
 | the console's user directory                                         | `admin:users:list`       |
+| create a user out of band                                            | `admin:users:create`     |
+| ban / unban                                                          | `admin:users:ban`        |
+| delete a user and their data                                         | `admin:users:remove`     |
+| revoke a user's sessions                                             | `admin:users:sessions`   |
+| set a user's password                                                | `admin:users:password`   |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -164,7 +170,14 @@ defineScope({
       },
       users: {
         description: 'The user directory',
-        scopes: { list: { description: 'List and search users' } },
+        scopes: {
+          list: { description: 'List and search users' },
+          create: { description: 'Create users out of band' },
+          ban: { description: 'Ban and unban users' },
+          remove: { description: 'Delete users and all their data' },
+          sessions: { description: "Revoke a user's sessions" },
+          password: { description: "Set a user's password" },
+        },
       },
     },
   },
@@ -178,9 +191,22 @@ a scope, so nothing is authorized, and the denial is logged at `warn` because
 that is a configuration bug rather than a permissions decision. Pass your own
 `canImpersonate` / `canLinkSingleton` to override the default entirely.
 
-Sibling concerns — banning a user, listing users from your own screens — are
-actions your app _invokes_, not things pikku gates. Put them on your own
-functions with `scopes: ['admin:users:ban']` and friends.
+### If you do wire better-auth's `admin()` plugin
+
+The last five capabilities in the table are implemented by better-auth's own
+`admin()` endpoints, which authorize against `user.role` — a column pikku
+otherwise ignores. Rather than making you maintain two grant systems,
+`syncProjectedAdminRole` keeps that column as a *projection* of the scope set:
+at the session boundary it writes `role = 'admin'` when the user holds any of
+`admin:users:{create,ban,remove,sessions,password}`, and the plugin's
+`defaultRole` otherwise. `projectedAdminRole(scopes, defaultRole)` computes the
+value if you need it yourself.
+
+The projection is deliberately not "any `admin:*` scope": `impersonate` and
+`users:list` are pikku's own gates, and rolling them in would hand ban and delete
+rights to someone granted only the ability to look. The plugin is auto-detected
+from the live instance, so an app without it never writes to a column that does
+not exist.
 
 ### 2. Production database adapter
 
@@ -281,6 +307,15 @@ Better Auth serves everything under `basePath` (default `/api/auth`). Call these
 
 The session cookie is `better-auth.session_token` (dev) / `__Secure-better-auth.session_token` (prod).
 
+### Dev quick login
+
+Set `PIKKU_DEV_QUICK_LOGIN=true` and `${basePath}/dev/quick-login` signs in a
+fixed dev admin (`admin@pikku.dev`), creating the user idempotently and granting
+it the bare `admin` scope. It is guarded twice — the env var *and* a localhost
+hostname check — because a one-request path to an admin session is exactly the
+thing that must not survive a deploy. An app that has not declared the `admin`
+scope still gets a session, with a warning, since a scopeless dev user is useful.
+
 ---
 
 ## Secret Management

package/skills/pikku-cli/SKILL.md

@@ -36,19 +36,23 @@ See `pikku-concepts` for the core mental model.
 
 ### `wireCLI(config)`
 
+All three factories come from `#pikku` (the generated types re-export
+`cli/pikku-cli-types.gen.js`). Importing them from `@pikku/core/cli` compiles but
+loses your project's service and middleware types.
+
 ```typescript
-import { wireCLI } from '@pikku/core/cli'
+import { wireCLI } from '#pikku'
 
 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,
-    }
-  },
+  description?: string,
+  summary?: string,
+  options?: CLIOptions,         // Global options — see below
   render?: PikkuCLIRender,      // Default renderer for all commands
+  middleware?: PikkuMiddleware[],
+  tags?: string[],              // Targets tag middleware
+  errors?: string[],
+  auth?: boolean,               // Only affects the websocket backend, not local runs
   commands: {
     [name: string]: PikkuCLICommand | {
       description: string,
@@ -65,24 +69,49 @@ import { pikkuCLICommand } from '#pikku'
 
 pikkuCLICommand({
   parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
-  func: PikkuFunc,              // Business logic function
+  func?: PikkuFunc,             // Business logic function — omit on a pure command group
+  title?: string,
   description?: string,
   render?: PikkuCLIRender,      // Custom output renderer
-  options?: {
-    [key: string]: {
-      description: string,
-      short?: string,
-      default?: any,
-      choices?: string[],       // Restrict to values
-    }
-  },
+  options?: CLIOptions,
+  subcommands?: { [name: string]: PikkuCLICommand },  // nests to any depth
+  middleware?: PikkuMiddleware[],
+  permissions?: PermissionGroup,
+  auth?: boolean,
+  isDefault?: boolean,          // Runs when the group is invoked with no subcommand
 })
 ```
 
+`parameters` is checked against the func's input at compile time — a name that is
+not a key of the input makes the type `never`, so a typo'd positional fails to
+build rather than arriving as `undefined`.
+
+### Options
+
+```typescript
+{
+  description: string,
+  short?: string,        // Single char alias (e.g. 'v')
+  default?: any,
+  choices?: any[],       // Restrict to these values
+  array?: boolean,       // Collect every value up to the next flag
+  required?: boolean,
+}
+```
+
+How the parser reads them, which is worth knowing before you name one:
+
+- **Flag names are camel-cased**, so `--api-url` and `--apiUrl` both fill `apiUrl`.
+- **`--no-x` negation only works when `x` has a boolean `default`.** Without one,
+  `--no-x` parses as an option literally named `noX` — which is why boolean flags
+  should always declare their default.
+- Short flags cluster (`-abc`), and only the last in a cluster may take a value.
+- An unknown `--flag` warns rather than throwing.
+
 ### `pikkuCLIRender(fn)`
 
 ```typescript
-import { pikkuCLIRender } from '@pikku/core/cli'
+import { pikkuCLIRender } from '#pikku'
 
 const renderer = pikkuCLIRender<OutputType>((services, data) => {
   // Format and print output to terminal
@@ -90,6 +119,15 @@ const renderer = pikkuCLIRender<OutputType>((services, data) => {
 })
 ```
 
+### Wire object (`wire.cli`)
+
+```typescript
+wire.cli.program   // program name
+wire.cli.command   // string[] — the resolved command path
+wire.cli.data      // all positionals and options, merged
+wire.cli.channel   // the channel when served remotely (see below)
+```
+
 ## Usage Patterns
 
 ### Basic Commands
@@ -193,6 +231,17 @@ wireCLI({
 
 The func's input is the positional `parameters` plus `options`, merged (e.g. `parameters: '<username> <email>'` + an `admin` option → func input `{ username, email, admin }`).
 
+A renderer's full signature is `(services, data, session?)`. It returns nothing —
+printing is its job.
+
+### Running the program over a websocket
+
+Codegen emits a `<program>-channel.gen.ts` beside your wiring: a `wireChannel`
+that serves the same commands remotely, so a local binary and a hosted session
+run identical code. `auth` on `wireCLI` guards **that channel only** — a locally
+executed CLI has no connection to authenticate, so it is not a way to require a
+session for local runs. Don't hand-write or edit the generated channel file.
+
 ## Complete Example
 
 For a full functions + renderers + nested-subcommand wiring walkthrough, see `references/complete-example.md`.

package/skills/pikku-cli/references/complete-example.md

@@ -32,6 +32,8 @@ export const deleteUser = pikkuFunc({
 })
 
 // wirings/cli.wiring.ts
+import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku'
+
 const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
   console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)
 })

package/skills/pikku-concepts/SKILL.md

@@ -28,7 +28,8 @@ Pikku is a TypeScript framework that separates business logic from transport mec
 For deep-dive on each topic, see the dedicated skills:
 
 - **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-ai-agent`, `pikku-workflow`
-- **Infrastructure**: `pikku-services`, `pikku-security`, `pikku-config`
+- **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
+- **Infrastructure**: `pikku-services`, `pikku-config`
 - **Project introspection**: `pikku-info`
 
 ## Core Mental Model
@@ -58,7 +59,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; middleware/auth/permissions → `pikku-security`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -95,22 +96,53 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
+  // Identity and documentation
   title?: string,           // Human-readable name
   description?: string,     // What the function does
-  version?: number,         // Contract version (see pikku-config for versioning)
+  version?: number,         // Contract version (see pikku-versioning)
+  override?: string,        // Logical name override, so several exports share a versioned base
   tags?: string[],          // For grouping and middleware targeting
+
+  // Contract
+  input?: ZodSchema,        // Input validation schema
+  output?: ZodSchema,       // Output validation schema
+  errors?: Array<typeof PikkuError>,  // Errors this function may throw
+
+  // Reachability
   expose?: boolean,         // Allow external RPC calls (see pikku-rpc)
   remote?: boolean,         // Allow remote RPC calls
   mcp?: boolean,            // Expose as MCP tool (see pikku-mcp)
+  readonly?: boolean,       // Declares the function performs no writes
+  deploy?: 'serverless' | 'server' | 'auto',
+
+  // Authorization — see pikku-permissions
   auth?: boolean,           // Override default auth requirement
-  input?: ZodSchema,        // Input validation schema
-  output?: ZodSchema,       // Output validation schema
-  permissions?: PermissionGroup,  // See pikku-security
-  middleware?: PikkuMiddleware[], // See pikku-security
+  scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
+  permissions?: PermissionGroup,  // OR-ed pool
+  permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
+  middleware?: PikkuMiddleware[], // See pikku-middleware
+
+  // Agent tooling — see pikku-ai-agent
+  approvalRequired?: boolean,
+  approvalDescription?: (services, data) => Promise<string>,
+
+  // Workflow step behavior — see pikku-workflow
+  workflowQueued?: boolean, // Dispatch via queue instead of inline
+  workflowRetries?: number,
+  workflowTimeout?: string, // e.g. '30s', '5m'
+
+  audit?: boolean | { durability?: 'best-effort' | 'transactional' },
+
   func: async (services, data, wire) => { ... },
 })
 ```
 
+`scopes` is the one option `pikkuSessionlessFunc` does not accept, and the
+omission is deliberate: scopes are AND-ed and fail closed, so an anonymous
+caller holds none and satisfies none — a sessionless function with scopes would
+reject every caller it exists to serve. Gate those with `permissions`, which
+receive the optional session and may pass anonymous.
+
 **Generics XOR `input`/`output` — never both.** A function's data and return
 types come from *one* source: either the `input`/`output` schemas (preferred —
 they double as runtime validation and OpenAPI) or type generics
@@ -145,7 +177,35 @@ Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI doc
 
 ## Server Bootstrap
 
-Every Pikku app follows the same bootstrap pattern regardless of runtime:
+There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+
+**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+
+`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely)
+  },
+  afterStart: async ({ logger }) => {
+    logger.info('accepting traffic')
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain()
+  },
+})
+```
+
+Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
+
+**2. Bootstrap it yourself (required for a specific runtime)**
+
+Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
 
 ```typescript
 import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
@@ -168,6 +228,10 @@ await server.init()
 await server.start()
 ```
 
+**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
+
+`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+
 ## Code Generation
 
 Run `npx pikku all` to generate:
@@ -175,7 +239,7 @@ Run `npx pikku all` to generate:
 - `pikku-types.gen.ts` — Typed function factories and wiring functions
 - `pikku-fetch.gen.ts` — Type-safe HTTP client
 - `pikku-websocket.gen.ts` — Type-safe WebSocket client
-- `pikku-bootstrap.gen.js` — Runtime initialization (auto-imports all wirings)
+- `pikku-bootstrap.gen.ts` — Runtime initialization (auto-imports all wirings)
 - `pikku-services.gen.ts` — Service factory types
 
 Config lives in `pikku.config.json`:
@@ -203,12 +267,13 @@ src/
 │   └── queue.wiring.ts
 ├── schemas.ts           # Zod/Valibot schemas
 ├── services.ts          # Service factories (see pikku-services)
+├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
 ├── middleware.ts         # Middleware definitions (see pikku-security)
 ├── permissions.ts       # Permission definitions (see pikku-security)
 └── .pikku/              # Generated (gitignored)
     ├── pikku-types.gen.ts
     ├── pikku-fetch.gen.ts
-    └── pikku-bootstrap.gen.js
+    └── pikku-bootstrap.gen.ts
 ```
 
 ## Environment Variables

package/skills/pikku-config/SKILL.md

@@ -4,9 +4,10 @@ description: >-
   Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app.
   Covers defineSecret, defineVariable, defineCredential, and typed config access. TRIGGER when:
   code uses defineSecret/defineVariable/defineCredential, 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).
+  config, OAuth2, SecretValue/.reveal(), SecretCoercionError, 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), middleware (use pikku-middleware), or
+  auth strategies and sessions (use pikku-security).
 installGroups: [core]
 ---
 
@@ -64,10 +65,17 @@ or any wire** — it is removed from their services type and throws at runtime i
 reached through a cast. Read it where you wire the app and hand the value to a
 service:
 
+`getSecret` returns a `SecretValue<T>`, not the bare value. It is nominal — not
+assignable to `string`, so every concretely-typed sink rejects it — it serializes
+to `[secret]` in logs and audits, and coercing it to a string (a template
+literal, a concatenation) throws `SecretCoercionError`, because that is always a
+leak. `.reveal()` is the one way out, which makes every disclosure deliberate and
+greppable. Call it at the point the value reaches the thing that needs it:
+
 ```typescript
 // services.ts — allowed
 const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
-  stripe: new StripeService(await secrets.getSecret('STRIPE_CONFIG')),
+  stripe: new StripeService((await secrets.getSecret('STRIPE_CONFIG')).reveal()),
 }))
 
 // functions/*.ts — ask the service, never the secret store
@@ -113,7 +121,7 @@ defineSecret({
 })
 
 // In your services factory — fully typed
-const config = await secrets.getSecret('STRIPE_CONFIG')
+const config = (await secrets.getSecret('STRIPE_CONFIG')).reveal()
 // config.apiKey       → string (autocompleted)
 // config.webhookSecret → string (autocompleted)
 
@@ -178,17 +186,34 @@ defineCredential({
   },
 })
 
-// In your function — tokens refresh automatically
-const response = await slackOAuth.request(
-  'https://slack.com/api/chat.postMessage',
-  {
-    method: 'POST',
-    body: JSON.stringify({ channel, text }),
+### Reading a Credential
+
+A declared credential is resolved per invocation through `wire.getCredential(name)`,
+so the natural place to read it is a wire service factory: build the client there
+once and let functions ask the client, the same way they ask a service for a
+secret-derived value. Tokens refresh automatically, so what arrives is already
+valid.
+
+```typescript
+export const createWireServices = pikkuWireServices(async (_services, wire) => {
+  const cred = await wire.getCredential?.<{ accessToken: string }>('slack')
+  if (!cred?.accessToken) {
+    // Tells the caller which credential to connect, and where.
+    throw new MissingCredentialError('slack', 'oauth2', '/credentials/slack/connect')
   }
-)
-const data = await response.json()
+  return { slack: new SlackClient(cred.accessToken) }
+})
+
+// functions/*.ts — ask the client, never the credential store
+export const postMessage = pikkuFunc({
+  func: async ({ slack }, { channel, text }) => slack.postMessage(channel, text),
+})
 ```
 
+A `wire` credential resolves per user, so an unconnected user hits
+`MissingCredentialError` rather than silently acting as someone else; a
+`singleton` credential is platform-level and identical for every caller.
+
 ## Key Rule
 
 **Never use `process.env` inside Pikku functions.** Use the `variables` or `secrets` service:
@@ -201,7 +226,24 @@ const apiKey = process.env.API_KEY
 const apiKey = services.variables.get('API_KEY')
 ```
 
-`process.env` belongs only in server bootstrap code (`start.ts`).
+`process.env` belongs only in server bootstrap code (`start.ts`). Under `pikku dev` / `pikku serve` there is no `start.ts` — startup work goes in a `pikkuServerLifecycle` export, and the hooks receive the singleton services, so read configuration through `variables` there too (see pikku-services).
+
+### Lint rules
+
+`pikku.config.json` can set the severity of individual checks:
+
+```json
+{
+  "lint": {
+    "servicesNotDestructured": "error",
+    "wiresNotDestructured": "error",
+    "functionDynamicImport": "warn",
+    "customServerBootstrap": "warn"
+  }
+}
+```
+
+`customServerBootstrap` is the one evaluated by `pikku validate` rather than codegen: it warns when the root `start`/`dev` script boots a server without `pikku dev` / `pikku serve` and no runtime adapter is installed. Set it to `"off"` to keep a hand-rolled entrypoint, or `"error"` to enforce the hooks.
 
 ## Complete Example
 

package/skills/pikku-cron/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   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).
+installGroups: [core]
 ---
 
 # Pikku Cron/Scheduler Wiring
@@ -42,6 +43,7 @@ wireScheduler({
   name: string,            // Unique scheduler name
   schedule: string,        // Cron expression
   func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
+  tags?: string[],         // Targets tag middleware — see pikku-middleware
   middleware?: PikkuMiddleware[],
 })
 ```
@@ -53,10 +55,17 @@ 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)
+wire.scheduledTask.executionTime // Date this execution was triggered
+wire.scheduledTask.skip(reason?) // Abort this execution — THROWS, never returns
 ```
 
+**`skip()` aborts by throwing.** It reads like an early return but it is not:
+nothing after the call runs, so there is no need to `return` afterwards. The
+consequence that bites is in middleware — a `try/catch` around `await next()`
+will catch a skip and report it as a failure. If your middleware distinguishes
+success from failure, let the skip pass through rather than logging it as an
+error.
+
 ### Cron Expression Reference
 
 ```
@@ -113,8 +122,7 @@ const weeklyCleanup = pikkuVoidFunc({
 
     const staleCount = await db.countStaleTodos()
     if (staleCount === 0) {
-      wire.scheduledTask.skip('No stale todos found')
-      return
+      wire.scheduledTask.skip('No stale todos found') // throws — nothing below runs
     }
 
     await db.deleteCompletedTodos({ olderThan: '30d' })
@@ -178,8 +186,7 @@ export const cleanupExpired = pikkuVoidFunc({
   func: async ({ db, logger }, _input, wire) => {
     const count = await db.countExpiredSessions()
     if (count === 0) {
-      wire.scheduledTask.skip('No expired sessions')
-      return
+      wire.scheduledTask.skip('No expired sessions') // throws — nothing below runs
     }
     await db.deleteExpiredSessions()
     logger.info(`Cleaned ${count} expired sessions`)