@pikku/cli 0.12.25 → 0.12.27

package/skills/pikku-security/SKILL.md

@@ -1,43 +1,26 @@
 ---
 name: pikku-security
-description: 'Use when adding authentication, authorization, permissions, middleware, or security to a Pikku app. Covers pikkuAuth, pikkuPermission, pikkuMiddleware, built-in auth strategies (bearer, cookie, API key), and permission scoping.
-TRIGGER when: code uses pikkuAuth/pikkuPermission/pikkuMiddleware, user asks about auth, login, session, permissions, RBAC, middleware, or API keys.
-DO NOT TRIGGER when: user asks about JWT service setup (use pikku-services) or secrets/env vars (use pikku-config).'
+description: 'Use when adding authentication or session management to a Pikku app — pikkuAuth, session lifecycle (setSession/clearSession), built-in auth strategies (authBearer, authCookie, authAPIKey), or JWT setup.
+TRIGGER when: user asks about login, logout, session, bearer tokens, cookie auth, API keys, or JWT.
+DO NOT TRIGGER when: user asks about middleware (use pikku-middleware), permissions/authorization checks (use pikku-permissions), or secrets/env vars (use pikku-config).'
 installGroups: [core]
 ---
 
-# Pikku Security (Auth, Permissions, Middleware)
+# Pikku Security (Authentication & Sessions)
 
 ## Agent Operating Procedure
 
-Use this skill as an execution checklist, not reference material.
+1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info functions --verbose` to understand existing auth setup.
+2. Auth strategies live in wirings files — do not put `addHTTPMiddleware` calls inside function bodies.
+3. Validate with `pikku tsc` after changes; run `pikku all` if wirings changed.
 
-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.
+For **middleware** (including tag middleware and service-to-service bearer auth) see `pikku-middleware`.
+For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see `pikku-permissions`.
 
-Pikku provides a layered security model: authentication middleware (who are you?), auth checks (are you logged in?), and permissions (can you do this?). All work across every transport (HTTP, WebSocket, CLI, queue, etc.).
-
-## Before You Start
-
-```bash
-pikku info middleware --verbose    # See existing middleware and where it's applied
-pikku info permissions --verbose   # See existing permissions
-pikku info functions --verbose     # See which functions have auth/permissions
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### Session Management
-
-Functions access session via the wire object:
+## Session Management
 
 ```typescript
-// In pikkuFunc (authenticated)
+// Read session in pikkuFunc (session guaranteed to exist)
 const getProfile = pikkuFunc({
   func: async ({ db }, _data, { session }) => {
     return await db.getUser(session.userId)
@@ -62,78 +45,19 @@ const logout = pikkuFunc({
 })
 ```
 
-### `pikkuAuth(fn)` — Session-Only Checks
-
-Use for authentication gates that only need the session (no request data).
-
-```typescript
-import { pikkuAuth } from '#pikku'
-
-// Receives (services, session)
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
-)
-
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
-)
-```
-
-### `pikkuPermission(fn)` — Data-Aware Checks
-
-Use when authorization depends on the actual request data.
-
-```typescript
-import { pikkuPermission } from '#pikku'
-
-// Receives (services, data, wire)
-export const isOwner = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    const book = await db.getBook(bookId)
-    return book?.authorId === session?.userId
-  }
-)
-
-export const hasBookAccess = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    return await db.hasAccess(session?.userId, bookId)
-  }
-)
-```
-
-### Permission Groups (OR/AND Logic)
+## Built-in Auth Strategies
 
-```typescript
-{
-  admin: isAdmin,                          // OR: admins can access
-  owner: isOwner,                          // OR: owners can access
-  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
-}
-// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
-```
-
-### `pikkuMiddleware(fn)` — Before/After Wrapping
-
-```typescript
-import { pikkuMiddleware } from '#pikku'
-
-const logRequest = pikkuMiddleware(async ({ logger }, wire, next) => {
-  logger.info('Before')
-  await next()
-  logger.info('After')
-})
-```
-
-### Built-in Auth Middleware
+Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
+import { addHTTPMiddleware } from '@pikku/core/http'
 
 // JWT bearer token — reads Authorization header
