turbine-orm 0.81.0 → 0.90.0

package/dist/cli/migrate.d.ts

@@ -14,6 +14,7 @@
 import type { DatabaseAdapter } from '../adapters/index.js';
 import { type Dialect } from '../dialect.js';
 import type { PgCompatQueryResult } from '../pg-types.js';
+import { type TypeWidening } from '../schema-sql.js';
 import { type DestructiveStatement } from './destructive.js';
 import { splitSqlStatements } from './sql-statements.js';
 /**
@@ -111,6 +112,14 @@ export declare function migrationTimestamp(name: string): string | null;
  * @internal exported for tests.
  */
 export declare function assertNoEmbeddedTransactions(files: MigrationFile[], section: 'up' | 'down'): void;
+/** The marker line for a {@link TypeWidening}. */
+export declare function wideningMarker(w: Pick<TypeWidening, 'from' | 'to'>): string;
+/**
+ * {@link scanDestructiveSql}, minus the `ALTER COLUMN ... TYPE` statements that
+ * carry a checked widening marker. Everything else is reported exactly as the
+ * scanner reports it.
+ */
+export declare function scanMigrationDestructive(sql: string): DestructiveStatement[];
 /** Scan a set of migration files' UP sections for data-destroying statements. */
 export declare function collectUpDestructive(files: MigrationFile[]): DestructiveOffender[];
 /**
@@ -166,7 +175,14 @@ export declare function headerSafeName(name: string): string;
  */
 export declare function sanitizeName(name: string): string;
 /**
- * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date, in UTC.
+ *
+ * Apply order is the filename order, so two people who create migrations in
+ * different time zones must stamp the same instant with the same digits. In local
+ * time a migration made at 09:00 in Berlin (07:00 UTC) sorted AFTER one made at
+ * 08:00 in New York (13:00 UTC) the same morning, and ran out of creation order.
+ * Files already on disk keep their local-time names; the runner reads any 14
+ * digits.
  */
 export declare function formatTimestamp(date: Date): string;
 /**
@@ -181,10 +197,14 @@ export declare function listMigrationFiles(migrationsDir: string): MigrationFile
 /**
  * `.sql` files in `migrationsDir` that the runner NEVER sees, because their
  * name lacks the `YYYYMMDDHHMMSS_<name>.sql` shape {@link listMigrationFiles}
- * requires (a hand-written `add_thing.sql`, a 13-digit prefix). Such a file
- * used to be skipped in silence by `status`, `up` and `deploy` alike, so a
- * misnamed migration simply never ran and nothing said so. The CLI prints one
- * warning per entry.
+ * requires (a hand-written `add_thing.sql`, a 13-digit prefix, an upper-case
+ * `.SQL` extension). Such a file used to be skipped in silence by `status`,
+ * `up` and `deploy` alike, so a misnamed migration simply never ran and
+ * nothing said so. The CLI prints one warning per entry.
+ *
+ * The extension is matched in any case here and only in lower case by the
+ * runner: `20260101000000_init.SQL` is a migration somebody meant to run, so
+ * it is reported rather than ignored like a `.txt` file.
  */
 export declare function listIgnoredSqlFiles(migrationsDir: string): string[];
 /** The parsed sections of a migration file plus its execution directives. */
