@pikku/cli 0.12.45 → 0.12.47

package/dist/.pikku/queue/pikku-queue-workers-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 /* The files with an addQueueWorkers function call */
 import '../../src/scaffold/rpc-remote.gen.js';

package/dist/.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { pikkuState } from '@pikku/core/internal';
 import metaData from './pikku-rpc-wirings-meta.internal.gen.json' with { type: 'json' };

package/dist/.pikku/scheduler/pikku-scheduler-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 /**
  * Scheduler-specific type definitions for tree-shaking optimization

package/dist/.pikku/scheduler/pikku-scheduler-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 /**
  * Scheduler-specific type definitions for tree-shaking optimization

package/dist/.pikku/schemas/register.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { addSchema } from '@pikku/core/schema';
 import * as PikkuSchemasOutput from './schemas/PikkuSchemasOutput.schema.json' with { type: 'json' };
@@ -216,8 +216,6 @@ import * as PikkuFunctionTypesInput from './schemas/PikkuFunctionTypesInput.sche
 addSchema('PikkuFunctionTypesInput', PikkuFunctionTypesInput);
 import * as PikkuFunctionsOutput from './schemas/PikkuFunctionsOutput.schema.json' with { type: 'json' };
 addSchema('PikkuFunctionsOutput', PikkuFunctionsOutput);
-import * as PikkuGatewayOutput from './schemas/PikkuGatewayOutput.schema.json' with { type: 'json' };
-addSchema('PikkuGatewayOutput', PikkuGatewayOutput);
 import * as PikkuCommandHTTPOutput from './schemas/PikkuCommandHTTPOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCommandHTTPOutput', PikkuCommandHTTPOutput);
 import * as PikkuHTTPOutput from './schemas/PikkuHTTPOutput.schema.json' with { type: 'json' };
@@ -234,16 +232,18 @@ import * as PikkuCommandQueueOutput from './schemas/PikkuCommandQueueOutput.sche
 addSchema('PikkuCommandQueueOutput', PikkuCommandQueueOutput);
 import * as PikkuQueueOutput from './schemas/PikkuQueueOutput.schema.json' with { type: 'json' };
 addSchema('PikkuQueueOutput', PikkuQueueOutput);
+import * as PikkuGatewayOutput from './schemas/PikkuGatewayOutput.schema.json' with { type: 'json' };
+addSchema('PikkuGatewayOutput', PikkuGatewayOutput);
 import * as PikkuEventsScaffoldOutput from './schemas/PikkuEventsScaffoldOutput.schema.json' with { type: 'json' };
 addSchema('PikkuEventsScaffoldOutput', PikkuEventsScaffoldOutput);
-import * as PikkuSchedulerOutput from './schemas/PikkuSchedulerOutput.schema.json' with { type: 'json' };
-addSchema('PikkuSchedulerOutput', PikkuSchedulerOutput);
 import * as PikkuPublicRPCOutput from './schemas/PikkuPublicRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuPublicRPCOutput', PikkuPublicRPCOutput);
 import * as PikkuRemoteRPCOutput from './schemas/PikkuRemoteRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuRemoteRPCOutput', PikkuRemoteRPCOutput);
 import * as PikkuRPCOutput from './schemas/PikkuRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuRPCOutput', PikkuRPCOutput);
+import * as PikkuSchedulerOutput from './schemas/PikkuSchedulerOutput.schema.json' with { type: 'json' };
+addSchema('PikkuSchedulerOutput', PikkuSchedulerOutput);
 import * as PikkuTriggerTypesInput from './schemas/PikkuTriggerTypesInput.schema.json' with { type: 'json' };
 addSchema('PikkuTriggerTypesInput', PikkuTriggerTypesInput);
 import * as PikkuTriggerOutput from './schemas/PikkuTriggerOutput.schema.json' with { type: 'json' };

package/dist/.pikku/secrets/pikku-secret-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 export { wireSecret } from '@pikku/core/secret';
 export type { CoreSecret, SecretDefinitionMeta, SecretDefinitionsMeta } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secret-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 export { wireSecret } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secrets.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 import type { SecretService } from '@pikku/core/services';

package/dist/.pikku/secrets/pikku-secrets.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 const CREDENTIALS_META = {};

package/dist/.pikku/trigger/pikku-trigger-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/trigger/pikku-trigger-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/variables/pikku-variable-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 export { wireVariable } from '@pikku/core/variable';
 export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variable-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 export { wireVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variables.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 import type { VariablesService } from '@pikku/core/services';

package/dist/.pikku/variables/pikku-variables.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 const VARIABLES_META = {};

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { pikkuState } from '@pikku/core/internal';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.45
+ * This file was generated by @pikku/cli@0.12.47
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.45') {
-      process.stderr.write(`\n  Update available  0.12.45 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.47') {
+      process.stderr.write(`\n  Update available  0.12.47 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/deploy/build-pipeline.js

@@ -81,6 +81,7 @@ export async function runBuildPipeline(options) {
         entryFiles.set(unitName, entryPath);
         const bundleResult = await bundleUnits(projectDir, manifest, entryFiles, providerDir, {
             externals: provider.getExternals?.(),
+            stubModules: provider.getStubModules?.(),
             aliases: provider.getAliases?.(),
             define: provider.getDefine?.(),
             platform: provider.getPlatform?.(),
@@ -206,6 +207,7 @@ export async function runBuildPipeline(options) {
             };
             const result = await bundleUnits(projectDir, serverlessManifestForBundle, serverlessEntryFiles, providerDir, {
                 externals: provider.getExternals?.(),
+                stubModules: provider.getStubModules?.(),
                 aliases: provider.getAliases?.(),
                 define: provider.getDefine?.(),
                 platform: provider.getPlatform?.(),

package/dist/src/deploy/bundler/bundler.d.ts

@@ -30,5 +30,6 @@ export declare function bundleUnits(projectDir: string, manifest: DeploymentMani
     noRequireShim?: boolean;
     sourcemap?: boolean;
     emitMetafile?: boolean;
+    stubModules?: string[];
     resolveOutputDir?: (unit: DeploymentUnit, baseOutputDir: string) => string;
 }): Promise<BundleOutput>;

package/dist/src/deploy/bundler/bundler.js

@@ -21,6 +21,21 @@ import { extractDependencies, generateMinimalPackageJson, } from './dep-extracto
 const SERVICE_GEN_FILE_MAP = {
     metaService: /pikku-meta-service\.gen/,
 };
+/**
+ * Mapping of service name -> npm module patterns to stub when the service is
+ * NOT required by a deployment unit. Unlike SERVICE_GEN_FILE_MAP these are
+ * external packages, not gen files: a unit that doesn't wire the service never
+ * executes the code path that imports them, so replacing them with `export {}`
+ * keeps their (often large) trees out of the bundle.
+ *
+ * The AI SDKs (@pikku/ai-vercel + @ai-sdk/* + `ai`, ~3MB) are only constructed
+ * when `aiAgentRunner` is wired (agent units). Every non-agent unit stubs them.
+ * The shared services factory must guard the runner construction behind a
+ * defined-check on the dynamic import so a stubbed unit simply skips it.
+ */
+const SERVICE_MODULE_MAP = {
+    aiAgentRunner: [/^@pikku\/ai-vercel/, /^@ai-sdk\//, /^ai$/],
+};
 /**
  * Read the per-unit pikku-services.gen.ts and return the set of gen file
  * patterns that should be stubbed (because their service is not required).
@@ -34,8 +49,14 @@ async function getDeadGenFilePatterns(unitOutputDir) {
         if (match) {
             for (const line of match[1].split('\n')) {
                 const kv = line.match(/'([^']+)':\s*false/);
-                if (kv && SERVICE_GEN_FILE_MAP[kv[1]]) {
-                    patterns.push(SERVICE_GEN_FILE_MAP[kv[1]]);
+                if (!kv)
+                    continue;
+                const service = kv[1];
+                if (SERVICE_GEN_FILE_MAP[service]) {
+                    patterns.push(SERVICE_GEN_FILE_MAP[service]);
+                }
+                if (SERVICE_MODULE_MAP[service]) {
+                    patterns.push(...SERVICE_MODULE_MAP[service]);
                 }
             }
         }
@@ -81,14 +102,20 @@ const EXACT_DEPENDENCIES_FILENAME = 'exact-dependencies.json';
  * - package.json: Minimal manifest with only the external deps this unit needs
  */
 async function bundleUnit(options) {
-    const { unit, entryPath, unitOutputDir, projectDir, externals, aliases, define, platform, format, sourcemap, emitMetafile, } = options;
+    const { unit, entryPath, unitOutputDir, projectDir, externals, aliases, define, platform, format, sourcemap, emitMetafile, stubModules, } = options;
     await mkdir(unitOutputDir, { recursive: true });
     const bundlePath = join(unitOutputDir, BUNDLE_FILENAME);
     const metafilePath = join(unitOutputDir, METAFILE_FILENAME);
     const packageJsonPath = join(unitOutputDir, PACKAGE_JSON_FILENAME);
     const exactDependenciesPath = join(unitOutputDir, EXACT_DEPENDENCIES_FILENAME);
-    // Determine which gen files to stub based on per-unit service requirements
+    // Determine which gen files to stub based on per-unit service requirements,
+    // plus any provider-supplied module stubs (modules the provider's runtime
+    // never executes — e.g. the `postgres` driver on CF Workers, which use a
+    // libsql/Turso dialect; the postgres branch is URL-gated and never taken).
     const deadPatterns = await getDeadGenFilePatterns(unitOutputDir);
+    for (const source of stubModules ?? []) {
+        deadPatterns.push(new RegExp(source));
+    }
     // Run esbuild — inline everything into a self-contained bundle.
     // Only Node built-ins are kept external (CF Workers provides them).
     // The stub plugin replaces gen files for unused services with empty
@@ -132,7 +159,11 @@ async function bundleUnit(options) {
         metafile: true,
         target: 'es2022',
         outfile: bundlePath,
-        minify: false,
+        // Minify every deploy bundle — esbuild output ships straight to the runtime
+        // (CF Workers / container), tsc is never the bundler. keepNames preserves
+        // Function.name / constructor.name so name-based reflection still works.
+        minify: true,
+        keepNames: true,
         sourcemap: sourcemap ?? false,
         logLevel: 'warning',
         loader: { '.ts': 'ts' },

package/dist/src/deploy/provider-adapter.d.ts

@@ -74,6 +74,13 @@ export interface ProviderAdapter {
      * Defaults to ['node:*'] if not provided.
      */
     getExternals?(): string[];
+    /**
+     * Regex sources for modules to stub to `export {}` during bundling — modules
+     * this provider's runtime never executes (e.g. the `postgres` driver on CF
+     * Workers, which use a libsql/Turso dialect). Unlike `getExternals`, a stub
+     * removes the bytes entirely rather than leaving a runtime import to resolve.
+     */
+    getStubModules?(): string[];
     /**
      * Module aliases for esbuild bundling (e.g. { crypto: 'node:crypto' }).
      * Used to remap bare imports to platform-compatible paths.

package/dist/src/fabric/functions/validate.function.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
 import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { added, changed, removed, dim } from '../lib/output.js';
 const FindingSchema = z.object({
@@ -59,6 +60,35 @@ async function readTextSafe(path) {
         return null;
     }
 }
+// List .ts/.tsx source files under a directory (skips node_modules). Used to
+// scan an app for raw @mantine/core imports and i18n usage.
+async function listSourceFiles(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 [];
+    }
+}
+// Module-singleton-sensitive packages: a SECOND physical copy splits
+// module-level state. The TanStack Start dev server registers its SSR
+// middleware on one copy of @tanstack/start-plugin-core while the config hook
+// reads another, so the frontend serves "Cannot GET /" (404). React/react-dom
+// duplicates break hooks. This is a workspace-hoisting artifact, not a version
+// mismatch — `resolutions` pins do NOT collapse it. Curated, not exhaustive:
+// most duplicate deps are harmless, so only these are checked.
+const SINGLETON_SENSITIVE_PKGS = [
+    'vite',
+    '@tanstack/start-plugin-core',
+    'react',
+    'react-dom',
+];
 // Minimum @pikku/* versions Fabric requires. The pikku packages are versioned
 // independently (e.g. @pikku/cli moves faster than @pikku/core), so this is a
 // per-package floor map, not a single number. Only listed packages are
@@ -318,6 +348,46 @@ export async function runValidate(startDir = process.cwd()) {
                 // readdir failure — skip
             }
         }
+        // ── better-auth stateless session (unit tree-shaking) ──────────────────
+        // Without `session.cookieCache`, the CLI wires the STATEFUL betterAuthSession
+        // bridge globally — every non-auth unit then bundles the full better-auth
+        // server (~2.5MB each), bloating bundles and the serial deploy uploads.
+        // Enabling cookieCache splits out a lean betterAuthStatelessSession that
+        // verifies the signed cookie, so only the auth unit carries the server. A
+        // hand-written global betterAuthSession defeats it the same way.
+        const fnSrcDir = join(fnDir, 'src');
+        if (existsSync(fnSrcDir)) {
+            try {
+                const srcFiles = (await readdir(fnSrcDir, { recursive: true })).filter((f) => typeof f === 'string' &&
+                    (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+                    !f.endsWith('.gen.ts') &&
+                    !f.includes('node_modules'));
+                for (const rel of srcFiles) {
+                    const full = join(fnSrcDir, rel);
+                    const text = await readTextSafe(full);
+                    if (!text)
+                        continue;
+                    // 1) better-auth config without cookieCache enabled.
+                    if (/\bpikkuBetterAuth\s*\(/.test(text) &&
+                        /\bbetterAuth\s*\(/.test(text)) {
+                        const cookieCacheDisabled = !/cookieCache/.test(text) ||
+                            /cookieCache\s*:\s*\{[^}]*enabled\s*:\s*false/.test(text);
+                        if (cookieCacheDisabled) {
+                            w('better-auth-stateless-session-disabled', 'better-auth config does not enable session.cookieCache — every non-auth unit bundles the full better-auth server (~2.5MB each), bloating bundles and the serial deploy uploads', full, 'Add `session: { cookieCache: { enabled: true } }` to the betterAuth({...}) config so the CLI splits out betterAuthStatelessSession (pikku #737)');
+                        }
+                    }
+                    // 2) hand-written global stateful betterAuthSession bridge.
+                    if (/addHTTPMiddleware\s*\(\s*['"`]\*['"`]/.test(text) &&
+                        /\bbetterAuthSession\s*\(/.test(text) &&
+                        !/betterAuthStatelessSession/.test(text)) {
+                        w('better-auth-stateful-session-global', 'a global addHTTPMiddleware registers the stateful betterAuthSession bridge — it pulls the full better-auth server into every unit, defeating stateless tree-shaking', full, 'Switch to betterAuthStatelessSession (requires session.cookieCache). A custom mapSession is currently pre-empted by the CLI-generated stateless middleware — see pikku #754');
+                    }
+                }
+            }
+            catch {
+                // readdir failure — skip
+            }
+        }
         // Database layout is declared by pikku.config.json db.engine.
         const migrationsDir = join(root, 'db', dbEngine === 'postgres' ? 'postgres' : 'sqlite');
         if (!existsSync(migrationsDir)) {
@@ -449,6 +519,121 @@ export async function runValidate(startDir = process.cwd()) {
             if (componentsPkgName && !appDeps[componentsPkgName]) {
                 info(`app-missing-components-${name}`, `apps/${name} does not depend on ${componentsPkgName}`, join(appPath, 'package.json'), `Add "${componentsPkgName}: workspace:*" to apps/${name}/package.json dependencies`);
             }
+            // The scaffolded dev vite config (generate-frontend-runtime) imports
+            // @babel/core to tag JSX with data-om-id for alt-click design editing.
+            // It resolves transitively via @vitejs/plugin-react, but that's a silent
+            // dependency — declare it explicitly so the resolution can't drift away.
+            if (!appPkg.devDependencies?.['@babel/core']) {
+                w(`app-missing-babel-core-${name}`, `apps/${name} does not declare @babel/core — the dev runtime needs it to instrument JSX (data-om-id) for design alt-click`, join(appPath, 'package.json'), `Add "@babel/core": "^7.26.0" to apps/${name}/package.json devDependencies`);
+            }
+            // ── i18n + @pikku/mantine convergence (React frontend apps) ──────────
+            // Every frontend converges onto the canonical starter-template stack:
+            // Paraglide JS (inlang) for translation + components imported from
+            // @pikku/mantine/core (whose I18nNode-typed props make untranslated
+            // strings a compile error). A raw @mantine/core import bypasses that gate.
+            // The i18next → Paraglide cutover is hard (no back-compat), so a residual
+            // i18next dep or useTranslation()/useI18n() call is an error.
+            const appAllDeps = {
+                ...appPkg.dependencies,
+                ...appPkg.devDependencies,
+            };
+            const isReactFrontend = !!(appAllDeps['@mantine/core'] ||
+                appAllDeps['@pikku/mantine'] ||
+                appAllDeps['react']);
+            if (isReactFrontend) {
+                const srcFiles = await listSourceFiles(join(appPath, 'src'));
+                let usesMessages = false;
+                const rawMantineFiles = [];
+                const legacyI18nFiles = [];
+                for (const file of srcFiles) {
+                    const text = await readTextSafe(file);
+                    if (!text)
+                        continue;
+                    const rel = file.slice(appPath.length + 1);
+                    const norm = rel.replace(/\\/g, '/');
+                    // Paraglide usage: the reactive useLocale() hook or an import from the
+                    // local `@/i18n` scaffold (messages `m`, mKey/mList) — either means
+                    // strings flow through compiled messages.
+                    if (/\buseLocale\s*\(/.test(text) ||
+                        /from\s+['"]@\/i18n(?:\/[\w-]+)?['"]/.test(text)) {
+                        usesMessages = true;
+                    }
+                    // Legacy i18next/react-i18next/@pikku/react-i18n markers — removed by
+                    // the cutover. The scaffold's own config.ts names these in comments,
+                    // so skip src/i18n/ and match imports/hook calls, not bare words.
+                    if (!/(?:^|\/)i18n\//.test(norm) &&
+                        (/from\s+['"](?:react-i18next|i18next|@pikku\/react\/i18n)['"]/.test(text) ||
+                            /\buseTranslation\s*\(/.test(text) ||
+                            /\buseI18n\s*\(/.test(text))) {
+                        legacyI18nFiles.push(rel);
+                    }
+                    // component import from @mantine/core — the trailing quote excludes
+                    // the `@mantine/core/styles.css` side-effect import and @mantine/hooks
+                    if (/from\s+['"]@mantine\/core['"]/.test(text)) {
+                        rawMantineFiles.push(rel);
+                    }
+                }
+                const hasParaglideDep = !!appAllDeps['@inlang/paraglide-js'];
+                const hasMessagesDir = existsSync(join(appPath, 'messages'));
+                const hasInlangProject = existsSync(join(appPath, 'project.inlang', 'settings.json'));
+                const hasLegacyI18nDeps = !!(appAllDeps['i18next'] || appAllDeps['react-i18next']);
+                // 1) i18next must be fully removed — hard cutover to Paraglide.
+                if (hasLegacyI18nDeps) {
+                    e(`app-legacy-i18next-dep-${name}`, `apps/${name} still depends on i18next/react-i18next — Fabric migrated to Paraglide JS (inlang); the i18next stack must be removed`, join(appPath, 'package.json'), lines('Remove "i18next", "react-i18next" and "i18next-browser-languagedetector".', 'Add "@inlang/paraglide-js" (devDependencies) and the src/i18n scaffold.', 'Reference: templates/starter-template/apps/app.'));
+                }
+                if (legacyI18nFiles.length > 0) {
+                    e(`app-legacy-i18n-usage-${name}`, `apps/${name} still calls useTranslation()/useI18n() or imports i18next in ${legacyI18nFiles.length} file(s) — these are removed by the Paraglide cutover`, join(appPath, 'src'), lines('Convert legacy i18n usage to Paraglide in:', ...legacyI18nFiles.slice(0, 10).map((f) => `  - ${f}`), ...(legacyI18nFiles.length > 10
+                        ? [`  …and ${legacyI18nFiles.length - 10} more`]
+                        : []), "Replace `const { t } = useTranslation()` with `useLocale()` from '@/i18n/config',", "and `t('a.b')` with `m.a_b()` from '@/i18n/messages'."));
+                }
+                // 2) Paraglide must be present and wired (messages + inlang project).
+                if (!hasParaglideDep) {
+                    e(`app-missing-paraglide-${name}`, `apps/${name} has no Paraglide i18n stack — every Fabric frontend must be translatable`, join(appPath, 'package.json'), lines('Add the canonical Paraglide stack:', '1. devDep: "@inlang/paraglide-js".', '2. messages/<locale>.json + project.inlang/settings.json (snake_case keys).', '3. src/i18n scaffold: config.ts (useLocale), messages.ts (branded `m`), ident.ts.', '4. vite.config: paraglideVitePlugin({ project: "./project.inlang", outdir: "./src/paraglide" }).', 'Route every user-visible string through `m.*()`; reference templates/starter-template/apps/app/src/i18n.'));
+                }
+                else if (!hasMessagesDir || !hasInlangProject) {
+                    e(`app-paraglide-not-wired-${name}`, `apps/${name} declares @inlang/paraglide-js but is missing ${!hasMessagesDir ? 'messages/' : 'project.inlang/settings.json'} — Paraglide cannot compile`, appPath, lines('Paraglide compiles `messages/<locale>.json` against `project.inlang/settings.json`.', 'Create both (snake_case keys) — the generated src/paraglide/ output is gitignored.'));
+                }
+                else if (!usesMessages && srcFiles.length > 0) {
+                    w(`app-i18n-unused-${name}`, `apps/${name} ships Paraglide but no component imports from @/i18n or calls useLocale() — strings are not actually translated`, appPath, "Route user-visible strings through `m.*()` from '@/i18n/messages' and subscribe via `useLocale()`.");
+                }
+                if (!appAllDeps['@pikku/mantine'] && appAllDeps['@mantine/core']) {
+                    e(`app-missing-pikku-mantine-${name}`, `apps/${name} uses @mantine/core but not @pikku/mantine — components bypass the i18n-typed compile gate`, join(appPath, 'package.json'), 'Add "@pikku/mantine": "^0.12.5" and import components from "@pikku/mantine/core" (a drop-in for @mantine/core with I18nNode-typed string props).');
+                }
+                if (rawMantineFiles.length > 0) {
+                    e(`app-raw-mantine-imports-${name}`, `apps/${name} imports components from "@mantine/core" directly in ${rawMantineFiles.length} file(s) — this bypasses the @pikku/mantine i18n gate, so untranslated strings compile silently`, join(appPath, 'src'), lines(`Swap 'from "@mantine/core"' → 'from "@pikku/mantine/core"' in:`, ...rawMantineFiles.slice(0, 10).map((f) => `  - ${f}`), ...(rawMantineFiles.length > 10
+                        ? [`  …and ${rawMantineFiles.length - 10} more`]
+                        : []), 'Keep "@mantine/core/styles.css", @mantine/hooks and @mantine/notifications imports as-is.'));
+                }
+            }
+        }
+        // ── singleton-sensitive deps must resolve to ONE physical copy ─────────
+        // A second physical copy of a peer-virtualized lib (or React) splits
+        // module-level state and breaks TanStack Start dev SSR — the perauset
+        // "Cannot GET /" 404. Invariant: one resolved install dir per package
+        // across {app, root}. Best-effort: needs node_modules installed; anything
+        // unresolvable is skipped.
+        for (const name of appEntries) {
+            const appPath = join(appsDir, name);
+            if (!existsSync(join(appPath, 'package.json')))
+                continue;
+            for (const pkg of SINGLETON_SENSITIVE_PKGS) {
+                const installDirs = new Set();
+                for (const base of [appPath, root]) {
+                    try {
+                        const resolved = createRequire(join(base, 'package.json')).resolve(pkg);
+                        const esc = pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        const m = resolved.match(new RegExp(`^(.*[\\\\/]node_modules[\\\\/]${esc})[\\\\/]`));
+                        if (m)
+                            installDirs.add(m[1]);
+                    }
+                    catch {
+                        // not resolvable from this base — skip
+                    }
+                }
+                if (installDirs.size > 1) {
+                    e(`dup-physical-copy-${name}-${pkg.replace(/[@/]/g, '-')}`, `apps/${name}: "${pkg}" resolves to ${installDirs.size} distinct physical copies — a module-singleton split (breaks TanStack Start dev SSR → frontend 404)`, appPath, lines(`"${pkg}" is installed more than once (e.g. one hoisted to the repo root and one nested under apps/${name}).`, `Declare "${pkg}" in exactly ONE workspace manifest (the root OR apps/${name}, not both), delete yarn.lock, and reinstall so it hoists to a single copy.`, '`resolutions` version-pins do NOT collapse a peer-virtualized duplicate.'));
+                }
+            }
         }
     }
     // ── packages/theme + packages/components ──────────────────────────────

package/dist/src/functions/commands/tests-init.js

@@ -75,6 +75,33 @@ registerHooks({ Before, After, BeforeAll, AfterAll, setDefaultTimeout }, db)
 registerCommonSteps({ Given, When, Then })
 `;
 }
+function starterFeature() {
+    return `Feature: Example function test
+
+  Starter scenario created by \`pikku tests init\`. It uses only the built-in
+  pikku/cucumber steps (no custom step code) and passes out of the box, so the
+  Run-tests button and coverage report work immediately. Replace it with real
+  scenarios that call your RPCs — see the commented example at the bottom.
+
+  Scenario: the function-test harness is wired up
+    Given the data "example" is:
+      | hello | world |
+    Then the data "example" is not empty
+
+  # Real example — call one of your RPCs and assert the outcome. Uncomment and
+  # adapt (run \`pikku meta\` to list versioned RPC names and input schemas):
+  #
+  # Scenario: an anonymous user cannot reach a protected RPC
+  #   When an anonymous user calls "yourProtectedRpc"
+  #   Then the call fails with "Unauthorized"
+  #
+  # Scenario: a public RPC returns data
+  #   When an anonymous user calls "yourPublicRpc" with:
+  #     | someField | someValue |
+  #   Then the call succeeds
+  #   And the result has "id"
+`;
+}
 function worldTs() {
     return `import { World, setWorldConstructor } from '@cucumber/cucumber'
 import { createFunctionWorld } from '@pikku/cucumber'
@@ -83,7 +110,7 @@ import { createStubServices } from './services.js'
 createFunctionWorld(World, setWorldConstructor, createStubServices)
 `;
 }
-function servicesTs(configImport, servicesImport, schemaImport, coercionImport, configVar, servicesVar, repoRootRel, hasDb) {
+function servicesTs(configImport, servicesImport, schemaImport, coercionImport, configVar, servicesVar, repoRootRel, hasDb, migrationsRel, seedRel) {
     if (!hasDb) {
         return `import { createDbUtils, type StubTracker } from '@pikku/cucumber'
 import { ${configVar} } from '${configImport}'
@@ -114,8 +141,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const repoRoot = (p: string) => resolve(__dirname, '${repoRootRel}', p)
 
 export const db = createDbUtils({
-  migrationsDir: repoRoot('db/migrations'),
-  seedFile: repoRoot('db/seed.sql'),
+  migrationsDir: repoRoot('${migrationsRel}'),
+  seedFile: repoRoot('${seedRel}'),
 })
 
 type StubKysely = ReturnType<typeof createNodeSqliteKysely<DB>>
@@ -198,9 +225,28 @@ export const pikkuTestsInit = pikkuSessionlessFunc({
         const schemaImport = toJs(rel(schemaFile));
         const coercionImport = toJs(rel(coercionFile));
         const repoRootRel = relative(supportDir, config.rootDir);
-        const hasDb = existsSync(join(config.rootDir, 'db', 'migrations'));
+        // Engine-aware db layout: stages live under db/sqlite or db/postgres with a
+        // matching db/<engine>-seed.sql (see the deploy convention). Pick whichever
+        // engine the project actually ships migrations for.
+        const engine = existsSync(join(config.rootDir, 'db', 'sqlite'))
+            ? 'sqlite'
+            : existsSync(join(config.rootDir, 'db', 'postgres'))
+                ? 'postgres'
+                : null;
+        // Only sqlite runs in the harness today (node:sqlite); postgres falls back
+        // to stubbed services until a pglite-backed harness lands.
+        const hasDb = engine === 'sqlite';
+        const migrationsRel = engine ? `db/${engine}` : '';
+        const seedRel = engine ? `db/${engine}-seed.sql` : '';
+        if (engine === 'postgres') {
+            logger.info('Note: Postgres function-test harness support is not wired yet (the harness runs on node:sqlite). Tracking in pikkujs/pikku#758 — the scaffold falls back to stubbed services.');
+        }
         const files = [
             [join(ftestDir, '.env.test'), envTest()],
+            // Empty lockfile so Yarn Berry treats tests/ as a standalone project
+            // rather than expecting it in the parent repo's workspaces (the harness
+            // is intentionally outside the workspace graph).
+            [join(ftestDir, 'yarn.lock'), ''],
             [join(ftestDir, 'package.json'), packageJson()],
             [join(ftestDir, 'tsconfig.json'), tsconfig()],
             [join(ftestDir, 'tests', 'cucumber.mjs'), cucumberMjs()],
@@ -208,9 +254,9 @@ export const pikkuTestsInit = pikkuSessionlessFunc({
             [join(supportDir, 'world.ts'), worldTs()],
             [
                 join(supportDir, 'services.ts'),
-                servicesTs(configImport, servicesImport, schemaImport, coercionImport, pikkuConfigFactory.variable, singletonServicesFactory.variable, repoRootRel, hasDb),
+                servicesTs(configImport, servicesImport, schemaImport, coercionImport, pikkuConfigFactory.variable, singletonServicesFactory.variable, repoRootRel, hasDb, migrationsRel, seedRel),
             ],
-            [join(ftestDir, 'tests', 'features', '.gitkeep'), ''],
+            [join(ftestDir, 'tests', 'features', 'example.feature'), starterFeature()],
         ];
         for (const [filePath, content] of files) {
             await mkdir(dirname(filePath), { recursive: true });
@@ -219,7 +265,7 @@ export const pikkuTestsInit = pikkuSessionlessFunc({
         }
         logger.info('\nFunction test harness initialized.');
         logger.info('Next steps:');
-        logger.info('  1. Add your first .feature file under tests/features/');
-        logger.info('  2. Install @pikku/cucumber and run: yarn test');
+        logger.info('  1. Install deps in tests/ and run: yarn test');
+        logger.info('  2. Edit tests/tests/features/example.feature — add scenarios that call your RPCs');
     },
 });