@payload-auth-link/migrate 0.3.1 → 0.4.1

package/src/doctor/database.ts

@@ -1,4 +1,9 @@
 import { Client } from 'pg'
+import {
+  resolveSourceTables,
+  sourceModelNames,
+  type ResolvedSourceTables,
+} from '../importer/types.js'
 import type { DatabaseFinding } from './types.js'
 
 /**
@@ -6,26 +11,18 @@ import type { DatabaseFinding } from './types.js'
  * payload-auth layout's auth tables, unverified users (who will not
  * JIT-link), and orphans. Only an honest SELECT — the doctor never
  * writes.
+ *
+ * Map-aware (issue #68): the ten source models are counted through the
+ * `--source-map` (defaulting to payload-auth's layout), and a mapped
+ * table that is absent comes back in `missingTables` for the caller to
+ * block on — a missing table is never silently reported as 0 rows.
+ * Satellite tables beyond the map (two-factor, passkey, sso, …) stay
+ * informational: apps drop plugins, and only the mapped models gate.
  */
 
-/**
- * The payload-auth 1.9.x Postgres layout (snake_case columns; Payload's
- * drizzle adapter stores hasMany selects as child tables like
- * `users_role`). Tables that don't exist are simply absent from the
- * report — apps customize slugs and drop plugins.
- */
+/** Satellite/extra tables reported when present, never gating. */
 const knownTables: readonly string[] = [
-  'users',
-  'accounts',
-  'sessions',
-  'verifications',
-  'api_keys',
-  'organizations',
-  'members',
-  'invitations',
-  'jwks',
   'admin_invitations',
-  'users_role',
   'two_factors',
   'passkeys',
   'oauth_applications',
@@ -60,70 +57,156 @@ async function columnsOf(client: Client, table: string): Promise<Set<string>> {
   return new Set(result.rows.map((row) => String((row as { column_name: unknown }).column_name)))
 }
 
-export async function introspectDatabase(connectionString: string): Promise<DatabaseFinding> {
+export type IntrospectOptions = {
+  /** Model → source table map (`--source-map`); defaults to the default layout. */
+  readonly sourceTables?: Readonly<Record<string, string | null>> | undefined
+}
+
+export async function introspectDatabase(
+  connectionString: string,
+  options: IntrospectOptions = {}
+): Promise<DatabaseFinding> {
+  const tables: ResolvedSourceTables = resolveSourceTables(options.sourceTables)
   const client = new Client({ connectionString })
   await client.connect()
   try {
-    const tables: { name: string; rows: number }[] = []
+    const counted: { name: string; rows: number }[] = []
+    const missing: { model: string; table: string }[] = []
+
+    // The mapped models count, and a missing mapped table is reported
+    // for the caller to block on (issue #68).
+    for (const model of sourceModelNames) {
+      const table = tables[model]
+      if (table === null) {
+        continue
+      }
+      if (!(await tableExists(client, table))) {
+        missing.push({ model, table })
+        continue
+      }
+      const result = await client.query(`SELECT count(*)::int AS n FROM ${table}`)
+      const first = result.rows[0] as { n?: number } | undefined
+      counted.push({ name: table, rows: first?.n ?? 0 })
+    }
+
+    // Satellite tables: informational when present.
     for (const table of knownTables) {
       if (!(await tableExists(client, table))) {
         continue
       }
-      const counted = await client.query(`SELECT count(*)::int AS n FROM ${table}`)
-      const first = counted.rows[0] as { n?: number } | undefined
-      tables.push({ name: table, rows: first?.n ?? 0 })
+      const result = await client.query(`SELECT count(*)::int AS n FROM ${table}`)
+      const first = result.rows[0] as { n?: number } | undefined
+      counted.push({ name: table, rows: first?.n ?? 0 })
     }
 
     let unverifiedUsers: number | null = null
-    if (await tableExists(client, 'users')) {
-      const columns = await columnsOf(client, 'users')
+    const usersTable = tables['users']
+    if (usersTable !== null && (await tableExists(client, usersTable))) {
+      const columns = await columnsOf(client, usersTable)
       if (columns.has('email_verified')) {
-        const counted = await client.query(
-          'SELECT count(*)::int AS n FROM users WHERE email_verified = false'
+        const result = await client.query(
+          `SELECT count(*)::int AS n FROM ${usersTable} WHERE email_verified = false`
         )
-        const first = counted.rows[0] as { n?: number } | undefined
+        const first = result.rows[0] as { n?: number } | undefined
         unverifiedUsers = first?.n ?? null
       }
     }
 
     const orphans: { kind: string; count: number }[] = []
-    const orphanChecks: readonly { kind: string; table: string; column: string; target: string }[] =
-      [
-        { kind: 'accounts-without-user', table: 'accounts', column: 'user_id', target: 'users' },
-        {
-          kind: 'members-without-org',
-          table: 'members',
-          column: 'organization_id',
-          target: 'organizations',
-        },
-        { kind: 'members-without-user', table: 'members', column: 'user_id', target: 'users' },
-        {
-          kind: 'invitations-without-org',
-          table: 'invitations',
-          column: 'organization_id',
-          target: 'organizations',
-        },
-      ]
+    const skippedChecks: string[] = []
+    const orphanChecks: readonly {
+      kind: string
+      table: string | null
+      column: string
+      target: string | null
+    }[] = [
+      {
+        kind: 'accounts-without-user',
+        table: tables['accounts'],
+        column: 'user_id',
+        target: usersTable,
+      },
+      {
+        kind: 'members-without-org',
+        table: tables['members'],
+        column: 'organization_id',
+        target: tables['organizations'],
+      },
+      {
+        kind: 'members-without-user',
+        table: tables['members'],
+        column: 'user_id',
+        target: usersTable,
+      },
+      {
+        kind: 'invitations-without-org',
+        table: tables['invitations'],
+        column: 'organization_id',
+        target: tables['organizations'],
+      },
+    ]
     for (const check of orphanChecks) {
+      if (check.table === null || check.target === null) {
+        skippedChecks.push(`${check.kind}: skipped — a mapped model is null-mapped (not installed)`)
+        continue
+      }
       if (
         (await tableExists(client, check.table)) &&
         (await tableExists(client, check.target)) &&
         (await columnsOf(client, check.table)).has(check.column)
       ) {
-        const counted = await client.query(
+        const result = await client.query(
           `SELECT count(*)::int AS n FROM ${check.table}
            WHERE ${check.column} IS NOT NULL
              AND NOT EXISTS (SELECT 1 FROM ${check.target} t WHERE t.id = ${check.table}.${check.column})`
         )
-        const first = counted.rows[0] as { n?: number } | undefined
+        const first = result.rows[0] as { n?: number } | undefined
         const count = first?.n ?? 0
         if (count > 0) {
           orphans.push({ kind: check.kind, count })
         }
+      } else {
+        skippedChecks.push(`${check.kind}: skipped — a table or column involved is absent`)
+      }
+    }
+
+    // api keys: the owner column is named per layout — probe it
+    // (issue #68: `reference_id` on current layouts, `user_id` on 1.6).
+    const apiKeysTable = tables['api_keys']
+    if (apiKeysTable === null) {
+      skippedChecks.push('api-keys-without-user: skipped — the model is null-mapped')
+    } else if (!(await tableExists(client, apiKeysTable))) {
+      if (!missing.some((entry) => entry.model === 'api_keys')) {
+        skippedChecks.push(`api-keys-without-user: skipped — table '${apiKeysTable}' is absent`)
+      }
+    } else {
+      const columns = await columnsOf(client, apiKeysTable)
+      const column = columns.has('reference_id')
+        ? 'reference_id'
+        : columns.has('user_id')
+          ? 'user_id'
+          : null
+      if (column === null || usersTable === null) {
+        skippedChecks.push(
+          `api-keys-without-user: skipped — neither 'reference_id' nor 'user_id' exists on '${apiKeysTable}'`
+        )
+      } else {
+        // Text casts on both sides: the owner column may be varchar
+        // (reference_id) or integer (1.6-era user_id).
+        const result = await client.query(
+          `SELECT count(*)::int AS n FROM ${apiKeysTable}
+           WHERE ${column} IS NOT NULL
+             AND NOT EXISTS (SELECT 1 FROM ${usersTable} t WHERE t.id::text = ${apiKeysTable}.${column}::text)`
+        )
+        const first = result.rows[0] as { n?: number } | undefined
+        const count = first?.n ?? 0
+        if (count > 0) {
+          orphans.push({ kind: 'api-keys-without-user', count })
+        }
       }
     }
 
-    return { tables, unverifiedUsers, orphans }
+    return { tables: counted, unverifiedUsers, orphans, missingTables: missing, skippedChecks }
   } finally {
     await client.end()
   }

package/src/doctor/plugins.ts

@@ -1,4 +1,7 @@
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
 import type { PluginFinding } from './types.js'
+import { listSourceFiles } from './source-scan.js'
 
 /**
  * Better Auth plugin classification (issue #52): for each plugin the
@@ -193,9 +196,17 @@ const callNameToPlugin: Readonly<Record<string, string>> = {
   nextCookies: 'next-cookies',
   tanstackStartCookies: 'tanstack-start-cookies',
   oidcProvider: 'oidcProvider',
+  mcp: 'mcp',
   passkey: 'passkey',
   apiKey: 'api-key',
   sso: 'sso',
+  multiSession: 'multi-session',
+  bearer: 'bearer',
+  oneTimeToken: 'one-time-token',
+  siwe: 'siwe',
+  expo: 'expo',
+  deviceAuthorization: 'device-authorization',
+  subscriptions: 'subscriptions',
 }
 
 /**
@@ -214,3 +225,43 @@ export function pluginsFromConfigSource(configSource: string): string[] {
   }
   return [...ids].sort()
 }
+
+/** One plugin factory call found in a source file. */
+export type PluginSourceHit = {
+  /** The Better Auth plugin id (or payload-auth-era name). */
+  readonly id: string
+  /** The file it was found in, relative to the scanned root. */
+  readonly file: string
+}
+
+/**
+ * Plugin factory calls across the WHOLE source tree (issue #71), not
+ * just the config file: a mid-upgrade app calls `admin(...)` or
+ * `oidcProvider(...)` in helpers too, and a schema-adding plugin that
+ * hides in a non-config file changes what the migration must carry.
+ * Same walk/skip rules as the source scan.
+ */
+export function pluginsFromSourceTree(srcDir: string): readonly PluginSourceHit[] {
+  const hits: PluginSourceHit[] = []
+  const seen = new Set<string>()
+  for (const file of listSourceFiles(srcDir)) {
+    let content: string
+    try {
+      content = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    for (const [call, id] of Object.entries(callNameToPlugin)) {
+      const pattern = new RegExp(`\\b${call}\\s*\\(`)
+      if (pattern.test(content)) {
+        const rel = relative(srcDir, file)
+        const key = `${id}\n${rel}`
+        if (!seen.has(key)) {
+          seen.add(key)
+          hits.push({ id, file: rel })
+        }
+      }
+    }
+  }
+  return hits
+}

package/src/doctor/run-doctor.ts

@@ -4,10 +4,16 @@ import { dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { checkVersions } from './bands.js'
 import { introspectDatabase } from './database.js'
-import { classifyPlugins, pluginsFromCollectionSlugs, pluginsFromConfigSource } from './plugins.js'
+import {
+  classifyPlugins,
+  pluginsFromCollectionSlugs,
+  pluginsFromConfigSource,
+  pluginsFromSourceTree,
+} from './plugins.js'
 import { scanSource } from './source-scan.js'
 import { analyzeUsersCollection, findUsersCollection } from './users.js'
-import type { BehaviourChange, DoctorIssue, DoctorReport } from './types.js'
+import { parseSourceMapJson, resolveSourceTables } from '../importer/types.js'
+import type { BehaviourChange, DoctorIssue, DoctorReport, PluginFinding } from './types.js'
 
 /**
  * The read-only doctor (issue #52): point it at a payload-auth app and
@@ -16,6 +22,12 @@ import type { BehaviourChange, DoctorIssue, DoctorReport } from './types.js'
  * Auth plugins, scans the source tree for call sites that must
  * migrate, and (with a database URL) reports row counts, unverified
  * users, and orphans. It never writes.
+ *
+ * Never crashes (issue #71): a config that cannot even be IMPORTED
+ * (the mid-upgrade state — better-auth 1.7 installed while the config
+ * still calls `oidcProvider`) is a `config-unloadable` blocker, not a
+ * crash. The static scans (config text, source tree, database) still
+ * run and still catch what the load cannot.
  */
 
 export type DoctorOptions = {
@@ -25,6 +37,11 @@ export type DoctorOptions = {
   readonly srcDir?: string | undefined
   /** Postgres connection string. Defaults to `DATABASE_URL`. */
   readonly databaseUrl?: string | undefined
+  /**
+   * The `--source-map` JSON (issue #68): model → source table name, or
+   * `null` for "model not installed". Shapes the database section.
+   */
+  readonly sourceMapJson?: string | undefined
   /** Config loader, injectable for tests. Defaults to dynamic import. */
   readonly loadModule?: ((path: string) => Promise<unknown>) | undefined
 }
@@ -141,7 +158,6 @@ async function defaultLoadModule(path: string): Promise<unknown> {
 export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   const configPath = resolve(options.configPath)
   const loadModule = options.loadModule ?? defaultLoadModule
-  const config = await loadModule(configPath)
   const configDir = dirname(configPath)
   const srcDir = options.srcDir === undefined ? configDir : resolve(options.srcDir)
 
@@ -162,8 +178,25 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     }
   }
 
-  const plugin = findPayloadAuthPlugin(config)
-  if (plugin === null) {
+  // Issue #71: the load can fail on the mid-upgrade state (better-auth
+  // 1.7 installed while the config still calls `oidcProvider`). That is
+  // a blocker — never a crash — and the static scans below still run.
+  let config: unknown = null
+  let configLoaded = true
+  try {
+    config = await loadModule(configPath)
+  } catch (error) {
+    configLoaded = false
+    blockers.push({
+      code: 'config-unloadable',
+      detail: `the config module could not be loaded: ${
+        error instanceof Error ? error.message : String(error)
+      } — fix the load error before migrating; the report below still reflects the static scans`,
+    })
+  }
+
+  const plugin = configLoaded ? findPayloadAuthPlugin(config) : null
+  if (configLoaded && plugin === null) {
     warnings.push({
       code: 'payload-auth-not-detected',
       detail:
@@ -179,22 +212,35 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   }
 
   // payload-auth keeps the builder's options in its closure, so the
-  // plugin set comes from what the built config proves: the collections
-  // payload-auth created and the plugin calls in the config source.
+  // plugin set comes from what the sources prove: the collections
+  // payload-auth built, the plugin calls in the config source, AND the
+  // plugin calls anywhere under --src (issue #71 — schema-adding
+  // plugins hide in helper files too).
   let configSource: string
   try {
     configSource = readFileSync(configPath, 'utf8')
   } catch {
     configSource = ''
   }
+  const sourceTreeHits = pluginsFromSourceTree(srcDir)
+  const filesById = new Map<string, string[]>()
+  for (const hit of sourceTreeHits) {
+    const list = filesById.get(hit.id) ?? []
+    list.push(hit.file)
+    filesById.set(hit.id, list)
+  }
   const pluginIds = [
     ...new Set([
-      ...betterAuthPluginIds(plugin?.pluginOptions ?? {}),
-      ...pluginsFromCollectionSlugs(collectionSlugs(config)),
+      ...(configLoaded ? betterAuthPluginIds(plugin?.pluginOptions ?? {}) : []),
+      ...(configLoaded ? pluginsFromCollectionSlugs(collectionSlugs(config)) : []),
       ...pluginsFromConfigSource(configSource),
+      ...sourceTreeHits.map((hit) => hit.id),
     ]),
   ]
-  const pluginFindings = classifyPlugins(pluginIds)
+  const pluginFindings: PluginFinding[] = classifyPlugins(pluginIds).map((finding) => {
+    const files = filesById.get(finding.id)
+    return files === undefined ? finding : { ...finding, files }
+  })
   for (const finding of pluginFindings) {
     if (finding.status === 'removed-upstream') {
       blockers.push({
@@ -206,20 +252,24 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     }
   }
 
-  const usersSlug = usersSlugOf(plugin?.pluginOptions ?? {})
-  const { finding: users, issues: userIssues } = analyzeUsersCollection(
-    findUsersCollection(config, usersSlug),
-    'roles'
-  )
-  for (const issue of userIssues) {
-    if (
-      issue.code === 'injected-field-collision' ||
-      issue.code === 'roles-field-not-select' ||
-      issue.code === 'users-collection-missing'
-    ) {
-      blockers.push(issue)
-    } else {
-      warnings.push(issue)
+  let users: DoctorReport['users'] = null
+  if (configLoaded) {
+    const usersSlug = usersSlugOf(plugin?.pluginOptions ?? {})
+    const { finding, issues: userIssues } = analyzeUsersCollection(
+      findUsersCollection(config, usersSlug),
+      'roles'
+    )
+    users = finding
+    for (const issue of userIssues) {
+      if (
+        issue.code === 'injected-field-collision' ||
+        issue.code === 'roles-field-not-select' ||
+        issue.code === 'users-collection-missing'
+      ) {
+        blockers.push(issue)
+      } else {
+        warnings.push(issue)
+      }
     }
   }
 
@@ -237,7 +287,11 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let database: DoctorReport['database'] = null
   if (databaseUrl !== undefined && databaseUrl !== '') {
     try {
-      const found = await introspectDatabase(databaseUrl)
+      const sourceTables =
+        options.sourceMapJson === undefined
+          ? undefined
+          : resolveSourceTables(parseSourceMapJson(options.sourceMapJson))
+      const found = await introspectDatabase(databaseUrl, { sourceTables })
       database = found
       if (found.unverifiedUsers !== null && found.unverifiedUsers > 0) {
         warnings.push({
@@ -245,12 +299,23 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
           detail: `${found.unverifiedUsers} user(s) have emailVerified = false: they will not JIT-link on a provider sign-in; they need a verified email (or a role manager's manual link) after migration`,
         })
       }
+      // Fail closed on the source layout (issue #68): a mapped model
+      // whose table is absent blocks until --source-map explains it.
+      for (const table of found.missingTables ?? []) {
+        blockers.push({
+          code: 'source-table-missing',
+          detail: `model '${table.model}' expects source table '${table.table}', which does not exist — if your layout renamed it, pass --source-map '{"${table.model}":"<table>"}', or map it null to record it as not installed`,
+        })
+      }
       for (const orphan of found.orphans) {
         blockers.push({
           code: 'orphan-rows',
           detail: `${orphan.count} orphaned row(s) of kind '${orphan.kind}': the importer refuses unmappable references rather than silently skipping them`,
         })
       }
+      for (const skip of found.skippedChecks ?? []) {
+        warnings.push({ code: 'orphan-check-skipped', detail: skip })
+      }
     } catch (error) {
       warnings.push({
         code: 'database-unreachable',

package/src/doctor/source-scan.ts

@@ -74,6 +74,16 @@ function walk(dir: string, into: string[]): void {
   }
 }
 
+/**
+ * Every scannable file under `dir` — the walk/skip rules the source
+ * scan uses, shared with the plugin factory scan (issue #71).
+ */
+export function listSourceFiles(dir: string): readonly string[] {
+  const files: string[] = []
+  walk(dir, files)
+  return files
+}
+
 export function scanSource(srcDir: string): SourceFinding[] {
   const files: string[] = []
   walk(srcDir, files)

package/src/doctor/types.ts

@@ -29,6 +29,8 @@ export type PluginFinding = {
   readonly id: string
   readonly status: 'supported' | 'auto-declarable' | 'unprobed' | 'unsupported' | 'removed-upstream'
   readonly detail: string
+  /** Files under `--src` whose source names this plugin (issue #71). */
+  readonly files?: readonly string[]
 }
 
 /** The users collection, as the migration will meet it. */
@@ -71,6 +73,13 @@ export type DatabaseFinding = {
   /** Users with `emailVerified = false` — they will not JIT-link. */
   readonly unverifiedUsers: number | null
   readonly orphans: readonly { readonly kind: string; readonly count: number }[]
+  /**
+   * Mapped source models whose table is absent (issue #68) — blockers
+   * unless `--source-map` records the model as not installed.
+   */
+  readonly missingTables?: readonly { readonly model: string; readonly table: string }[]
+  /** Orphan checks that could not run, with the reason (issue #68). */
+  readonly skippedChecks?: readonly string[]
 }
 
 /** Default-behaviour changes in payload-auth-link 0.7.0 that bite. */

package/src/exporters.ts

@@ -39,6 +39,46 @@ export type ExportResult = {
   /** The JSONL document: one JSON object per line, `{"table": …, "row": …}`. */
   readonly jsonl: string
   readonly totalRows: number
+  /**
+   * Requested tables that do not exist on the source (issue #68). The
+   * caller decides policy: `--tables` names must abort (exit 1),
+   * default-list gaps are reported but tolerated.
+   */
+  readonly missing: readonly string[]
+}
+
+/**
+ * The `--tables` flag value (issue #68): a JSON array of table names or
+ * a comma-separated list of table names. Anything else is a usage error.
+ */
+const tableName = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+export function parseExportTables(value: string): readonly string[] {
+  const trimmed = value.trim()
+  const reject = (): never => {
+    throw new Error('--tables must be a JSON array of table names or a comma-separated list')
+  }
+  if (trimmed === '') {
+    return reject()
+  }
+  if (trimmed.startsWith('[')) {
+    const parsed: unknown = JSON.parse(trimmed)
+    if (
+      !Array.isArray(parsed) ||
+      parsed.some((entry) => typeof entry !== 'string' || !tableName.test(entry.trim()))
+    ) {
+      return reject()
+    }
+    return (parsed as string[]).map((entry) => entry.trim())
+  }
+  const names = trimmed
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '')
+  if (names.length === 0 || names.some((entry) => !tableName.test(entry))) {
+    return reject()
+  }
+  return names
 }
 
 /** Export the auth tables to lossless JSONL (issue #58). */
@@ -49,6 +89,7 @@ export async function exportToJsonl(options: ExportOptions): Promise<ExportResul
   try {
     const lines: string[] = []
     const exported: { name: string; rows: number }[] = []
+    const missing: string[] = []
     let totalRows = 0
     for (const table of tables) {
       const exists = await client.query(
@@ -56,6 +97,10 @@ export async function exportToJsonl(options: ExportOptions): Promise<ExportResul
         [table]
       )
       if (exists.rows.length === 0) {
+        // Nothing is silently omitted (issue #68): every absent table
+        // is logged and lands in `missing` for the caller's policy.
+        missing.push(table)
+        options.log?.(`table '${table}' does not exist on the source — not exported`)
         continue
       }
       // Export EVERY column raw (JSON types preserved by ::jsonb cast
@@ -70,7 +115,7 @@ export async function exportToJsonl(options: ExportOptions): Promise<ExportResul
       }
     }
     options.log?.(`exported ${totalRows} row(s) across ${exported.length} table(s)`)
-    return { tables: exported, jsonl: `${lines.join('\n')}\n`, totalRows }
+    return { tables: exported, jsonl: `${lines.join('\n')}\n`, totalRows, missing }
   } finally {
     await client.end()
   }