@pikku/cli 0.12.93 → 0.12.99

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 };
+}

package/dist/src/functions/validate/workspace-validate.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export declare const FindingSchema: z.ZodObject<{
     id: z.ZodString;
     severity: z.ZodEnum<{
@@ -28,7 +29,5 @@ export declare const WorkspaceValidateOutput: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function findProjectRoot(startDir: string): Promise<string>;
-export declare function readJsonSafe<T>(path: string): Promise<T | null>;
-export declare function readTextSafe(path: string): Promise<string | null>;
 export declare function runWorkspaceValidate(startDir?: string): Promise<z.infer<typeof WorkspaceValidateOutput>>;
 export declare const renderWorkspaceValidate: (_s: unknown, { ok, root, findings }: z.infer<typeof WorkspaceValidateOutput>) => void;

package/dist/src/functions/validate/workspace-validate.js

@@ -1,8 +1,10 @@
 import { existsSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
+import { runSharedProjectChecks } from './shared-checks.js';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export const FindingSchema = z.object({
     id: z.string(),
     severity: z.enum(['error', 'warn', 'info']),
@@ -35,203 +37,9 @@ export async function findProjectRoot(startDir) {
         dir = parent;
     }
 }
-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;
-    }
-}
-async function hasAuthSessionMiddleware(fnDir) {
-    const metaPath = join(fnDir, '.pikku', 'middleware', 'pikku-middleware-groups-meta.gen.json');
-    const meta = await readJsonSafe(metaPath);
-    if (!meta?.instances)
-        return false;
-    return Object.values(meta.instances).some((instance) => instance.definitionId === 'betterAuthSession');
-}
-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);
-}
 export async function runWorkspaceValidate(startDir = process.cwd()) {
     const root = await findProjectRoot(startDir);
-    const findings = [];
-    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 });
-    };
-    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, 'Create pikku.config.json with srcDirectories pointing to packages/functions/src, outDir, and clientFiles');
-    }
-    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, 'Add clientFiles.rpcMapDeclarationFile and clientFiles.reactQueryFile pointing to packages/functions-sdk/src/pikku/ (for example: rpc-map.gen.d.ts and api.gen.ts)');
-        }
-        const scaffold = pikkuConfig.scaffold;
-        if (!scaffold?.console) {
-            e('pikku-config-no-console-scaffold', 'pikku.config.json missing "scaffold.console" — Fabric cannot introspect the running app (console:getFunctionsMeta and friends 404), so the sandbox builder shows no functions', pikkuConfigPath, 'Add "console": "auth" under "scaffold" in pikku.config.json — the console requires an authenticated session, so Better Auth must be set up (see the pikku-better-auth skill)');
-        }
-    }
-    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');
-        }
-        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, `Restore or replace the missing vendor package at ${relPath}`);
-            }
-        }
-    }
-    const fnDir = join(root, 'packages', 'functions');
-    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 {
-        const fnPkgPath = join(fnDir, 'package.json');
-        const 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.
-        if (fnPkg) {
-            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');
-            }
-        }
-        const servicesPath = join(fnDir, 'src', 'services.ts');
-        const servicesText = await readTextSafe(servicesPath);
-        if (!servicesText) {
-            w('services-missing', 'packages/functions/src/services.ts not found', servicesPath, 'Create services.ts and export your service factory for the workspace');
-        }
-        const authEnabled = await hasAuthSessionMiddleware(fnDir);
-        const configText = await readTextSafe(join(fnDir, 'src', 'config.ts'));
-        const hasConfiguredDevDb = /sqliteDb/.test(configText ?? '');
-        const hasPostgresUrl = /postgresUrl/.test(configText ?? '');
-        const migrationsDir = hasPostgresUrl
-            ? join(fnDir, 'db', 'postgres')
-            : join(fnDir, 'db', 'sqlite');
-        let createsAppUser = false;
-        let createsAuthVerificationToken = false;
-        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;
-                    }
-                }
-                for (const f of files) {
-                    const sql = await readTextSafe(join(migrationsDir, f));
-                    if (!sql)
-                        continue;
-                    createsAppUser ||= migrationCreatesTable(sql, 'app_user');
-                    createsAuthVerificationToken ||= migrationCreatesTable(sql, 'auth_verification_token');
-                }
-            }
-            catch {
-                // readdir failure — skip
-            }
-        }
-        if (authEnabled && !hasConfiguredDevDb) {
-            e('auth-dev-db-missing', 'Auth middleware is registered, but createConfig is missing sqliteDb so local auth schema validation and db migrate cannot run', pikkuConfigPath, 'Add sqliteDb to createConfig so `pikku db migrate` can create and validate the local auth schema');
-        }
-        if (authEnabled && !createsAppUser) {
-            e('auth-schema-missing-app-user', 'Auth middleware is registered, but no SQL migration creates the app_user table', migrationsDir, 'Add a migration that creates app_user before enabling auth');
-        }
-        if (authEnabled && !createsAuthVerificationToken) {
-            e('auth-schema-missing-verification-token', 'Auth middleware is registered, but no SQL migration creates the auth_verification_token table', migrationsDir, 'Add a migration that creates auth_verification_token before enabling auth');
-        }
-        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");
-            }
-        }
-        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');
-        }
-        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');
-    }
+    const { findings } = await runSharedProjectChecks(root);
     const ok = !findings.some((f) => f.severity === 'error');
     return { ok, root, findings };
 }

