@payload-auth-link/migrate 0.4.2 → 0.5.0

package/src/cli.ts

@@ -9,16 +9,19 @@
  * the `--json` echo of what the caller passed, and secrets inside them
  * are the caller's own input.
  */
+import type * as Codemods from './codemods.js'
 import { runDoctor } from './doctor/run-doctor.js'
 import type { DoctorReport } from './doctor/types.js'
 import {
+  runAdoptPrelink,
   runFinalize,
   runFromPayloadAuth,
   runRollback,
   runVerify,
   type ImportCommandOptions,
 } from './importer/run-import.js'
-import { applyCodemods } from './codemods.js'
+import { summarizePlanRows } from './importer/apply.js'
+import { writePrivateFile } from './private-file.js'
 import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { extname, join, relative } from 'node:path'
 
@@ -73,6 +76,12 @@ Commands:
                     [--source-map '{"accounts":"user_accounts","sessions":"user_sessions"}']
   rollback          --config ./src/payload.config.ts [--manifest ...]
   finalize          [--manifest ...]
+  adopt-prelink     --config ./src/payload.config.ts [--apply] [--json]
+                    [--manifest ./payload-auth-link-prelink.json]
+                    [--users-slug users] [--verified-field emailVerified]
+                    (adopt mode: one better-auth identity per user, plus the
+                    linking proof for verified emails; undo with
+                    rollback --manifest ./payload-auth-link-prelink.json)
 
   --source-map renames source models to your layout's tables (custom
   slugs like user_accounts/user_sessions); a null value records a
@@ -93,6 +102,12 @@ Commands:
   rollback undoes exactly the manifest; finalize marks it read-only
   so the legacy tables may be dropped later, in their own migration.
 
+  The manifest lands in the CURRENT DIRECTORY unless --manifest says
+  otherwise. It holds ids and sealed values only (no emails in the
+  clear; sealed with the app's PAYLOAD_SECRET, so rollback must run
+  against the same app) and is written with mode 0600. Delete it once
+  the migration is finalized and your soak window has passed.
+
   codemod rewrites the three named payload-auth call-site patterns
   (getPayloadAuth, payload.betterAuth.api.getSession, toNextJsHandler)
   and reports what needs a human. Dry run by default; --write rewrites.
