@nextsparkjs/core 0.1.0-beta.189 → 0.1.0-beta.190

package/scripts/db/run-migrations.mjs

@@ -1,9 +1,7 @@
-import pg from "pg";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from 'url';
-
-const { Client } = pg;
+import { migrationTimeLimit, migrationClient, ignoredParametersNotice, runMigrationSql, recordMigration, migrationFailure } from './migration-time-limit.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -17,8 +15,11 @@ const packageRoot = path.join(__dirname, '..', '..'); // scripts/db/ -> core/
 const isMonorepoMode = fs.existsSync(path.join(projectRoot, 'packages', 'core'));
 const rootDir = projectRoot; // For backward compatibility with code below
 
-// Read environment variables: prefer .env file if it exists, fallback to process.env (e.g. Vercel/CI)
+// Read environment variables: prefer .env file if it exists, fallback to process.env (e.g. Vercel/CI).
+// `--no-env-file` skips the .env file, so the connection and theme come only from the
+// environment this process was started with (db:verify-theme runs it that way).
 const envPath = path.join(projectRoot, '.env');
+const readEnvFile = !process.argv.includes('--no-env-file');
 
 let DATABASE_URL = process.env.DATABASE_URL ?? null;
 // Migrations and seeds run as the table OWNER. After the runtime cutover the app
@@ -27,8 +28,9 @@ let DATABASE_URL = process.env.DATABASE_URL ?? null;
 // Falls back to DATABASE_URL when unset (pre-cutover: same owner connection).
 let MIGRATE_DATABASE_URL = process.env.MIGRATE_DATABASE_URL ?? null;
 let ACTIVE_THEME = process.env.NEXT_PUBLIC_ACTIVE_THEME ?? null;
+let MIGRATION_TIMEOUT_SECONDS = process.env.MIGRATION_TIMEOUT_SECONDS;
 
-if (fs.existsSync(envPath)) {
+if (readEnvFile && fs.existsSync(envPath)) {
   const envContent = fs.readFileSync(envPath, 'utf8');
   const envLines = envContent.split('\n');
 
@@ -46,6 +48,9 @@ if (fs.existsSync(envPath)) {
       if (key?.trim() === 'NEXT_PUBLIC_ACTIVE_THEME' && valueParts.length > 0) {
         ACTIVE_THEME = value;
       }
+      if (key?.trim() === 'MIGRATION_TIMEOUT_SECONDS' && valueParts.length > 0) {
+        MIGRATION_TIMEOUT_SECONDS = value;
+      }
     }
   });
 }
@@ -63,15 +68,21 @@ if (!ACTIVE_THEME) {
   process.exit(1);
 }
 
