@pikku/cli 0.12.25 → 0.12.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.25",
+  "version": "0.12.26",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -26,10 +26,10 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.24",
+    "@pikku/core": "^0.12.25",
     "@pikku/deploy-cloudflare": "^0.12.3",
     "@pikku/fetch": "^0.12.2",
-    "@pikku/inspector": "^0.12.12",
+    "@pikku/inspector": "^0.12.13",
     "@pikku/kysely": "^0.12.12",
     "@pikku/kysely-node-sqlite": "^0.12.1",
     "@pikku/node-http-server": "^0.12.1",
@@ -44,6 +44,7 @@
     "open": "^10.2.0",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
+    "pg": "^8.13.0",
     "tinyglobby": "^0.2.12",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",
@@ -55,6 +56,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.11.0",
+    "@types/pg": "^8.11.0",
     "@types/ws": "^8"
   },
   "files": [

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

package/dist/src/functions/db/sql-migrator.d.ts

@@ -1,26 +0,0 @@
-import type { SyncSqliteDatabase } from './sqlite-runtime.js';
-export declare class MigrationDriftError extends Error {
-    readonly file: string;
-    readonly recordedHash: string;
-    readonly currentHash: string | null;
-    readonly appliedAt: string;
-    constructor(file: string, recordedHash: string, currentHash: string | null, appliedAt: string);
-}
-export interface MigrateResult {
-    applied: string[];
-    skipped: string[];
-}
-/**
- * Apply pending migrations from <migrationsDir>/*.sql against the open db.
- * Hashes raw bytes on apply; subsequent runs re-hash and bail with
- * MigrationDriftError if any applied file has changed on disk.
- *
- * The same bytes that get hashed are the bytes passed to db.exec — no
- * splitting, trimming, or normalization. See docs/dev-builtin-sqlite.md.
- */
-export declare function migrate(db: SyncSqliteDatabase, migrationsDir: string): MigrateResult;
-/**
- * Wipe the tracking table. Used by `pikku db reset` after the DB file is
- * removed (calling this on its own does NOT drop user tables).
- */
-export declare function dropTrackingTable(db: SyncSqliteDatabase): void;

package/dist/src/functions/db/sql-migrator.js

@@ -1,104 +0,0 @@
-import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-const TRACKING_TABLE = 'sql_migrations';
-export class MigrationDriftError extends Error {
-    file;
-    recordedHash;
-    currentHash;
-    appliedAt;
-    constructor(file, recordedHash, currentHash, appliedAt) {
-        const onDisk = currentHash === null
-            ? 'file missing on disk'
-            : `sha256:${currentHash.slice(0, 8)}…`;
-        super(`[PKU-DB-DRIFT] db/migrations/${file}\n\n` +
-            `Migration content has changed since it was applied.\n` +
-            `  recorded:  sha256:${recordedHash.slice(0, 8)}…  applied ${appliedAt}\n` +
-            `  on disk:   ${onDisk}\n\n` +
-            `If this edit was intentional, run \`pikku db reset\` to rebuild the dev\n` +
-            `database from scratch. Production migrations are immutable.`);
-        this.file = file;
-        this.recordedHash = recordedHash;
-        this.currentHash = currentHash;
-        this.appliedAt = appliedAt;
-        this.name = 'MigrationDriftError';
-    }
-}
-function sha256(bytes) {
-    return createHash('sha256').update(bytes).digest('hex');
-}
-function ensureTrackingTable(db) {
-    db.exec(`CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
-       name       TEXT PRIMARY KEY,
-       hash       TEXT NOT NULL,
-       applied_at TEXT NOT NULL DEFAULT (datetime('now'))
-     )`);
-}
-function listMigrationFiles(migrationsDir) {
-    return readdirSync(migrationsDir)
-        .filter((f) => f.endsWith('.sql'))
-        .sort();
-}
-function readApplied(db) {
-    return db
-        .prepare(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`)
-        .all();
-}
-function checkDrift(applied, migrationsDir) {
-    for (const row of applied) {
-        let currentHash = null;
-        try {
-            currentHash = sha256(readFileSync(join(migrationsDir, row.name)));
-        }
-        catch {
-            currentHash = null;
-        }
-        if (currentHash !== row.hash) {
-            throw new MigrationDriftError(row.name, row.hash, currentHash, row.applied_at);
-        }
-    }
-}
-/**
- * Apply pending migrations from <migrationsDir>/*.sql against the open db.
- * Hashes raw bytes on apply; subsequent runs re-hash and bail with
- * MigrationDriftError if any applied file has changed on disk.
- *
- * The same bytes that get hashed are the bytes passed to db.exec — no
- * splitting, trimming, or normalization. See docs/dev-builtin-sqlite.md.
- */
-export function migrate(db, migrationsDir) {
-    ensureTrackingTable(db);
-    const applied = readApplied(db);
-    checkDrift(applied, migrationsDir);
-    const appliedSet = new Set(applied.map((r) => r.name));
-    const files = listMigrationFiles(migrationsDir);
-    const result = { applied: [], skipped: [] };
-    const insertStmt = db.prepare(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES (?, ?)`);
-    for (const name of files) {
-        if (appliedSet.has(name)) {
-            result.skipped.push(name);
-            continue;
-        }
-        const raw = readFileSync(join(migrationsDir, name));
-        const hash = sha256(raw);
-        db.exec('BEGIN');
-        try {
-            db.exec(raw.toString('utf8'));
-            insertStmt.run(name, hash);
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            db.exec('ROLLBACK');
-            throw err;
-        }
-        result.applied.push(name);
-    }
-    return result;
-}
-/**
- * Wipe the tracking table. Used by `pikku db reset` after the DB file is
- * removed (calling this on its own does NOT drop user tables).
- */
-export function dropTrackingTable(db) {
-    db.exec(`DROP TABLE IF EXISTS ${TRACKING_TABLE}`);
-}

package/dist/src/functions/db/sqlite-codegen.d.ts

@@ -1,45 +0,0 @@
-import type { ColumnKind } from './coercion-plugin.js';
-import type { SyncSqliteDatabase } from './sqlite-runtime.js';
-/** Internal annotation: column kind plus an optional TS type string (for @json). */
-interface ColAnnotation {
-    kind: ColumnKind;
-    /** TypeScript type string, e.g. `string[]` or `Record<string, number>`. Only set for @json. */
-    tsType?: string;
-}
-/** Internal annotation map used during codegen. */
-type AnnotationMap = Record<string, Record<string, ColAnnotation>>;
-/**
- * Parse `-- @bool | @date | @json [TypescriptType]` inline annotations from
- * migration SQL files. The TypeScript type is optional and only meaningful for
- * `@json` — it controls the generated TypeScript type (e.g. `string[]`,
- * `Record<string, number>`).
- *
- * Returns an AnnotationMap: { table_name: { col_name: ColAnnotation } }.
- */
-export declare function parseAnnotations(migrationsDir: string): AnnotationMap;
-export interface CodegenOptions {
-    outFile: string;
-    coercionFile: string;
-    camelCase?: boolean;
-    migrationsDir?: string;
-}
-export interface CodegenResult {
-    outFile: string;
-    coercionFile: string;
-    written: boolean;
-    coercionWritten: boolean;
-    tables: string[];
-}
-/**
- * Introspect the open SQLite database and emit a Kysely DB type to outFile
- * plus a CoercionMap to coercionFile.
- *
- * Columns are annotated via:
- *   1. Naming conventions (_at/_on → date; is_/has_/can_ → bool)
- *   2. Inline SQL comments: `col_name TYPE ... -- @bool|@date|@json [TsType]`
- *      For @json, an optional TypeScript type string controls the generated type.
- *
- * Returns `written: false` if the on-disk file already matches.
- */
-export declare function generateSchemaTypes(db: SyncSqliteDatabase, options: CodegenOptions): CodegenResult;
-export {};