-addHTTPMiddleware([authBearer()])
+addHTTPMiddleware('*', [authBearer()])
 
 // Cookie-based sessions — auto-refreshes JWT
-addHTTPMiddleware([
+addHTTPMiddleware('*', [
   authCookie({
     name: 'session',
     expiresIn: { value: 30, unit: 'day' },
@@ -141,48 +65,8 @@ addHTTPMiddleware([
   }),
 ])
 
-// API key — from x-api-key header or ?apiKey= query
-addHTTPMiddleware([authAPIKey({ source: 'all' })])
-```
-
-### Scoping: Where to Apply
-
-Four levels of scoping, from broadest to narrowest:
-
-```typescript
-// 1. Global: all HTTP routes
-addHTTPMiddleware('*', [authBearer()])
-
-// 2. Prefix-based: URL pattern
-addHTTPMiddleware('/admin/*', [auditLog])
-addHTTPPermission('/admin/*', { admin: requireAdmin })
-
-// 3. Tag-based: any wiring with matching tag
-addMiddleware('api', [rateLimiter])
-addPermission('api', { auth: requireAuth })
-
-// 4. Inline: per-wiring
-wireHTTP({
-  route: '/books/:id',
-  func: getBook,
-  middleware: [cacheControl],
-  permissions: { owner: requireOwnership },
-})
-```
-
-### Per-Function Permissions
-
-```typescript
-export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-  },
-  permissions: {
-    admin: isAdmin,
-    owner: isOwner,
-    reviewer: [isAuthenticated, hasBookAccess],
-  },
-})
+// API key — from x-api-key header or ?apiKey= query param
+addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 ```
 
 ## Complete Example
@@ -191,53 +75,30 @@ export const deleteBook = pikkuFunc({
 // permissions.ts
 import { pikkuAuth, pikkuPermission } from '#pikku'
 
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
-)
-
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
-)
-
-export const isBookOwner = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    const book = await db.getBook(bookId)
-    return book?.authorId === session?.userId
-  }
-)
-
-// middleware.ts
-import { pikkuMiddleware } from '#pikku'
-
-export const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
-  const start = Date.now()
-  await next()
-  await db.createAuditLog({
-    duration: Date.now() - start,
-  })
-})
-
-// wirings/security.wiring.ts
-import { authBearer } from '@pikku/core/middleware'
-import { addHTTPMiddleware, addHTTPPermission } from '#pikku'
+export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
+export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
 
-// All routes require bearer auth
-addHTTPMiddleware('*', [authBearer()])
+// wirings/auth.wiring.ts
+import { authCookie } from '@pikku/core/middleware'
+import { addHTTPMiddleware } from '@pikku/core/http'
 
-// Admin routes need admin permission + audit logging
-addHTTPMiddleware('/admin/*', [auditLog])
-addHTTPPermission('/admin/*', { admin: isAdmin })
+addHTTPMiddleware('*', [
+  authCookie({ name: 'session', expiresIn: { value: 30, unit: 'day' } }),
+])
 
-// functions/books.functions.ts
-export const deleteBook = pikkuFunc({
-  title: 'Delete Book',
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-    return { deleted: true }
+// functions/auth.functions.ts
+export const login = pikkuFunc({
+  auth: false,
+  func: async ({ jwt, db }, { email, password }, { setSession }) => {
+    const user = await db.verifyCredentials(email, password)
+    setSession({ userId: user.id, role: user.role })
+    return { token: jwt.sign({ userId: user.id }) }
   },
-  permissions: {
-    admin: isAdmin,
-    owner: isBookOwner,
+})
+
+export const logout = pikkuFunc({
+  func: async ({}, _data, { clearSession }) => {
+    clearSession()
   },
 })
 ```

package/skills/pikku-tag-middleware/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: pikku-tag-middleware
+description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.'
+---
+
+# Deprecated: use `pikku-middleware`
+
+Tag middleware is covered in the **`pikku-middleware`** skill, which also covers:
+- `addHTTPMiddleware` (global / prefix-based)
+- `addTagMiddleware` (tag-scoped)
+- Middleware execution order and priority
+- Service-to-service bearer auth pattern
+- Session-setting middleware pattern

package/skills/pikku-testing/SKILL.md

@@ -27,6 +27,132 @@ pikku info functions --verbose   # See existing functions and their middleware/p
 pikku info middleware --verbose  # See middleware applied
 ```
 
+## Personas and Named Data — Never Inline JSON
+
+**Never put JSON, inline tables, or raw values inside `.feature` files.** Feature files are for human-readable scenarios. All test data belongs in typed maps that step definitions look up by name.
+
+`@pikku/cucumber` exports `PersonaData<T>` for this purpose — a typed map that throws a clear error when a name is missing.
+
+### Personas
+
+A **persona** is a named user: their login credentials plus the session they hold after authenticating. Define all personas in one file:
+
+```ts
+// tests/tests/support/personas.ts
+import { PersonaData } from '@pikku/cucumber'
+
+export const logins = new PersonaData({
+  yasser: { email: 'yasser@example.com', password: 'hunter2' },
+  guest:  { email: 'guest@example.com',  password: 'guest123' },
+})
+```
+
+A persona step logs in and stores the session in the world so every subsequent call by that persona carries it automatically:
+
+```ts
+// tests/tests/support/steps/auth.steps.ts
+import { Given } from '@cucumber/cucumber'
+import { logins } from '../personas.js'
+
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', logins.get(name))
+  const { token } = this.lastResult as { token: string }
+  this.setSession(name, { token })
+})
+```
+
+### Named Domain Data
+
+Use a separate `PersonaData` map for each domain concept. Name entries after real-world meaning, not technical fields:
+
+```ts
+// tests/tests/support/data/cards.ts
+import { PersonaData } from '@pikku/cucumber'
+
+export const cards = new PersonaData({
+  'writing a blog post': { title: 'Writing a blog post', columnId: 'backlog' },
+  'fix the login bug':   { title: 'Fix the login bug',   columnId: 'in-progress' },
+})
+```
+
+Steps resolve the name and make the call — the feature file never sees raw data:
+
+```ts
+// tests/tests/support/steps/card.steps.ts
+import { When, Then } from '@cucumber/cucumber'
+import assert from 'node:assert/strict'
+import { cards } from '../data/cards.js'
+
+When('{string} creates a card for {string}', async function (persona: string, cardName: string) {
+  await this.call(persona, 'kanban:createCard', cards.get(cardName))
+})
+
+When('{string} gets the card {string}', async function (persona: string, cardName: string) {
+  const { title } = cards.get(cardName)
+  await this.call(persona, 'kanban:getCard', { title })
+})
+
+// "the newly created card" — checks the live result against the data map entry
+// AND any server-assigned fields (id, createdAt) are present
+Then('the result is the newly created card {string}', function (cardName: string) {
+  const expected = cards.get(cardName)
+  const result = this.lastResult as typeof expected & { id: string; createdAt: string }
+  assert.equal(result.title, expected.title)
+  assert.equal(result.columnId, expected.columnId)
+  assert.ok(result.id, 'expected server-assigned id')
+  assert.ok(result.createdAt, 'expected server-assigned createdAt')
+})
+```
+
+The feature file reads naturally:
+
+```gherkin
+Feature: Card management
+
+  Scenario: Create and retrieve a card
+    Given 'yasser' logs in
+    When 'yasser' creates a card for 'writing a blog post'
+    And 'yasser' gets the card 'writing a blog post'
+    Then the result is the newly created card 'writing a blog post'
+```
+
+### File layout
+
+```
+tests/tests/support/
+  personas.ts          ← logins PersonaData (one per project)
+  data/
+    cards.ts           ← cards PersonaData
+    users.ts           ← users PersonaData
+  steps/
+    auth.steps.ts      ← login / logout steps
+    card.steps.ts      ← card CRUD steps
+```
+
+Keep one `PersonaData` instance per domain concept. Steps import only what they need — no cross-domain coupling.
+
+## Coverage-Driven Test Writing
+
+When asked to improve or fill test coverage, start with the AI prompt from the coverage command:
+
+```bash
+# Run tests and emit an AI-ready prompt listing every uncovered/partial function
+pikku tests coverage --ai-out coverage-prompt.md
+
+# Or skip re-running if you already have fresh coverage data
+pikku tests coverage --no-run --ai-out coverage-prompt.md
+
+# Pipe directly to stdout (e.g. to paste into a chat)
+pikku tests coverage --ai-out -
+```
+
+The prompt lists each function that needs work with its status (`uncovered`/`partial`), coverage ratio, missed line numbers, and source file path. Use it as your starting point:
+
+1. Read the prompt to know which functions need Gherkin scenarios.
+2. Run `pikku meta functions list` or `pikku meta context` to get input/output schemas for those functions.
+3. Write `.feature` files under `tests/tests/features/` — one feature per domain, one scenario per case.
+4. Re-run `pikku tests coverage` to confirm coverage improved.
+
 See `pikku-concepts` for the core mental model.
 
 ## Test Runner Setup
@@ -426,3 +552,85 @@ describe('createTodo', () => {
   })
 })
 ```
