@pikku/inspector 0.12.24 → 0.12.26

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 0.12.26
+
+### Patch Changes
+
+- ed548d5: fix(auth): skip the generated global `betterAuthSession()` when the user registers their own
+
+  The CLI's `auth.gen.ts` unconditionally wired a global
+  `addHTTPMiddleware('*', [betterAuthSession()])` (default map) on the stateful
+  path. A project that needs a customized session bridge — `mapSession`,
+  `impersonation`, `apiKey` — had to register a second global
+  `betterAuthSession({...})`, leaving two in the chain; the generated default ran
+  first and short-circuited (`if (session) next()`) so the custom one never took
+  effect.
+
+  The inspector now records `state.auth.hasUserSessionMiddleware` when it sees a
+  user-authored **global** `betterAuthSession` registration (route-scoped and
+  `.gen.ts` registrations are ignored, so regeneration never self-suppresses).
+  The CLI omits its own global `betterAuthSession()` from `auth.gen.ts` when that
+  flag is set — exactly one session bridge in the chain, the user's. Mirrors the
+  existing stateless skip (`userStatelessSession`, #754).
+
+## 0.12.25
+
+### Patch Changes
+
+- b6ba601: fix(lint): don't flag pikkuAuth's session param as a non-destructured wire
+
+  `pikkuAuth`'s handler is `(services, session)` — the second parameter is the
+  resolved user session, not a wires bag. The inspector was extracting "wires"
+  from that parameter (`extractUsedWires(handler, 1)`), so a permission like
+  `pikkuAuth(async ({ logger }, session) => !!session)` tripped
+  `wiresNotDestructured` even though `session` cannot be destructured. pikkuAuth
+  exposes no user-facing wires parameter, so no wires meta is recorded for it.
+
+- ae7fc5d: Include gateway platform and auth fields in inspected gateway metadata.
+- decdad5: fix(lint): don't fail the build on framework-synthesized functions
+
+  The `servicesNotDestructured`/`wiresNotDestructured` defaults (`error`) were
+  tripping on functions the user can't edit: generated `.gen.ts` wrappers (the
+  opaque `authHandler`, the cli channel raw dispatcher) and synthetic route→addon
+  bridges (`http:<method>:<route>`, no source file). `computeDiagnostics` now skips
+  any function without a real, non-generated source file, so the lint only nudges
+  hand-written user code. Also destructures the CLI's own `all` command.
+
+- Updated dependencies [ae7fc5d]
+- Updated dependencies [fa7a09c]
+  - @pikku/core@0.12.37
+
 ## 0.12.24
 
 ### Patch Changes

package/dist/add/add-auth.js

@@ -137,6 +137,17 @@ export const addAuth = (logger, node, _checker, state) => {
         isInsideGlobalMiddlewareRegistration(node)) {
         state.auth.userStatelessSession = true;
     }
+    // Same rule for the stateful variant: a user-registered global
+    // betterAuthSession(...) (custom mapSession/impersonation/apiKey) means the CLI
+    // must NOT auto-generate its own default one — the generated one runs first and
+    // pre-empts the user's via the `if (session) next()` short-circuit. Stateful
+    // analogue of the betterAuthStatelessSession skip above.
+    if (ts.isIdentifier(expression) &&
+        expression.text === 'betterAuthSession' &&
+        !node.getSourceFile().fileName.endsWith('.gen.ts') &&
+        isInsideGlobalMiddlewareRegistration(node)) {
+        state.auth.hasUserSessionMiddleware = true;
+    }
     if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
         return;
     const sourceFile = node.getSourceFile().fileName;

package/dist/add/add-gateway.js

@@ -23,6 +23,8 @@ export const addGateway = (logger, node, checker, state, _options) => {
     const nameValue = getPropertyValue(obj, 'name');
     const typeValue = getPropertyValue(obj, 'type');
     const routeValue = getPropertyValue(obj, 'route');
+    const platformValue = getPropertyValue(obj, 'platform');
+    const authValue = getPropertyValue(obj, 'auth');
     const { disabled, tags, summary, description, errors } = getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker);
     if (disabled)
         return;
