@payload-auth-link/migrate 0.0.0-stage → 0.2.0

package/src/doctor/bands.ts

@@ -0,0 +1,66 @@
+import {
+  describeBand,
+  isSupportedVersion,
+  readInstalledVersion,
+  type VersionRange,
+} from '@payload-auth-link/core'
+import type { VersionFinding } from './types.js'
+
+/**
+ * The bands the doctor checks against. These mirror the authoritative
+ * constants — `supportedPayloadBand` (packages/plugin) and
+ * `supportedBetterAuthBand` (packages/provider-better-auth) — and a
+ * unit test asserts the copies never drift from them, so the doctor
+ * cannot promise a band the runtime would refuse.
+ */
+export const payloadBand: readonly VersionRange[] = [
+  { min: '3.83.0', maxExclusive: '4.0.0' },
+  { exact: '4.0.0-beta.0' },
+]
+export const betterAuthBand: readonly VersionRange[] = [{ min: '1.7.6', maxExclusive: '1.8.0' }]
+/** Next is a peer of the Next adapter; the doctor reports it informationally. */
+export const nextBand: readonly VersionRange[] = [{ min: '15.0.0', maxExclusive: '17.0.0' }]
+
+/**
+ * Better Auth minors this doctor knows the payload-auth app must move
+ * off: 1.6 removed `oidcProvider` in 1.7 and payload-auth's peer range
+ * still admits 1.4+, so an app can sit far below the supported band
+ * without anything telling it.
+ */
+function versionFinding(
+  name: string,
+  band: readonly VersionRange[],
+  fromUrl: string,
+  note?: (installed: string | null) => string | undefined
+): VersionFinding {
+  const installed = readInstalledVersion(name, fromUrl)
+  const status =
+    installed === null ? 'unknown' : isSupportedVersion(installed, band) ? 'ok' : 'blocker'
+  const base =
+    installed === null
+      ? 'could not read the installed manifest; resolve the version manually'
+      : isSupportedVersion(installed, band)
+        ? `installed ${installed} is inside the supported band`
+        : `installed ${installed} is OUTSIDE the supported band; upgrade before migrating`
+  return {
+    name,
+    installed,
+    band: describeBand(band),
+    status,
+    detail: [base, note?.(installed)].filter((part) => part !== undefined).join(' — '),
+  }
+}
+
+/** Band checks for the three upstreams that gate a migration. */
+export function checkVersions(fromUrl: string): VersionFinding[] {
+  return [
+    versionFinding('payload', payloadBand, fromUrl),
+    versionFinding('better-auth', betterAuthBand, fromUrl, (installed) =>
+      installed !== null &&
+      (installed.startsWith('1.4.') || installed.startsWith('1.5.') || installed.startsWith('1.6.'))
+        ? 'better-auth 1.7 removed `oidcProvider` and the `mcp` plugin; an OAuth 2.1 server moves to @better-auth/oauth-provider (a schema migration — see the journey notes in issue #60)'
+        : undefined
+    ),
+    versionFinding('next', nextBand, fromUrl),
+  ]
+}

package/src/doctor/database.ts

@@ -0,0 +1,130 @@
+import { Client } from 'pg'
+import type { DatabaseFinding } from './types.js'
+
+/**
+ * Read-only database introspection (issue #52): row counts for the
+ * payload-auth layout's auth tables, unverified users (who will not
+ * JIT-link), and orphans. Only an honest SELECT — the doctor never
+ * writes.
+ */
+
+/**
+ * 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.
+ */
+const knownTables: readonly string[] = [
+  'users',
+  'accounts',
+  'sessions',
+  'verifications',
+  'api_keys',
+  'organizations',
+  'members',
+  'invitations',
+  'jwks',
+  'admin_invitations',
+  'users_role',
+  'two_factors',
+  'passkeys',
+  'oauth_applications',
+  'oauth_access_tokens',
+  'oauth_consents',
+  'teams',
+  'team_members',
+  'subscriptions',
+  'device_code',
+  'sso_providers',
+]
+
+async function tableExists(client: Client, table: string): Promise<boolean> {
+  const result = await client.query(
+    `SELECT 1 FROM information_schema.tables
+     WHERE table_schema = 'public' AND table_name = $1`,
+    [table]
+  )
+  return result.rows.length > 0
+}
+
+/**
+ * Discover the columns a table actually has, so checks adapt to
+ * customized layouts instead of assuming.
+ */
+async function columnsOf(client: Client, table: string): Promise<Set<string>> {
+  const result = await client.query(
+    `SELECT column_name FROM information_schema.columns
+     WHERE table_schema = 'public' AND table_name = $1`,
+    [table]
+  )
+  return new Set(result.rows.map((row) => String((row as { column_name: unknown }).column_name)))
+}
+
+export async function introspectDatabase(connectionString: string): Promise<DatabaseFinding> {
+  const client = new Client({ connectionString })
+  await client.connect()
+  try {
+    const tables: { name: string; rows: number }[] = []
+    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 })
+    }
+
+    let unverifiedUsers: number | null = null
+    if (await tableExists(client, 'users')) {
+      const columns = await columnsOf(client, 'users')
+      if (columns.has('email_verified')) {
+        const counted = await client.query(
+          'SELECT count(*)::int AS n FROM users WHERE email_verified = false'
+        )
+        const first = counted.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',
+        },
+      ]
+    for (const check of orphanChecks) {
+      if (
+        (await tableExists(client, check.table)) &&
+        (await tableExists(client, check.target)) &&
+        (await columnsOf(client, check.table)).has(check.column)
+      ) {
+        const counted = 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 count = first?.n ?? 0
+        if (count > 0) {
+          orphans.push({ kind: check.kind, count })
+        }
+      }
+    }
+
+    return { tables, unverifiedUsers, orphans }
+  } finally {
+    await client.end()
+  }
+}