package/dist/src/functions/wirings/ai-agent/pikku-command-public-agent.js

@@ -4,11 +4,12 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializePublicAgent } from './serialize-public-agent.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuPublicAgent = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (config.scaffold?.agent && config.publicAgentSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicAgentFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializePublicAgent(pathToPikkuTypes, config.scaffold.agent === 'auth', config.globalHTTPPrefix || '');
+            const { schemas, functions } = serializePublicAgent(pathToPikkuTypes, resolveScaffoldFeature('agent', config.scaffold.agent).auth, config.globalHTTPPrefix || '');
             await writeFileInDir(logger, config.publicAgentSchemasFile, schemas);
             await writeFileInDir(logger, config.publicAgentFile, functions);
             await removeLegacyScaffoldFile(config.publicAgentFile);

package/dist/src/functions/wirings/ai-agent/serialize-public-agent.js

@@ -81,6 +81,7 @@ export const isThreadOwner = pikkuPermission<{ threadId: string }>(
 )
 
 export const agentCaller = pikkuSessionlessFunc({
+  description: 'Run a named AI agent with a message and return its reply',
   tags: ['pikku'],
   auth: ${authFlag},
   input: AgentCall,

package/dist/src/functions/wirings/auth/serialize-auth-gen.d.ts

@@ -5,14 +5,14 @@ import type { AuthDefinition } from '@pikku/inspector';
  * They are split because the CLI's schema/wiring-separation rule (PKU490)
  * forbids a file from declaring Zod schemas AND `wireHTTPRoutes` together —
  * schema files are imported at runtime, which would fire HTTP wiring
- * side-effects without a server context. `wireSecret`/`wireVariable` are NOT
+ * side-effects without a server context. `defineSecret`/`defineVariable` are NOT
  * HTTP wiring, so schemas may sit alongside them; only the route wiring must be
  * separated out.
  */
 export interface AuthGenOutput {
     /** Handler + catch-all routes (+ session middleware, unless split out). */
     wiring: string;
-    /** The secrets file: Zod schemas + wireSecret/wireVariable. */
+    /** The secrets file: Zod schemas + defineSecret/defineVariable. */
     secrets: string;
     /** Global session-middleware registration, split into its own file only when
      * `session.cookieCache` is enabled (stateless path); undefined otherwise. */