@@ -169,6 +184,17 @@ function formatReport(report: DoctorReport): string {
     if (report.database.unverifiedUsers !== null) {
       lines.push(`  unverified users: ${report.database.unverifiedUsers}`)
     }
+    if (report.database.bannedUsers !== undefined && report.database.bannedUsers !== null) {
+      lines.push(`  banned users: ${report.database.bannedUsers}`)
+    }
+    if (report.database.anonymousUsers !== undefined && report.database.anonymousUsers !== null) {
+      lines.push(`  anonymous users: ${report.database.anonymousUsers}`)
+    }
+    if ((report.database.oauthTables ?? []).length > 0) {
+      lines.push(
+        `  oauth_* tables (NOT carried by the importer): ${(report.database.oauthTables ?? []).join(', ')}`
+      )
+    }
     for (const orphan of report.database.orphans) {
       lines.push(`  ORPHANS ${orphan.kind}: ${orphan.count}`)
     }
@@ -216,9 +242,18 @@ async function main(
     'verify',
     'rollback',
     'finalize',
+    'adopt-prelink',
     'codemod',
     'export',
   ]
+  const json = flags.get('json') === true
+  // Every command prints (issue #88): progress and the summary go to
+  // stdout; --json replaces the human lines with one JSON document.
+  const log = (message: string): void => {
+    if (!json) {
+      out.write(`${message}\n`)
+    }
+  }
   if (command !== 'doctor' && !importCommands.includes(command)) {
     err.write(`unknown command '${command}'\n\n${usage()}`)
     return 3
@@ -263,7 +298,9 @@ async function main(
         return 1
       }
       if (typeof flags.get('out') === 'string') {
-        writeFileSync(flags.get('out') as string, result.jsonl)
+        // The export carries credential material (password hashes, OAuth
+        // tokens, sessions, API keys, JWKS private keys): owner-only.
+        writePrivateFile(flags.get('out') as string, result.jsonl)
         out.write(`wrote ${result.totalRows} row(s) to ${String(flags.get('out'))}\n`)
       } else {
         out.write(result.jsonl)
@@ -280,6 +317,10 @@ async function main(
       }
       const srcDir = new URL(srcFlag, `file://${process.cwd()}/`).pathname
       const write = flags.get('write') === true
+      // Lazy: the codemods parse with the TypeScript compiler API
+      // (~24 MB). Only this command loads it; importing the package
+      // (or running doctor/import/export) never does.
+      const codemods: typeof Codemods = await import('./codemods.js')
       const changed: string[] = []
       const manual: string[] = []
       const walk = (dir: string): void => {
@@ -304,7 +345,7 @@ async function main(
             walk(full)
           } else if (['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs'].includes(extname(entry))) {
             const before = readFileSync(full, 'utf8')
-            const result = applyCodemods(relative(srcDir, full), before)
+            const result = codemods.applyCodemods(relative(srcDir, full), before)
             if (result.changed) {
               if (write) {
                 writeFileSync(full, result.after)
@@ -331,11 +372,15 @@ async function main(
     // finalize [--manifest ...]
     // (no --config: manifest-only; no Payload instance is loaded)
     if (command === 'finalize') {
-      await runFinalize(
-        typeof flags.get('manifest') === 'string'
+      const finalized = await runFinalize({
+        log,
+        ...(typeof flags.get('manifest') === 'string'
           ? { manifestPath: flags.get('manifest') as string }
-          : {}
-      )
+          : {}),
+      })
+      if (json) {
+        out.write(`${JSON.stringify({ finalized: finalized.finalized })}\n`)
+      }
       return 0
     }
     // The remaining commands (from-payload-auth, verify, rollback) all
@@ -345,6 +390,29 @@ async function main(
       err.write(`${command} requires --config <path to payload.config.ts>\n`)
       return 3
     }
+    if (command === 'adopt-prelink') {
+      const usersSlug = flags.get('users-slug')
+      const verifiedField = flags.get('verified-field')
+      const result = await runAdoptPrelink({
+        configPath: new URL(configFlag, `file://${process.cwd()}/`).pathname,
+        apply: flags.get('apply') === true,
+        json,
+        log,
+        ...(typeof flags.get('manifest') === 'string'
+          ? { manifestPath: flags.get('manifest') as string }
+          : {}),
+        ...(typeof usersSlug === 'string' ? { usersSlug } : {}),
+        ...(typeof verifiedField === 'string' ? { verifiedField } : {}),
+      })
+      if (json) {
+        out.write(`${JSON.stringify(result, null, 2)}\n`)
+      }
+      if (result.unmappable.length > 0) {
+        err.write(`ABORT: ${result.unmappable.length} unmappable user(s); nothing was written\n`)
+        return 1
+      }
+      return 0
+    }
     if ((command === 'from-payload-auth' || command === 'verify') && databaseUrl === '') {
       err.write(`${command} requires --database-url or DATABASE_URL\n`)
       return 3
@@ -365,10 +433,29 @@ async function main(
       ...(typeof flags.get('source-map') === 'string'
         ? { sourceMapJson: flags.get('source-map') as string }
         : {}),
-      json: flags.get('json') === true,
+      json,
+      log,
     }
     if (command === 'from-payload-auth') {
       const outcome = await runFromPayloadAuth(importOptions)
+      if (json) {
+        out.write(
+          `${JSON.stringify(
+            {
+              exitCode: outcome.exitCode,
+              created: outcome.result?.created ?? 0,
+              skipped: outcome.result?.skipped ?? 0,
+              fieldWrites: outcome.result?.fieldWrites ?? 0,
+              rows: summarizePlanRows(outcome.plan.rows),
+              unmappable: outcome.plan.unmappable,
+              warnings: outcome.plan.warnings,
+              unverified: outcome.unverified.length,
+            },
+            null,
+            2
+          )}\n`
+        )
+      }
       if (outcome.plan.unmappable.length > 0) {
         err.write(
           `ABORT: ${outcome.plan.unmappable.length} unmappable row(s); nothing was silently skipped\n`
@@ -379,10 +466,16 @@ async function main(
     }
     if (command === 'verify') {
       const result = await runVerify(importOptions)
+      if (json) {
+        out.write(`${JSON.stringify(result, null, 2)}\n`)
+      }
       return result.ok ? 0 : 1
     }
     if (command === 'rollback') {
-      await runRollback(importOptions)
+      const undone = await runRollback(importOptions)
+      if (json) {
+        out.write(`${JSON.stringify(undone)}\n`)
+      }
       return 0
     }
   }
@@ -423,7 +516,16 @@ const invokedDirectly =
 if (invokedDirectly) {
   main(process.argv.slice(2))
     .then((code) => {
+      // Every resource the command opened is closed by now (issue #88:
+      // Payload destroyed, pg clients ended); exit explicitly anyway,
+      // after stdout/stderr drain, so a third-party handle in the app's
+      // config (a cron, a websocket) can never park a finished CLI.
       process.exitCode = code
+      process.stdout.write('', () => {
+        process.stderr.write('', () => {
+          process.exit(code)
+        })
+      })
     })
     .catch((error: unknown) => {
       // Name the command that failed (issue #71) — 'doctor failed:' was

package/src/doctor/database.ts

@@ -100,18 +100,41 @@ export async function introspectDatabase(
     }
 
     let unverifiedUsers: number | null = null
+    let bannedUsers: number | null = null
+    let anonymousUsers: number | null = null
     const usersTable = tables['users']
     if (usersTable !== null && (await tableExists(client, usersTable))) {
       const columns = await columnsOf(client, usersTable)
-      if (columns.has('email_verified')) {
+      const countWhere = async (predicate: string): Promise<number | null> => {
         const result = await client.query(
-          `SELECT count(*)::int AS n FROM ${usersTable} WHERE email_verified = false`
+          `SELECT count(*)::int AS n FROM ${usersTable} WHERE ${predicate}`
         )
         const first = result.rows[0] as { n?: number } | undefined
-        unverifiedUsers = first?.n ?? null
+        return first?.n ?? null
+      }
+      if (columns.has('email_verified')) {
+        unverifiedUsers = await countWhere('email_verified = false')
+      }
+      // Better Auth plugin state the import must carry (issue #88).
+      if (columns.has('banned')) {
+        bannedUsers = await countWhere('banned = true')
+      }
+      if (columns.has('is_anonymous')) {
+        anonymousUsers = await countWhere('is_anonymous = true')
       }
     }
 
+    // OAuth-provider plugin tables (oauthProvider / oidcProvider /
+    // mcp): the importer does not carry them (issue #88).
+    const oauthResult = await client.query(
+      `SELECT table_name FROM information_schema.tables
+       WHERE table_schema = 'public' AND table_name LIKE 'oauth\\_%'
+       ORDER BY table_name`
+    )
+    const oauthTables = oauthResult.rows.map((row) =>
+      String((row as { table_name: unknown }).table_name)
+    )
+
     const orphans: { kind: string; count: number }[] = []
     const skippedChecks: string[] = []
     const orphanChecks: readonly {
@@ -206,7 +229,16 @@ export async function introspectDatabase(
       }
     }
 
-    return { tables: counted, unverifiedUsers, orphans, missingTables: missing, skippedChecks }
+    return {
+      tables: counted,
+      unverifiedUsers,
+      orphans,
+      missingTables: missing,
+      skippedChecks,
+      bannedUsers,
+      anonymousUsers,
+      oauthTables,
+    }
   } finally {
     await client.end()
   }

package/src/doctor/run-doctor.ts

@@ -143,6 +143,29 @@ export function collectionSlugs(config: unknown): string[] {
     .filter((slug): slug is string => typeof slug === 'string')
 }
 
+/**
+ * Top-level field names of one collection in the loaded config, or
+ * `null` when the config declares no such collection.
+ */
+function collectionFieldNames(config: unknown, slug: string): Set<string> | null {
+  if (!isRecord(config) || !Array.isArray(config.collections)) {
+    return null
+  }
+  const collection = config.collections.find(
+    (entry): entry is Record<string, unknown> => isRecord(entry) && entry.slug === slug
+  )
+  if (collection === undefined || !Array.isArray(collection.fields)) {
+    return null
+  }
+  const names = new Set<string>()
+  for (const field of collection.fields) {
+    if (isRecord(field) && typeof field.name === 'string') {
+      names.add(field.name)
+    }
+  }
+  return names
+}
+
 /** Default config loader: a dynamic import of the TS/JS config module. */
 async function defaultLoadModule(path: string): Promise<unknown> {
   const mod: unknown = await import(pathToFileURL(path).href)
@@ -241,6 +264,13 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     const files = filesById.get(finding.id)
     return files === undefined ? finding : { ...finding, files }
   })
+  if (pluginIds.includes('generic-oauth')) {
+    warnings.push({
+      code: 'generic-oauth-providers',
+      detail:
+        "genericOAuth() is declared: its provider list lives in the engine options, not the database — carry every `config` entry (providerId, discovery URL, client id/secret, scopes) into the new engine's genericOAuth() call. The importer copies the accounts rows (provider_id stays), so a provider missing from the new config strands those users' sign-in",
+    })
+  }
   for (const finding of pluginFindings) {
     if (finding.status === 'removed-upstream') {
       blockers.push({
@@ -316,6 +346,45 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
       for (const skip of found.skippedChecks ?? []) {
         warnings.push({ code: 'orphan-check-skipped', detail: skip })
       }
+      // Better Auth plugin state and tables the migration must account
+      // for (issue #88). When the loaded config is the TARGET (it
+      // declares the engine's ba-users collection), a target that
+      // cannot hold the state is a blocker — the importer refuses it.
+      const baUsersFields = configLoaded ? collectionFieldNames(config, 'ba-users') : null
+      const banned = found.bannedUsers ?? 0
+      if (banned > 0) {
+        if (baUsersFields !== null && !baUsersFields.has('banned')) {
+          blockers.push({
+            code: 'target-cannot-hold-bans',
+            detail: `${banned} banned user(s) on the source, but this config's ba-users collection declares no 'banned' field — add Better Auth's admin() plugin to the engine (autoDeclare derives banned/banReason/banExpires); the importer refuses to import a banned user unbanned`,
+          })
+        } else {
+          warnings.push({
+            code: 'banned-users',
+            detail: `${banned} banned user(s) (Better Auth admin plugin): the importer carries banned/banReason/banExpires onto ba-users only when the target engine declares admin(), and refuses the run otherwise — a banned user never imports unbanned`,
+          })
+        }
+      }
+      const anonymous = found.anonymousUsers ?? 0
+      if (anonymous > 0) {
+        if (baUsersFields !== null && !baUsersFields.has('isAnonymous')) {
+          blockers.push({
+            code: 'target-cannot-hold-anonymous',
+            detail: `${anonymous} anonymous user(s) on the source, but this config's ba-users collection declares no 'isAnonymous' field — add Better Auth's anonymous() plugin to the engine, or delete the anonymous users before importing`,
+          })
+        } else {
+          warnings.push({
+            code: 'anonymous-users',
+            detail: `${anonymous} anonymous user(s) (Better Auth anonymous plugin): they import with isAnonymous only when the target engine declares anonymous(), and the plugin refuses anonymous sessions by design — they never JIT-link to a Payload document`,
+          })
+        }
+      }
+      if ((found.oauthTables ?? []).length > 0) {
+        warnings.push({
+          code: 'oauth-tables-not-carried',
+          detail: `OAuth-provider tables present (${(found.oauthTables ?? []).join(', ')}): the importer does NOT copy them — registered OAuth clients, consents, and issued tokens stay in the legacy tables. Re-register the clients on @better-auth/oauth-provider (a separate schema migration) before dropping the legacy tables`,
+        })
+      }
     } catch (error) {
       warnings.push({
         code: 'database-unreachable',

package/src/doctor/types.ts

@@ -80,6 +80,18 @@ export type DatabaseFinding = {
   readonly missingTables?: readonly { readonly model: string; readonly table: string }[]
   /** Orphan checks that could not run, with the reason (issue #68). */
   readonly skippedChecks?: readonly string[]
+  /**
+   * Users banned by Better Auth's admin plugin (`banned = true`), or
+   * `null` when the source has no `banned` column (issue #88).
+   */
+  readonly bannedUsers?: number | null
+  /** Anonymous-plugin users (`is_anonymous = true`), or `null` (issue #88). */
+  readonly anonymousUsers?: number | null
+  /**
+   * OAuth-provider plugin tables present (`oauth_*`, issue #88). The
+   * importer does NOT carry them; the doctor says so explicitly.
+   */
+  readonly oauthTables?: readonly string[]
 }
 
 /** Default-behaviour changes in payload-auth-link 0.7.0 that bite. */

package/src/doctor/users.ts

@@ -98,6 +98,15 @@ export function localStrategyOn(collection: Record<string, unknown>): boolean {
   return isRecord(auth) ? auth.disableLocalStrategy !== true : false
 }
 
+/**
+ * The payload-auth-link plugin's own auth strategy name
+ * (`packages/plugin/src/strategy.ts`). A users collection carrying it
+ * has ALREADY been through `authLink` — its identities/linkable/…
+ * fields are the plugin's own injections, not host collisions
+ * (issue #88: the doctor run against the TARGET config).
+ */
+const pluginStrategyName = 'auth-link'
+
 export function analyzeUsersCollection(
   collection: Record<string, unknown> | null,
   rolesFieldName: string
@@ -114,10 +123,20 @@ export function analyzeUsersCollection(
   const issues: DoctorIssue[] = []
   const notes: string[] = []
 
-  const collisions = fields
-    .map(fieldName)
-    .filter((name): name is string => name !== null)
-    .filter((name) => injectedFieldNames.has(name))
+  // On the target config the plugin already injected these fields:
+  // they are its own, never a collision (issue #88).
+  const pluginInstalled = strategiesOf(collection).includes(pluginStrategyName)
+  const collisions = pluginInstalled
+    ? []
+    : fields
+        .map(fieldName)
+        .filter((name): name is string => name !== null)
+        .filter((name) => injectedFieldNames.has(name))
+  if (pluginInstalled) {
+    notes.push(
+      'payload-auth-link is already installed on this collection (its auth-link strategy is present): the injected fields are the plugin’s own'
+    )
+  }
 
   let roleField: UsersFinding['roleField'] = null
   const roleCandidates = fields.filter((field) => {