@@ -283,6 +303,11 @@ export interface DiffMigrationBody {
  *   when any exist, a loud file-level banner is prepended to UP.
  * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
  *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ * - A type change the diff proved lossless (`widenings`) is not flagged: it is
+ *   preceded by a {@link wideningMarker}, which `migrate up` checks before it
+ *   stops excusing the statement.
+ * - Every `DROP COLUMN` in UP has a comment block in DOWN saying the data
+ *   cannot be restored automatically (the diff supplies it as a reverse entry).
  *
  * Pure and DB-free, so it is unit-testable from a synthesized diff.
  */
@@ -290,6 +315,7 @@ export declare function buildDiffMigrationBody(diff: {
     statements: string[];
     reverseStatements: string[];
     warnings?: string[];
+    widenings?: readonly TypeWidening[];
 }): DiffMigrationBody;
 /**
  * Create a new migration file.
@@ -479,6 +505,32 @@ export interface MigrationLock {
  * @internal exported for tests.
  */
 export declare function acquireMigrationLock(runner: MigrationLockClient, lockId: number, adapter: DatabaseAdapter | undefined, openLockConnection: () => Promise<MigrationLockClient>): Promise<MigrationLock>;
+/** How long, and how, {@link acquireMigrationLockWaiting} waits for a held lock. */
+export interface MigrationLockWait {
+    /** The longest total wait, in milliseconds. */
+    timeoutMs: number;
+    /** The pause between attempts, in milliseconds. Default 1000. */
+    intervalMs?: number;
+    /** Called once, on the first refusal, so the CLI can say it is waiting. */
+    onWait?: () => void;
+    /** @internal clock and sleep, replaced by tests. */
+    now?: () => number;
+    /** @internal */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * {@link acquireMigrationLock}, retried until `wait.timeoutMs` has passed.
+ *
+ * Polls the adapter's own non-blocking acquire rather than issuing a blocking
+ * `pg_advisory_lock`: a blocking wait needs a `lock_timeout` to be bounded, and
+ * setting one is a `SET`, which must never run on a connection that may sit
+ * behind a pooler. Polling needs nothing but the statement the adapter already
+ * uses, and works for the lock-table adapters too. Without `wait` it is exactly
+ * one attempt, which is what every caller did before.
+ *
+ * @internal exported for tests.
+ */
+export declare function acquireMigrationLockWaiting(runner: MigrationLockClient, lockId: number, adapter: DatabaseAdapter | undefined, openLockConnection: () => Promise<MigrationLockClient>, wait?: MigrationLockWait): Promise<MigrationLock>;
 /**
  * Release a lock taken by {@link acquireMigrationLock}, and close the dedicated
  * connection when there is one. A refused lock owns nothing, so releasing it is
@@ -598,6 +650,18 @@ export declare function formatChecksumMismatchError(mismatches: ChecksumMismatch
  * @internal exported for tests.
  */
 export declare function assertUpHasStatements(files: MigrationFile[]): void;
+/** True when `sql` holds at least one statement that is not just comments. */
+export declare function hasExecutableStatement(sql: string): boolean;
+/**
+ * The files among `files` whose DOWN section runs no SQL at all (comments only).
+ *
+ * A diff-generated migration that drops a column ships a commented IRREVERSIBLE
+ * note as its DOWN, because no statement can bring the data back. Rolling such a
+ * migration back succeeds, removes its tracking row, and restores nothing, so
+ * the CLI names these files after a rollback instead of letting "rolled back"
+ * stand unqualified.
+ */
+export declare function rollbacksWithoutSql(files: readonly MigrationFile[]): MigrationFile[];
 /**
  * Build a deploy plan from local migration files and applied migration rows.
  * This is pure file-system planning; callers with a database connection should
@@ -642,6 +706,14 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
      * SQL and the tracking table alike. See {@link connectionStringForSchema}.
      */
     schema?: string;
+    /**
+     * Wait up to this many milliseconds for another migration to release the
+     * lock, instead of failing at once. The pending list is read AFTER the lock
+     * is taken, so whatever the other run applied is simply no longer pending.
+     */
+    lockWaitMs?: number;
+    /** Called once when the lock is held by someone else and the wait begins. */
+    onLockWait?: () => void;
 }): Promise<MigrationRunResult>;
 /**
  * Production migration apply. This intentionally applies files as written and
@@ -651,6 +723,9 @@ export declare function migrateDeploy(connectionString: string, migrationsDir: s
     adapter?: DatabaseAdapter;
     allowDrift?: boolean;
     schema?: string;
+    /** Wait up to this many milliseconds for a concurrent deploy to finish. See `migrateUp`. */
+    lockWaitMs?: number;
+    onLockWait?: () => void;
 }): Promise<MigrationRunResult>;
 /**
  * Roll back a prepared LIFO batch, newest first, stopping at the first
@@ -738,3 +813,36 @@ export declare function migrateDown(connectionString: string, migrationsDir: str
 export declare function migrateStatus(connectionString: string, migrationsDir: string, options?: {
     schema?: string;
 }): Promise<MigrationStatus[]>;
+/** The migration files in `statuses` that have not been applied to the database. */
+export declare function pendingMigrationFiles(statuses: readonly MigrationStatus[]): MigrationFile[];
+/**
+ * The refusal `migrate create --auto` / `--from-diff` prints while migrations
+ * are still pending.
+ *
+ * Both flags diff the schema file against the LIVE database. A pending migration
+ * is a change the file already describes and the database does not have yet, so
+ * the diff reports it AGAIN: the new migration repeats those statements and
+ * fails on the first database that applies the pending one before it.
+ */
+export declare function formatPendingAutoRefusal(pending: readonly MigrationFile[], flag: string): string;
+/** What `migrate status --exit-code` decides from. */
+export interface MigrationHealth {
+    /** Migration files not yet applied. */
+    pending: number;
+    /** Applied migrations whose file has changed since. */
+    drifted: number;
+    /** Applied migrations whose file is gone. */
+    missing: number;
+    /** True only when all three are zero. */
+    ok: boolean;
+}
+/**
+ * Every reason `migrate status --exit-code` exits 2, as phrases for the message.
+ * Empty means the gate passes. `ignoredFiles` are the `.sql` files in the
+ * migrations directory whose name the runner never matches (see
+ * {@link listIgnoredSqlFiles}): a migration that will never run is as much a
+ * disagreement between the files and the database as a pending one.
+ */
+export declare function statusGateProblems(health: MigrationHealth, ignoredFiles: readonly string[]): string[];
+/** Count the ways a migration history can disagree with the files on disk. */
+export declare function summarizeMigrationStatus(statuses: readonly MigrationStatus[]): MigrationHealth;

