@pikku/cli 0.12.96 → 0.12.99

package/dist/src/functions/validate/persona-checks.js

@@ -0,0 +1,136 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const lines = (...parts) => parts.join('\n');
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((v) => typeof v === 'string')
+    : [];
+/**
+ * Source files under one directory, flat list, generated files included.
+ *
+ * A persona declaration is `definePersonas({ … })` written by hand, but the
+ * actor plugin is routinely wired in a file the auth scaffold generated, so
+ * `.gen.ts` cannot be skipped the way the undeclared-import walk skips it.
+ */
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+const readTextSafe = async (path) => {
+    if (!existsSync(path))
+        return null;
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Where the persona meta lands when the project has not overridden it, mirroring
+ * the default `pikku-cli-config` resolves — validate reads the raw config file
+ * rather than the resolved one, so the default has to be repeated here.
+ */
+const personaMetaPath = (root, config) => {
+    if (typeof config.personasMetaJsonFile === 'string') {
+        return join(root, config.personasMetaJsonFile);
+    }
+    const outDir = typeof config.outDir === 'string' ? config.outDir : '.pikku';
+    return join(root, outDir, 'scopes', 'pikku-personas-meta.gen.json');
+};
+/**
+ * Whether this project declares anyone to run as.
+ *
+ * Two sources, because either one alone is wrong at a predictable moment: the
+ * generated meta is empty on a checkout where codegen has not run yet, and a
+ * source scan cannot see personas a dependency contributed. Declared by either
+ * counts as declared — a validator that cries about a missing persona on a
+ * fresh clone gets muted, and then it never says anything worth hearing.
+ */
+const countPersonas = async (root, config, sourceFiles) => {
+    const metaText = await readTextSafe(personaMetaPath(root, config));
+    if (metaText) {
+        try {
+            const meta = JSON.parse(metaText);
+            const declared = Object.keys(meta).length;
+            if (declared > 0)
+                return declared;
+        }
+        catch {
+            // A corrupt meta file is the scan's problem to answer, not a reason to
+            // claim there are no personas.
+        }
+    }
+    for (const file of sourceFiles) {
+        const text = await readTextSafe(file);
+        if (text && /\bdefinePersonas\s*\(/.test(text))
+            return 1;
+    }
+    return 0;
+};
+/**
+ * Whether a persona can actually sign in.
+ *
+ * Two shapes count. `actor()` from `@pikku/better-auth` is the one the scaffold
+ * wires, and a hand-rolled `/sign-in/actor` route is the one a project that does
+ * not use better-auth ends up with. Both terminate at the same endpoint, so
+ * either satisfies the check.
+ */
+const hasActorSignIn = async (sourceFiles) => {
+    for (const file of sourceFiles) {
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const wiresPlugin = /@pikku\/better-auth/.test(text) && /\bactor\s*\(/.test(text);
+        if (wiresPlugin || /sign-in\/actor/.test(text))
+            return true;
+    }
+    return false;
+};
+/**
+ * The people this project can run as, and whether it can run as them.
+ *
+ * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * validators are separate implementations, and a check that only one of them
+ * makes is a check half the projects never see.
+ *
+ * knowledge: decisions/internals/validate-checks-personas-through-a-shared-module.md
+ */
+export const runPersonaChecks = async (root, config) => {
+    const findings = [];
+    const w = (id, message, path, fixHint) => {
+        findings.push({ id, severity: 'warn', message, path, fixHint });
+    };
+    const srcDirectories = stringArray(config?.srcDirectories);
+    const searchDirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const sourceFiles = (await Promise.all(searchDirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    const personas = await countPersonas(root, config ?? {}, sourceFiles);
+    const pikkuConfigPath = join(root, 'pikku.config.json');
+    if (personas === 0) {
+        w('no-personas', 'No personas are declared — `pikku scenario run` and `pikku persona run` have nobody to run as, so nothing exercises this app the way a user would', pikkuConfigPath, lines('Declare the people who use this app with definePersonas(), e.g. in', 'packages/functions/src/scenarios/personas.virtual-user.ts:', "  import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'", '  definePersonas({', "    founder: { name: 'Anna Müller', jobTitle: 'Managing director' },", '  })', 'Their email addresses are computed from the key and scenarios.emailDomain.'));
+        return findings;
+    }
+    if (!(await hasActorSignIn(sourceFiles))) {
+        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', 'The plugin refuses every sign-in while the secret is unset, so a stage', 'that must not run scenarios simply leaves SCENARIO_ACTOR_SECRET out.'));
+    }
+    const environments = config?.environments;
+    const hasEnvironment = typeof environments === 'object' &&
+        environments !== null &&
+        Object.keys(environments).length > 0;
+    if (!hasEnvironment) {
+        w('personas-no-environments', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but pikku.config.json configures no environments — \`pikku scenario run <environment>\` has no target to resolve and refuses every name`, pikkuConfigPath, lines('Add the targets a run may point at:', '  "environments": {', '    "local": { "apiUrl": "http://localhost:4002", "appUrl": "http://localhost:3000" }', '  }'));
+    }
+    return findings;
+};

package/dist/src/functions/validate/scenario-file-checks.d.ts

@@ -0,0 +1,17 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * Scenarios, features and steps live in files named for what they are.
+ *
+ * A `pikkuScenario` declared next to the functions it exercises reads as more
+ * of the same file — the wiring, the function and the test of the function all
+ * in one scroll — and the scenario is the part that gets lost. Keeping them in
+ * `*.scenario.ts` / `*.scenarios.ts` / `*.steps.ts` means a file's name tells
+ * you whether it ships or whether it tests, before you open it.
+ *
+ * An error rather than a warning: the mixing is only cheap to undo while it is
+ * one file, and every project that let it slide ended up with scenarios spread
+ * across dozens.
+ *
+ * knowledge: decisions/internals/scenarios-live-in-files-named-for-them.md
+ */
+export declare const runScenarioFileChecks: (root: string, srcDirectories: string[]) => Promise<ValidateFinding[]>;

package/dist/src/functions/validate/scenario-file-checks.js

@@ -0,0 +1,123 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readTextSafe } from './shared-checks.js';
+/**
+ * The declarations that must live in a dedicated scenario file.
+ *
+ * Matched on the call, not the import, so a re-export or an aliased import does
+ * not slip past — and a file that only mentions the name in a comment or a
+ * string does not get flagged.
+ */
+const SCENARIO_DECLARATIONS = [
+    'pikkuScenario',
+    'pikkuFeature',
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+];
+/**
+ * A file allowed to declare them.
+ *
+ * Three suffixes rather than one because the split that matters is scenarios
+ * apart from application code, not a particular spelling: `.scenario.ts` and
+ * `.scenarios.ts` hold the scenarios, `.steps.ts` holds the steps they call.
+ */
+const SCENARIO_FILE = /\.(scenario|scenarios|steps)\.tsx?$/;
+/**
+ * The declarations that make up a virtual user, and where they live.
+ *
+ * There is no `defineVirtualUsers` to look for — that name was retired in
+ * favour of `definePersonas`, because a virtual user is derived rather than
+ * authored: the function meta becomes its catalogue, the scenario meta becomes
+ * its intents, and the declared personas become its identities. So the thing a
+ * project actually writes is the persona list, and that is what has to be
+ * findable by filename.
+ */
+const VIRTUAL_USER_DECLARATIONS = ['definePersonas', 'runVirtualUser'];
+const VIRTUAL_USER_FILE = /\.(virtual-user|vu)\.tsx?$/;
+const isGenerated = (path) => path.includes('.gen.') || path.includes(`${'/'}.pikku${'/'}`);
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Scenarios, features and steps live in files named for what they are.
+ *
+ * A `pikkuScenario` declared next to the functions it exercises reads as more
+ * of the same file — the wiring, the function and the test of the function all
+ * in one scroll — and the scenario is the part that gets lost. Keeping them in
+ * `*.scenario.ts` / `*.scenarios.ts` / `*.steps.ts` means a file's name tells
+ * you whether it ships or whether it tests, before you open it.
+ *
+ * An error rather than a warning: the mixing is only cheap to undo while it is
+ * one file, and every project that let it slide ended up with scenarios spread
+ * across dozens.
+ *
+ * knowledge: decisions/internals/scenarios-live-in-files-named-for-them.md
+ */
+export const runScenarioFileChecks = async (root, srcDirectories) => {
+    const findings = [];
+    const dirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const files = (await Promise.all(dirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    for (const file of files) {
+        if (SCENARIO_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = SCENARIO_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        const suggested = rel.replace(/\.tsx?$/, (ext) => `.scenarios${ext}`);
+        findings.push({
+            id: 'scenario-declared-outside-scenario-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — scenarios, features and steps must live in a *.scenario.ts, *.scenarios.ts or *.steps.ts file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                `Move the ${used.length === 1 ? 'declaration' : 'declarations'} into a dedicated file, e.g.:`,
+                `  ${suggested}`,
+                'Steps belong in *.steps.ts; the scenarios that call them in *.scenarios.ts.',
+                'Keeping them apart is what lets a file name say whether it ships or tests.',
+            ].join('\n'),
+        });
+    }
+    for (const file of files) {
+        if (VIRTUAL_USER_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = VIRTUAL_USER_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        findings.push({
+            id: 'virtual-user-declared-outside-virtual-user-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — the personas a virtual user plays must live in a *.virtual-user.ts (or *.vu.ts) file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                'Move the declaration into a dedicated file, e.g.:',
+                `  ${rel.replace(/[^/\\]+$/, 'personas.virtual-user.ts')}`,
+                'A virtual user is derived from what the project already generates —',
+                'the personas are the only part it authors, so they get their own file.',
+            ].join('\n'),
+        });
+    }
+    return findings;
+};

package/dist/src/functions/validate/shared-checks.d.ts

@@ -0,0 +1,59 @@
+import { type ValidateFinding } from './persona-checks.js';
+export type Finding = ValidateFinding;
+export type SharedPikkuConfig = {
+    srcDirectories?: unknown;
+    outDir?: unknown;
+    environments?: unknown;
+    clientFiles?: unknown;
+    scaffold?: {
+        console?: unknown;
+        rpc?: unknown;
+        agent?: unknown;
+        workflow?: unknown;
+        events?: unknown;
+        remoteRpc?: unknown;
+    };
+    db?: {
+        engine?: 'sqlite' | 'postgres';
+    };
+    lint?: {
+        customServerBootstrap?: 'off' | 'warn' | 'error';
+    };
+};
+export type SharedFnPkg = {
+    type?: string;
+    imports?: Record<string, unknown>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+};
+export type SharedCheckResult = {
+    findings: Finding[];
+    /** Read once here and handed back, so a caller never parses these twice. */
+    pikkuConfig: SharedPikkuConfig | null;
+    fnPkg: SharedFnPkg | null;
+    fnDir: string;
+    dbEngine: 'sqlite' | 'postgres';
+    migrationsDir: string;
+};
+/**
+ * A malformed config is named, never reported as absent.
+ *
+ * `pikku fabric validate` used to swallow the parse error and report
+ * `pikku-config-missing` for a file that is right there — the one message
+ * guaranteed to send you looking in the wrong place.
+ */
+export declare function readJsonSafe<T>(path: string): Promise<T | null>;
+export declare function readTextSafe(path: string): Promise<string | null>;
+/**
+ * Every check that is true of any pikku project, regardless of where it deploys.
+ *
+ * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
+ * .gitignore contract). Before this module the two were separate walks over the
+ * same project that duplicated sixteen findings verbatim, and each carried
+ * checks the other lacked for no reason anyone could name.
+ *
+ * knowledge: decisions/internals/one-project-shape-check-two-validators.md
+ */
+export declare function runSharedProjectChecks(root: string): Promise<SharedCheckResult>;

package/dist/src/functions/validate/shared-checks.js

@@ -0,0 +1,311 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runKnowledgeValidate } from '@pikku/knowledge';
+import { runBootstrapChecks } from './bootstrap-checks.js';
+import { runPersonaChecks } from './persona-checks.js';
+import { runScenarioFileChecks } from './scenario-file-checks.js';
+/**
+ * A malformed config is named, never reported as absent.
+ *
+ * `pikku fabric validate` used to swallow the parse error and report
+ * `pikku-config-missing` for a file that is right there — the one message
+ * guaranteed to send you looking in the wrong place.
+ */
+export async function readJsonSafe(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in ${path}: ${message}`);
+    }
+}
+export async function readTextSafe(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether this app authenticates HTTP requests at all.
+ *
+ * Matches any `betterAuth*Session` definition rather than the literal
+ * `betterAuthSession`. The stateless variant is a separate definition id that
+ * the CLI wires whenever `session.cookieCache` is enabled, which is the
+ * configuration Fabric asks for — so an exact-match check saw no auth on
+ * precisely the apps most likely to have it, and silently skipped every auth
+ * schema check below.
+ */
+async function hasAuthSessionMiddleware(fnDir) {
+    const meta = await readJsonSafe(join(fnDir, '.pikku', 'middleware', 'pikku-middleware-groups-meta.gen.json'));
+    if (!meta?.instances)
+        return false;
+    return Object.values(meta.instances).some((instance) => /^betterAuth\w*Session$/.test(instance.definitionId ?? ''));
+}
+function migrationCreatesTable(sql, tableName) {
+    const escapedTable = tableName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+    const re = new RegExp(`\\bcreate\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?["'\`]?${escapedTable}["'\`]?\\b`, 'i');
+    return re.test(sql);
+}
+/** better-auth's core schema — the tables its adapter queries on every request. */
+const BETTER_AUTH_TABLES = ['user', 'session', 'account', 'verification'];
+/**
+ * Scaffold flags that gate a generated surface the pikku console calls.
+ *
+ * `console` gates app introspection, so nothing renders without it;
+ * `rpc`/`agent`/`workflow` gate endpoints the console hits directly; `events`
+ * gates the realtime channel, which no template ships yet — hence the warning.
+ */
+const REQUIRED_SCAFFOLD = [
+    {
+        key: 'console',
+        severity: 'error',
+        surface: 'app introspection (console:getFunctionsMeta and friends) — the console shows no functions',
+    },
+    { key: 'rpc', severity: 'error', surface: 'the generic /rpc/:name endpoint' },
+    {
+        key: 'agent',
+        severity: 'error',
+        surface: 'the agent endpoints (/rpc/agent/:agentName) — the agent playground 404s',
+    },
+    {
+        key: 'workflow',
+        severity: 'error',
+        surface: 'the workflow endpoints (/workflow/:workflowName/start) — triggering a workflow 404s',
+    },
+    { key: 'events', severity: 'warn', surface: 'the realtime events channel' },
+];
+/**
+ * Every check that is true of any pikku project, regardless of where it deploys.
+ *
+ * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
+ * .gitignore contract). Before this module the two were separate walks over the
+ * same project that duplicated sixteen findings verbatim, and each carried
+ * checks the other lacked for no reason anyone could name.
+ *
+ * knowledge: decisions/internals/one-project-shape-check-two-validators.md
+ */
+export async function runSharedProjectChecks(root) {
+    const findings = [];
+    const lines = (...parts) => parts.join('\n');
+    const e = (id, message, path, fixHint) => {
+        findings.push({ id, severity: 'error', message, path, fixHint });
+    };
+    const w = (id, message, path, fixHint) => {
+        findings.push({ id, severity: 'warn', message, path, fixHint });
+    };
+    const info = (id, message, path, fixHint) => {
+        findings.push({ id, severity: 'info', message, path, fixHint });
+    };
+    // ── pikku.config.json ──────────────────────────────────────────────────
+    const pikkuConfigPath = join(root, 'pikku.config.json');
+    const pikkuConfig = await readJsonSafe(pikkuConfigPath);
+    if (!pikkuConfig) {
+        e('pikku-config-missing', 'pikku.config.json not found at project root', pikkuConfigPath, lines('Create `pikku.config.json` at the repo root.', 'Minimum useful shape:', '{', '  "srcDirectories": ["packages/functions/src"],', '  "outDir": "packages/functions/.pikku",', '  "clientFiles": {', '    "rpcMapDeclarationFile": "packages/functions-sdk/src/pikku/rpc-map.gen.d.ts",', '    "reactQueryFile": "packages/functions-sdk/src/pikku/api.gen.ts"', '  }', '}'));
+    }
+    else {
+        if (!pikkuConfig.srcDirectories) {
+            e('pikku-config-no-src-dirs', 'pikku.config.json missing "srcDirectories"', pikkuConfigPath, 'Add "srcDirectories": ["packages/functions/src"] to pikku.config.json');
+        }
+        if (!pikkuConfig.outDir) {
+            e('pikku-config-no-out-dir', 'pikku.config.json missing "outDir"', pikkuConfigPath, 'Add "outDir": "packages/functions/.pikku" to pikku.config.json');
+        }
+        if (!pikkuConfig.clientFiles) {
+            info('pikku-config-no-client-files', 'pikku.config.json missing "clientFiles" — generated RPC client files and React Query hooks will not be written', pikkuConfigPath, lines('Add a `clientFiles` block to `pikku.config.json`.', 'Recommended values:', '"clientFiles": {', '  "rpcMapDeclarationFile": "packages/functions-sdk/src/pikku/rpc-map.gen.d.ts",', '  "reactQueryFile": "packages/functions-sdk/src/pikku/api.gen.ts"', '}', 'Those files should live in `packages/functions-sdk/src/pikku/` and are generated by Pikku.'));
+        }
+        for (const s of REQUIRED_SCAFFOLD) {
+            if (pikkuConfig.scaffold?.[s.key])
+                continue;
+            const report = s.severity === 'error' ? e : w;
+            report(`pikku-config-no-scaffold-${s.key}`, `pikku.config.json scaffold is missing "${s.key}" — ${s.surface} is never generated, so the console 404s for it`, pikkuConfigPath, lines(`Add "${s.key}" to the scaffold block in pikku.config.json:`, '"scaffold": {', '  "pikkuDir": "packages/functions/src/scaffold",', `  "${s.key}": true`, '}', 'true means enabled and authenticated; write { "auth": false } to go public.', 'Then re-run codegen (`pikku all`) and restart the dev server.'));
+        }
+    }
+    const dbEngine = pikkuConfig?.db?.engine ?? 'sqlite';
+    const rootPkgPath = join(root, 'package.json');
+    const rootPkg = await readJsonSafe(rootPkgPath);
+    if (!rootPkg) {
+        e('root-package-missing', 'root package.json not found', rootPkgPath, 'Create a root package.json with workspaces: {"workspaces": ["packages/*", "apps/*"]}');
+    }
+    else {
+        if (!rootPkg.workspaces) {
+            w('root-package-no-workspaces', 'root package.json missing "workspaces"', rootPkgPath, 'Add "workspaces": ["packages/*", "apps/*"] to enable yarn workspaces');
+        }
+        const allDeps = { ...rootPkg.dependencies, ...rootPkg.devDependencies };
+        if (!allDeps['@pikku/core']) {
+            e('missing-core', '@pikku/core not in dependencies', rootPkgPath, 'Add "@pikku/core" to dependencies');
+        }
+        // Vendor tgz presence — only file: deps that reference a vendor/ path.
+        for (const [pkg, spec] of Object.entries(allDeps)) {
+            if (typeof spec !== 'string' || !spec.startsWith('file:'))
+                continue;
+            const relPath = spec.slice(5);
+            if (!relPath.includes('vendor'))
+                continue;
+            const absPath = join(root, relPath);
+            if (!existsSync(absPath)) {
+                w(`vendor-missing-${pkg.replace(/[@/]/g, '-')}`, `Vendor file missing for ${pkg}: ${relPath}`, absPath, `Run \`pikku pack\` in the pikku source repo and copy the output to ${relPath}`);
+            }
+        }
+    }
+    // ── packages/functions/ ────────────────────────────────────────────────
+    const fnDir = join(root, 'packages', 'functions');
+    const fnPkgPath = join(fnDir, 'package.json');
+    let fnPkg = null;
+    // Migrations live at the repo root, which is where `pikku db migrate` reads
+    // them from (see local-db.ts). Workspace validate used to look inside
+    // packages/functions/db, so every auth schema check it made ran against a
+    // directory that does not exist in any project the CLI can migrate.
+    const migrationsDir = join(root, 'db', dbEngine);
+    if (!existsSync(fnDir)) {
+        e('functions-pkg-missing', 'packages/functions/ directory not found', fnDir, 'Create packages/functions/ as a workspace containing src/, tests/, config.ts, and any local db assets you use');
+    }
+    else {
+        fnPkg = await readJsonSafe(fnPkgPath);
+        if (!fnPkg) {
+            e('functions-package-json-missing', 'packages/functions/package.json not found', fnPkgPath, 'Create packages/functions/package.json and declare the workspace package');
+        }
+        else {
+            if (fnPkg.type !== 'module') {
+                w('functions-pkg-no-esm', 'packages/functions/package.json is missing "type": "module"', fnPkgPath, 'Add "type": "module" to packages/functions/package.json');
+            }
+            // zod v4 must be installed in the functions package: pikku's generated
+            // schemas and the auth scaffold (auth-secrets.gen.ts) both `import { z }
+            // from 'zod'`, so a missing/old zod fails codegen (PKU489) or type-checks.
+            const fnDeps = { ...fnPkg.dependencies, ...fnPkg.devDependencies };
+            const zodRange = fnDeps.zod;
+            const zodMajor = zodRange?.match(/(\d+)/)?.[1];
+            if (!zodRange) {
+                e('functions-missing-zod', 'packages/functions/package.json does not declare "zod" — pikku schemas and the generated auth scaffold import it', fnPkgPath, 'Add "zod": "^4" to packages/functions dependencies');
+            }
+            else if (zodMajor !== '4') {
+                e('functions-zod-not-v4', `packages/functions requires zod v4 but found "${zodRange}"`, fnPkgPath, 'Set "zod": "^4" in packages/functions dependencies');
+            }
+            // @pikku/playwright earns its keep by declaration merging: it is what
+            // puts `page`, `context` and `locate` on a step's `PikkuBrowserWire`. A
+            // merge only applies if the compiler loads the module, and a tsconfig
+            // with an explicit `types` array loads nothing it is not told to. A step
+            // that reaches for `wire.page` without importing the package anywhere in
+            // the program then fails to type-check with a message about a property
+            // that does not exist — which reads like the step is wrong, not the
+            // tsconfig. Listing the package in `types` loads it either way.
+            if (fnDeps['@pikku/playwright']) {
+                const tsconfigPath = join(fnDir, 'tsconfig.json');
+                const tsconfig = await readJsonSafe(tsconfigPath);
+                const types = tsconfig?.compilerOptions?.types;
+                if (types && !types.includes('@pikku/playwright')) {
+                    w('playwright-types-not-loaded', 'packages/functions depends on @pikku/playwright but does not list it in "compilerOptions.types" — the browser bindings it adds to a step (page, context, locate) will not be typed', tsconfigPath, lines('Add it to the types array in packages/functions/tsconfig.json:', `  "types": ${JSON.stringify([...types, '@pikku/playwright'])}`, 'The package declaration-merges PikkuBrowserWire, and an explicit', '`types` array means the compiler only loads what it is told to.'));
+                }
+            }
+        }
+        const servicesPath = join(fnDir, 'src', 'services.ts');
+        if (!(await readTextSafe(servicesPath))) {
+            w('services-missing', 'packages/functions/src/services.ts not found', servicesPath, 'Create services.ts and export your service factory for the workspace');
+        }
+        // ── auth schema ──────────────────────────────────────────────────────
+        // The tables are better-auth's own (`user`, `session`, `account`,
+        // `verification`) because those are what the adapter queries. This check
+        // used to look for `app_user` and `auth_verification_token`, two names that
+        // appear nowhere else in pikku or in any template — it never fired against a
+        // real app, and would have been wrong for every one of them if it had.
+        const authEnabled = await hasAuthSessionMiddleware(fnDir);
+        const configText = await readTextSafe(join(fnDir, 'src', 'config.ts'));
+        const missingAuthTables = [];
+        if (existsSync(migrationsDir)) {
+            try {
+                const files = (await readdir(migrationsDir))
+                    .filter((f) => f.endsWith('.sql'))
+                    .sort();
+                const nums = [];
+                for (const f of files) {
+                    const m = f.match(/^(\d+)/);
+                    if (m)
+                        nums.push(parseInt(m[1], 10));
+                }
+                for (let idx = 1; idx < nums.length; idx++) {
+                    if (nums[idx] !== nums[idx - 1] + 1) {
+                        const missing = `${nums[idx - 1] + 1}..${nums[idx] - 1}`;
+                        e('migration-gap', `Migration numbering gap: IDs ${missing} are missing`, migrationsDir, 'Migrations must be consecutive. Add the missing .sql file or renumber if not yet applied.');
+                        break;
+                    }
+                }
+                if (authEnabled) {
+                    const allSql = (await Promise.all(files.map((f) => readTextSafe(join(migrationsDir, f)))))
+                        .filter((sql) => Boolean(sql))
+                        .join('\n');
+                    for (const table of BETTER_AUTH_TABLES) {
+                        if (!migrationCreatesTable(allSql, table)) {
+                            missingAuthTables.push(table);
+                        }
+                    }
+                }
+            }
+            catch {
+                // readdir failure — skip
+            }
+        }
+        else if (authEnabled) {
+            missingAuthTables.push(...BETTER_AUTH_TABLES);
+        }
+        // `pikku db migrate` falls back to .pikku-runtime/dev.db whenever db/sqlite
+        // exists (see db-shared.ts), so sqliteDb in createConfig is only required
+        // when the project has no conventional db assets at all. Demanding it
+        // unconditionally failed every project using the layout the CLI expects.
+        const hasConventionalDbAssets = existsSync(join(root, 'db', 'sqlite')) ||
+            existsSync(join(root, 'db', 'postgres'));
+        if (authEnabled &&
+            dbEngine !== 'postgres' &&
+            !/sqliteDb/.test(configText ?? '') &&
+            !hasConventionalDbAssets) {
+            e('auth-dev-db-missing', 'Auth middleware is registered, but there is no db/sqlite directory and createConfig does not set sqliteDb — `pikku db migrate` has no database to create', join(fnDir, 'src', 'config.ts'), 'Add db/sqlite/ with numbered migrations, or set sqliteDb in createConfig');
+        }
+        if (missingAuthTables.length > 0) {
+            e('auth-schema-missing-tables', `Auth middleware is registered, but no SQL migration creates: ${missingAuthTables.join(', ')} — better-auth queries these tables on every request`, migrationsDir, lines(`Add a migration under db/${dbEngine}/ that creates the better-auth core schema:`, '  user, session, account, verification', 'The pikku-better-auth skill generates one for the dialect you are on.'));
+        }
+        // ── generated types must stay generated ──────────────────────────────
+        const dbTypesPath = join(fnDir, 'src', 'types', 'db.types.ts');
+        const dbTypesText = await readTextSafe(dbTypesPath);
+        if (dbTypesText) {
+            const isReexport = dbTypesText.includes('.pikku/db/schema') ||
+                dbTypesText.includes('.pikku\\db\\schema');
+            const hasInlineTypes = /(?:^|\n)\s*(?:export\s+)?(?:interface\s+\w|type\s+\w+\s*=)/.test(dbTypesText);
+            if (hasInlineTypes && !isReexport) {
+                w('db-types-hand-edited', 'src/types/db.types.ts contains inline type definitions — it should only re-export from .pikku', dbTypesPath, "Replace the file with a single line: export type { DB } from '../../.pikku/db/schema.gen.js' then regenerate");
+            }
+        }
+        // ── layout ───────────────────────────────────────────────────────────
+        if (!existsSync(join(fnDir, 'src', 'functions'))) {
+            info('functions-dir-missing', 'packages/functions/src/functions/ not found', join(fnDir, 'src', 'functions'), 'Create src/functions/ to hold pikkuSessionlessFunc definitions (one function per file)');
+        }
+        if (!existsSync(join(fnDir, 'src', 'wirings'))) {
+            info('wirings-dir-missing', 'packages/functions/src/wirings/ not found', join(fnDir, 'src', 'wirings'), 'Create src/wirings/ for transport bindings such as *.http.ts or *.queue.ts');
+        }
+        if (!existsSync(join(fnDir, 'src', 'config.ts'))) {
+            info('config-missing', 'packages/functions/src/config.ts not found', join(fnDir, 'src', 'config.ts'), 'Create src/config.ts and export your workspace config factory');
+        }
+    }
+    const sdkDir = join(root, 'packages', 'functions-sdk');
+    if (!existsSync(sdkDir)) {
+        info('functions-sdk-missing', 'packages/functions-sdk/ not found — generated RPC client and React Query hooks will not be available', sdkDir, 'Create packages/functions-sdk/ as a workspace with src/pikku/ as the generated output root; point clientFiles.rpcMapDeclarationFile and clientFiles.reactQueryFile there');
+    }
+    // ── server bootstrap ───────────────────────────────────────────────────
+    findings.push(...(await runBootstrapChecks(root, rootPkg, pikkuConfig)));
+    // ── personas, scenario files and the knowledge base ────────────────────
+    findings.push(...(await runPersonaChecks(root, pikkuConfig)));
+    const srcDirectories = Array.isArray(pikkuConfig?.srcDirectories)
+        ? pikkuConfig.srcDirectories.filter((d) => typeof d === 'string')
+        : [];
+    findings.push(...(await runScenarioFileChecks(root, srcDirectories)));
+    const knowledge = await runKnowledgeValidate(root, join(root, typeof pikkuConfig?.outDir === 'string' ? pikkuConfig.outDir : '.pikku'));
+    for (const finding of knowledge.findings) {
+        findings.push({ ...finding, path: join(root, finding.path) });
+    }
+    return { findings, pikkuConfig, fnPkg, fnDir, dbEngine, migrationsDir };
+}