@pikku/cli 0.12.82 → 0.12.83

package/skills/pikku-n8n-code-translate/SKILL.md

@@ -1,166 +0,0 @@
----
-name: pikku-n8n-code-translate
-description: "Use when translating an n8n Code node body into a real Pikku function body. Triggered when the user opens or points at a stub generated by @pikku/n8n-import (look for `STUB — generated from n8n Code node` in the file's JSDoc), or when the user says 'translate this n8n code', 'port this n8n code node', 'finish the codeStub__... function', etc. The stub file is a `pikkuSessionlessFunc` with a Zod input/output, a JSDoc preserving the original n8n JavaScript verbatim, and a `throw new Error('… — implement me')` body. DO NOT TRIGGER when: the stub is an n8n integration/service node such as gmailTool or slackTool (use pikku-n8n-addon-map), or the code is not an n8n-generated stub at all."
-metadata:
-  version: 1.0.0
----
-
-# n8n Code Node → Pikku Function Translator
-
-## 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.
-
-You are translating an n8n **Code node** body into a Pikku `pikkuSessionlessFunc` body. The original JavaScript is preserved verbatim in the JSDoc above the function. Your job: replace the `throw new Error(...)` body with a faithful TypeScript reimplementation, keep the function signature and the JSDoc intact, and only widen the Zod input/output if the original code's data shape demands it.
-
-This is a **narrow, mechanical translation**. Do not "improve" the logic, refactor for style, add error handling, or invent fields. The goal is behavioral parity, not better code.
-
-## Process
-
-1. **Read the file** the user points you at. Identify:
-   - The exported input schema (e.g. `CodeStubCustomCodeInput`)
-   - The exported output schema (e.g. `CodeStubCustomCodeOutput`)
-   - The verbatim JavaScript inside the JSDoc block
-   - The function name and `pikkuSessionlessFunc` shape
-2. **Determine the n8n mode** from the original n8n JSON if available (the importer leaves the JSON on disk in `fixtures/` or you can ask the user). The two modes:
-   - `runOnceForAllItems` (default) — code runs once with `items: Array<{ json, binary, pairedItem }>` in scope, returns an array of envelopes.
-   - `runOnceForEachItem` — code runs once per input item, with `$json` / `$input.item.json` in scope, returns a single envelope.
-     If you can't determine the mode, infer from the code: bare `items.X` → all-items; bare `$json.X` or `$input.item.X` → each-item.
-3. **Apply the rubric below** to translate.
-4. **Edit the file** to replace only the function body. Leave the import block, schema definitions, JSDoc, function name, description, and Zod refs untouched unless step 5 forces a change.
-5. **If the schemas are wrong** (e.g. the code reads `$json.userId: string` but the input schema is `items: z.array(z.unknown())`), tighten the schemas with the smallest change that lets the code compile. Prefer `z.unknown()` over `z.any()`. Never widen output to `z.any()`.
-6. **Add a one-line comment at the top of the body** noting the n8n mode you assumed: `// translated from n8n Code node, mode: runOnceForAllItems`. This is the _only_ comment you may add.
-7. **Run the test/typecheck** if available (`yarn tsc` from the package root). Fix any type errors with the smallest viable change.
-
-## Translation rubric
-
-### Envelope unwrapping (all-items mode)
-
-The n8n `items` is an array of `{ json, binary, pairedItem }` envelopes. In Pikku, the input is typed — `data.items` is the payload array. Translate by treating `items[i]` as the payload directly.
-
-| n8n                        | Pikku                                             |
-| -------------------------- | ------------------------------------------------- |
-| `items`                    | `(data.items ?? []) as any[]` (or typed if known) |
-| `items[i].json.X`          | `items[i].X`                                      |
-| `items[i].json`            | `items[i]`                                        |
-| `items[i].binary`          | **NOT supported** — leave a TODO and explain      |
-| `items.length`             | `items.length`                                    |
-| `items.map(i => i.json.X)` | `items.map((i: any) => i.X)`                      |
-
-### Envelope unwrapping (each-item mode)
-
-| n8n                              | Pikku                                             |
-| -------------------------------- | ------------------------------------------------- |
-| `$json.X` / `$input.item.json.X` | `data.X` (assuming input is the item itself)      |
-| `$input.item.json`               | `data`                                            |
-| `$input.all()`                   | not available per-item — change to all-items mode |
-
-### Return statement
-
-| n8n                                      | Pikku                                                       |
-| ---------------------------------------- | ----------------------------------------------------------- |
-| `return [{ json: X }]`                   | `return { items: [X] }`                                     |
-| `return items.map(i => ({ json: ... }))` | `return { items: items.map(...) }`                          |
-| `return [{ json: X }, { json: Y }]`      | `return { items: [X, Y] }`                                  |
-| `return { json: X }` (each-item)         | `return X`                                                  |
-| `return [...]` (already plain)           | wrap in `{ items: [...] }` only if output schema expects it |
-
-### n8n built-ins and helpers — do NOT auto-translate
-
-If the code references **any** of the following, **stop**, leave the body as a stub, and ask the user how to handle it (or annotate with a `// TODO:` line and explain in your reply):
-
-- `this.helpers.*` (binary buffers, HTTP requests, prepareBinaryData, etc.)
-- `$node['Some Node'].json` (cross-node references — these need to be resolved via Pikku's `ref()` upstream wiring, not in the function body)
-- `$workflow`, `$execution`, `$item()`, `$items('Other Node')`
-- `$now`, `$today`, `$env.X` — translate to `new Date()`, `new Date()`, and `services.variables.get('X')` respectively, but only if the function signature lets you reach `services` (it does — first param). NOTE: `process.env` is forbidden per Pikku house rules; always use `services.variables.get()`.
-- `getBinaryDataBuffer` / `getStaticData` — Pikku has no equivalent, leave a TODO
-- `require()` / dynamic `import()` — flag and stop
-
-### Async
-
-- If the original uses `await`, the Pikku body is already `async` — keep all `await` calls intact.
-- If the original references `this.helpers.httpRequest(...)`, **do not translate** — the user should use a separate `httpRequest` rpc node in the workflow, not embed the call. Leave a `// TODO:` and explain.
-
-### Types
-
-- Cast incoming `items` as `any[]` only if the schema is `z.array(z.unknown())`. If the user has tightened the schema, use the inferred type.
-- Never use `as any` on the _return_ value. If the return doesn't match the output schema, the schema is wrong — fix it (step 5).
-
-## Example
-
-### Before (stub the importer emitted)
-
-```ts
-import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku'
-
-export const CodeStubCustomCodeInput = z.object({
-  items: z.array(z.unknown()),
-})
-
-export const CodeStubCustomCodeOutput = z.object({
-  items: z.array(z.unknown()),
-})
-
-/**
- * STUB — generated from n8n Code node "Custom Code".
- *
- * Original n8n JavaScript (preserved verbatim for reference; rewrite for Pikku semantics):
- *
- *   const total = items.reduce((acc, i) => acc + i.json.amount, 0);
- *   return [{ json: { total } }];
- *
- * TODO: re-implement in TypeScript. ...
- */
-export const codeStubCustomCode = pikkuSessionlessFunc({
-  description: 'Stub: ported from n8n Code node "Custom Code"',
-  input: CodeStubCustomCodeInput,
-  output: CodeStubCustomCodeOutput,
-  func: async (_services, _data) => {
-    throw new Error(
-      'Stub: ported from n8n Code node "Custom Code" — implement me'
-    )
-  },
-})
-```
-
-### After (your output)
-
-```ts
-export const codeStubCustomCode = pikkuSessionlessFunc({
-  description: 'Ported from n8n Code node "Custom Code"',
-  input: CodeStubCustomCodeInput,
-  output: CodeStubCustomCodeOutput,
-  func: async (_services, data) => {
-    // translated from n8n Code node, mode: runOnceForAllItems
-    const items = (data.items ?? []) as any[]
-    const total = items.reduce((acc, i) => acc + i.amount, 0)
-    return { items: [{ total }] }
-  },
-})
-```
-
-## What you should report back to the user
-
-A short summary, no fluff:
-
-- The mode you inferred and why (one sentence).
-- The literal translations you applied from the rubric (e.g. `items[i].json.amount → items[i].amount`).
-- Anything you flagged as a TODO and why.
-- Any schema tightening you did (with before → after).
-
-Do **not**:
-
-- Add tests
-- Refactor surrounding code
-- Edit other files unless the user asked
-- "Improve" the logic
-- Wrap things in `try/catch` unless the original did
-
-If the original is empty, contains only comments, or is so dependent on n8n internals (binary, cross-node refs, helpers) that no honest translation is possible, leave the stub in place and tell the user which n8n features are blocking it.

package/skills/pikku-testing/SKILL.md

@@ -1,328 +0,0 @@
----
-name: pikku-testing
-description: 'Use when writing tests for Pikku functions, middleware, permissions, or services. Covers unit testing with direct invocation, runPikkuFunc, service mocking, and integration testing with the HTTP runner.
-TRIGGER when: user asks about testing, writing tests, test setup, mocking services, or integration testing Pikku functions.
-DO NOT TRIGGER when: user asks about running the existing test suite (use Bash) or CI configuration (not a Pikku skill).'
-installGroups: [core]
----
-
-# Pikku Testing
-
-## 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 functions are pure business logic — no HTTP, no framework — making them easy to test. Test at three levels: direct function calls, `runPikkuFunc` (with middleware/permissions), and integration tests (full HTTP stack).
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # existing functions + their middleware/permissions
-pikku info middleware --verbose  # middleware applied
-```
-
-## Cucumber / BDD (feature files)
-
-When writing `.feature` files, the golden rule: **never put JSON, inline tables, or raw values inside `.feature` files** — all test data goes in typed `PersonaData<T>` maps (from `@pikku/cucumber`) that step definitions look up by name. For personas, named domain data, the support file layout, and the full set of BDD anti-patterns, read `references/cucumber-bdd-testing.md`.
-
-## Coverage-Driven Test Writing
-
-When asked to improve or fill test coverage, start with the AI prompt from the coverage command:
-
-```bash
-pikku tests coverage --ai-out coverage-prompt.md     # run tests + emit AI-ready prompt of uncovered/partial functions
-pikku tests coverage --no-run --ai-out coverage-prompt.md   # skip re-running, use existing coverage data
-pikku tests coverage --ai-out -                      # pipe to stdout
-```
-
-The prompt lists each function needing work with status (`uncovered`/`partial`), coverage ratio, missed line numbers, and source 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
-
-Pikku uses the Node.js built-in test runner with tsx for TypeScript:
-
-```bash
-node --import tsx --test src/**/*.test.ts
-```
-
-```typescript
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert'
-```
-
-A reusable mock logger / singleton services bag used throughout the examples below:
-
-```typescript
-const mockLogger = { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} }
-const mockSingletonServices = { logger: mockLogger /* + any services your funcs need */ } as any
-```
-
-## Level 1: Direct Function Invocation
-
-The simplest approach — call `func` directly with mock services. Tests pure business logic: no middleware, permissions, or validation.
-
-```typescript
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-
-describe('createTodo', () => {
-  test('should create a todo', async () => {
-    const mockServices = {
-      todoStore: { add: async (title: string) => ({ id: '1', title, completed: false }) },
-    }
-    const result = await createTodo.func(mockServices as any, { title: 'Buy milk' })
-    assert.equal(result.title, 'Buy milk')
-    assert.equal(result.completed, false)
-  })
-})
-```
-
-## Level 2: `runPikkuFunc` (Full Pipeline)
-
-Tests the function through Pikku's middleware, permissions, and schema-validation pipeline. Always `resetPikkuState()` in `beforeEach`. Register function metadata into `pikkuState(null, 'function', 'meta')`, register the function with `addFunction`, then invoke with `runPikkuFunc`.
-
-```typescript
-import { runPikkuFunc, addFunction, addMiddleware, addPermission } from '@pikku/core'
-import { resetPikkuState, pikkuState } from '@pikku/core'
-
-beforeEach(() => resetPikkuState())
-
-test('should run function with middleware', async () => {
-  pikkuState(null, 'function', 'meta')['myFunc'] = {
-    pikkuFuncId: 'myFunc', inputSchemaName: null, outputSchemaName: null,
-  }
-  addFunction('myFunc', {
-    func: async (services, data) => ({ greeting: `Hello ${data.name}` }),
-  })
-
-  const result = await runPikkuFunc('rpc', 'test-wire', 'myFunc', {
-    singletonServices: mockSingletonServices,
-    getAllServices: () => mockSingletonServices,
-    data: () => ({ name: 'World' }),
-    auth: false,
-    wire: {},
-  })
-
-  assert.deepEqual(result, { greeting: 'Hello World' })
-})
-```
-
-### Testing Middleware Execution Order
-
-Middleware runs: wiring tags → wiring → func tags → func. Register tag middleware with `addMiddleware(tag, [...])`, reference func tags in the meta's `middleware: [{ type: 'tag', tag }]`, pass wiring middleware via `wireMiddleware` and inherited tags via `inheritedMiddleware`.
-
-```typescript
-test('middleware runs in order: wiring tags -> wiring -> func tags -> func', async () => {
-  const order: string[] = []
-  const createMiddleware =
-    (name: string) => async (services: any, wire: any, next: Function) => {
-      order.push(name); await next()
-    }
-
-  addMiddleware('apiTag', [createMiddleware('apiTag')])
-  addMiddleware('funcTag', [createMiddleware('funcTag')])
-
-  pikkuState(null, 'function', 'meta')['myFunc'] = {
-    pikkuFuncId: 'myFunc', inputSchemaName: null, outputSchemaName: null,
-    middleware: [{ type: 'tag', tag: 'funcTag' }],
-  }
-  addFunction('myFunc', {
-    func: async () => { order.push('main'); return 'ok' },
-    middleware: [createMiddleware('funcMiddleware')],
-    tags: ['funcTag'],
-  })
-
-  await runPikkuFunc('rpc', 'test', 'myFunc', {
-    singletonServices: mockSingletonServices,
-    getAllServices: () => mockSingletonServices,
-    data: () => ({}),
-    wireMiddleware: [createMiddleware('wiringMiddleware')],
-    inheritedMiddleware: [{ type: 'tag', tag: 'apiTag' }],
-    auth: false,
-    wire: {},
-  })
-
-  assert.deepEqual(order, ['apiTag', 'wiringMiddleware', 'funcTag', 'funcMiddleware', 'main'])
-})
-```
-
-### Testing Permissions
-
-Register a denying permission with `addPermission(tag, [...])` and reference it in the meta's `permissions`.
-
-```typescript
-test('should reject when permission fails', async () => {
-  addPermission('admin', [async () => false]) // always deny
-
-  pikkuState(null, 'function', 'meta')['adminFunc'] = {
-    pikkuFuncId: 'adminFunc', inputSchemaName: null, outputSchemaName: null,
-    permissions: [{ type: 'tag', tag: 'admin' }],
-  }
-  addFunction('adminFunc', { func: async () => 'secret' })
-
-  await assert.rejects(
-    runPikkuFunc('rpc', 'test', 'adminFunc', {
-      singletonServices: mockSingletonServices,
-      getAllServices: () => mockSingletonServices,
-      data: () => ({}),
-      auth: false,
-      wire: {},
-    }),
-    /Permission/
-  )
-})
-```
-
-## Level 3: Integration Testing (HTTP)
-
-Test the full HTTP stack using the `fetch` export. Set singleton services and factories into state, register route metadata + function, then `wireHTTP`.
-
-```typescript
-import { fetch, wireHTTP } from '@pikku/core/http'
-import { resetPikkuState, pikkuState, addFunction } from '@pikku/core'
-
-const listTodos = { func: async () => ({ todos: [{ id: '1', title: 'Test todo' }] }) }
-
-beforeEach(() => {
-  resetPikkuState()
-  pikkuState(null, 'package', 'singletonServices', mockSingletonServices)
-  pikkuState(null, 'package', 'factories', { createWireServices: async () => ({}) })
-})
-
-test('GET /todos returns todo list', async () => {
-  pikkuState(null, 'http', 'meta')['get'] = pikkuState(null, 'http', 'meta')['get'] || {}
-  pikkuState(null, 'http', 'meta')['get']['/todos'] = {
-    pikkuFuncId: 'listTodos', method: 'get', route: '/todos',
-  }
-  addFunction('listTodos', listTodos)
-  wireHTTP({ method: 'get', route: '/todos', func: listTodos })
-
-  const response = await fetch(new Request('http://localhost/todos'))
-  const data = await response.json()
-  assert.equal(response.status, 200)
-  assert.ok(Array.isArray(data.todos))
-})
-```
-
-## Testing Services
-
-Test custom services in isolation:
-
-```typescript
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { LocalVariablesService } from '@pikku/core/services'
-
-describe('LocalVariablesService', () => {
-  test('should get and set variables', () => {
-    const service = new LocalVariablesService({ API_KEY: 'test-key' })
-    assert.equal(service.get('API_KEY'), 'test-key')
-    service.set('NEW_KEY', 'value')
-    assert.equal(service.get('NEW_KEY'), 'value')
-  })
-})
-```
-
-## Testing with Real Services (Verifier Pattern)
-
-For integration testing with a running server, build real services via `pikkuServices`/`pikkuWireServices` and bootstrap a server:
-
-```typescript
-// services.ts — real service setup for tests
-import { pikkuServices, pikkuWireServices } from '#pikku'
-import { LocalSecretService, LocalVariablesService } from '@pikku/core/services'
-
-export const createSingletonServices = pikkuServices(async (config) => {
-  const variables = new LocalVariablesService()
-  const secrets = new LocalSecretService(variables)
-  return { config, variables, secrets, logger: new ConsoleLogger() }
-})
-export const createWireServices = pikkuWireServices(async () => ({}))
-```
-
-```typescript
-// start.ts — bootstrap server for tests
-import './.pikku/pikku-bootstrap.gen.js'
-import { createSingletonServices, createWireServices } from './services.js'
-
-const config = {}
-const singletonServices = await createSingletonServices(config)
-const server = new PikkuFastifyServer(config, singletonServices, createWireServices)
-await server.init()
-await server.start()
-```
-
-## Common Patterns
-
-- **Mock logger / singleton services** — see the reusable bag defined under "Test Runner Setup".
-- **Reset state between tests** — always `resetPikkuState()` in `beforeEach` to isolate tests.
-
-```typescript
-import { resetPikkuState } from '@pikku/core'
-beforeEach(() => resetPikkuState())
-```
-
-- **Async error assertions**:
-
-```typescript
-await assert.rejects(
-  async () => await myFunc.func(services, { id: 'nonexistent' }),
-  { message: 'Not found' }
-)
-```
-
-## Complete Example
-
-```typescript
-// functions/todos.functions.ts
-export const createTodo = pikkuSessionlessFunc({
-  description: 'Create a todo',
-  input: z.object({ title: z.string().min(1) }),
-  output: z.object({ id: z.string(), title: z.string() }),
-  func: async ({ todoStore }, { title }) => todoStore.add(title),
-})
-
-// functions/todos.test.ts
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert'
-
-class MockTodoStore {
-  private todos: any[] = []
-  async add(title: string) {
-    const todo = { id: String(this.todos.length + 1), title, completed: false }
-    this.todos.push(todo)
-    return todo
-  }
-  async list() { return this.todos }
-}
-
-describe('createTodo', () => {
-  let todoStore: MockTodoStore
-  beforeEach(() => { todoStore = new MockTodoStore() })
-
-  test('creates a todo with the given title', async () => {
-    const result = await createTodo.func({ todoStore } as any, { title: 'Buy milk' })
-    assert.equal(result.id, '1')
-    assert.equal(result.title, 'Buy milk')
-  })
-
-  test('increments IDs', async () => {
-    await createTodo.func({ todoStore } as any, { title: 'First' })
-    const second = await createTodo.func({ todoStore } as any, { title: 'Second' })
-    assert.equal(second.id, '2')
-  })
-})
-```

package/skills/pikku-testing/references/cucumber-bdd-testing.md

@@ -1,176 +0,0 @@
-# Cucumber / BDD Testing with `@pikku/cucumber`
-
-## 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>` — a typed map that throws a clear error when a name is missing.
-
-### Personas
-
-A **persona** is a named user: login credentials plus the session held 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 per 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.
-
-## Anti-Patterns
-
-### Inline data in feature files
-
-Raw values/JSON in `.feature` files make scenarios brittle and unreadable. Use named references resolved by step definitions instead.
-
-```gherkin
-# Wrong
-When I call 'kanban:createCard' with {"title": "My card", "columnId": "backlog"}
-Then the result title is "My card"
-
-# Right
-When 'yasser' creates a card for '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. Name step files after the domain they cover — a login step belongs in `auth.steps.ts` regardless of which feature needs it.
-
-```
-Wrong:                          Right:
-steps/                          steps/
-  edit_work_experience.ts         auth.steps.ts
-  edit_languages.ts               profile.steps.ts
-  edit_education.ts               card.steps.ts
-```
-
-### Conjunction steps
-
-Don't combine multiple actions into a single step — it makes reuse impossible. Use `And` / `But`: each step does exactly one thing.
-
-```gherkin
-# Wrong — two actions in one step
-Given 'yasser' is logged in and has created a card
-
-# Right — atomic, composable
-Given 'yasser' logs in
-And 'yasser' creates a card for 'writing a blog post'
-```
-
-### 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/test inputs embedded in step code can't be reused and break when data changes — look them up from `PersonaData`.
-
-```ts
-// Wrong
-Given('{string} logs in', async function (name: string) {
-  await this.call(name, 'auth:login', { email: 'yasser@example.com', password: 'hunter2' })
-})
-
-// Right
-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 }))
-})
-```