@pikku/cli 0.12.45 → 0.12.46

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.46
  */
 import { addSchema } from '@pikku/core/schema';
 import * as PikkuSchemasOutput from './schemas/PikkuSchemasOutput.schema.json' with { type: 'json' };
@@ -236,14 +236,14 @@ import * as PikkuQueueOutput from './schemas/PikkuQueueOutput.schema.json' with
 addSchema('PikkuQueueOutput', PikkuQueueOutput);
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 /**
  * 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.46
  */
 /**
  * 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46
  */
 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.46') {
+      process.stderr.write(`\n  Update available  0.12.46 → ${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/wirings/auth/pikku-command-auth.js

@@ -1,4 +1,6 @@
 import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
 import { pikkuSessionlessFunc } from '#pikku';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
@@ -24,10 +26,17 @@ export const pikkuAuth = pikkuSessionlessFunc({
         await writeFileInDir(logger, authFile, wiring);
         await writeFileInDir(logger, secretsFile, secrets);
         // Stateless split: session middleware in its own file (see serializeAuthGen).
+        // Skip it when the project registers its own betterAuthStatelessSession — the
+        // generated default-map one would run first and pre-empt the user's custom
+        // mapSession (pikkujs/pikku#754). Remove a stale file so it can't linger and
+        // double-register.
         const middlewareFile = join(dirname(authFile), 'auth-middleware.gen.ts');
-        if (middleware) {
+        if (middleware && !state.auth.userStatelessSession) {
             await writeFileInDir(logger, middlewareFile, middleware);
         }
+        else if (existsSync(middlewareFile)) {
+            await rm(middlewareFile, { force: true });
+        }
         // Static metadata of the enabled providers/plugins for the console SSO page,
         // following the `*-meta.gen.json` convention. Read at runtime by the console
         // getAuthProviders function instead of a runtime registry.

package/dist/src/scaffold/rpc-remote.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.46
  */
 /**
  * Auto-generated remote internal RPC queue worker and HTTP endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.45",
+  "version": "0.12.46",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -29,9 +29,9 @@
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
     "@pikku/better-auth": "^0.12.9",
     "@pikku/core": "^0.12.35",
-    "@pikku/deploy-cloudflare": "^0.12.3",
+    "@pikku/deploy-cloudflare": "^0.12.4",
     "@pikku/fetch": "^0.12.3",
-    "@pikku/inspector": "^0.12.23",
+    "@pikku/inspector": "^0.12.24",
     "@pikku/kysely": "^0.12.16",
     "@pikku/kysely-node-sqlite": "^0.12.2",
     "@pikku/node-http-server": "^0.12.2",

package/skills/pikku-better-auth/SKILL.md

@@ -46,9 +46,9 @@ yarn add @pikku/better-auth better-auth
 Better Auth owns its own HTTP surface, database tables, and session cookie. The Pikku integration is thin:
 
 1. **`pikkuBetterAuth(factory)`** — you export ONE `pikkuBetterAuth` call whose factory returns a configured `betterAuth({...})` instance. The pikku CLI inspects this export and generates everything else.
-2. **Generated `auth.gen.ts`** — a catch-all `${basePath}{/*splat}` HTTP route per method (GET + POST) that forwards every request under the base path to better-auth's own internal router, plus `addHTTPMiddleware('*', [betterAuthSession({ auth })])`. The enabled providers and plugins are written to `auth/pikku-auth-meta.gen.json` (read by the console SSO page via `getAuthProviders`).
-3. **Generated `auth-secrets.gen.ts`** — a `wireSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `wireVariable` for any non-secret provider config (e.g. `tenantId`).
-4. **`betterAuthSession`** — middleware that reads better-auth's session on every request and populates the Pikku session object.
+2. **Generated `auth.gen.ts`** — a catch-all `${basePath}{/*splat}` HTTP route per method (GET + POST) that forwards every request under the base path to better-auth's own internal router. The enabled providers and plugins are written to `auth/pikku-auth-meta.gen.json` (read by the console SSO page via `getAuthProviders`).
+3. **Generated session middleware** — with `session.cookieCache` enabled (recommended), a separate `auth-middleware.gen.ts` adds the lean stateless `betterAuthStatelessSession()`; without it, `auth.gen.ts` adds the stateful `betterAuthSession()` that bundles the full server into every unit. See "Stateless session" below.
+4. **Generated `auth-secrets.gen.ts`** — a `wireSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `wireVariable` for any non-secret provider config (e.g. `tenantId`).
 
 You do NOT hand-write routes, the session middleware, or the secret wiring — `pikkuBetterAuth` + the CLI generate all of it. Re-run `pikku auth` (or `pikku all`) to regenerate.
 
@@ -78,6 +78,8 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
     // at runtime. Swap for the Kysely adapter in production (see below).
     database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
     emailAndPassword: { enabled: true },
+    // ALWAYS enable for deployed apps — see "Stateless session" below.
+    session: { cookieCache: { enabled: true } },
     socialProviders: {
       github: GITHUB_OAUTH,
     },
@@ -89,6 +91,19 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
 - `socialProviders` keys must be string literals — the CLI reads them statically to emit a `wireSecret` per provider. Provider keys mirror better-auth's built-in ids exactly (e.g. `microsoft`, NOT `microsoft-entra-id`; `cognito`; `github`).
 - The factory runs lazily on the first auth request, so it pulls secrets/DB off the injected `services`.
 - The default `basePath` is `/api/auth`. Override it by passing `basePath` to `betterAuth`.
+- **Enable `session: { cookieCache: { enabled: true } }`** so non-auth units tree-shake the better-auth server out (see below).
+
+## ⚠️ Stateless session — ALWAYS enable `cookieCache` for deployed apps
+
+By default the CLI wires the **stateful** `betterAuthSession` bridge globally — it calls `services.auth()`, so EVERY unit/worker bundles the full better-auth server (~2.5MB each). On per-unit deploy targets (Fabric/Cloudflare) that bloats every bundle and the serial upload phase.
+
+Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a lean `betterAuthStatelessSession` (`src/scaffold/auth-middleware.gen.ts`) that verifies the signed session cookie using only `BETTER_AUTH_SECRET` — no `services.auth()`, no server bundled. Non-auth units drop from ~2.5MB to ~20KB. Only the auth unit carries the server. `pikku fabric validate` warns (`better-auth-stateless-session-disabled`) when it's off.
+
+**Tradeoff:** server-side session revocation isn't seen until the cookie cache expires (sign-out is still immediate — it deletes the cookie).
+
+**Do NOT also hand-write a global `addHTTPMiddleware('*', [betterAuthSession()])`** — that re-drags the stateful server into every unit and defeats the split (validate flags it as `better-auth-stateful-session-global`). The generated middleware is enough.
+
+**Custom session fields (`role`, `locale`, …):** the generated stateless middleware uses the default map (`{ userId }` only). To use a custom map, register your own `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI detects a global user registration and skips generating its own (pikkujs/pikku#754), so you keep cookieCache's lean bundles *and* your custom fields. A route-scoped registration (`addHTTPMiddleware('/some/path', [...])`) does not count — the generated global middleware is still emitted.
 
 ### 2. Production database adapter
 
@@ -105,6 +120,7 @@ export const auth = pikkuBetterAuth(async ({ secrets, kysely }) => {
     secret: BETTER_AUTH_SECRET,
     database: kyselyAdapter(kysely, { type: 'postgres' }),
     emailAndPassword: { enabled: true },
+    session: { cookieCache: { enabled: true } },
   })
 })
 ```