@pikku/cli 0.12.50 → 0.12.52

package/dist/.pikku/pikku-meta-service.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export declare class PikkuMetaService extends LocalMetaService {

package/dist/.pikku/pikku-meta-service.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export class PikkuMetaService extends LocalMetaService {

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import type { SingletonServices } from '../types/application-types.d.js';
 import type { Services } from '../types/application-types.d.js';

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * Main type export hub - re-exports all wiring-specific types

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * Main type export hub - re-exports all wiring-specific types

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * Queue-specific type definitions for tree-shaking optimization

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * Queue-specific type definitions for tree-shaking optimization

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

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

package/dist/.pikku/queue/pikku-queue-workers-wirings.gen.d.ts

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import '../../src/scaffold/rpc-remote.gen.js';

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /* 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import { pikkuState } from '@pikku/core/internal';
 import metaData from './pikku-rpc-wirings-meta.internal.gen.json' with { type: 'json' };

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

@@ -109,15 +109,15 @@
     "pikkuCommandChannels": "pikkuCommandChannels",
     "pikkuCLIEntry": "pikkuCLIEntry",
     "pikkuCLI": "pikkuCLI",
-    "pikkuCredentials": "pikkuCredentials",
     "pikkuConsoleFunctions": "pikkuConsoleFunctions",
     "pikkuNodeTypes": "pikkuNodeTypes",
     "pikkuNodesMeta": "pikkuNodesMeta",
-    "pikkuGateway": "pikkuGateway",
+    "pikkuCredentials": "pikkuCredentials",
     "pikkuFunctionTypesSplit": "pikkuFunctionTypesSplit",
     "pikkuFunctionTypes": "pikkuFunctionTypes",
     "pikkuFunctions": "pikkuFunctions",
     "pikkuServices": "pikkuServices",
+    "pikkuGateway": "pikkuGateway",
     "pikkuHTTPMap": "pikkuHTTPMap",
     "pikkuCommandHTTP": "pikkuCommandHTTP",
     "pikkuHTTPTypes": "pikkuHTTPTypes",

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 import { addSchema } from '@pikku/core/schema';
 import * as PikkuSchemasOutput from './schemas/PikkuSchemasOutput.schema.json' with { type: 'json' };
@@ -202,14 +202,14 @@ import * as PikkuPublicAgentOutput from './schemas/PikkuPublicAgentOutput.schema
 addSchema('PikkuPublicAgentOutput', PikkuPublicAgentOutput);
 import * as PikkuCommandChannelsOutput from './schemas/PikkuCommandChannelsOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCommandChannelsOutput', PikkuCommandChannelsOutput);
-import * as PikkuConsoleFunctionsOutput from './schemas/PikkuConsoleFunctionsOutput.schema.json' with { type: 'json' };
-addSchema('PikkuConsoleFunctionsOutput', PikkuConsoleFunctionsOutput);
-import * as PikkuNodesMetaOutput from './schemas/PikkuNodesMetaOutput.schema.json' with { type: 'json' };
-addSchema('PikkuNodesMetaOutput', PikkuNodesMetaOutput);
 import * as PikkuCLIEntryOutput from './schemas/PikkuCLIEntryOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCLIEntryOutput', PikkuCLIEntryOutput);
 import * as PikkuCLIOutput from './schemas/PikkuCLIOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCLIOutput', PikkuCLIOutput);
+import * as PikkuConsoleFunctionsOutput from './schemas/PikkuConsoleFunctionsOutput.schema.json' with { type: 'json' };
+addSchema('PikkuConsoleFunctionsOutput', PikkuConsoleFunctionsOutput);
+import * as PikkuNodesMetaOutput from './schemas/PikkuNodesMetaOutput.schema.json' with { type: 'json' };
+addSchema('PikkuNodesMetaOutput', PikkuNodesMetaOutput);
 import * as PikkuFunctionTypesSplitInput from './schemas/PikkuFunctionTypesSplitInput.schema.json' with { type: 'json' };
 addSchema('PikkuFunctionTypesSplitInput', PikkuFunctionTypesSplitInput);
 import * as PikkuFunctionTypesInput from './schemas/PikkuFunctionTypesInput.schema.json' with { type: 'json' };
@@ -236,6 +236,12 @@ 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 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' };
@@ -244,11 +250,5 @@ import * as PikkuTriggerOutput from './schemas/PikkuTriggerOutput.schema.json' w
 addSchema('PikkuTriggerOutput', PikkuTriggerOutput);
 import * as PikkuWorkflowRoutesOutput from './schemas/PikkuWorkflowRoutesOutput.schema.json' with { type: 'json' };
 addSchema('PikkuWorkflowRoutesOutput', PikkuWorkflowRoutesOutput);
-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 PikkuCLIConfig from './schemas/PikkuCLIConfig.schema.json' with { type: 'json' };
 addSchema('PikkuCLIConfig', PikkuCLIConfig);

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 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.50') {
-      process.stderr.write(`\n  Update available  0.12.50 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.52') {
+      process.stderr.write(`\n  Update available  0.12.52 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

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

@@ -188,7 +188,8 @@ export async function runBuildPipeline(options) {
             await mkdir(unitDir, { recursive: true });
             const ctx = getEntryContext(unitDir, pikkuDir, unit, inspectorState);
             const source = unit.target === 'server'
-                ? generateServerEntrySource(ctx)
+                ? (provider.generateServerEntrySource?.(ctx) ??
+                    generateServerEntrySource(ctx))
                 : provider.generateEntrySource(ctx);
             await writeFile(entryPath, source, 'utf-8');
             if (unit.target === 'server') {

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

@@ -59,6 +59,19 @@ export interface ProviderAdapter {
      * Called once per unit.
      */
     generateEntrySource(ctx: EntryGenerationContext): string;
+    /**
+     * Generate the entry file source for a `target: 'server'` (container) unit.
+     *
+     * Optional. When a provider implements it, the deploy pipeline uses it
+     * instead of the provider-agnostic `generateServerEntrySource`, so the
+     * provider can inject the SAME platform services (kysely, secrets, …) into
+     * the container that it injects into its serverless workers — sourcing the
+     * bindings from `process.env` instead of a runtime `env` object. When
+     * omitted, the pipeline falls back to the generic generator (no platform
+     * injection), which is correct for providers whose containers carry no
+     * platform services.
+     */
+    generateServerEntrySource?(ctx: EntryGenerationContext): string;
     /**
      * Generate provider-specific config files per unit (e.g. wrangler.toml).
      * Returns a map of filename → content to write into the unit directory.

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

@@ -18,7 +18,7 @@ export const pikkuAuth = pikkuSessionlessFunc({
         // has no OAuth providers — still generates its /auth/* wiring.
         if (!state.auth.definition)
             return;
-        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, typesDeclarationFile, packageMappings ?? {});
+        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, typesDeclarationFile, packageMappings ?? {}, state.auth.hasUserSessionMiddleware ?? false);
         // The secrets file sits alongside authFile so re-inspection rediscovers it.
         // It is kept separate from the wiring file because the CLI forbids Zod
         // schemas and HTTP wiring (wireHTTPRoutes) in the same file (PKU490).

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

@@ -33,4 +33,4 @@ export interface AuthGenOutput {
  * wiring, the routes flow through inspection into the deploy manifest (one
  * worker for all auth routes).
  */
-export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, typesDeclarationFile: string, packageMappings: Record<string, string>) => AuthGenOutput;
+export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, typesDeclarationFile: string, packageMappings: Record<string, string>, hasUserSessionMiddleware?: boolean) => AuthGenOutput;

