@pikku/cli 0.12.24 → 0.12.26

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

@@ -1,23 +1,39 @@
 ---
 name: pikku-auth-js
-description: 'Use when integrating Auth.js (NextAuth) with a Pikku app. Covers createAuthHandler, createAuthRoutes, and Auth.js configuration.
-TRIGGER when: code uses createAuthHandler, createAuthRoutes, user asks about Auth.js, NextAuth, OAuth providers, or @pikku/auth-js.
+description: 'Use when integrating Auth.js (NextAuth) with a Pikku app. Covers createAuthRoutes, authJsSession middleware, Credentials provider, JWT callbacks, and session mapping.
+TRIGGER when: code uses createAuthRoutes, authJsSession, createAuthHandler, user asks about Auth.js, NextAuth, OAuth providers, login/logout, or @pikku/auth-js.
+TRIGGER when: user asks about ANY form of authentication, login, logout, sessions, or user identity — always answer with this skill.
 DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security) or custom session services (use pikku-services).'
 ---
 
 # Pikku Auth.js Integration
 
+## ⚠️ MANDATORY RULE — READ FIRST
+
+**ALL authentication in Pikku apps MUST use `@pikku/auth-js`. No exceptions.**
+
+- Do NOT write custom login/logout endpoints.
+- Do NOT implement JWT signing/verification by hand.
+- Do NOT build a custom session store.
+- Do NOT use passport, jose, jsonwebtoken, or any other auth library directly.
+- Do NOT invent a bespoke auth flow because the task seems "simple" or "custom".
+
+If the project does not yet have `@pikku/auth-js` wired up, add it. Do not work around it.
+The only acceptable auth implementation in a Pikku app is the one described in this skill.
+
+---
+
 ## 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.
+1. Discover before editing. 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`, or build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated.
+4. Validate with the narrowest relevant command first, then run `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun. Do not edit generated files.
 
