@pikku/cli 0.12.44 → 0.12.46

package/dist/.pikku/workflow/meta/allWorkflow.gen.json

@@ -349,7 +349,7 @@
         "HTTP": {
             "nodeId": "HTTP",
             "rpcName": "pikkuCommandHTTP",
-            "next": "Scheduler",
+            "next": "Channels",
             "stepHash": "ba1b4f85fc79"
         },
         "Scheduler": {
@@ -397,9 +397,21 @@
         "Realtime client": {
             "nodeId": "Realtime client",
             "rpcName": "pikkuRealtime",
-            "next": "Functions",
+            "next": "HTTP",
             "stepHash": "3aa3265e392d"
         },
+        "Channels": {
+            "nodeId": "Channels",
+            "rpcName": "pikkuCommandChannels",
+            "next": "Gateway",
+            "stepHash": "aae49a4acd3c"
+        },
+        "CLI": {
+            "nodeId": "CLI",
+            "rpcName": "pikkuCLI",
+            "next": "Queue map",
+            "stepHash": "8b5a8e81446a"
+        },
         "Functions": {
             "nodeId": "Functions",
             "rpcName": "pikkuFunctions",
@@ -412,12 +424,6 @@
             "next": "Channels",
             "stepHash": "fba2e19d515a"
         },
-        "Channels": {
-            "nodeId": "Channels",
-            "rpcName": "pikkuCommandChannels",
-            "next": "Gateway",
-            "stepHash": "aae49a4acd3c"
-        },
         "Gateway": {
             "nodeId": "Gateway",
             "rpcName": "pikkuGateway",
@@ -430,12 +436,6 @@
             "next": "CLI",
             "stepHash": "fd4e9c89c777"
         },
-        "CLI": {
-            "nodeId": "CLI",
-            "rpcName": "pikkuCLI",
-            "next": "Queue map",
-            "stepHash": "8b5a8e81446a"
-        },
         "Queue map": {
             "nodeId": "Queue map",
             "rpcName": "pikkuCommandQueueMap",
@@ -545,5 +545,5 @@
     "entryNodeIds": [
         "Bootstrap inspect"
     ],
-    "graphHash": "ae92575e1187"
+    "graphHash": "e6e8c0ae99f8"
 }

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.44
+ * 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.44
+ * 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.44
+ * 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.44
+ * 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.44') {
-      process.stderr.write(`\n  Update available  0.12.44 → ${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/functions/wirings/channels/pikku-channels.js

@@ -6,19 +6,28 @@ import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 export const pikkuChannels = pikkuVoidFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
-        const { channelsWiringFile, channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings, schema, } = config;
-        const { channels } = visitState;
-        if (channels.files.size === 0 || Object.keys(channels.meta).length === 0) {
+        const { channelsWiringFile, channelsWiringMetaFile, channelsWiringMetaJsonFile, channelContractsMetaJsonFile, packageMappings, schema, } = config;
+        const { channels, exportedContracts } = visitState;
+        const hasChannelContracts = Object.keys(exportedContracts.channel).length > 0;
+        if ((channels.files.size === 0 || Object.keys(channels.meta).length === 0) &&
+            !hasChannelContracts) {
             return;
         }
-        await writeFileInDir(logger, channelsWiringFile, serializeFileImports('addChannel', channelsWiringFile, channels.files, packageMappings));
-        await writeFileInDir(logger, channelsWiringMetaJsonFile, JSON.stringify(channels.meta, null, 2));
-        const jsonImportPath = getFileImportRelativePath(channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings);
-        const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
-        const importStatement = supportsImportAttributes
-            ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
-            : `import metaData from '${jsonImportPath}'`;
-        await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core/internal'\nimport { ChannelsMeta } from '@pikku/core/channel'\n${importStatement}\npikkuState(null, 'channel', 'meta', metaData as ChannelsMeta)`);
+        if (channels.files.size > 0 && Object.keys(channels.meta).length > 0) {
+            await writeFileInDir(logger, channelsWiringFile, serializeFileImports('addChannel', channelsWiringFile, channels.files, packageMappings));
+        }
+        if (Object.keys(channels.meta).length > 0) {
+            await writeFileInDir(logger, channelsWiringMetaJsonFile, JSON.stringify(channels.meta, null, 2));
+        }
+        await writeFileInDir(logger, channelContractsMetaJsonFile, JSON.stringify(exportedContracts.channel, null, 2));
+        if (Object.keys(channels.meta).length > 0) {
+            const jsonImportPath = getFileImportRelativePath(channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings);
+            const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
+            const importStatement = supportsImportAttributes
+                ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+                : `import metaData from '${jsonImportPath}'`;
+            await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core/internal'\nimport { ChannelsMeta } from '@pikku/core/channel'\n${importStatement}\npikkuState(null, 'channel', 'meta', metaData as ChannelsMeta)`);
+        }
     },
     middleware: [
         logCommandInfoAndTime({

package/dist/src/functions/wirings/channels/pikku-command-channels-map.js

@@ -5,8 +5,8 @@ import { serializeTypedChannelsMap } from './serialize-typed-channel-map.js';
 export const pikkuChannelsMap = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const state = await getInspectorState();
-        const { channelsMapDeclarationFile, packageMappings } = config;
-        const content = serializeTypedChannelsMap(logger, channelsMapDeclarationFile, packageMappings, state.functions.typesMap, state.functions.meta, state.addonFunctions, state.channels.meta);
+        const { channelsMapDeclarationFile, packageMappings, rpcInternalMapDeclarationFile, } = config;
+        const content = serializeTypedChannelsMap(logger, channelsMapDeclarationFile, packageMappings, state.functions.typesMap, state.functions.meta, state.addonFunctions, state.channels.meta, rpcInternalMapDeclarationFile);
         await writeFileInDir(logger, channelsMapDeclarationFile, content);
     },
     middleware: [

package/dist/src/functions/wirings/channels/pikku-command-channels.js

@@ -7,21 +7,35 @@ import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verb
 export const pikkuCommandChannels = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
-        const { channelsWiringFile, channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings, schema, } = config;
-        const { channels } = visitState;
-        if (channels.files.size === 0 || Object.keys(channels.meta).length === 0) {
+        const { channelsWiringFile, channelsWiringMetaFile, channelsWiringMetaJsonFile, channelContractsMetaJsonFile, channelContractsMetaFile, packageMappings, schema, } = config;
+        const { channels, exportedContracts } = visitState;
+        const hasChannelContracts = Object.keys(exportedContracts.channel).length > 0;
+        if ((channels.files.size === 0 || Object.keys(channels.meta).length === 0) &&
+            !hasChannelContracts) {
             return undefined;
         }
+        // The bootstrap imports channelsWiringFile and channelsWiringMetaFile
+        // whenever this command reports channels as active (truthy return), so both
+        // must always be written once past the guard above — including the
+        // contracts-only case where there are no local channel source files
+        // (channels.files is empty). Skipping either leaves the bootstrap importing
+        // a file that was never generated and the per-unit deploy bundle fails.
         await writeFileInDir(logger, channelsWiringFile, serializeFileImports('addChannel', channelsWiringFile, channels.files, packageMappings));
-        // Write minimal JSON (runtime-only fields)
         const minimalMeta = stripVerboseFields(channels.meta);
         await writeFileInDir(logger, channelsWiringMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
-        // Write verbose JSON only if it has additional fields
         if (hasVerboseFields(channels.meta)) {
             const verbosePath = channelsWiringMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
             await writeFileInDir(logger, verbosePath, JSON.stringify(channels.meta, null, 2));
         }
-        // Generate TypeScript file that imports the minimal JSON
+        await writeFileInDir(logger, channelContractsMetaJsonFile, JSON.stringify(exportedContracts.channel, null, 2));
+        if (hasChannelContracts) {
+            const contractsJsonImportPath = getFileImportRelativePath(channelContractsMetaFile, channelContractsMetaJsonFile, packageMappings);
+            const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
+            const contractsImportStatement = supportsImportAttributes
+                ? `import contractsMeta from '${contractsJsonImportPath}' with { type: 'json' }`
+                : `import contractsMeta from '${contractsJsonImportPath}'`;
+            await writeFileInDir(logger, channelContractsMetaFile, `${contractsImportStatement}\nexport default contractsMeta`);
+        }
         const jsonImportPath = getFileImportRelativePath(channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings);
         const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
         const importStatement = supportsImportAttributes

package/dist/src/functions/wirings/channels/serialize-typed-channel-map.d.ts

@@ -2,4 +2,4 @@ import type { ChannelsMeta } from '@pikku/core/channel';
 import type { TypesMap } from '@pikku/inspector';
 import type { FunctionsMeta } from '@pikku/core';
 import type { Logger } from '@pikku/core/services';
-export declare const serializeTypedChannelsMap: (logger: Logger, relativeToPath: string, packageMappings: Record<string, string>, typesMap: TypesMap, functionsMeta: FunctionsMeta, addonFunctions: Record<string, FunctionsMeta>, channelsMeta: ChannelsMeta) => string;
+export declare const serializeTypedChannelsMap: (logger: Logger, relativeToPath: string, packageMappings: Record<string, string>, typesMap: TypesMap, functionsMeta: FunctionsMeta, addonFunctions: Record<string, FunctionsMeta>, channelsMeta: ChannelsMeta, rpcInternalMapDeclarationFile: string) => string;