@@ -51,7 +53,9 @@ export const addGateway = (logger, node, checker, state, _options) => {
         ...(packageName && { packageName }),
         name: nameValue,
         type: typeValue,
-        route: routeValue,
+        ...(routeValue && { route: routeValue }),
+        ...(platformValue && { platform: platformValue }),
+        ...(typeof authValue === 'boolean' && { auth: authValue }),
         gateway: true,
         summary,
         description,

package/dist/add/add-permission.js

@@ -141,7 +141,11 @@ export const addPermission = (logger, node, checker, state) => {
             return;
         }
         const services = extractServicesFromFunction(actualHandler);
-        const wires = extractUsedWires(actualHandler, 1);
+        // pikkuAuth's handler is (services, session) — its second parameter is the
+        // resolved user session, NOT a wires bag, so it must not be analyzed (or
+        // flagged) as a non-destructured wires parameter. pikkuAuth exposes no
+        // user-facing wires parameter.
+        const wires = { optimized: true, wires: [] };
         let { pikkuFuncId, exportedName } = extractFunctionName(node, checker, state.rootDir);
         if (pikkuFuncId.startsWith('__temp_')) {
             if (ts.isVariableDeclaration(node.parent) &&

package/dist/types.d.ts

@@ -436,6 +436,12 @@ export interface InspectorState {
          *  own default-map stateless middleware, which would otherwise pre-empt the
          *  user's custom mapSession (pikkujs/pikku#754). */
         userStatelessSession?: boolean;
+        /** True when a user (non-generated) file already registers a global
+         *  `betterAuthSession(...)`. The CLI then skips auto-generating its own
+         *  default stateful middleware, which would otherwise run first and pre-empt
+         *  the user's config (mapSession/impersonation/apiKey). Stateful analogue of
+         *  `userStatelessSession`. */
+        hasUserSessionMiddleware?: boolean;
     };
     secrets: {
         definitions: SecretDefinitions;

package/dist/utils/post-process.js

@@ -525,6 +525,14 @@ export function validateSchemaWiringSeparation(logger, state) {
 export function computeDiagnostics(state) {
     const diagnostics = [];
     for (const [id, meta] of Object.entries(state.functions.meta)) {
+        // Skip framework-synthesized functions: generated wrappers (auth.gen.ts's
+        // opaque authHandler, the cli channel's raw dispatcher) and synthetic route
+        // bridges that reference addon functions (id `http:<method>:<route>`, no
+        // source file). The user can't edit any of these, so a destructure lint
+        // meant to nudge them about their own code must not fail the build over them.
+        if (!meta.sourceFile || meta.sourceFile.endsWith('.gen.ts')) {
+            continue;
+        }
         if (meta.services && !meta.services.optimized) {
             diagnostics.push({
                 code: ErrorCode.SERVICES_NOT_DESTRUCTURED,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.24",
+  "version": "0.12.26",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.35",
+    "@pikku/core": "^0.12.37",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",

package/src/add/add-auth.test.ts

@@ -616,4 +616,54 @@ describe('addAuth inspector', () => {
       await rm(rootDir, { recursive: true, force: true })
     }
   })
+
+  test('user-registered global betterAuthSession sets hasUserSessionMiddleware', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-session-'))
+    const file = join(rootDir, 'middleware.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [",
+        '  betterAuthSession({',
+        '    impersonation: { loadUser: (id: string) => ({ id }) },',
+        '  }),',
+        '])',
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(state.auth.hasUserSessionMiddleware, true)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('betterAuthSession in a .gen.ts file does NOT set hasUserSessionMiddleware', async () => {
+    // Critical: the CLI's own auth.gen.ts contains addHTTPMiddleware('*',
+    // [betterAuthSession()]). It must not count as a user registration, or it
+    // would suppress itself and leave the chain with no session middleware.
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-session-gen-'))
+    const file = join(rootDir, 'auth.gen.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [betterAuthSession()])",
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.ok(
+        !state.auth.hasUserSessionMiddleware,
+        'generated file must not self-trigger the skip'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
 })

package/src/add/add-auth.ts

@@ -168,6 +168,20 @@ export const addAuth: AddWiring = (logger, node, _checker, state) => {
     state.auth.userStatelessSession = true
   }
 
+  // Same rule for the stateful variant: a user-registered global
+  // betterAuthSession(...) (custom mapSession/impersonation/apiKey) means the CLI
+  // must NOT auto-generate its own default one — the generated one runs first and
+  // pre-empts the user's via the `if (session) next()` short-circuit. Stateful
+  // analogue of the betterAuthStatelessSession skip above.
+  if (
+    ts.isIdentifier(expression) &&
+    expression.text === 'betterAuthSession' &&
+    !node.getSourceFile().fileName.endsWith('.gen.ts') &&
+    isInsideGlobalMiddlewareRegistration(node)
+  ) {
+    state.auth.hasUserSessionMiddleware = true
+  }
+
   if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
     return
 

package/src/add/add-gateway.ts

@@ -43,7 +43,9 @@ export const addGateway: AddWiring = (
 
   const nameValue = getPropertyValue(obj, 'name') as string | null
   const typeValue = getPropertyValue(obj, 'type') as GatewayTransportType | null
-  const routeValue = getPropertyValue(obj, 'route') as string | undefined
+  const routeValue = getPropertyValue(obj, 'route') as string | null
+  const platformValue = getPropertyValue(obj, 'platform') as string | null
+  const authValue = getPropertyValue(obj, 'auth')
   const { disabled, tags, summary, description, errors } =
     getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker)
 
@@ -94,7 +96,9 @@ export const addGateway: AddWiring = (
     ...(packageName && { packageName }),
     name: nameValue,
     type: typeValue,
-    route: routeValue,
+    ...(routeValue && { route: routeValue }),
+    ...(platformValue && { platform: platformValue }),
+    ...(typeof authValue === 'boolean' && { auth: authValue }),
     gateway: true,
     summary,
     description,

package/src/add/add-permission-auth.test.ts

@@ -0,0 +1,59 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+describe('addPermission — pikkuAuth', () => {
+  test('does not record a wires meta for the session parameter', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-auth-wires-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        'const pikkuAuth = (x: any) => x',
+        'export const isAuthenticated = pikkuAuth(async ({ logger }, session) => {',
+        '  logger.info({ type: "auth-check" })',
+        '  return !!session',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      const def = state.permissions.definitions['isAuthenticated']
+      assert.ok(def, 'isAuthenticated permission should be recorded')
+      // The pikkuAuth handler is (services, session) — session is NOT a wires
+      // bag and must not be flagged as a non-destructured wires parameter.
+      assert.equal(def.wires, undefined)
+      const wireDiag = (state.diagnostics ?? []).find(
+        (d) =>
+          d.code === ErrorCode.WIRES_NOT_DESTRUCTURED &&
+          d.message.includes('isAuthenticated')
+      )
+      assert.equal(wireDiag, undefined)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-permission.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript'
+import type { FunctionWiresMeta } from '@pikku/core'
 import type { AddWiring, InspectorState } from '../types.js'
 import {
   extractFunctionName,
@@ -195,7 +196,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     }
 
     const services = extractServicesFromFunction(actualHandler)
-    const wires = extractUsedWires(actualHandler, 1)
+    // pikkuAuth's handler is (services, session) — its second parameter is the
+    // resolved user session, NOT a wires bag, so it must not be analyzed (or
+    // flagged) as a non-destructured wires parameter. pikkuAuth exposes no
+    // user-facing wires parameter.
+    const wires: FunctionWiresMeta = { optimized: true, wires: [] }
     let { pikkuFuncId, exportedName } = extractFunctionName(
       node,
       checker,

package/src/types.ts

@@ -502,6 +502,12 @@ export interface InspectorState {
      *  own default-map stateless middleware, which would otherwise pre-empt the
      *  user's custom mapSession (pikkujs/pikku#754). */
     userStatelessSession?: boolean
+    /** True when a user (non-generated) file already registers a global
+     *  `betterAuthSession(...)`. The CLI then skips auto-generating its own
+     *  default stateful middleware, which would otherwise run first and pre-empt
+     *  the user's config (mapSession/impersonation/apiKey). Stateful analogue of
+     *  `userStatelessSession`. */
+    hasUserSessionMiddleware?: boolean
   }
   secrets: {
     definitions: SecretDefinitions

package/src/utils/compute-diagnostics.test.ts

@@ -0,0 +1,69 @@
+import { test, describe } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { computeDiagnostics } from './post-process.js'
+import type { InspectorState } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+function stateWithFunctions(
+  meta: InspectorState['functions']['meta']
+): InspectorState {
+  return {
+    functions: { meta },
+    middleware: { definitions: {} },
+    permissions: { definitions: {} },
+  } as unknown as InspectorState
+}
+
+describe('computeDiagnostics', () => {
+  test('flags a user-authored function that does not destructure services', () => {
+    const state = stateWithFunctions({
+      myFunc: {
+        pikkuFuncId: 'myFunc',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/src/my-func.ts',
+        services: { optimized: false, services: ['kysely'] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 1)
+    assert.equal(
+      state.diagnostics[0].code,
+      ErrorCode.SERVICES_NOT_DESTRUCTURED
+    )
+  })
+
+  test('does NOT flag a generated .gen.ts function (user cannot edit it)', () => {
+    const state = stateWithFunctions({
+      cliRaw: {
+        pikkuFuncId: 'cliRaw',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/src/wirings/cli-channel.gen.ts',
+        services: { optimized: false, services: ['kysely'] },
+      },
+      authHandler: {
+        pikkuFuncId: 'authHandler',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/.pikku/auth.gen.ts',
+        wires: { optimized: false, wires: ['http'] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 0)
+  })
+
+  test('does NOT flag a synthetic route bridge with no source file', () => {
+    const state = stateWithFunctions({
+      'http:get:/workflow-run/:runId/stream': {
+        pikkuFuncId: 'http:get:/workflow-run/:runId/stream',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        services: { optimized: false, services: [] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 0)
+  })
+})

package/src/utils/post-process.ts

@@ -661,6 +661,14 @@ export function computeDiagnostics(state: InspectorState): void {
   const diagnostics: InspectorDiagnostic[] = []
 
   for (const [id, meta] of Object.entries(state.functions.meta)) {
+    // Skip framework-synthesized functions: generated wrappers (auth.gen.ts's
+    // opaque authHandler, the cli channel's raw dispatcher) and synthetic route
+    // bridges that reference addon functions (id `http:<method>:<route>`, no
+    // source file). The user can't edit any of these, so a destructure lint
+    // meant to nudge them about their own code must not fail the build over them.
+    if (!meta.sourceFile || meta.sourceFile.endsWith('.gen.ts')) {
+      continue
+    }
     if (meta.services && !meta.services.optimized) {
       diagnostics.push({
         code: ErrorCode.SERVICES_NOT_DESTRUCTURED,