package/src/doctor/plugins.ts

@@ -0,0 +1,216 @@
+import type { PluginFinding } from './types.js'
+
+/**
+ * Better Auth plugin classification (issue #52): for each plugin the
+ * app's `betterAuthOptions.plugins` declares, the doctor says whether
+ * payload-auth-link's engine supports it out of the box
+ * (`autoDeclare` derives its models from Better Auth's own
+ * `getAuthTables`), whether it is a probed satellite, or whether it
+ * blocks migration.
+ */
+
+/**
+ * Core + first-party plugins the engine derives confidently. Mirrors
+ * what the derive-schema snapshot tests pin in
+ * packages/provider-better-auth; new entries land together with a
+ * derived-schema probe.
+ */
+const autoDeclared: ReadonlySet<string> = new Set([
+  'magic-link',
+  'email-otp',
+  'anonymous',
+  'two-factor',
+  'admin',
+  'organization',
+  'jwt',
+  'username',
+  'phone-number',
+  'generic-oauth',
+  'one-time-token',
+  'multi-session',
+  'bearer',
+  'expo',
+  'siwe',
+  'next-cookies',
+  'tanstack-start-cookies',
+  'svelte-kit-cookies',
+  'solid-start-cookies',
+])
+
+/** Satellites with a committed schema probe in this repo (compat matrix). */
+const probedSatellites: ReadonlySet<string> = new Set([
+  '@better-auth/passkey',
+  '@better-auth/api-key',
+])
+
+/** Satellites explicitly unsupported until probed (see compatibility.md). */
+const unsupportedSatellites: ReadonlyMap<string, string> = new Map([
+  [
+    '@better-auth/sso',
+    'not probed by payload-auth-link; adding it meets UnsupportedSchemaError at wiring time',
+  ],
+])
+
+/**
+ * Payload-auth's own plugin additions the engine has no equivalent
+ * for. `oidcProvider` is the headline: Better Auth 1.7 removed it, and
+ * the replacement (@better-auth/oauth-provider) uses different tables,
+ * so the data move is the app's phase-1 prerequisite.
+ */
+const removedUpstream: ReadonlyMap<string, string> = new Map([
+  [
+    'oidc-provider',
+    'Better Auth 1.7 removed `oidcProvider`; moving to @better-auth/oauth-provider is a schema migration (oauthApplication → oauthClient, token splits, jwks gains alg/crv) — plan it before the auth migration',
+  ],
+  [
+    'mcp',
+    'Better Auth 1.7 removed the `mcp` plugin; move its surface to @better-auth/oauth-provider',
+  ],
+])
+
+/** The satellite's own id convention: package name or its short id. */
+function satelliteId(id: string): string {
+  return id.startsWith('@better-auth/') ? id : `@better-auth/${id}`
+}
+
+export function classifyPlugins(ids: readonly string[]): PluginFinding[] {
+  const findings: PluginFinding[] = []
+  for (const raw of ids) {
+    const id = raw.trim()
+    if (id === '') {
+      continue
+    }
+    const satellite = satelliteId(id)
+    if (removedUpstream.has(id) || removedUpstream.has(satellite)) {
+      findings.push({
+        id,
+        status: 'removed-upstream',
+        detail: removedUpstream.get(id) ?? removedUpstream.get(satellite) ?? '',
+      })
+      continue
+    }
+    if (id === 'oidcProvider') {
+      const detail = removedUpstream.get('oidc-provider') ?? ''
+      findings.push({ id, status: 'removed-upstream', detail })
+      continue
+    }
+    if (unsupportedSatellites.has(satellite)) {
+      findings.push({
+        id,
+        status: 'unsupported',
+        detail: unsupportedSatellites.get(satellite) ?? '',
+      })
+      continue
+    }
+    if (probedSatellites.has(satellite)) {
+      findings.push({
+        id,
+        status: 'supported',
+        detail: 'probed satellite — schema covered by the committed probe and the compat matrix',
+      })
+      continue
+    }
+    if (autoDeclared.has(id)) {
+      findings.push({
+        id,
+        status: 'auto-declarable',
+        detail: 'derived from Better Auth’s own getAuthTables via autoDeclare',
+      })
+      continue
+    }
+    if (satellite !== id) {
+      findings.push({
+        id,
+        status: 'unprobed',
+        detail:
+          'Better Auth satellite without a committed probe; the engine will derive its models but nothing here has validated them',
+      })
+      continue
+    }
+    findings.push({
+      id,
+      status: 'unprobed',
+      detail:
+        'unknown plugin id; the engine derives what Better Auth’s schema reports, but treat it as unvalidated until probed',
+    })
+  }
+  return findings
+}
+
+/**
+ * payload-auth does not keep the builder's Better Auth options on the
+ * built config (the plugin closure holds them), so the doctor derives
+ * the plugin set from what IS visible: the collections payload-auth
+ * built (each plugin model gets a slug) and the config source's plugin
+ * calls (for plugins without dedicated tables — magic link, cookies).
+ * Both probes feed the same classifier.
+ */
+
+/** payload-auth slug (baPluginSlugs) → Better Auth plugin id. */
+const slugToPlugin: Readonly<Record<string, string>> = {
+  apiKeys: 'api-key',
+  jwks: 'jwt',
+  twoFactors: 'two-factor',
+  passkeys: 'passkey',
+  oauthApplications: 'oidcProvider',
+  oauthAccessTokens: 'oidcProvider',
+  oauthConsents: 'oidcProvider',
+  ssoProviders: 'sso',
+  organizations: 'organization',
+  members: 'organization',
+  invitations: 'organization',
+  organizationRoles: 'organization',
+  teams: 'organization',
+  teamMembers: 'organization',
+  deviceCode: 'device-authorization',
+  subscriptions: 'subscriptions',
+}
+
+/** Plugin ids proven live by the collections payload-auth built. */
+export function pluginsFromCollectionSlugs(slugs: readonly string[]): string[] {
+  const ids = new Set<string>()
+  for (const slug of slugs) {
+    const id: string | undefined = slugToPlugin[slug]
+    if (id !== undefined) {
+      ids.add(id)
+    }
+  }
+  return [...ids].sort()
+}
+
+/** Plugin call names a config source can name, mapped to plugin ids. */
+const callNameToPlugin: Readonly<Record<string, string>> = {
+  magicLink: 'magic-link',
+  emailOTP: 'email-otp',
+  anonymous: 'anonymous',
+  twoFactor: 'two-factor',
+  admin: 'admin',
+  organization: 'organization',
+  jwt: 'jwt',
+  username: 'username',
+  phoneNumber: 'phone-number',
+  genericOAuth: 'generic-oauth',
+  nextCookies: 'next-cookies',
+  tanstackStartCookies: 'tanstack-start-cookies',
+  oidcProvider: 'oidcProvider',
+  passkey: 'passkey',
+  apiKey: 'api-key',
+  sso: 'sso',
+}
+
+/**
+ * Plugin ids found by scanning the config source for plugin factory
+ * calls. Regex on purpose: the loaded config cannot reveal these
+ * (closure-held options), and the doctor must not execute app code
+ * beyond loading its config module.
+ */
+export function pluginsFromConfigSource(configSource: string): string[] {
+  const ids = new Set<string>()
+  for (const [call, id] of Object.entries(callNameToPlugin)) {
+    const pattern = new RegExp(`\\b${call}\\s*\\(`)
+    if (pattern.test(configSource)) {
+      ids.add(id)
+    }
+  }
+  return [...ids].sort()
+}