package/dist/src/functions/wirings/auth/serialize-auth-gen.js

@@ -33,7 +33,7 @@ function variableSchemaName(name, field) {
  * wiring, the routes flow through inspection into the deploy manifest (one
  * worker for all auth routes).
  */
-export const serializeAuthGen = (definition, providers, authFile, typesDeclarationFile, packageMappings) => {
+export const serializeAuthGen = (definition, providers, authFile, typesDeclarationFile, packageMappings, hasUserSessionMiddleware = false) => {
     const known = providers.filter((p) => p in PROVIDER_REGISTRY);
     const basePath = definition.basePath;
     // Side-effect import of the user's auth file so `pikkuBetterAuth` runs and
@@ -116,15 +116,22 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
     // file's auth.wiring import (the full better-auth server) isn't dragged into
     // every unit — only the auth unit bundles it.
     const stateless = definition.cookieCache;
+    // Emit the generated global betterAuthSession() only when it's the stateful
+    // path AND the user hasn't registered their own global betterAuthSession(...).
+    // A user registration means they want to customize it (mapSession/impersonation/
+    // apiKey); the generated default-map one would run first and pre-empt theirs via
+    // the `if (session) next()` short-circuit, so we step aside. Mirrors the
+    // stateless skip (state.auth.userStatelessSession, pikkujs/pikku#754).
+    const emitStatefulSession = !stateless && !hasUserSessionMiddleware;
     const wiring = [
         '// AUTO-GENERATED by pikku CLI — do not edit',
         '',
-        stateless
-            ? `import { pikkuSessionlessFunc, wireHTTPRoutes } from '${pikkuTypesImportPath}'`
-            : `import { pikkuSessionlessFunc, wireHTTPRoutes, addHTTPMiddleware } from '${pikkuTypesImportPath}'`,
-        stateless
-            ? `import { createAuthHandler } from '@pikku/better-auth'`
-            : `import { createAuthHandler, betterAuthSession } from '@pikku/better-auth'`,
+        emitStatefulSession
+            ? `import { pikkuSessionlessFunc, wireHTTPRoutes, addHTTPMiddleware } from '${pikkuTypesImportPath}'`
+            : `import { pikkuSessionlessFunc, wireHTTPRoutes } from '${pikkuTypesImportPath}'`,
+        emitStatefulSession
+            ? `import { createAuthHandler, betterAuthSession } from '@pikku/better-auth'`
+            : `import { createAuthHandler } from '@pikku/better-auth'`,
         `import '${configImportPath}'`,
         '',
         // createAuthHandler is called once at module load; the exported handler is a
@@ -138,7 +145,7 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         `})`,
         '',
     ];
-    if (!stateless) {
+    if (emitStatefulSession) {
         // Stateful: betterAuthSession calls services.auth(), so it stays here with
         // the auth.wiring import.
         wiring.push(`addHTTPMiddleware('*', [betterAuthSession()])`, '');

package/dist/src/scaffold/rpc-remote.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.50
+ * This file was generated by @pikku/cli@0.12.52
  */
 /**
  * Auto-generated remote internal RPC queue worker and HTTP endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.50",
+  "version": "0.12.52",
   "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.11",
+    "@pikku/better-auth": "^0.12.12",
     "@pikku/core": "^0.12.37",
-    "@pikku/deploy-cloudflare": "^0.12.4",
-    "@pikku/fetch": "^0.12.4",
-    "@pikku/inspector": "^0.12.25",
+    "@pikku/deploy-cloudflare": "^0.12.5",
+    "@pikku/fetch": "^0.12.5",
+    "@pikku/inspector": "^0.12.26",
     "@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

@@ -101,9 +101,14 @@ Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a
 
 **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.
+**Don't add a redundant default `addHTTPMiddleware('*', [betterAuthSession()])`** — with cookieCache on, that re-drags the stateful server into every unit and defeats the split (validate flags it as `better-auth-stateful-session-global`). If you don't need to customize the session, 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.
+**Customizing the session bridge (`mapSession`, `impersonation`, `apiKey`, …):** you do NOT chain a second middleware on top of the generated one — register your OWN global session middleware and the CLI steps aside (it stops generating its default). This works on both paths and is detected the same way:
+
+- **Stateless (cookieCache on):** register `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI sees the global registration and skips emitting `auth-middleware.gen.ts` (pikkujs/pikku#754), so you keep cookieCache's lean bundles *and* your custom fields.
+- **Stateful (cookieCache off):** register `betterAuthSession({ mapSession, impersonation })` **globally**. The CLI detects it (`hasUserSessionMiddleware`) and omits its own `addHTTPMiddleware('*', [betterAuthSession()])` from `auth.gen.ts` — so there's exactly one session bridge in the chain, yours.
+
+In both cases a **route-scoped** registration (`addHTTPMiddleware('/some/path', [...])`) does NOT count — only a global one suppresses the generated default. The generated middleware in a `.gen.ts` file is also ignored by the detector, so regeneration never self-suppresses.
 
 ### 2. Production database adapter