+// How long each migration may run, when MIGRATION_TIMEOUT_SECONDS asks for a limit
+// (see migration-time-limit.mjs). Without it, a migration runs for as long as it takes.
+let TIME_LIMIT;
+try {
+  TIME_LIMIT = migrationTimeLimit({ MIGRATION_TIMEOUT_SECONDS });
+} catch (error) {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+}
+
+const ignoredParameters = ignoredParametersNotice(MIGRATION_URL, TIME_LIMIT);
+if (ignoredParameters) console.log(`⚠️  ${ignoredParameters}\n`);
+
 async function runMigrations() {
-  const client = new Client({
-    connectionString: MIGRATION_URL,
-    ssl: { 
-      rejectUnauthorized: false,
-      require: true
-    },
-    connectionTimeoutMillis: 10000
-  });
+  const client = migrationClient(MIGRATION_URL, TIME_LIMIT);
   
   try {
     await client.connect();
@@ -113,17 +124,14 @@ async function runMigrations() {
       const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf8');
       
       try {
-        await client.query(sql);
+        await runMigrationSql(client, { sql, limit: TIME_LIMIT, connectionString: MIGRATION_URL });
         
         // Record successful migration
-        await client.query(
-          'INSERT INTO "_migrations" (filename) VALUES ($1)',
-          [file]
-        );
+        await recordMigration(client, { file, table: '_migrations', row: { filename: file }, limit: TIME_LIMIT });
         
         console.log(`✅ Successfully executed ${file}\n`);
       } catch (error) {
-        console.error(`❌ Failed to execute ${file}:`, error.message);
+        console.error(`❌ ${migrationFailure(file, error)}`);
         throw error;
       }
     }
@@ -328,11 +336,13 @@ async function executeContentMigration(client, migration) {
   console.log(`  🔄 ${filename}...`);
   const sql = fs.readFileSync(fullPath, 'utf8');
 
-  await client.query(sql);
-  await client.query(
-    'INSERT INTO "_content_migrations" (source_type, source_name, filename) VALUES ($1, $2, $3)',
-    [sourceType, sourceName, filename]
-  );
+  await runMigrationSql(client, { sql, limit: TIME_LIMIT, connectionString: MIGRATION_URL });
+  await recordMigration(client, {
+    file: filename,
+    table: '_content_migrations',
+    row: { source_type: sourceType, source_name: sourceName, filename },
+    limit: TIME_LIMIT,
+  });
 
   console.log(`  ✅ ${filename} executed successfully`);
   return true;
@@ -357,11 +367,13 @@ async function executeEntityMigration(client, migration) {
   console.log(`${indent}🔄 ${filename}...`);
   const sql = fs.readFileSync(fullPath, 'utf8');
 
-  await client.query(sql);
-  await client.query(
-    'INSERT INTO "_entity_migrations" (entity_name, source_type, source_name, filename) VALUES ($1, $2, $3, $4)',
-    [entityName, sourceType, sourceName, filename]
-  );
+  await runMigrationSql(client, { sql, limit: TIME_LIMIT, connectionString: MIGRATION_URL });
+  await recordMigration(client, {
+    file: filename,
+    table: '_entity_migrations',
+    row: { entity_name: entityName, source_type: sourceType, source_name: sourceName, filename },
+    limit: TIME_LIMIT,
+  });
 
   console.log(`${indent}✅ ${filename} executed successfully`);
   return true;
@@ -369,14 +381,7 @@ async function executeEntityMigration(client, migration) {
 
 // Entity migrations runner - WordPress-like architecture with sample_data deferred execution
 async function runEntityMigrations() {
-  const client = new Client({
-    connectionString: MIGRATION_URL,
-    ssl: {
-      rejectUnauthorized: false,
-      require: true
-    },
-    connectionTimeoutMillis: 10000
-  });
+  const client = migrationClient(MIGRATION_URL, TIME_LIMIT);
 
   try {
     await client.connect();
@@ -545,7 +550,7 @@ async function runEntityMigrations() {
           const executed = await executeContentMigration(client, migration);
           if (executed) totalContentMigrations++;
         } catch (error) {
-          console.error(`  ❌ Failed to execute ${migration.filename}:`, error.message);
+          console.error(`  ❌ ${migrationFailure(migration.filename, error)}`);
           throw error;
         }
       }
@@ -566,7 +571,7 @@ async function runEntityMigrations() {
           const executed = await executeEntityMigration(client, migration);
           if (executed) totalEntityMigrations++;
         } catch (error) {
-          console.error(`  ❌ Failed to execute ${migration.filename}:`, error.message);
+          console.error(`  ❌ ${migrationFailure(migration.filename, error)}`);
           throw error;
         }
       }
@@ -586,7 +591,7 @@ async function runEntityMigrations() {
           const executed = await executeContentMigration(client, migration);
           if (executed) totalContentMigrations++;
         } catch (error) {
-          console.error(`  ❌ Failed to execute ${migration.filename}:`, error.message);
+          console.error(`  ❌ ${migrationFailure(migration.filename, error)}`);
           throw error;
         }
       }
@@ -607,7 +612,7 @@ async function runEntityMigrations() {
           const executed = await executeEntityMigration(client, migration);
           if (executed) totalEntityMigrations++;
         } catch (error) {
-          console.error(`  ❌ Failed to execute ${migration.filename}:`, error.message);
+          console.error(`  ❌ ${migrationFailure(migration.filename, error)}`);
           throw error;
         }
       }

package/scripts/db/ssl-config.mjs

@@ -0,0 +1,194 @@
+import pg from 'pg'
+import { EventEmitter } from 'node:events'
+
+/**
+ * SSL handling for the database maintenance scripts.
+ *
+ * This deliberately mirrors `src/lib/db.ts` without importing application
+ * runtime code: scripts run as standalone Node ESM programs while the runtime
+ * remains bundled separately until its next release.
+ */
+
+/**
+ * Strip SSL-related parameters so pg cannot override the explicit `ssl` option.
+ * pg v8+ otherwise resolves `sslmode=require` as certificate validation.
+ */
+export function stripSSLParams(databaseUrl) {
+  if (!databaseUrl) return databaseUrl
+  try {
+    const url = new URL(databaseUrl)
+    url.searchParams.delete('sslmode')
+    url.searchParams.delete('uselibpqcompat')
+    return url.toString()
+  } catch {
+    return databaseUrl
+      .replace(/[?&]sslmode=[^&]*/g, '')
+      .replace(/[?&]uselibpqcompat=[^&]*/g, '')
+      .replace(/\?&/, '?')
+      .replace(/\?$/, '')
+  }
+}
+
+/**
+ * Parse the SSL policy used by database scripts.
+ *
+ * Explicit sslmode takes precedence. With no recognized mode, only production
+ * uses validated TLS; all other environments use no TLS.
+ */
+export function parseSSLConfig(databaseUrl) {
+  const isProduction = process.env.NODE_ENV === 'production'
+
+  if (!databaseUrl) return isProduction ? { rejectUnauthorized: true } : false
+
+  try {
+    const url = new URL(databaseUrl)
+    const sslmode = url.searchParams.get('sslmode')?.trim().toLowerCase()
+
+    if (sslmode) {
+      switch (sslmode) {
+        case 'disable':
+          if (isProduction) console.warn('[DB] WARNING: SSL disabled in production environment. This is insecure!')
+          return false
+        case 'require':
+        case 'prefer':
+        case 'allow':
+          return { rejectUnauthorized: false }
+        case 'verify-ca':
+        case 'verify-full':
+          return { rejectUnauthorized: true }
+        default:
+          console.warn(`[DB] Unknown sslmode value: "${sslmode}". Using environment defaults.`)
+      }
+    }
+
+    return isProduction ? { rejectUnauthorized: true } : false
+  } catch {
+    if (databaseUrl.includes('sslmode=disable')) return false
+    return isProduction ? { rejectUnauthorized: true } : false
+  }
+}
+
+/** True only for a syntactically valid URL which does not state an sslmode. */
+export function prefersSSL(databaseUrl) {
+  if (!databaseUrl) return false
+  try {
+    return !new URL(databaseUrl).searchParams.has('sslmode')
+  } catch {
+    // Keep malformed URLs on the runtime's conservative, documented policy.
+    return false
+  }
+}
+
+/**
+ * The initial configuration for a script connection.
+ *
+ * A URL without sslmode has libpq's `prefer` semantics: first ask for TLS
+ * without validating the certificate, and fall back only when Postgres says it
+ * has no TLS support. `parseSSLConfig` intentionally remains the runtime's
+ * policy; the distinct initial value here is what makes the scripts differ on
+ * that one, documented case.
+ */
+export function scriptConnectionOptions(databaseUrl, options = {}) {
+  return {
+    ...options,
+    connectionString: stripSSLParams(databaseUrl),
+    ssl: prefersSSL(databaseUrl) ? { rejectUnauthorized: false } : parseSSLConfig(databaseUrl),
+  }
+}
+
+const NO_SSL_SUPPORT = 'The server does not support SSL connections'
+
+function isNoSSLSupport(error) {
+  return error?.message === NO_SSL_SUPPORT
+}
+
+/**
+ * A small Client facade for the only case where scripts deliberately differ
+ * from the runtime: a URL with no sslmode. It preserves pg's Client surface
+ * while swapping the first TLS-only connection for one without TLS only after
+ * pg's precise "server does not support SSL" error. Every other failure is
+ * returned unchanged.
+ */
+class SSLPreferClient extends EventEmitter {
+  constructor(options) {
+    super()
+    this.options = options
+    this.client = new pg.Client(options)
+    this.eventsForwarded = false
+  }
+
+  get connection() { return this.client.connection }
+  get connectionParameters() { return this.client.connectionParameters }
+  get database() { return this.client.database }
+  set database(value) { this.client.database = value }
+  get processID() { return this.client.processID }
+  get _queryable() { return this.client._queryable }
+  get _ending() { return this.client._ending }
+
+  forwardEvents() {
+    if (this.eventsForwarded) return
+    this.eventsForwarded = true
+    // Pool relies on these two; the scripts use the underlying connection for
+    // protocol events. Forwarding also keeps the normal pg error/end contract.
+    for (const event of ['error', 'end', 'notice', 'notification']) {
+      this.client.on(event, (...args) => this.emit(event, ...args))
+    }
+  }
+
+  async connectPromise() {
+    const startedAt = performance.now()
+    try {
+      await this.client.connect()
+    } catch (error) {
+      if (!isNoSSLSupport(error)) throw error
+
+      // A retry shares, rather than resets, the connection time budget. This
+      // matters for timeLimitedClient(), whose connectMs is a hard bound.
+      const timeout = Number(this.options.connectionTimeoutMillis) || 0
+      const elapsed = performance.now() - startedAt
+      if (timeout > 0 && elapsed >= timeout) throw new Error('timeout expired')
+
+      // The facade exposes pg's live connection parameters. Callers such as
+      // timeLimitedClient() deliberately update those after construction so a
+      // connection string cannot disable their limits. Build the plaintext
+      // retry from that live, resolved state (rather than re-parsing the URL),
+      // or it would silently discard every such update.
+      const { connectionString: _connectionString, ...options } = this.options
+      this.client = new pg.Client({
+        ...options,
+        ...this.client.connectionParameters,
+        password: this.client.password,
+        ssl: false,
+        ...(timeout > 0 ? { connectionTimeoutMillis: Math.max(1, Math.ceil(timeout - elapsed)) } : {}),
+      })
+      await this.client.connect()
+    }
+    this.forwardEvents()
+  }
+
+  connect(callback) {
+    const promise = this.connectPromise()
+    if (!callback) return promise
+    promise.then(() => callback(null, this), callback)
+  }
+
+  query(...args) { return this.client.query(...args) }
+  end(...args) { return this.client.end(...args) }
+  ref() { return this.client.ref() }
+  unref() { return this.client.unref() }
+}
+
+/** A Client with explicit modes unchanged, or libpq-style `prefer` otherwise. */
+export function scriptClient(databaseUrl, options = {}) {
+  const config = scriptConnectionOptions(databaseUrl, options)
+  return prefersSSL(databaseUrl) ? new SSLPreferClient(config) : new pg.Client(config)
+}
+
+/** A Pool whose clients have the same `prefer` behavior as direct clients. */
+export function scriptPool(databaseUrl, options = {}) {
+  const config = scriptConnectionOptions(databaseUrl, options)
+  return new pg.Pool({
+    ...config,
+    ...(prefersSSL(databaseUrl) ? { Client: SSLPreferClient } : {}),
+  })
+}

package/scripts/db/theme-location.mjs

@@ -0,0 +1,69 @@
+// Where db:verify-theme finds a theme, and the directory run-migrations.mjs has
+// to run in to migrate it.
+//
+// run-migrations.mjs reads the active theme from `<cwd>/contents/themes/<theme>`.
+// The monorepo's themes reach it through apps/dev/contents, which links to
+// themes/. The starter a generated project ships is not among them: it lives in
+// packages/core/templates/contents/themes/starter, and themes/starter holds only
+// its tests. packages/core/templates has the same contents/ layout a generated
+// project has, so the runner reads the starter from there.
+
+import fs from 'fs';
+import path from 'path';
+
+/** The directories the runner can run in, each with its own contents/themes. */
+export const THEME_PROJECTS = ['apps/dev', 'packages/core/templates'];
+
+// The runner reads a theme's plugins from one of these; a directory with
+// neither is not a theme, and migrating it migrates core alone.
+const THEME_CONFIGS = ['config/theme.config.ts', 'theme.config.ts'];
+
+const SKIP_DIRS = new Set(['node_modules', '.next', 'dist']);
+
+/** Every .sql file inside a `migrations` directory under `dir`, at any depth. */
+export function migrationFiles(dir, insideMigrations = false, found = []) {
+  if (!fs.existsSync(dir)) return found;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      migrationFiles(entryPath, insideMigrations || entry.name === 'migrations', found);
+    } else if (insideMigrations && entry.name.endsWith('.sql')) {
+      found.push(entryPath);
+    }
+  }
+  return found;
+}
+
+/**
+ * The theme called `theme`: its directory, the directory to run the runner in,
+ * and the migration files it holds. `{ error }` when there is no such theme,
+ * when the name is a theme in more than one place, or when it has no
+ * migrations, since a run over none of them proves nothing about it.
+ */
+export function findTheme(repoRoot, theme) {
+  const candidates = THEME_PROJECTS.map(project => ({
+    projectDir: path.join(repoRoot, project),
+    themeDir: path.join(repoRoot, project, 'contents', 'themes', theme),
+  }));
+  // A theme reached through a link is shown where it really lives: themes/blog, not apps/dev/contents/themes/blog.
+  const shown = dir =>
+    fs.existsSync(dir) ? path.relative(fs.realpathSync(repoRoot), fs.realpathSync(dir)) : path.relative(repoRoot, dir);
+  const found = candidates.filter(({ themeDir }) => THEME_CONFIGS.some(config => fs.existsSync(path.join(themeDir, config))));
+
+  if (found.length === 0) {
+    return {
+      error: `no theme "${theme}": none of ${candidates.map(({ themeDir }) => shown(themeDir)).join(', ')} has a theme config`,
+    };
+  }
+  if (found.length > 1) {
+    return { error: `"${theme}" is a theme in more than one place: ${found.map(({ themeDir }) => shown(themeDir)).join(', ')}` };
+  }
+
+  const [{ projectDir, themeDir }] = found;
+  const migrations = migrationFiles(themeDir);
+  if (migrations.length === 0) {
+    return { error: `theme "${theme}" at ${shown(themeDir)} has no migrations to verify` };
+  }
+  return { projectDir, themeDir, shownDir: shown(themeDir), migrations };
+}

package/scripts/db/verify-tables.mjs

@@ -1,9 +1,7 @@
-import pg from "pg";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from 'url';
-
-const { Client } = pg;
+import { scriptClient } from './ssl-config.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -24,10 +22,7 @@ envLines.forEach(line => {
 });
 
 async function verifyTables() {
-  const client = new Client({
-    connectionString: DATABASE_URL,
-    ssl: { rejectUnauthorized: false }
-  });
+  const client = scriptClient(DATABASE_URL);
   
   try {
     await client.connect();
@@ -139,4 +134,4 @@ async function verifyTables() {
   }
 }
 
-verifyTables();
+verifyTables();

package/scripts/db/verify-teams.mjs

@@ -5,17 +5,13 @@
  * Run with: node core/scripts/db/verify-teams.mjs
  */
 
-import pg from 'pg'
 import dotenv from 'dotenv'
+import { scriptPool } from './ssl-config.mjs'
 
 dotenv.config()
 
-const { Pool } = pg
-
 async function verifyTeamsSetup() {
-  const pool = new Pool({
-    connectionString: process.env.DATABASE_URL,
-  })
+  const pool = scriptPool(process.env.DATABASE_URL)
 
   try {
     console.log('🔍 Verifying Teams Core Setup...\n')

package/scripts/db/verify-theme-migrations.mjs

@@ -0,0 +1,169 @@
+// Runs a single theme's migrations end to end against an explicitly-named
+// database, to catch problems like #193 (sample data referencing a row no
+// migration creates) before they ship. Refuses to run against a database that
+// already holds anything, since running a theme's migrations there would mix
+// that theme's schema and sample data into whatever is already there.
+//
+// Usage: VERIFY_THEME_DATABASE_URL=<database-url> pnpm db:verify-theme <theme>
+//
+// The theme is looked up among the monorepo's themes and the starter core
+// ships to generated projects (see theme-location.mjs). A name that is not a
+// theme, or a theme with no migrations, is refused: a run over core's
+// migrations alone would pass without saying anything about the theme.
+//
+// The run reaches past that database: the core migrations create and alter
+// cluster-wide roles (see cluster-changes.mjs), which every database on the
+// same Postgres server shares. The output names those roles before the
+// migrations run, and the run is refused when the server shows signs of being
+// in use — one of those roles already exists, another database lives there, or
+// the server will not say, or not in time, what is on it.
+// VERIFY_THEME_ALLOW_CLUSTER_CHANGES=1 says the server is yours to change and
+// runs anyway. A disposable server, one per run, needs neither.
+//
+// The database URL comes from the environment, never from an argument:
+// arguments show up in pnpm's command echo and in the process list, and the
+// URL carries the password. The output names only the host and the database.
+//
+// The migrations run through run-migrations.mjs, the same script
+// `pnpm db:migrate` uses, with `--no-env-file` and the theme and database in
+// its environment. No file is read or written for that: no .env is touched,
+// even if this process is killed mid-run.
+//
+// MIGRATE_DATABASE_URL is removed from the child's environment because
+// run-migrations.mjs connects to it in preference to DATABASE_URL, which
+// would migrate a database this script never checked.
+//
+// Every migration runs under a time limit, MIGRATION_TIMEOUT_SECONDS (30 s
+// unless set; see migration-time-limit.mjs). A migration that runs past it
+// fails the run with the migration's name, and its session on the server is
+// ended, instead of leaving the command waiting.
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import { GLOBAL_OBJECTS, inspectCluster } from './cluster-changes.mjs';
+import { inspectTarget, inspectMaintenanceDatabase } from './inspect-server.mjs';
+import { findTheme } from './theme-location.mjs';
+import { TIME_LIMIT_VARIABLE, migrationTimeLimit } from './migration-time-limit.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.join(__dirname, '..', '..', '..', '..'); // scripts/db/ -> core/ -> packages/ -> repo root
+const runnerPath = path.join(repoRoot, 'packages', 'core', 'scripts', 'db', 'run-migrations.mjs');
+
+const USAGE = 'Usage: VERIFY_THEME_DATABASE_URL=<database-url> pnpm db:verify-theme <theme>';
+
+const ACKNOWLEDGEMENT_VAR = 'VERIFY_THEME_ALLOW_CLUSTER_CHANGES';
+const acknowledgesClusterChanges = process.env[ACKNOWLEDGEMENT_VAR] === '1';
+
+const args = process.argv.slice(2);
+const theme = args[0];
+const databaseUrl = process.env.VERIFY_THEME_DATABASE_URL;
+
+// An extra argument, or a theme that looks like a URL, is most likely the
+// database URL passed the old way: reject it without printing it.
+if (!theme || args.length > 1 || theme.includes('://')) {
+  if (theme) console.error('❌ Pass the database URL in VERIFY_THEME_DATABASE_URL, not as an argument.');
+  console.error(USAGE);
+  process.exit(1);
+}
+
+if (!databaseUrl) {
+  console.error(`❌ VERIFY_THEME_DATABASE_URL is not set.\n${USAGE}`);
+  process.exit(1);
+}
+
+let target;
+try {
+  const url = new URL(databaseUrl);
+  target = `${url.host}${url.pathname}`;
+} catch {
+  console.error('❌ VERIFY_THEME_DATABASE_URL is not a valid URL.');
+  process.exit(1);
+}
+
+const located = findTheme(repoRoot, theme);
+if (located.error) {
+  console.error(`❌ ${located.error}`);
+  process.exit(1);
+}
+
+// Against an empty database no migration a theme ships takes a second; the
+// default leaves a slow runner room many times over, and a migration that needs
+// more can be given it.
+const DEFAULT_TIME_LIMIT_SECONDS = '30';
+const timeLimitSetting = process.env[TIME_LIMIT_VARIABLE] || DEFAULT_TIME_LIMIT_SECONDS;
+let timeLimit;
+try {
+  timeLimit = migrationTimeLimit({ [TIME_LIMIT_VARIABLE]: timeLimitSetting });
+} catch (error) {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+}
+
+async function main() {
+  console.log(`🔎 Verifying theme "${theme}" (${located.shownDir}, ${located.migrations.length} migration files) against ${target}...\n`);
+
+  let inspection;
+  try {
+    inspection = await inspectTarget(databaseUrl);
+  } catch (error) {
+    console.error(`❌ Could not inspect ${target}: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (inspection.existingObjects.length > 0) {
+    const examples = inspection.existingObjects.map(({ kind, name }) => `${name} (${kind})`).join(', ');
+    console.error(
+      `❌ Refusing to run: ${target} already holds objects, for example ${examples}.\n` +
+      '   This script only runs against a fresh, empty database, to avoid mixing\n' +
+      '   this theme\'s schema and sample data into whatever is already there.'
+    );
+    process.exit(1);
+  }
+
+  console.log('This run also changes these cluster-wide roles, which every database on this server shares:');
+  for (const { role, change } of GLOBAL_OBJECTS) console.log(`   ${role}: ${change}`);
+  console.log('');
+
+  const maintenance = await inspectMaintenanceDatabase(databaseUrl);
+  const cluster = inspectCluster({ ...inspection, maintenance });
+  if (!cluster.disposable && !acknowledgesClusterChanges) {
+    console.error(
+      `❌ Refusing to run: ${target} is on a Postgres server that is not this run's to change.\n` +
+      cluster.reasons.map(reason => `   - ${reason}\n`).join('') +
+      '   The roles above are cluster-wide: altering them here reaches every database\n' +
+      '   on this server. Point the run at a disposable Postgres server, or, if this\n' +
+      `   server is yours to change, re-run it with ${ACKNOWLEDGEMENT_VAR}=1.`
+    );
+    process.exit(1);
+  }
+  if (!cluster.disposable) {
+    console.log(`⚠️  ${ACKNOWLEDGEMENT_VAR}=1: changing those roles on a server in use (${cluster.reasons.join('; ')}).\n`);
+  }
+
+  console.log(`Each migration may run for ${timeLimit.seconds} s; ${TIME_LIMIT_VARIABLE} changes that.\n`);
+
+  const { MIGRATE_DATABASE_URL: _migrateUrl, VERIFY_THEME_DATABASE_URL: _verifyUrl, ...inheritedEnv } = process.env;
+
+  const result = spawnSync(process.execPath, [runnerPath, '--no-env-file'], {
+    cwd: located.projectDir,
+    stdio: 'inherit',
+    env: {
+      ...inheritedEnv,
+      DATABASE_URL: databaseUrl,
+      NEXT_PUBLIC_ACTIVE_THEME: theme,
+      [TIME_LIMIT_VARIABLE]: timeLimitSetting,
+    },
+  });
+
+  if (result.status !== 0) {
+    const reason = result.signal ? `signal ${result.signal}` : `exit code ${result.status}`;
+    console.error(`\n❌ Theme "${theme}" migrations failed (${reason}).`);
+    process.exit(result.status ?? 1);
+  }
+
+  console.log(`\n✅ Theme "${theme}" migrations ran cleanly against ${target}.`);
+}
+
+main();