@pikku/cli 0.12.45 → 0.12.47

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.47
  */
 /**
  * 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.47",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -27,11 +27,11 @@
   "dependencies": {
     "@electric-sql/pglite": "^0.5.1",
     "@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/fetch": "^0.12.3",
-    "@pikku/inspector": "^0.12.23",
+    "@pikku/better-auth": "^0.12.10",
+    "@pikku/core": "^0.12.36",
+    "@pikku/deploy-cloudflare": "^0.12.4",
+    "@pikku/fetch": "^0.12.4",
+    "@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 } },
   })
 })
 ```