package/dist/cli/migrate.js

@@ -20,6 +20,7 @@ import { guardConnection } from '../connection-guard.js';
 import { isPlainSchemaIdentifier, parseSearchPathValue, withSearchPathOption } from '../connection-url.js';
 import { postgresDialect } from '../dialect.js';
 import { MigrationError, ValidationError } from '../errors.js';
+import { isLosslessWidening } from '../schema-sql.js';
 import { DESTRUCTIVE_KIND_LABEL, scanDestructiveSql } from './destructive.js';
 import { splitSqlStatements, tokenizeSql } from './sql-statements.js';
 /**
@@ -76,6 +77,81 @@ export function assertNoEmbeddedTransactions(files, section) {
     lines.push('add `-- turbine:no-transaction` to the file header and manage it yourself.');
     throw new MigrationError(lines.join('\n'));
 }
+// ---------------------------------------------------------------------------
+// Lossless type widenings
+// ---------------------------------------------------------------------------
+/**
+ * The comment a diff-generated migration puts directly above an
+ * `ALTER COLUMN ... TYPE` that cannot lose a value: `-- turbine:widening
+ * <from> -> <to>`.
+ *
+ * `ALTER COLUMN ... TYPE` is a destructive statement to the scanner, which can
+ * read the new type and nothing else. The generator knows the old one, so it
+ * says what it knows in the file, and {@link scanMigrationDestructive} believes
+ * the claim only as far as it can check it: the pair must itself be a lossless
+ * widening ({@link isLosslessWidening}) and the statement below must change that
+ * one column to exactly the claimed type. It is an accident guard, like the rest
+ * of the scanner: a hand-written marker over a column whose real type differs
+ * from `from` is not caught.
+ */
+const WIDENING_MARKER = /^--\s*turbine:widening\s+(.+?)\s*->\s*(.+?)\s*$/i;
+/** `ALTER TABLE <t> ALTER [COLUMN] <c> [SET DATA] TYPE <type>` and nothing else. */
+const SINGLE_ALTER_TYPE = /^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:ONLY\s+)?(?:"[^"]+"|[A-Za-z_][\w$]*)(?:\.(?:"[^"]+"|[A-Za-z_][\w$]*))?\s+ALTER\s+(?:COLUMN\s+)?(?:"[^"]+"|[A-Za-z_][\w$]*)\s+(?:SET\s+DATA\s+)?TYPE\s+((?:[^,();]|\([^)]*\))+?)\s*$/i;
+/** The marker's claim from a statement's leading comment lines, or null. */
+function leadingWideningClaim(raw) {
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t === '')
+            continue;
+        const m = WIDENING_MARKER.exec(t);
+        if (m)
+            return { from: m[1], to: m[2] };
+        if (!t.startsWith('--'))
+            break;
+    }
+    return null;
+}
+const normalizeTypeText = (t) => t.replace(/\s+/g, ' ').trim().toUpperCase();
+/** The marker line for a {@link TypeWidening}. */
+export function wideningMarker(w) {
+    return `-- turbine:widening ${w.from} -> ${w.to}`;
+}
+/**
+ * {@link scanDestructiveSql}, minus the `ALTER COLUMN ... TYPE` statements that
+ * carry a checked widening marker. Everything else is reported exactly as the
+ * scanner reports it.
+ */
+export function scanMigrationDestructive(sql) {
+    const hits = scanDestructiveSql(sql);
+    if (!hits.some((h) => h.kind === 'alter-column-type'))
+        return hits;
+    // How many marked widenings of each statement text the file holds, so that one
+    // marked statement cannot excuse an identical unmarked one beside it.
+    const excused = new Map();
+    for (const st of tokenizeSql(sql)) {
+        if (st.commentOnly)
+            continue;
+        const claim = leadingWideningClaim(st.raw);
+        if (!claim || !isLosslessWidening(claim.from, claim.to))
+            continue;
+        const display = st.stripped.replace(/\s+/g, ' ');
+        const alter = SINGLE_ALTER_TYPE.exec(display.trim());
+        if (!alter || normalizeTypeText(alter[1]) !== normalizeTypeText(claim.to))
+            continue;
+        excused.set(display, (excused.get(display) ?? 0) + 1);
+    }
+    if (excused.size === 0)
+        return hits;
+    return hits.filter((h) => {
+        if (h.kind !== 'alter-column-type')
+            return true;
+        const left = excused.get(h.statement) ?? 0;
+        if (left === 0)
+            return true;
+        excused.set(h.statement, left - 1);
+        return false;
+    });
+}
 /** Scan a set of migration files' UP sections for data-destroying statements. */
 export function collectUpDestructive(files) {
     const offenders = [];
@@ -83,7 +159,7 @@ export function collectUpDestructive(files) {
         const { up } = parseMigrationSQL(file.path);
         if (!up)
             continue;
-        const hits = scanDestructiveSql(up);
+        const hits = scanMigrationDestructive(up);
         if (hits.length > 0)
             offenders.push({ file: file.filename, hits });
     }
@@ -240,16 +316,23 @@ export function sanitizeName(name) {
         .replace(/^_|_$/g, '');
 }
 /**
- * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date, in UTC.
+ *
+ * Apply order is the filename order, so two people who create migrations in
+ * different time zones must stamp the same instant with the same digits. In local
+ * time a migration made at 09:00 in Berlin (07:00 UTC) sorted AFTER one made at
+ * 08:00 in New York (13:00 UTC) the same morning, and ran out of creation order.
+ * Files already on disk keep their local-time names; the runner reads any 14
+ * digits.
  */
 export function formatTimestamp(date) {
     return [
-        date.getFullYear(),
-        String(date.getMonth() + 1).padStart(2, '0'),
-        String(date.getDate()).padStart(2, '0'),
-        String(date.getHours()).padStart(2, '0'),
-        String(date.getMinutes()).padStart(2, '0'),
-        String(date.getSeconds()).padStart(2, '0'),
+        date.getUTCFullYear(),
+        String(date.getUTCMonth() + 1).padStart(2, '0'),
+        String(date.getUTCDate()).padStart(2, '0'),
+        String(date.getUTCHours()).padStart(2, '0'),
+        String(date.getUTCMinutes()).padStart(2, '0'),
+        String(date.getUTCSeconds()).padStart(2, '0'),
     ].join('');
 }
 /**
@@ -282,16 +365,20 @@ export function listMigrationFiles(migrationsDir) {
 /**
  * `.sql` files in `migrationsDir` that the runner NEVER sees, because their
  * name lacks the `YYYYMMDDHHMMSS_<name>.sql` shape {@link listMigrationFiles}
- * requires (a hand-written `add_thing.sql`, a 13-digit prefix). Such a file
- * used to be skipped in silence by `status`, `up` and `deploy` alike, so a
- * misnamed migration simply never ran and nothing said so. The CLI prints one
- * warning per entry.
+ * requires (a hand-written `add_thing.sql`, a 13-digit prefix, an upper-case
+ * `.SQL` extension). Such a file used to be skipped in silence by `status`,
+ * `up` and `deploy` alike, so a misnamed migration simply never ran and
+ * nothing said so. The CLI prints one warning per entry.
+ *
+ * The extension is matched in any case here and only in lower case by the
+ * runner: `20260101000000_init.SQL` is a migration somebody meant to run, so
+ * it is reported rather than ignored like a `.txt` file.
  */
 export function listIgnoredSqlFiles(migrationsDir) {
     if (!existsSync(migrationsDir))
         return [];
     return readdirSync(migrationsDir)
-        .filter((f) => f.endsWith('.sql') && parseMigrationFilename(f) === null)
+        .filter((f) => /\.sql$/i.test(f) && parseMigrationFilename(f) === null)
         .sort();
 }
 /**
@@ -540,19 +627,50 @@ const DESTRUCTIVE_MIGRATION_BANNER = [
     '-- every flagged statement carefully before running.',
     '-- ============================================================',
 ];
+/** Same banner when only the DOWN direction is destructive: UP runs without a prompt. */
+const DESTRUCTIVE_DOWN_ONLY_BANNER = [
+    '-- ============================================================',
+    '-- WARNING: this migration contains DESTRUCTIVE statement(s).',
+    '-- Only the DOWN section is destructive (flagged inline there).',
+    '-- `turbine migrate up` runs UP as written; `turbine migrate down`',
+    '-- asks you to confirm before it runs the flagged statements.',
+    '-- ============================================================',
+];
+/** True for a block that is nothing but comments and blank lines. */
+function isCommentBlock(text) {
+    return text.split('\n').every((line) => {
+        const t = line.trim();
+        return t === '' || t.startsWith('--');
+    });
+}
 /**
  * Annotate a list of SQL statements: scan each for data-destroying operations
  * (via {@link scanDestructiveSql}) and prefix any offender with loud, commented
  * warnings. Statements are left intact so the existing `migrate up` gate still
  * refuses them by default; the comments just make the danger visible on review.
+ *
+ * A comment-only entry (the DOWN placeholder for a dropped column) is written
+ * through untouched: it is not SQL, so it is neither scanned nor given a `;`.
+ * A statement the diff proved to be a lossless widening gets its
+ * {@link wideningMarker} instead of a warning, and is not scanned.
  */
-function annotateDiffStatements(statements) {
+function annotateDiffStatements(statements, widenings = []) {
     const destructive = [];
     const out = [];
+    const widened = new Map(widenings.map((w) => [w.statement.trim(), w]));
     for (const raw of statements) {
         const stmt = raw.trim();
         if (!stmt)
             continue;
+        if (isCommentBlock(stmt)) {
+            out.push(stmt);
+            continue;
+        }
+        const widening = widened.get(stmt.endsWith(';') ? stmt : `${stmt};`);
+        if (widening) {
+            out.push(wideningMarker(widening), stmt.endsWith(';') ? stmt : `${stmt};`);
+            continue;
+        }
         const hits = scanDestructiveSql(stmt);
         if (hits.length > 0) {
             destructive.push(...hits);
@@ -575,18 +693,23 @@ function annotateDiffStatements(statements) {
  *   when any exist, a loud file-level banner is prepended to UP.
  * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
  *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ * - A type change the diff proved lossless (`widenings`) is not flagged: it is
+ *   preceded by a {@link wideningMarker}, which `migrate up` checks before it
+ *   stops excusing the statement.
+ * - Every `DROP COLUMN` in UP has a comment block in DOWN saying the data
+ *   cannot be restored automatically (the diff supplies it as a reverse entry).
  *
  * Pure and DB-free, so it is unit-testable from a synthesized diff.
  */
 export function buildDiffMigrationBody(diff) {
-    const up = annotateDiffStatements(diff.statements);
+    const up = annotateDiffStatements(diff.statements, diff.widenings);
     const hasReverse = diff.reverseStatements.length > 0;
     const down = hasReverse
         ? annotateDiffStatements(diff.reverseStatements)
         : { text: '', destructive: [] };
     const upParts = [];
     if (up.destructive.length > 0 || down.destructive.length > 0) {
-        upParts.push(...DESTRUCTIVE_MIGRATION_BANNER, '');
+        upParts.push(...(up.destructive.length > 0 ? DESTRUCTIVE_MIGRATION_BANNER : DESTRUCTIVE_DOWN_ONLY_BANNER), '');
     }
     if (diff.warnings && diff.warnings.length > 0) {
         for (const w of diff.warnings)
@@ -676,7 +799,18 @@ ${autoContent.down}
 -- Write your rollback SQL here
 `;
     }
-    writeFileSync(filePath, template, 'utf-8');
+    // `wx` (create, fail if the name exists): the name carries a one-second
+    // timestamp, so a second create with the same name in that second would
+    // otherwise silently replace the first file, edits included.
+    try {
+        writeFileSync(filePath, template, { encoding: 'utf-8', flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        throw new MigrationError(`Migration file ${filename} already exists, and its name is timestamped to the second. ` +
+            'Wait a second and run the command again, or choose a different name.');
+    }
     return {
         filename,
         path: filePath,
@@ -921,6 +1055,33 @@ export async function acquireMigrationLock(runner, lockId, adapter, openLockConn
         throw err;
     }
 }
+/**
+ * {@link acquireMigrationLock}, retried until `wait.timeoutMs` has passed.
+ *
+ * Polls the adapter's own non-blocking acquire rather than issuing a blocking
+ * `pg_advisory_lock`: a blocking wait needs a `lock_timeout` to be bounded, and
+ * setting one is a `SET`, which must never run on a connection that may sit
+ * behind a pooler. Polling needs nothing but the statement the adapter already
+ * uses, and works for the lock-table adapters too. Without `wait` it is exactly
+ * one attempt, which is what every caller did before.
+ *
+ * @internal exported for tests.
+ */
+export async function acquireMigrationLockWaiting(runner, lockId, adapter, openLockConnection, wait) {
+    let lock = await acquireMigrationLock(runner, lockId, adapter, openLockConnection);
+    if (lock.acquired || !wait)
+        return lock;
+    const now = wait.now ?? Date.now;
+    const sleep = wait.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const interval = wait.intervalMs ?? 1000;
+    const deadline = now() + wait.timeoutMs;
+    wait.onWait?.();
+    while (!lock.acquired && now() < deadline) {
+        await sleep(Math.max(0, Math.min(interval, deadline - now())));
+        lock = await acquireMigrationLock(runner, lockId, adapter, openLockConnection);
+    }
+    return lock;
+}
 /**
  * Release a lock taken by {@link acquireMigrationLock}, and close the dedicated
  * connection when there is one. A refused lock owns nothing, so releasing it is
@@ -1147,14 +1308,29 @@ action = 'apply pending migrations') {
 export function assertUpHasStatements(files) {
     for (const file of files) {
         const { up } = parseMigrationSQL(file.path);
-        const executable = tokenizeSql(up).filter((s) => !s.commentOnly && s.stripped.trim() !== '');
-        if (executable.length > 0)
+        if (hasExecutableStatement(up))
             continue;
         throw new MigrationError(`Migration ${file.filename} has an UP section with no executable statement (comments only). ` +
             `Applying it would record the migration as applied while running nothing, and filling the file in ` +
             `afterwards would then be refused as drift. Write the UP section or delete the file.`);
     }
 }
+/** True when `sql` holds at least one statement that is not just comments. */
+export function hasExecutableStatement(sql) {
+    return tokenizeSql(sql).some((s) => !s.commentOnly && s.stripped.trim() !== '');
+}
+/**
+ * The files among `files` whose DOWN section runs no SQL at all (comments only).
+ *
+ * A diff-generated migration that drops a column ships a commented IRREVERSIBLE
+ * note as its DOWN, because no statement can bring the data back. Rolling such a
+ * migration back succeeds, removes its tracking row, and restores nothing, so
+ * the CLI names these files after a rollback instead of letting "rolled back"
+ * stand unqualified.
+ */
+export function rollbacksWithoutSql(files) {
+    return files.filter((f) => f.path !== '' && !hasExecutableStatement(parseMigrationSQL(f.path).down));
+}
 /**
  * Build a deploy plan from local migration files and applied migration rows.
  * This is pure file-system planning; callers with a database connection should
@@ -1240,9 +1416,13 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         // table-lock adapter gets its OWN connection so the per-migration
         // BEGIN/COMMIT below cannot end the transaction the lock lives in.
         const adapter = options?.adapter;
-        const lock = await acquireMigrationLock(client, lockId, adapter, () => openLockConnection(url));
+        const lockWaitMs = options?.lockWaitMs;
+        const lock = await acquireMigrationLockWaiting(client, lockId, adapter, () => openLockConnection(url), lockWaitMs !== undefined && lockWaitMs > 0 ? { timeoutMs: lockWaitMs, onWait: options?.onLockWait } : undefined);
         if (!lock.acquired) {
-            throw new MigrationError('Could not acquire migration lock, another migration is already running');
+            throw new MigrationError(lockWaitMs !== undefined && lockWaitMs > 0
+                ? `Could not acquire migration lock within ${Math.round(lockWaitMs / 1000)}s: another migration is still running. ` +
+                    'Raise --wait if it is expected to take longer.'
+                : 'Could not acquire migration lock, another migration is already running');
         }
         try {
             await ensureTrackingTable(client, dialect);
@@ -1384,6 +1564,8 @@ export async function migrateDeploy(connectionString, migrationsDir, options) {
         allowDestructive: true,
         adapter: options?.adapter,
         schema: options?.schema,
+        lockWaitMs: options?.lockWaitMs,
+        onLockWait: options?.onLockWait,
     });
 }
 /**
@@ -1652,3 +1834,61 @@ export async function migrateStatus(connectionString, migrationsDir, options) {
         await client.end();
     }
 }
+// ---------------------------------------------------------------------------
+// Status helpers (pending files, CI exit code)
+// ---------------------------------------------------------------------------
+/** The migration files in `statuses` that have not been applied to the database. */
+export function pendingMigrationFiles(statuses) {
+    return statuses.filter((st) => !st.applied).map((st) => st.file);
+}
+/**
+ * The refusal `migrate create --auto` / `--from-diff` prints while migrations
+ * are still pending.
+ *
+ * Both flags diff the schema file against the LIVE database. A pending migration
+ * is a change the file already describes and the database does not have yet, so
+ * the diff reports it AGAIN: the new migration repeats those statements and
+ * fails on the first database that applies the pending one before it.
+ */
+export function formatPendingAutoRefusal(pending, flag) {
+    const lines = [
+        `Refusing to create a migration with ${flag}: ${pending.length} migration(s) in the migrations directory are not applied to this database yet:`,
+        '',
+        ...pending.map((f) => `  ${f.filename}`),
+        '',
+        `${flag} compares your schema file with the LIVE database. The pending file(s) above already describe part of`,
+        'that difference, so the new migration would repeat their statements and fail when they run first.',
+        '',
+        'Apply them, then run this command again:   npx turbine migrate up',
+        `If they do not touch what the schema file describes (a data migration, say), pass --allow-pending.`,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Every reason `migrate status --exit-code` exits 2, as phrases for the message.
+ * Empty means the gate passes. `ignoredFiles` are the `.sql` files in the
+ * migrations directory whose name the runner never matches (see
+ * {@link listIgnoredSqlFiles}): a migration that will never run is as much a
+ * disagreement between the files and the database as a pending one.
+ */
+export function statusGateProblems(health, ignoredFiles) {
+    const problems = [];
+    if (health.pending > 0)
+        problems.push(`${health.pending} pending`);
+    if (health.drifted > 0)
+        problems.push(`${health.drifted} modified after being applied`);
+    if (health.missing > 0)
+        problems.push(`${health.missing} missing from disk`);
+    if (ignoredFiles.length > 0) {
+        problems.push(`${ignoredFiles.length} misnamed .sql file(s) that will never run (${ignoredFiles.join(', ')}; ` +
+            `a migration filename is YYYYMMDDHHMMSS_name.sql)`);
+    }
+    return problems;
+}
+/** Count the ways a migration history can disagree with the files on disk. */
+export function summarizeMigrationStatus(statuses) {
+    const pending = statuses.filter((st) => !st.applied).length;
+    const missing = statuses.filter((st) => st.missingFile).length;
+    const drifted = statuses.filter((st) => st.applied && st.checksumValid === false && !st.missingFile).length;
+    return { pending, drifted, missing, ok: pending === 0 && drifted === 0 && missing === 0 };
+}

package/dist/cli/observe.d.ts

@@ -7,6 +7,7 @@
  */
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { PgCompatPool } from '../pg-types.js';
+import { type TicketGate } from './local-server-guard.js';
 export interface ObserveOptions {
     url: string;
     port: number;
@@ -15,11 +16,15 @@ export interface ObserveOptions {
 }
 export interface ObserveServerHandle {
     dispose: () => Promise<void>;
+    /** The session credential (header or cookie). Never part of `url`. */
     authToken: string;
+    /** Printable URL carrying a ONE-TIME login ticket, exchanged for the session cookie on first load. */
     url: string;
 }
 export declare function startObserve(options: ObserveOptions): Promise<ObserveServerHandle>;
 export declare function handleRequest(req: IncomingMessage, res: ServerResponse, pool: PgCompatPool, options: ObserveOptions, authToken: string, rateLimiter: Map<string, {
     count: number;
     resetAt: number;
-}>): Promise<void>;
+}>, 
+/** The one-time login ticket. Absent on a hand-built call: the ticket is then `authToken` itself. */
+ticketGate?: TicketGate): Promise<void>;