@pikku/inspector 0.12.19 → 0.12.21

package/src/add/add-auth.ts

@@ -1,49 +1,269 @@
 import * as ts from 'typescript'
+import type { FunctionServicesMeta } from '@pikku/core'
 import type { AddWiring } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
+import { extractServicesFromFunction } from '../utils/extract-services.js'
 
-export const addAuth: AddWiring = (logger, node, _checker, state) => {
-  if (!ts.isCallExpression(node)) return
+/**
+ * The pikku function id of the single shared auth handler the CLI generates
+ * (`export const authHandler = pikkuSessionlessFunc(...)` in auth.gen.ts). An
+ * exported top-level const collapses the catch-all `/api/auth/**` route onto one
+ * worker, and the export name becomes the function id. Shared with the CLI
+ * codegen and the post-process service stamp so all three agree on the same id
+ * without the inspector having to import `@pikku/better-auth`.
+ */
+export const AUTH_HANDLER_FUNC_ID = 'authHandler'
 
-  const expression = node.expression
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireAuth') return
+/** The default better-auth base path when `basePath` is not configured. */
+const DEFAULT_BASE_PATH = '/api/auth'
+
+/**
+ * Find the first `betterAuth({...})` call anywhere inside the `pikkuBetterAuth`
+ * factory body. Supports both `(s) => betterAuth({...})` and
+ * `(s) => { ...; return betterAuth({...}) }`.
+ */
+const findBetterAuthCall = (node: ts.Node): ts.CallExpression | undefined => {
+  let found: ts.CallExpression | undefined
+  const visit = (n: ts.Node) => {
+    if (found) return
+    if (
+      ts.isCallExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === 'betterAuth'
+    ) {
+      found = n
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+  return found
+}
+
+/** Read a string-literal property off an object literal, if present. */
+const readStringProp = (
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): string | undefined => {
+  const prop = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === name
+  ) as ts.PropertyAssignment | undefined
+  if (prop && ts.isStringLiteral(prop.initializer)) return prop.initializer.text
+  return undefined
+}
 
-  const firstArg = node.arguments[0]
-  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+/** Find an object-literal-valued property off an object literal, if present. */
+const readObjectProp = (
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): ts.ObjectLiteralExpression | undefined => {
+  const prop = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === name
+  ) as ts.PropertyAssignment | undefined
+  if (prop && ts.isObjectLiteralExpression(prop.initializer))
+    return prop.initializer
+  return undefined
+}
 
-  const providersProp = firstArg.properties.find(
+/** Find an array-literal-valued property off an object literal, if present. */
+const readArrayProp = (
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): ts.ArrayLiteralExpression | undefined => {
+  const prop = obj.properties.find(
     (p) =>
       ts.isPropertyAssignment(p) &&
       (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
-      p.name.text === 'providers'
+      p.name.text === name
   ) as ts.PropertyAssignment | undefined
+  if (prop && ts.isArrayLiteralExpression(prop.initializer))
+    return prop.initializer
+  return undefined
+}
+
+/**
+ * Read the callee name of a `plugins: [...]` entry. better-auth plugins are
+ * factory calls (`bearer()`, `twoFactor({ ... })`, `admin()`); the entry's id
+ * is the called function's name. Member-expression callees (`foo.bar()`) and
+ * non-call entries are ignored.
+ */
+const readPluginId = (el: ts.Expression): string | undefined => {
+  if (ts.isCallExpression(el) && ts.isIdentifier(el.expression))
+    return el.expression.text
+  return undefined
+}
+
+/**
+ * Detects `pikkuBetterAuth((services) => betterAuth({...}))` calls.
+ *
+ * `pikkuBetterAuth` is pure: it wraps a factory that returns a configured better-auth
+ * instance and has NO side effects. The user assigns it to an exported binding,
+ * e.g.
+ *
+ *   export const auth = pikkuBetterAuth(async (services) => betterAuth({ ... }))
+ *
+ * The pikku CLI discovers that single export and generates a catch-all
+ * `auth.gen.ts` that wires `${basePath}/**` to one shared handler, registers the
+ * better-auth session middleware, and emits a `wireSecret` for every configured
+ * social provider — so the auth routes and secret requirements flow through
+ * normal inspection into the deploy manifest.
+ *
+ * This add-wiring records the exported binding name, source file, basePath, the
+ * `socialProviders` keys, whether email/password is enabled, and the services
+ * the factory touches. Exactly one `pikkuBetterAuth` is allowed per codebase.
+ */
+export const addAuth: AddWiring = (logger, node, _checker, state) => {
+  if (!ts.isCallExpression(node)) return
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
+    return
 
   const sourceFile = node.getSourceFile().fileName
-  state.auth.files.add(sourceFile)
 
-  if (!providersProp) {
+  // Walk up to the `export const <name> = pikkuBetterAuth(...)` binding.
+  const varDecl = node.parent
+  if (!ts.isVariableDeclaration(varDecl) || !ts.isIdentifier(varDecl.name)) {
+    logger.critical(
+      ErrorCode.AUTH_NOT_EXPORTED,
+      `pikkuBetterAuth(...) must be assigned to an exported const, e.g. \`export const auth = pikkuBetterAuth((services) => betterAuth({...}))\` in ${sourceFile}`
+    )
+    return
+  }
+  const exportName = varDecl.name.text
+
+  // VariableDeclaration -> VariableDeclarationList -> VariableStatement
+  const declList = varDecl.parent
+  const varStatement = declList?.parent
+  const isConst =
+    ts.isVariableDeclarationList(declList) &&
+    (declList.flags & ts.NodeFlags.Const) !== 0
+  const isExported =
+    varStatement &&
+    ts.isVariableStatement(varStatement) &&
+    varStatement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+  if (!isExported || !isConst) {
+    logger.critical(
+      ErrorCode.AUTH_NOT_EXPORTED,
+      `pikkuBetterAuth(...) must be assigned to an exported const so the CLI can import it. Use \`export const ${exportName} = pikkuBetterAuth(...)\` in ${sourceFile}`
+    )
+    return
+  }
+
+  if (state.auth.definition) {
+    logger.critical(
+      ErrorCode.DUPLICATE_AUTH_DEFINITION,
+      `Only one pikkuBetterAuth(...) is allowed per codebase. Found a second in ${sourceFile} (first: ${state.auth.definition.sourceFile}).`
+    )
     return
   }
 
-  if (!ts.isArrayLiteralExpression(providersProp.initializer)) {
+  // The single argument must be the factory: (services) => betterAuth({...}).
+  const factory = node.arguments[0]
+  if (
+    !factory ||
+    (!ts.isArrowFunction(factory) && !ts.isFunctionExpression(factory))
+  ) {
     logger.critical(
       ErrorCode.MISSING_NAME,
-      'wireAuth: providers must be an array literal of string literals.'
+      `pikkuBetterAuth(...) must take a factory function returning betterAuth(...), e.g. \`pikkuBetterAuth((services) => betterAuth({...}))\` in ${sourceFile}`
     )
     return
   }
 
-  for (const element of (providersProp.initializer as ts.ArrayLiteralExpression)
-    .elements) {
-    if (!ts.isStringLiteral(element)) {
-      logger.critical(
-        ErrorCode.NON_LITERAL_WIRE_NAME,
-        `wireAuth: each provider must be a string literal. Found: ${element.getText()}`
-      )
-      return
+  state.auth.files.add(sourceFile)
+
+  // Derive the services the factory touches from its destructured first param —
+  // the same convention as every other pikku wiring. A non-destructured param
+  // yields optimized:false (handler gets all singleton services), with the
+  // standard diagnostic steering the user to destructure.
+  const services: FunctionServicesMeta = extractServicesFromFunction(factory)
+
+  // Find the inner betterAuth({...}) call to read providers/basePath/credentials.
+  let basePath = DEFAULT_BASE_PATH
+  let hasCredentials = false
+  let cookieCache = false
+  const betterAuthCall = findBetterAuthCall(factory)
+  const config = betterAuthCall?.arguments[0]
+
+  if (config && ts.isObjectLiteralExpression(config)) {
+    basePath = readStringProp(config, 'basePath') ?? DEFAULT_BASE_PATH
+
+    // Detect `session.cookieCache.enabled` → drives the stateless middleware split.
+    const session = readObjectProp(config, 'session')
+    if (session) {
+      const cookieCacheBlock = readObjectProp(session, 'cookieCache')
+      if (cookieCacheBlock) {
+        const enabledProp = cookieCacheBlock.properties.find(
+          (p) =>
+            ts.isPropertyAssignment(p) &&
+            (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+            p.name.text === 'enabled'
+        ) as ts.PropertyAssignment | undefined
+        cookieCache =
+          !enabledProp ||
+          enabledProp.initializer.kind !== ts.SyntaxKind.FalseKeyword
+      }
     }
-    if (!state.auth.providers.includes(element.text)) {
-      state.auth.providers.push(element.text)
+
+    const emailAndPassword = readObjectProp(config, 'emailAndPassword')
+    if (emailAndPassword) {
+      // `emailAndPassword: { enabled: true }` — treat a present block without an
+      // explicit `enabled: false` as credentials being available.
+      const enabledProp = emailAndPassword.properties.find(
+        (p) =>
+          ts.isPropertyAssignment(p) &&
+          ts.isIdentifier(p.name) &&
+          p.name.text === 'enabled'
+      ) as ts.PropertyAssignment | undefined
+      hasCredentials =
+        !enabledProp ||
+        enabledProp.initializer.kind !== ts.SyntaxKind.FalseKeyword
     }
+
+    const socialProviders = readObjectProp(config, 'socialProviders')
+    if (socialProviders) {
+      for (const prop of socialProviders.properties) {
+        const key =
+          (ts.isPropertyAssignment(prop) ||
+            ts.isShorthandPropertyAssignment(prop)) &&
+          (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))
+            ? prop.name.text
+            : undefined
+        if (key && !state.auth.providers.includes(key)) {
+          state.auth.providers.push(key)
+        }
+      }
+    }
+
+    const plugins = readArrayProp(config, 'plugins')
+    if (plugins) {
+      for (const el of plugins.elements) {
+        const id = readPluginId(el)
+        if (id && !state.auth.plugins.includes(id)) {
+          state.auth.plugins.push(id)
+        }
+      }
+    }
+  } else {
+    logger.warn(
+      `pikkuBetterAuth in ${sourceFile}: could not statically find a betterAuth({...}) call inside the factory — social provider secrets will not be auto-wired.`
+    )
+  }
+
+  state.auth.definition = {
+    exportName,
+    sourceFile,
+    basePath,
+    hasCredentials,
+    cookieCache,
+    plugins: [...state.auth.plugins],
+    services,
   }
 }

package/src/add/add-cli-renderers.test.ts

@@ -0,0 +1,73 @@
+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 type { InspectorLogger } from '../types.js'
+
+const makeLogger = () =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }) satisfies InspectorLogger
+
+describe('addCLIRenderers inspector', () => {
+  test('extracts destructured renderer services from the callback param', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-cli-renderer-'))
+    const file = join(rootDir, 'cli.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireCLI, pikkuCLIRender } from '@pikku/core/cli'",
+        'export const render = pikkuCLIRender(({ logger }, data) => {',
+        '  logger.info(data.message)',
+        '})',
+        "wireCLI({ program: 'pikku', render, commands: {} })",
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [file], { rootDir })
+      assert.deepEqual(state.cli.meta.renderers['render'], {
+        name: 'render',
+        exportedName: 'render',
+        services: { optimized: true, services: ['logger'] },
+        filePath: file,
+      })
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('marks non-destructured renderer services as unoptimized', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-cli-renderer-all-'))
+    const file = join(rootDir, 'cli.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireCLI, pikkuCLIRender } from '@pikku/core/cli'",
+        'export const render = pikkuCLIRender((services, data) => {',
+        '  services.logger.info(data.message)',
+        '})',
+        "wireCLI({ program: 'pikku', render, commands: {} })",
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [file], { rootDir })
+      assert.deepEqual(state.cli.meta.renderers['render']?.services, {
+        optimized: false,
+        services: [],
+      })
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-cli.ts

@@ -18,6 +18,7 @@ import { getPropertyValue } from '../utils/get-property-value.js'
 import { resolveIdentifier } from '../utils/resolve-identifier.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
+import { extractServicesFromFunction } from '../utils/extract-services.js'
 
 // Track if we've warned about missing Config type to avoid duplicate warnings
 const configTypeWarningShown = new Set<string>()
@@ -924,7 +925,7 @@ export const addCLIRenderers: AddWiring = (
 ) => {
   if (!ts.isCallExpression(node)) return
 
-  const { expression, arguments: args, typeArguments } = node
+  const { expression, arguments: args } = node
 
   // Only handle pikkuCLIRender calls
   if (!ts.isIdentifier(expression) || expression.text !== 'pikkuCLIRender') {
@@ -944,30 +945,13 @@ export const addCLIRenderers: AddWiring = (
   const sourceFile = node.getSourceFile()
   const filePath = sourceFile.fileName
 
-  // Extract services from type parameters (second type param is Services)
-  const services: { optimized: boolean; services: string[] } = {
-    optimized: true,
-    services: [],
-  }
-
-  if (typeArguments && typeArguments.length >= 2) {
-    // Second type parameter is the Services type
-    const servicesTypeNode = typeArguments[1]
-    if (servicesTypeNode) {
-      const servicesType = typeChecker.getTypeFromTypeNode(servicesTypeNode)
-
-      // Extract property names from the Services type
-      const properties = servicesType.getProperties()
-      for (const prop of properties) {
-        services.services.push(prop.getName())
-      }
-
-      // If no specific services found, it might be using the full services object
-      if (properties.length === 0) {
-        services.optimized = false
-      }
-    }
-  }
+  // Renderer service usage is defined by the callback's first parameter shape,
+  // the same way function/auth service usage is tracked elsewhere in the inspector.
+  const renderFunc = args[0]
+  const services =
+    ts.isArrowFunction(renderFunc) || ts.isFunctionExpression(renderFunc)
+      ? extractServicesFromFunction(renderFunc)
+      : { optimized: true, services: [] }
 
   // Store renderer metadata
   inspectorState.cli.meta.renderers[pikkuFuncId] = {

package/src/error-codes.ts

@@ -37,6 +37,10 @@ export enum ErrorCode {
   FUNCTION_METADATA_NOT_FOUND = 'PKU559',
   HANDLER_NOT_RESOLVED = 'PKU568',
 
+  // Auth errors
+  DUPLICATE_AUTH_DEFINITION = 'PKU581',
+  AUTH_NOT_EXPORTED = 'PKU582',
+
   // HTTP Route errors
   ROUTE_PARAM_MISMATCH = 'PKU571',
   ROUTE_QUERY_MISMATCH = 'PKU572',

package/src/index.ts

@@ -3,6 +3,7 @@ export type { TypesMap } from './types-map.js'
 export type * from './types.js'
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js'
 export { ErrorCode } from './error-codes.js'
+export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js'
 export {
   serializeInspectorState,
   deserializeInspectorState,

package/src/inspector.ts

@@ -11,6 +11,7 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
 import {
   aggregateRequiredServices,
+  stampAuthHandlerServices,
   validateAgentModels,
   validateSecretOverrides,
   validateVariableOverrides,
@@ -147,7 +148,9 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     },
     auth: {
       providers: [],
+      plugins: [],
       files: new Set(),
+      definition: null,
     },
     secrets: {
       definitions: [],
@@ -333,6 +336,9 @@ export const inspect = async (
 
   if (!options.setupOnly) {
     const startAggregate = performance.now()
+    // Apply the inspected auth handler service set before aggregation so it
+    // flows into requiredServices (the generated handler's own func is opaque).
+    stampAuthHandlerServices(state)
     aggregateRequiredServices(state)
     logger.debug(
       `Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`

package/src/types.ts

@@ -301,6 +301,41 @@ export interface InspectorDiagnostic {
   position: number
 }
 
+/** A single discovered `export const X = pikkuBetterAuth((services) => betterAuth({...}))`. */
+export interface AuthDefinition {
+  /** The exported binding name the CLI imports (`export const <exportName>`). */
+  exportName: string
+  /** Absolute path of the file declaring it. */
+  sourceFile: string
+  /** better-auth base path (the `basePath` option, default `/api/auth`). */
+  basePath: string
+  /** Whether email/password auth is enabled (`emailAndPassword.enabled`). Written
+   *  into the generated `auth-meta.gen.json` so the console knows credentials are
+   *  available alongside the OAuth providers. */
+  hasCredentials: boolean
+  /** better-auth plugin ids used in the config's `plugins: [...]` array, read
+   *  from each entry's callee name (e.g. `bearer()` → `'bearer'`). Written into
+   *  `auth-meta.gen.json` so the console SSO page can show which plugins are
+   *  enabled. */
+  plugins: string[]
+  /** Whether `session.cookieCache` is enabled — drives the stateless session
+   * middleware split in the auth codegen. Absent/false ⇒ stateful middleware. */
+  cookieCache?: boolean
+  /**
+   * Singleton services the generated auth handler must have available at
+   * runtime — the services the `pikkuBetterAuth` factory reaches for (either
+   * destructured from its first param, or accessed as `services.<name>` in its
+   * body). better-auth's factory typically touches `secrets` and the DB.
+   *
+   * The generated `authHandler` calls `createAuthHandler(...).func`, an opaque
+   * property access the inspector can't see through; without this stamp the
+   * deployed auth worker would instantiate none of these services and the
+   * factory would receive an undefined `kysely`. Re-derived every inspect and
+   * applied to the handler meta before service aggregation runs.
+   */
+  services: FunctionServicesMeta
+}
+
 export interface InspectorState {
   rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
@@ -384,7 +419,12 @@ export interface InspectorState {
   }
   auth: {
     providers: string[]
+    plugins: string[]
     files: Set<string>
+    /** The single `export const X = pikkuBetterAuth({...})` discovered in the
+     *  codebase, if any. The CLI generates the `/auth/*` HTTP wiring from it.
+     *  More than one `pikkuBetterAuth` is a critical error. */
+    definition: AuthDefinition | null
   }
   secrets: {
     definitions: SecretDefinitions

package/src/utils/post-process.ts

@@ -12,6 +12,33 @@ import type {
 } from '@pikku/core'
 import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
+import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
+
+/**
+ * Stamp the inspected authorize/callbacks service set onto the generated auth
+ * handler's function meta.
+ *
+ * The CLI generates `export const authHandler = pikkuSessionlessFunc({ func:
+ * createAuthHandler(...).func })`. That `func` is an opaque property access, so
+ * normal extraction records zero services for the handler — which would leave
+ * the deployed auth worker without `kysely`/`variables`/`secrets` and break
+ * `authorize` at runtime. `add-auth` already computed the real dependency set
+ * (from the pikkuBetterAuth source) into `state.auth.definition.services`; copy it
+ * onto the handler meta. Re-derived every inspect and ordered BEFORE
+ * `aggregateRequiredServices` so it flows into `requiredServices`.
+ */
+export function stampAuthHandlerServices(
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const definition = state.auth.definition
+  if (!definition) return
+  const handlerMeta = state.functions.meta[AUTH_HANDLER_FUNC_ID]
+  if (!handlerMeta) return
+  handlerMeta.services = {
+    optimized: definition.services.optimized,
+    services: [...definition.services.services],
+  }
+}
 
 /**
  * Helper to extract wire-level middleware/permission names from metadata.

package/src/utils/serialize-inspector-state.ts

@@ -183,7 +183,9 @@ export interface SerializableInspectorState {
   }
   auth: {
     providers: string[]
+    plugins: string[]
     files: string[]
+    definition: InspectorState['auth']['definition']
   }
   secrets: {
     definitions: InspectorState['secrets']['definitions']
@@ -389,7 +391,9 @@ export function serializeInspectorState(
     },
     auth: {
       providers: state.auth.providers,
+      plugins: state.auth.plugins,
       files: Array.from(state.auth.files),
+      definition: state.auth.definition,
     },
     secrets: {
       definitions: state.secrets.definitions,
@@ -566,7 +570,9 @@ export function deserializeInspectorState(
     },
     auth: {
       providers: data.auth?.providers || [],
+      plugins: data.auth?.plugins || [],
       files: new Set(data.auth?.files || []),
+      definition: data.auth?.definition || null,
     },
     secrets: {
       definitions: data.secrets?.definitions || [],