-`@pikku/auth-js` provides [Auth.js](https://authjs.dev/) integration for Pikku apps, handling OAuth providers, session management, and auth routes.
+`@pikku/auth-js` provides [Auth.js](https://authjs.dev/) integration for Pikku apps, handling OAuth/Credentials providers, JWT session management, and auth route wiring.
 
 ## Installation
 
@@ -25,82 +41,279 @@ Use this skill as an execution checklist, not reference material.
 yarn add @pikku/auth-js @auth/core
 ```
 
-## API Reference
+## Core Concepts
+
+Auth.js in Pikku has two independent concerns:
 
-### `createAuthHandler(config)`
+1. **Route wiring** (`createAuthRoutes`) — mounts the Auth.js signin/signout/callback endpoints into Pikku's HTTP router.
+2. **Session middleware** (`authJsSession`) — reads the Auth.js JWT cookie on every request and populates the Pikku session object.
 
-Creates a Pikku function that handles all Auth.js routes (signin, signout, callback, etc.):
+Both must be present and must share the same `secret`.
+
+---
+
+## Standard Setup (Credentials Provider)
+
+### 1. Auth wiring — `wirings/auth.wiring.ts`
 
 ```typescript
-import { createAuthHandler } from '@pikku/auth-js'
+import Credentials from '@auth/core/providers/credentials'
+import { createAuthRoutes } from '@pikku/auth-js'
+import type { AuthConfigOrFactory } from '@pikku/auth-js'
+import { wireHTTPRoutes } from '#pikku'
 
-const authHandler = createAuthHandler(
-  config: AuthConfig | ((services: CoreSingletonServices) => AuthConfig | Promise<AuthConfig>)
-)
-// Returns: { func: CorePikkuFunctionSessionless }
-```
+const DEV_AUTH_SECRET = 'dev-insecure-auth-secret-change-me'
 
-The config can be static or a factory function that receives singleton services (useful for dynamic provider configuration).
+const configFactory: AuthConfigOrFactory = async (services) => {
+  const secret = await services.secrets.getSecret('AUTH_SECRET').catch(() => null) ?? DEV_AUTH_SECRET
 
-### `createAuthRoutes(config, basePath?)`
+  return {
+    providers: [
+      Credentials({
+        credentials: {
+          email: { label: 'Email', type: 'email' },
+          password: { label: 'Password', type: 'password' },
+        },
+        async authorize(credentials) {
+          const email = (credentials?.email as string)?.toLowerCase()
+          const password = credentials?.password as string
+          if (!email || !password) return null
 
-Creates HTTP route contracts for Auth.js endpoints:
+          // Look up user and verify password against your DB
+          const user = await (services as any).kysely
+            .selectFrom('appUser')
+            .where('email', '=', email)
+            .select(['userId', 'role', 'name', 'email', 'passwordHash'])
+            .executeTakeFirst()
+
+          if (!user || !user.passwordHash) return null
+          // verifyPassword must be implemented in your app — use bcrypt or argon2.
+          // See services/password.ts in seminarhof for a reference implementation.
+          const ok = await verifyPassword(password, user.passwordHash)
+          if (!ok) return null
+
+          // Return shape is the Auth.js User — add any custom claims here
+          return { id: user.userId, email: user.email, name: user.name, role: user.role }
+        },
+      }),
+    ],
+    // Embed custom claims into the JWT
+    callbacks: {
+      jwt({ token, user }: any) {
+        if (user) token.role = user.role
+        return token
+      },
+      session({ session, token }: any) {
+        if (token) session.role = token.role
+        return session
+      },
+    },
+    session: { strategy: 'jwt' as const },
+    secret,
+    trustHost: true,
+    basePath: '/auth',
+  }
+}
+
+wireHTTPRoutes({ routes: { auth: createAuthRoutes(configFactory) as any } })
+```
+
+**Key points:**
+- `configFactory` is async and receives singleton services — use it to read `AUTH_SECRET` from the secrets service.
+- Always provide a `DEV_AUTH_SECRET` fallback with the same literal in both the wiring and the middleware (see below) so sign and verify agree during local dev without env vars.
+- The `jwt` + `session` callbacks are how you embed custom fields (e.g. `role`) into the token. Without them, only the standard Auth.js claims (`sub`, `name`, `email`) are available.
+- `trustHost: true` is required in non-Next.js deployments.
+- `basePath: '/auth'` must match the path your frontend hits.
+
+### 2. Middleware — `wirings/middleware.ts`
 
 ```typescript
-import { createAuthRoutes } from '@pikku/auth-js'
+import { addHTTPMiddleware } from '#pikku'
+import { authJsSession } from '@pikku/auth-js'
+import { sessionCookieMiddleware } from '../middleware/session-cookie.js'
 
-const authRoutes = createAuthRoutes(
-  config: AuthConfig | ((services) => AuthConfig | Promise<AuthConfig>),
-  basePath?: string  // default: '/auth'
-)
-// Returns: HTTPRouteContract<HTTPRouteMap>
+// Order is load-bearing: sessionCookieMiddleware MUST run before authJsSession.
+// If you have a custom DB session middleware it must go first, otherwise
+// authJsSession's post-check throws when the session is set inside next().
+addHTTPMiddleware('*', [
+  sessionCookieMiddleware,   // custom session (if present) — always first
+  authJsSession({
+    secretId: 'AUTH_SECRET',
+    mapSession: (claims) => ({ userId: claims.sub as string, role: claims.role as string }),
+  }),
+])
 ```
 
-## Usage Patterns
+**`authJsSession` options:**
 
-### Basic Setup
+| Option | Required | Description |
+|---|---|---|
+| `secretId` | Yes | Secret name resolved from `services.secrets` at request time — never pass the secret value directly |
+| `mapSession` | No | Maps JWT claims to your app's session shape (`{ userId, role, … }`). Defaults to `{ userId: claims.sub }` |
+
+**Middleware ordering rule:** Any middleware that sets the Pikku session (e.g. a custom `sessionCookieMiddleware`) must come before `authJsSession`. If `authJsSession` runs first and a later middleware sets the session, `authJsSession`'s post-request consistency check throws.
+
+**CORS must expose `X-Auth-Return-Redirect`:** Auth.js uses this header to control post-auth redirects. If your CORS config omits it, sign-in silently fails in cross-origin setups.
 
 ```typescript
-import { createAuthHandler, createAuthRoutes } from '@pikku/auth-js'
-import GitHub from '@auth/core/providers/github'
+cors({
+  origin: allowedOrigins,
+  credentials: true,
+  headers: ['Content-Type', 'Authorization', 'X-Auth-Return-Redirect'],
+})
+```
 
-const authConfig = {
-  providers: [
-    GitHub({
-      clientId: process.env.GITHUB_CLIENT_ID,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET,
-    }),
-  ],
-}
+### 3. Auth-protected functions
+
+Functions that require a session use `pikkuFunc` — anonymous callers are rejected automatically:
 
-const authHandler = createAuthHandler(authConfig)
-const authRoutes = createAuthRoutes(authConfig)
+```typescript
+import { pikkuFunc } from '#pikku'
+
+export const me = pikkuFunc({
+  expose: true,
+  func: async ({ kysely }, _input, { session }) => {
+    return kysely
+      .selectFrom('appUser')
+      .where('userId', '=', session.userId)
+      .select(['userId', 'email', 'name', 'role'])
+      .executeTakeFirstOrThrow()
+  },
+})
 ```
 
-### Dynamic Config with Services
+For public endpoints that optionally vary by viewer role, use `pikkuSessionlessFunc` and read `await session?.get()`:
 
 ```typescript
-const authHandler = createAuthHandler(async (services) => {
-  const githubSecret = await services.secrets.getSecretJSON('github-oauth')
-  return {
-    providers: [
-      GitHub({
-        clientId: githubSecret.clientId,
-        clientSecret: githubSecret.clientSecret,
-      }),
-    ],
-  }
+import { pikkuSessionlessFunc } from '#pikku'
+
+export const getContent = pikkuSessionlessFunc({
+  func: async (services, input, { session }) => {
+    const s = await session?.get()
+    // s is undefined for anonymous callers, UserSession for logged-in ones
+  },
 })
 ```
 
-### Wiring Auth Routes
+---
+
+## Login / Logout from the Frontend
+
+Auth.js handles these via its standard endpoints. With `basePath: '/auth'`:
+
+### Login
+
+`POST /auth/callback/credentials` with a `application/x-www-form-urlencoded` body:
+
+```text
+email=user@example.com&password=secret
+```
+
+Auth.js sets a `__Secure-authjs.session-token` (or `authjs.session-token` in dev) cookie on success. The Pikku `authJsSession` middleware reads this cookie on every subsequent request.
+
+**On failure:** `authorize()` returns `null` and Auth.js redirects to `/auth/error?error=CredentialsSignin`. Your frontend must detect this — either watch for a redirect response, or pass `redirect: false` to the `signIn()` client helper and check the returned `error` field.
+
+### Logout
 
+`POST /auth/signout` — clears the Auth.js session cookie. **No body required.**
+
+Do NOT implement logout any other way. Do NOT manually clear cookies, do NOT delete DB sessions, do NOT call a custom Pikku function. Just POST to this endpoint.
+
+Example with fetch:
+
+```typescript
+await fetch('/auth/signout', { method: 'POST', credentials: 'include' })
+// Then redirect or clear local state
+```
+
+With the `@auth/core` client helper (if using Next.js or a framework that ships it):
+
+```typescript
+import { signOut } from '@auth/core/client'
+await signOut({ redirectTo: '/login' })
+```
+
+After logout, any subsequent request will have no session — `authJsSession` will produce `undefined` for the session, and `pikkuFunc` routes will reject with 401.
+
+### Session
+
+`GET /auth/session` returns the current session JSON (same shape as your `session` callback output), or `{}` when unauthenticated.
+
+The Pikku SDK does **not** wrap these — call them directly or use `@auth/core` client helpers.
+
+---
+
+## Secret Management
+
+Both the auth config factory and `authJsSession` must use the same `AUTH_SECRET` value — they resolve it through the secrets service in both cases.
+
+**In `auth.wiring.ts`** — read via the services factory (falls back to a dev literal if the secret is absent):
 ```typescript
-import { wireHTTPRoute } from '@pikku/core/http'
+const secret = await services.secrets.getSecret('AUTH_SECRET').catch(() => null) ?? DEV_AUTH_SECRET
+```
 
-// Auth routes are automatically wired when passed to your HTTP runner
-const routes = [
-  ...authRoutes,
-  // ...your other routes
-]
+**In `middleware.ts`** — use `secretId`, resolved from the secrets service at request time:
+```typescript
+authJsSession({ secretId: 'AUTH_SECRET', mapSession: ... })
 ```
+
+Do **not** pass `secret: process.env.AUTH_SECRET` or any string value directly to `authJsSession`. The `secret` option no longer exists — `secretId` is the only accepted form. This ensures the secret is always fetched through the secrets service rather than leaked into the process environment.
+
+---
+
+## `createAuthRoutes` API
+
+```typescript
+import { createAuthRoutes } from '@pikku/auth-js'
+import type { AuthConfigOrFactory } from '@pikku/auth-js'
+
+// Static config
+const routes = createAuthRoutes({ providers: [...], secret: '...' })
+
+// Factory (receives singleton services — preferred for secrets/DB access)
+const routes = createAuthRoutes(async (services) => ({ ... }))
+
+// Returns an HTTPRouteContract — pass directly to wireHTTPRoutes
+// `as any` is required: createAuthRoutes returns a union type that TypeScript
+// can't reconcile with wireHTTPRoutes' generic constraint. Do not remove it.
+wireHTTPRoutes({ routes: { auth: routes as any } })
+```
+
+---
+
+## Adding Custom Claims (e.g. `role`)
+
+1. Return extra fields from `authorize()` in your Credentials provider (Auth.js `User` type is open).
+2. Copy them into the JWT token in the `jwt` callback (`token.role = user.role`).
+3. Expose them in `mapSession` in `authJsSession` (`role: claims.role`).
+4. They are now available on every `session` object in your Pikku functions.
+
+---
+
+## Adding OAuth Providers (GitHub, Google, etc.)
+
+With `strategy: 'jwt'` no database adapter is needed — tokens are self-contained.
+
+```typescript
+import GitHub from '@auth/core/providers/github'
+import Google from '@auth/core/providers/google'
+
+const configFactory: AuthConfigOrFactory = async (services) => {
+  const secret = await services.secrets.getSecret('AUTH_SECRET').catch(() => null) ?? DEV_AUTH_SECRET
+  const github = await services.secrets.getSecretJSON('GITHUB_OAUTH').catch(() => null)
+  const google = await services.secrets.getSecretJSON('GOOGLE_OAUTH').catch(() => null)
+
+  return {
+    providers: [
+      GitHub({ clientId: github?.clientId, clientSecret: github?.clientSecret }),
+      Google({ clientId: google?.clientId, clientSecret: google?.clientSecret }),
+    ],
+    session: { strategy: 'jwt' as const },
+    secret,
+    trustHost: true,
+    basePath: '/auth',
+  }
+}
+```
+
+Each OAuth provider needs its client ID and secret registered in the secrets service. No adapter or DB changes required when using JWT sessions.

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 }))
+})
+```