+
+## Anti-Patterns
+
+### Inline data in feature files
+
+**Wrong** — raw values and JSON in `.feature` files make scenarios brittle and unreadable:
+
+```gherkin
+When I call 'kanban:createCard' with {"title": "My card", "columnId": "backlog"}
+And I call 'kanban:getCard' with {"title": "My card"}
+Then the result title is "My card"
+```
+
+**Right** — named references resolved by step definitions:
+
+```gherkin
+When 'yasser' creates a card for 'writing a blog post'
+And 'yasser' gets the card 'writing a blog post'
+Then the result is the newly created card 'writing a blog post'
+```
+
+### Feature-coupled step definitions
+
+Steps tied to one feature can't be reused and cause duplication. Organise by **domain concept**, not by feature:
+
+```
+Wrong:                          Right:
+steps/
+  edit_work_experience.ts  →    steps/
+  edit_languages.ts        →      auth.steps.ts
+  edit_education.ts        →      profile.steps.ts
+                                  card.steps.ts
+```
+
+Name step files after the domain they cover. A login step belongs in `auth.steps.ts` regardless of which feature needs it.
+
+### Conjunction steps
+
+Don't combine multiple actions into a single step — it makes reuse impossible:
+
+```gherkin
+# Wrong — two actions in one step
+Given 'yasser' is logged in and has created a card
+```
+
+```gherkin
+# Right — atomic steps, composable via And
+Given 'yasser' logs in
+And 'yasser' creates a card for 'writing a blog post'
+```
+
+Use `And` / `But` for a reason: each step should do exactly one thing.
+
+### Asserting in When steps
+
+`When` steps perform actions; `Then` steps assert outcomes. Mixing them hides intent:
+
+```gherkin
+# Wrong
+When 'yasser' creates a card and the title is 'writing a blog post'
+
+# Right
+When 'yasser' creates a card for 'writing a blog post'
+Then the call succeeds
+```
+
+### Hard-coding persona data in step definitions
+
+Credentials and test inputs embedded in step code can't be reused across scenarios and break when data changes:
+
+```ts
+// Wrong
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', { email: 'yasser@example.com', password: 'hunter2' })
+})
+
+// Right — look up from PersonaData
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', logins.get(name))
+  this.setSession(name, (this.lastResult as { token: string }))
+})
+```