package/src/doctor/run-doctor.ts

@@ -0,0 +1,278 @@
+import { isRecord } from '@payload-auth-link/core'
+import { readFileSync } from 'node:fs'
+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 { scanSource } from './source-scan.js'
+import { analyzeUsersCollection, findUsersCollection } from './users.js'
+import type { BehaviourChange, DoctorIssue, DoctorReport } from './types.js'
+
+/**
+ * The read-only doctor (issue #52): point it at a payload-auth app and
+ * get the exact list of what breaks before touching anything. It loads
+ * the app's config module, inspects the users collection and Better
+ * 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.
+ */
+
+export type DoctorOptions = {
+  /** Absolute or cwd-relative path to the app's payload config. */
+  readonly configPath: string
+  /** Source directory to scan. Defaults to the config's directory. */
+  readonly srcDir?: string | undefined
+  /** Postgres connection string. Defaults to `DATABASE_URL`. */
+  readonly databaseUrl?: string | undefined
+  /** Config loader, injectable for tests. Defaults to dynamic import. */
+  readonly loadModule?: ((path: string) => Promise<unknown>) | undefined
+}
+
+/**
+ * Behaviour changes in payload-auth-link 0.7.0 that a payload-auth app
+ * feels on day one. Static by nature; kept next to the doctor so the
+ * report is one artifact.
+ */
+export const behaviourChanges: readonly BehaviourChange[] = [
+  {
+    title: 'Provider-linked documents lose local sign-in and forgot/reset',
+    detail:
+      '0.7.0 makes documents with linked identities provider-owned: Payload local login and the self-service forgot/reset flow are refused for them (GHSA-f4hj). Break-glass operator accounts (no linked identities) keep everything. Set allowLocalCredentialsForLinkedDocs: true only for a migration window.',
+  },
+  {
+    title: 'Suspension is enforced on every strategy',
+    detail:
+      'suspendedUntil now refuses provider sessions, local sign-ins, existing local JWTs and API keys on the next request — including refresh-token and GraphQL.',
+  },
+  {
+    title: 'Collection access defaults tighten',
+    detail:
+      'Engine collections default to deny-all API access, and the users collection ships governed defaults for update/delete/unlock. Hosts opening access do so explicitly.',
+  },
+  {
+    title: 'req.user is a projection by default',
+    detail:
+      "req.user carries { id, collection, email, roles } plus assurance/actor fields, not the full document. Access functions reading other fields see undefined — audit them or opt into reqUser: 'document' (#57).",
+  },
+]
+
+/**
+ * Detect payload-auth in the built config. The plugin stamps
+ * `config.custom.hasBetterAuthPlugin = true` when it runs; older or
+ * future builds that instead expose `pluginOptions` on the plugin
+ * function are honored too.
+ */
+export function findPayloadAuthPlugin(config: unknown): {
+  pluginOptions: Record<string, unknown>
+} | null {
+  if (!isRecord(config)) {
+    return null
+  }
+  if (isRecord(config.custom) && config.custom.hasBetterAuthPlugin === true) {
+    return { pluginOptions: {} }
+  }
+  if (!Array.isArray(config.plugins)) {
+    return null
+  }
+  for (const plugin of config.plugins) {
+    if (typeof plugin === 'function' && 'pluginOptions' in plugin) {
+      const options: unknown = (plugin as { pluginOptions: unknown }).pluginOptions
+      if (isRecord(options)) {
+        return { pluginOptions: options }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * The Better Auth plugin ids the app declared. Reads them off
+ * `betterAuthOptions.plugins` when a pluginOptions object is visible;
+ * callers otherwise derive them from the built collections and the
+ * config source (see {@link pluginsFromCollectionSlugs} and
+ * {@link pluginsFromConfigSource}).
+ */
+export function betterAuthPluginIds(pluginOptions: Record<string, unknown>): string[] {
+  const baOptions: unknown = pluginOptions.betterAuthOptions
+  if (!isRecord(baOptions) || !Array.isArray(baOptions.plugins)) {
+    return []
+  }
+  const ids: string[] = []
+  for (const plugin of baOptions.plugins) {
+    if (isRecord(plugin) && typeof plugin.id === 'string' && plugin.id !== '') {
+      ids.push(plugin.id)
+    }
+  }
+  return ids
+}
+
+/** The users collection slug the payload-auth app configured. */
+export function usersSlugOf(pluginOptions: Record<string, unknown>): string {
+  const users: unknown = pluginOptions.users
+  return isRecord(users) && typeof users.slug === 'string' && users.slug !== ''
+    ? users.slug
+    : 'users'
+}
+
+/** Collection slugs of the built config. */
+export function collectionSlugs(config: unknown): string[] {
+  if (!isRecord(config) || !Array.isArray(config.collections)) {
+    return []
+  }
+  return config.collections
+    .filter(isRecord)
+    .map((collection) => collection.slug)
+    .filter((slug): slug is string => typeof slug === 'string')
+}
+
+/** 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)
+  let config: unknown = isRecord(mod) && 'default' in mod ? mod.default : mod
+  // Payload configs may be async (buildConfig returns a Promise when the
+  // config awaits) — the doctor reads the resolved object either way.
+  if (typeof (config as Partial<Promise<unknown>> | undefined)?.then === 'function') {
+    config = await config
+  }
+  return config
+}
+
+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)
+
+  const versions = checkVersions(pathToFileURL(configPath).href)
+  const blockers: DoctorIssue[] = []
+  const warnings: DoctorIssue[] = []
+  for (const finding of versions) {
+    if (finding.status === 'blocker') {
+      blockers.push({
+        code: `${finding.name}-out-of-band`,
+        detail: `${finding.name}: ${finding.detail}`,
+      })
+    } else if (finding.status === 'unknown') {
+      warnings.push({
+        code: `${finding.name}-version-unknown`,
+        detail: `${finding.name}: ${finding.detail}`,
+      })
+    }
+  }
+
+  const plugin = findPayloadAuthPlugin(config)
+  if (plugin === null) {
+    warnings.push({
+      code: 'payload-auth-not-detected',
+      detail:
+        'no payload-auth plugin found in the config; if this app runs payload-auth elsewhere, point --config at that config',
+    })
+  }
+  if (plugin !== null) {
+    blockers.push({
+      code: 'payload-auth-installed',
+      detail:
+        'payload-auth is installed and configured: migrate with adopt (#49, zero row moves) or the importer (#50, reversible copy). Its admin views, payload.betterAuth accessor, and user-table layout all change.',
+    })
+  }
+
+  // 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.
+  let configSource: string
+  try {
+    configSource = readFileSync(configPath, 'utf8')
+  } catch {
+    configSource = ''
+  }
+  const pluginIds = [
+    ...new Set([
+      ...betterAuthPluginIds(plugin?.pluginOptions ?? {}),
+      ...pluginsFromCollectionSlugs(collectionSlugs(config)),
+      ...pluginsFromConfigSource(configSource),
+    ]),
+  ]
+  const pluginFindings = classifyPlugins(pluginIds)
+  for (const finding of pluginFindings) {
+    if (finding.status === 'removed-upstream') {
+      blockers.push({
+        code: 'ba-plugin-removed-upstream',
+        detail: `${finding.id}: ${finding.detail}`,
+      })
+    } else if (finding.status === 'unsupported' || finding.status === 'unprobed') {
+      warnings.push({ code: 'ba-plugin-unvalidated', detail: `${finding.id}: ${finding.detail}` })
+    }
+  }
+
+  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)
+    }
+  }
+
+  const source = scanSource(srcDir)
+  for (const finding of source) {
+    if (finding.kind === 'ba-internals') {
+      blockers.push({
+        code: 'ba-internals-usage',
+        detail: `${finding.files.length} file(s) use Better Auth internals (${finding.files.join(', ')}): these break across Better Auth minors and hand-roll session cookies — rewrite on the supported server API (#54) before migrating`,
+      })
+    }
+  }
+
+  const databaseUrl = options.databaseUrl ?? process.env.DATABASE_URL
+  let database: DoctorReport['database'] = null
+  if (databaseUrl !== undefined && databaseUrl !== '') {
+    try {
+      const found = await introspectDatabase(databaseUrl)
+      database = found
+      if (found.unverifiedUsers !== null && found.unverifiedUsers > 0) {
+        warnings.push({
+          code: 'unverified-users',
+          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`,
+        })
+      }
+      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`,
+        })
+      }
+    } catch (error) {
+      warnings.push({
+        code: 'database-unreachable',
+        detail: `could not inspect the database: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  } else {
+    warnings.push({
+      code: 'database-not-inspected',
+      detail:
+        'no database URL (pass --database-url or set DATABASE_URL); row counts, unverified users, and orphans were not checked',
+    })
+  }
+
+  return {
+    versions,
+    plugins: pluginFindings,
+    users,
+    source,
+    database,
+    behaviourChanges,
+    blockers,
+    warnings,
+  }
+}