@pikku/inspector 0.12.18 → 0.12.20

package/src/add/add-auth.ts

@@ -1,49 +1,250 @@
 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
+}
 
-  const firstArg = node.arguments[0]
-  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+/** 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 providersProp = firstArg.properties.find(
+/** 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 === 'providers'
+      p.name.text === name
   ) as ts.PropertyAssignment | undefined
+  if (prop && ts.isObjectLiteralExpression(prop.initializer))
+    return prop.initializer
+  return undefined
+}
+
+/** 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 === 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
+  const betterAuthCall = findBetterAuthCall(factory)
+  const config = betterAuthCall?.arguments[0]
+
+  if (config && ts.isObjectLiteralExpression(config)) {
+    basePath = readStringProp(config, 'basePath') ?? DEFAULT_BASE_PATH
+
+    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
     }
-    if (!state.auth.providers.includes(element.text)) {
-      state.auth.providers.push(element.text)
+
+    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,
+    plugins: [...state.auth.plugins],
+    services,
   }
 }

package/src/add/pii-check.test.ts

@@ -27,10 +27,15 @@ function makeLogger() {
  * Mirrors what schema.d.ts emits so the TypeScript program sees the correct
  * structural brand type even without @pikku/core being importable from /tmp.
  */
+// Optional `__classification__?` mirrors what @pikku/core and `pikku db migrate`
+// actually emit (optional so plain values stay assignable to branded columns).
+// The `Secret`-in-sessioned-function cases below double as the level-fidelity
+// guard: they only pass if `findPiiPaths` reads the level union-aware
+// ('secret' | undefined), not via a naive `.value`.
 const BRAND_TYPES = `
-type Private<T> = T & { readonly __classification__: 'private' }
-type Pii<T> = T & { readonly __classification__: 'pii' }
-type Secret<T> = T & { readonly __classification__: 'secret' }
+type Private<T> = T & { readonly __classification__?: 'private' }
+type Pii<T> = T & { readonly __classification__?: 'pii' }
+type Secret<T> = T & { readonly __classification__?: 'secret' }
 `
 
 async function runInspect(sourceCode: string) {

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,38 @@ 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[]
+  /**
+   * 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 +416,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/check-pii-output.ts

@@ -29,8 +29,12 @@ export function findPiiPaths(
   seen.add(type)
 
   // ── Is this type itself branded? ─────────────────────────────────────────
-  // Private<T> = T & { readonly __classification__: 'private' }  →  isIntersection()
-  // where one constituent has a `__classification__` property whose type is a string literal.
+  // Private<T> = T & { readonly __classification__?: 'private' }  →  isIntersection()
+  // where one constituent has a `__classification__` property whose type is a
+  // string literal. The marker is OPTIONAL (so plain values stay assignable to
+  // branded columns), which means its resolved type is `'private' | undefined` —
+  // a union, not a bare literal. Read the level union-aware via `literalString`,
+  // otherwise pii/secret silently downgrade to the `'private'` fallback.
   if (type.isIntersection()) {
     for (const t of type.types) {
       const classificationProp = t
@@ -41,9 +45,9 @@ export function findPiiPaths(
           classificationProp.valueDeclaration ??
           classificationProp.declarations?.[0]
         const classification = decl
-          ? ((
-              checker.getTypeOfSymbolAtLocation(classificationProp, decl) as any
-            )?.value ?? 'private')
+          ? (literalString(
+              checker.getTypeOfSymbolAtLocation(classificationProp, decl)
+            ) ?? 'private')
           : 'private'
         return [{ path: path || '<return value>', classification }]
       }
@@ -96,3 +100,21 @@ export function findPiiPaths(
 
   return violations
 }
+
+/**
+ * Recover a string-literal value from a type that may be the literal itself or a
+ * union containing it (e.g. `'private' | undefined`, produced by the optional
+ * `__classification__?` marker). Returns undefined when no string literal is
+ * present so the caller can apply its own fallback.
+ */
+function literalString(type: ts.Type): string | undefined {
+  const value = (type as { value?: unknown }).value
+  if (typeof value === 'string') return value
+  if (type.isUnion()) {
+    for (const member of type.types) {
+      const found = literalString(member)
+      if (found !== undefined) return found
+    }
+  }
+  return undefined
+}

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 || [],