turbine-orm 0.40.0 → 0.40.1

package/dist/cjs/seed.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStackFramePath = parseStackFramePath;
 exports.defineSeed = defineSeed;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -7,29 +8,101 @@ const node_url_1 = require("node:url");
 const client_js_1 = require("./client.js");
 const errors_js_1 = require("./errors.js");
 const emptySchema = { tables: {}, enums: {} };
-function entryUrl() {
-    const entry = process.argv[1];
-    if (!entry)
+/**
+ * Extract the filesystem path from a single V8 stack-trace line, regardless of
+ * whether the frame is a `file://` URL (ESM), a bare absolute path (CJS / tsx),
+ * or a wrapped `(… )` location. The trailing `:line:col` (and any surrounding
+ * parens) are peeled from the END so a Windows drive colon or a URL scheme colon
+ * inside the path never confuses the match. Non-file frames (`node:internal/…`,
+ * `<anonymous>`) return null.
+ *
+ * Exported for unit testing the frame parser in isolation.
+ */
+function parseStackFramePath(line) {
+    // Peel the trailing `:line:col` (with any closing paren) from the END so a
+    // Windows drive colon or a `file://` scheme colon earlier in the path is never
+    // mistaken for the location separator.
+    const loc = line.match(/:(\d+):(\d+)\)?\s*$/);
+    if (!loc || loc.index === undefined)
         return null;
+    let head = line.slice(0, loc.index);
+    const paren = head.lastIndexOf('(');
+    if (paren !== -1) {
+        // `at fn (PATH:line:col)`: the path is whatever the last "(" wraps.
+        head = head.slice(paren + 1);
+    }
+    else {
+        // `at PATH:line:col`: drop the leading "    at " prefix.
+        head = head.replace(/^\s*at\s+/, '');
+    }
+    head = head.trim();
+    if (head.startsWith('file://')) {
+        try {
+            return (0, node_url_1.fileURLToPath)(head);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Accept only absolute filesystem paths (POSIX `/…` or Windows `C:\…` / `C:/…`).
+    if (/^(\/|[A-Za-z]:[\\/])/.test(head))
+        return head;
+    return null;
+}
+/** Best-effort canonicalization so two spellings of the same file compare equal. */
+function canonicalPath(p) {
     try {
-        return (0, node_url_1.pathToFileURL)((0, node_fs_1.realpathSync)(entry)).href;
+        return (0, node_fs_1.realpathSync)(p);
     }
     catch {
-        return (0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(entry)).href;
+        return (0, node_path_1.resolve)(p);
+    }
+}
+/**
+ * The canonical path of THIS module's own file, captured once at load time from
+ * a fresh stack. It is used to skip the library's own frames when locating the
+ * caller. This is robust to the src (`seed.ts`) vs published dist (`seed.js`)
+ * basename difference AND to the fact that the user's own file is ALSO named
+ * `seed.ts`, which a basename skip-list would wrongly exclude. This fixes the
+ * silent no-op: previously the plain-path skip-list only knew `src/seed.ts`, so
+ * the library's own `dist/seed.js` frame (or a tsx plain-path frame) was
+ * mistaken for the caller and the entry===caller self-run check never passed.
+ */
+const SELF_PATH = (() => {
+    const stack = new Error().stack;
+    if (!stack)
+        return null;
+    // Frame [1] (after the "Error" header) is this IIFE, i.e. the current module.
+    for (const line of stack.split('\n').slice(1)) {
+        const p = parseStackFramePath(line);
+        if (p)
+            return canonicalPath(p);
     }
+    return null;
+})();
+function entryUrl() {
+    const entry = process.argv[1];
+    if (!entry)
+        return null;
+    return (0, node_url_1.pathToFileURL)(canonicalPath(entry)).href;
 }
+/**
+ * The first stack frame that is NOT part of this module, expressed as a
+ * canonical `file://` URL. That frame is whoever invoked `defineSeed`: the
+ * user's seed module when the file is run directly.
+ */
 function callerUrl() {
     const stack = new Error().stack;
     if (!stack)
         return null;
     for (const line of stack.split('\n').slice(2)) {
-        const fileUrl = line.match(/(file:\/\/\/[^):]+):\d+:\d+/)?.[1];
-        if (fileUrl && !fileUrl.endsWith('/seed.ts') && !fileUrl.endsWith('/seed.js'))
-            return fileUrl;
-        const filePath = line.match(/\(?((?:\/|[A-Za-z]:\\)[^):]+):\d+:\d+\)?/)?.[1];
-        if (filePath && !filePath.endsWith('/src/seed.ts') && !filePath.endsWith('\\src\\seed.ts')) {
-            return (0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(filePath)).href;
-        }
+        const p = parseStackFramePath(line);
+        if (!p)
+            continue;
+        const canonical = canonicalPath(p);
+        if (SELF_PATH && canonical === SELF_PATH)
+            continue; // skip the library's own frames
+        return (0, node_url_1.pathToFileURL)(canonical).href;
     }
     return null;
 }
@@ -38,6 +111,24 @@ function isDirectSeedModule() {
     const caller = callerUrl();
     return process.env.NODE_TEST_CONTEXT === undefined && !!entry && !!caller && entry === caller;
 }
+/**
+ * Signal, to a parent `turbine seed` process, that a defineSeed callback
+ * actually executed to completion. The CLI sets `TURBINE_SEED_SENTINEL` to a
+ * temp path before spawning the seed; if the file never appears the CLI knows
+ * the seed module loaded but no callback ran, and reports that as a failure
+ * instead of a false "Seed completed".
+ */
+function markSeedRan() {
+    const sentinel = process.env.TURBINE_SEED_SENTINEL;
+    if (!sentinel)
+        return;
+    try {
+        (0, node_fs_1.writeFileSync)(sentinel, 'ran');
+    }
+    catch {
+        // Best-effort only: an unwritable sentinel must never fail a good seed run.
+    }
+}
 async function runSeed(fn) {
     const connectionString = process.env.DATABASE_URL;
     if (!connectionString) {
@@ -46,6 +137,7 @@ async function runSeed(fn) {
     const db = new client_js_1.TurbineClient({ connectionString }, emptySchema);
     try {
         await fn(db);
+        markSeedRan();
     }
     finally {
         await db.disconnect();

package/dist/cli/index.d.ts

@@ -189,8 +189,8 @@ export interface InitPlanFlags {
  * skipped when there is no URL or the database is unreachable.
  */
 export declare function planInitSteps(state: InitPlanState, flags: InitPlanFlags): InitPlanStep[];
-export declare function buildMigrateDeployOptions(_args: CliArgs): {
-    allowDrift: false;
+export declare function buildMigrateDeployOptions(args: CliArgs): {
+    allowDrift: boolean;
     allowDestructive: true;
     step: undefined;
 };

package/dist/cli/index.js

@@ -23,7 +23,8 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
@@ -31,9 +32,10 @@ import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
+import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.js';
-import { buildDiffMigrationBody, createMigration, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
+import { buildDiffMigrationBody, collectUpDestructive, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
 import { startObserve } from './observe.js';
 import { startStudio } from './studio.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
@@ -1086,12 +1088,13 @@ async function cmdMigrate(args, config) {
         console.log(`    ${cyan('status')}                   Show migration status`);
         newline();
         console.log(`  ${bold('Options:')}`);
-        console.log(`    ${cyan('--auto')}             Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${cyan('--from-diff')}        Like --auto, but flags destructive statements in the file`);
+        console.log(`    ${cyan('--auto')}             Auto-generate UP/DOWN SQL from schema diff (destructive flagged)`);
+        console.log(`    ${cyan('--from-diff')}        Generate from schema diff, destructive statements flagged inline`);
         console.log(`    ${cyan('--recipe <name>')}    Scaffold a sanctioned migration pattern`);
         console.log(`    ${cyan('--step, -n')}         Number of migrations to apply/rollback`);
         console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
-        console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+        console.log(`    ${cyan('--allow-destructive')} Run data-destroying statements without prompting`);
+        console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation on ${cyan('up')} / ${cyan('deploy')} ${dim('(advanced)')}`);
         newline();
         console.log(`  ${bold('Recipes')} ${dim('(--recipe):')}`);
         for (const [key, recipe] of Object.entries(MIGRATION_RECIPES)) {
@@ -1174,9 +1177,13 @@ async function cmdMigrateCreate(args, config) {
         }
         diffSpinner.succeed(`Found ${bold(String(diff.statements.length))} change(s)`);
         newline();
-        const upSQL = diff.statements.join('\n');
-        const downSQL = diff.reverseStatements.join('\n');
-        const file = createMigration(config.migrationsDir, name, { up: upSQL, down: downSQL });
+        // Route through buildDiffMigrationBody so any destructive statement (a lossy
+        // ALTER COLUMN ... TYPE, or a DROP COLUMN for a column removed from the
+        // schema) is flagged inline in the file, matching --from-diff. A
+        // destructive-only diff therefore produces a real, flagged migration instead
+        // of the old "already in sync" false negative.
+        const body = buildDiffMigrationBody(diff);
+        const file = createMigration(config.migrationsDir, name, { up: body.up, down: body.down });
         const relPath = relative(process.cwd(), file.path);
         success(`Created auto-migration: ${bold(file.filename)}`);
         newline();
@@ -1204,6 +1211,27 @@ async function cmdMigrateCreate(args, config) {
             }
         }
         newline();
+        // Loudly flag any destructive statements written into the file (same as
+        // --from-diff). They stay intact so `migrate up` still refuses them by
+        // default, but the operator must know they are there before running.
+        const destructiveCount = body.destructiveUp.length + body.destructiveDown.length;
+        if (destructiveCount > 0) {
+            warn(`This migration contains ${bold(String(destructiveCount))} DESTRUCTIVE statement(s), flagged in the file.`);
+            for (const h of body.destructiveUp) {
+                console.log(`    ${red(symbols.warning)} ${dim('UP')}   [${h.kind}] ${h.target}`);
+            }
+            for (const h of body.destructiveDown) {
+                console.log(`    ${red(symbols.warning)} ${dim('DOWN')} [${h.kind}] ${h.target}`);
+            }
+            newline();
+            console.log(`  ${dim('`migrate up` refuses destructive statements by default: confirm interactively or pass')} ${cyan('--allow-destructive')}${dim('.')}`);
+            newline();
+        }
+        if (diff.warnings && diff.warnings.length > 0) {
+            for (const w of diff.warnings)
+                warn(w);
+            newline();
+        }
         console.log(`  ${dim('Review the migration, then run:')}`);
         console.log(`  ${cyan('npx turbine migrate up')}`);
         newline();
@@ -1374,6 +1402,7 @@ async function cmdMigrateUp(args, config) {
             console.log(`    ${green(symbols.check)} ${file.filename}`);
         }
     }
+    warnOutOfOrder(result.outOfOrder);
     if (result.errors.length > 0) {
         spinner.fail('Migration failed');
         for (const { file, error: msg } of result.errors) {
@@ -1385,58 +1414,101 @@ async function cmdMigrateUp(args, config) {
     }
     newline();
 }
-export function buildMigrateDeployOptions(_args) {
+/** Print a one-line warning for each migration applied out of timestamp order. */
+function warnOutOfOrder(outOfOrder) {
+    if (outOfOrder.length === 0)
+        return;
+    newline();
+    for (const o of outOfOrder) {
+        warn(`Applied ${bold(o.applied)} out of order (older than already-applied ${bold(o.newestPrior)}).`);
+    }
+}
+export function buildMigrateDeployOptions(args) {
     return {
-        allowDrift: false,
+        allowDrift: args.allowDrift === true,
         allowDestructive: true,
         step: undefined,
     };
 }
+/**
+ * Print the itemized, classified destructive-statement report as a NOTICE.
+ * `deploy` proceeds by design (the gate ran at author time), but it must not run
+ * data-destroying SQL in total silence; the notice ends that zero-ceremony hole.
+ */
+function printDestructiveNotice(offenders) {
+    warn('NOTICE: this deploy runs DESTRUCTIVE statement(s):');
+    for (const o of offenders) {
+        console.log(`    ${red(symbols.warning)} ${o.file}`);
+        for (const h of o.hits) {
+            console.log(`      ${dim('-')} [${h.kind}] ${h.target} ${dim(DESTRUCTIVE_KIND_LABEL[h.kind])}`);
+        }
+    }
+    newline();
+}
 async function cmdMigrateDeploy(args, config) {
     banner();
     const url = requireUrl(config);
     label('Database', redactUrl(url));
     label('Migrations', config.migrationsDir);
     newline();
-    if (args.dryRun) {
-        const spinner = new Spinner('Checking pending migrations').start();
-        const plan = await inspectMigrationDeploy(url, config.migrationsDir);
-        if (plan.mismatches.length > 0) {
-            spinner.fail('Deploy blocked by migration drift');
-            for (const mismatch of plan.mismatches) {
-                const reason = mismatch.type === 'missing' ? 'deleted from disk' : 'modified on disk';
-                console.log(`    ${red(symbols.cross)} ${mismatch.name}.sql ${dim(`(${reason})`)}`);
+    const spinner = new Spinner('Checking pending migrations').start();
+    const plan = await inspectMigrationDeploy(url, config.migrationsDir);
+    spinner.stop();
+    // Drift handling: honor --allow-drift exactly like `up`. Without it, block;
+    // with it, warn loudly and proceed.
+    if (plan.mismatches.length > 0) {
+        if (!args.allowDrift) {
+            error('Deploy blocked by migration drift');
+            newline();
+            for (const line of formatChecksumMismatchError(plan.mismatches).split('\n')) {
+                console.log(`  ${line.replace('[turbine] ', '')}`);
             }
             newline();
             process.exit(1);
         }
+        warn('--allow-drift is set: checksum validation is DISABLED for this deploy.');
+        console.log(`  ${dim('Applied migrations may have been modified or deleted on disk.')}`);
+        newline();
+    }
+    if (args.dryRun) {
         if (plan.pending.length === 0) {
-            spinner.succeed('No pending migrations');
+            info('No pending migrations');
             newline();
             return;
         }
-        spinner.succeed(`${bold(String(plan.pending.length))} pending migration(s)`);
+        info(`${bold(String(plan.pending.length))} pending migration(s)`);
         for (const file of plan.pending) {
             console.log(`    ${yellow(symbols.dot)} ${file.filename}`);
         }
+        // Surface destructive statements even in a dry run so CI can see them.
+        const destructive = collectUpDestructive(plan.pending);
+        if (destructive.length > 0) {
+            newline();
+            printDestructiveNotice(destructive);
+        }
         newline();
         return;
     }
-    const spinner = new Spinner('Deploying migrations').start();
-    const result = await migrateDeploy(url, config.migrationsDir);
+    // Destructive notice before applying (deploy still proceeds by design).
+    const destructive = collectUpDestructive(plan.pending);
+    if (destructive.length > 0)
+        printDestructiveNotice(destructive);
+    const runSpinner = new Spinner('Deploying migrations').start();
+    const result = await migrateDeploy(url, config.migrationsDir, { allowDrift: args.allowDrift });
     if (result.applied.length === 0 && result.errors.length === 0) {
-        spinner.succeed('0 applied — all migrations are up to date');
+        runSpinner.succeed('0 applied, all migrations are up to date');
         newline();
         return;
     }
     if (result.applied.length > 0) {
-        spinner.succeed(`${bold(String(result.applied.length))} applied`);
+        runSpinner.succeed(`${bold(String(result.applied.length))} applied`);
         for (const file of result.applied) {
             console.log(`    ${green(symbols.check)} ${file.filename}`);
         }
     }
+    warnOutOfOrder(result.outOfOrder);
     if (result.errors.length > 0) {
-        spinner.fail('Deploy failed');
+        runSpinner.fail('Deploy failed');
         for (const { file, error: msg } of result.errors) {
             console.log(`    ${red(symbols.cross)} ${file.filename}`);
             console.log(`      ${dim(msg)}`);
@@ -1553,8 +1625,17 @@ async function cmdMigrateStatus(_args, config) {
     const pendingCount = statuses.filter((s) => !s.applied).length;
     info(`${bold(String(appliedCount))} applied, ${pendingCount > 0 ? yellow(bold(String(pendingCount))) : bold(String(pendingCount))} pending`);
     newline();
-    // Check for checksum mismatches
-    const driftCount = statuses.filter((s) => s.checksumValid === false).length;
+    // Applied migrations whose file was deleted from disk (distinct from an
+    // on-disk edit). Counted in "applied" above; surfaced with their own banner.
+    const missingCount = statuses.filter((s) => s.missingFile).length;
+    if (missingCount > 0) {
+        warn(`${bold(String(missingCount))} applied migration(s) are missing from disk!`);
+        console.log(`  ${dim('The history table records them, but their .sql file is gone.')}`);
+        console.log(`  ${dim('Restore the file(s) before running')} ${cyan('migrate up')} ${dim('or')} ${cyan('migrate deploy')}${dim('.')}`);
+        newline();
+    }
+    // Check for checksum mismatches (on-disk edits only; missing files above).
+    const driftCount = statuses.filter((s) => s.checksumValid === false && !s.missingFile).length;
     if (driftCount > 0) {
         warn(`${bold(String(driftCount))} migration(s) have been modified after application!`);
         console.log(`  ${dim('Applied migrations should be immutable. Modifying them can cause drift.')}`);
@@ -1564,7 +1645,10 @@ async function cmdMigrateStatus(_args, config) {
     const headers = ['Status', 'Migration', 'Applied at'];
     const rows = statuses.map((s) => {
         let status;
-        if (s.applied && s.checksumValid === false) {
+        if (s.missingFile) {
+            status = red(`${symbols.warning} Missing file`);
+        }
+        else if (s.applied && s.checksumValid === false) {
             status = red(`${symbols.warning} Drifted`);
         }
         else if (s.applied) {
@@ -1613,21 +1697,40 @@ async function runSeedPlan(plan, config) {
             if (!canResolveTsx()) {
                 throw new Error('TypeScript seed files require tsx — install tsx or use seed.js/seed.sql.');
             }
+            // The seed runs in a child process, so we cannot observe its callback
+            // directly. Hand it a sentinel path: `defineSeed`'s runner writes the file
+            // only after a callback executes to completion. If the child exits cleanly
+            // but the sentinel never appears, the seed module loaded without running
+            // anything: a silent no-op we must report as a failure, not success.
+            const sentinelDir = mkdtempSync(join(tmpdir(), 'turbine-seed-'));
+            const sentinel = join(sentinelDir, 'ran');
             const { execFileSync } = await import('node:child_process');
-            execFileSync(plan.command, plan.args, {
-                stdio: 'inherit',
-                env: {
-                    ...process.env,
-                    DATABASE_URL: config.url || process.env.DATABASE_URL,
-                },
-            });
+            try {
+                execFileSync(plan.command, plan.args, {
+                    stdio: 'inherit',
+                    env: {
+                        ...process.env,
+                        DATABASE_URL: config.url || process.env.DATABASE_URL,
+                        TURBINE_SEED_SENTINEL: sentinel,
+                    },
+                });
+                if (!existsSync(sentinel)) {
+                    throw new Error('The seed file completed without running a seed callback. ' +
+                        'Make sure it calls defineSeed(async (db) => { ... }) at the top level.');
+                }
+            }
+            finally {
+                rmSync(sentinelDir, { recursive: true, force: true });
+            }
             return;
         }
         if (plan.kind === 'js') {
             const mod = await import(pathToFileURL(plan.file).href);
-            if (typeof mod.default === 'function') {
-                await mod.default();
+            if (typeof mod.default !== 'function') {
+                throw new Error('The seed file has no callable default export. ' +
+                    'Export your seed with `export default defineSeed(async (db) => { ... })`.');
             }
+            await mod.default();
             return;
         }
         const url = requireUrl(config);
@@ -2220,8 +2323,18 @@ function showHelp() {
     newline();
     console.log(`  ${bold('Migrate options:')}`);
     console.log(`    ${cyan('--auto')}               Auto-generate UP/DOWN SQL from schema diff ${dim('(create)')}`);
+    console.log(`    ${cyan('--from-diff')}          Generate from schema diff, destructive statements flagged ${dim('(create)')}`);
+    console.log(`    ${cyan('--recipe')} ${dim('<name>')}       Scaffold a named migration recipe, e.g. backfill ${dim('(create)')}`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}       Number of migrations to apply/rollback`);
-    console.log(`    ${cyan('--allow-drift')}        Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+    console.log(`    ${cyan('--allow-destructive')}  Run data-destroying statements without prompting ${dim('(up/down/push)')}`);
+    console.log(`    ${cyan('--allow-drift')}        Bypass checksum validation on ${cyan('migrate up')} / ${cyan('deploy')} ${dim('(advanced)')}`);
+    newline();
+    console.log(`  ${bold('Init options:')}`);
+    console.log(`    ${cyan('--yes, -y')}            Accept every step's default (non-interactive)`);
+    console.log(`    ${cyan('--skip-schema')}        Don't scaffold the schema file`);
+    console.log(`    ${cyan('--skip-seed')}          Don't scaffold or run the seed file`);
+    console.log(`    ${cyan('--skip-push')}          Don't offer to push the schema to the database`);
+    console.log(`    ${cyan('--skip-generate')}      Don't offer to generate the typed client`);
     newline();
     console.log(`  ${bold('Studio / observe options:')}`);
     console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983 studio, 4984 observe)')}`);

package/dist/cli/migrate.d.ts

@@ -36,7 +36,43 @@ export interface MigrationStatus {
     appliedAt?: Date;
     /** True if the file checksum matches the stored checksum (only set for applied migrations) */
     checksumValid?: boolean;
+    /** True when the migration was applied but its file is missing from disk. */
+    missingFile?: boolean;
+}
+/** A pending migration whose UP section contains data-destroying statements. */
+export interface DestructiveOffender {
+    file: string;
+    hits: DestructiveStatement[];
 }
+/**
+ * A migration that was applied even though an already-applied migration carries
+ * a newer timestamp prefix, i.e. history was written out of order.
+ */
+export interface OutOfOrderApply {
+    /** The out-of-order migration that was just applied. */
+    applied: string;
+    /** The newest previously-applied migration it landed behind. */
+    newestPrior: string;
+}
+export interface MigrationRunResult {
+    applied: MigrationFile[];
+    errors: Array<{
+        file: MigrationFile;
+        error: string;
+    }>;
+    /**
+     * Destructive statements found in the pending batch. Populated whether or not
+     * the run was allowed to proceed, so a caller (deploy) can print a notice even
+     * when it applies them by design.
+     */
+    destructive: DestructiveOffender[];
+    /** Migrations applied with a timestamp older than an already-applied one. */
+    outOfOrder: OutOfOrderApply[];
+}
+/** Extract the YYYYMMDDHHMMSS timestamp prefix from a migration name, or null. */
+export declare function migrationTimestamp(name: string): string | null;
+/** Scan a set of migration files' UP sections for data-destroying statements. */
+export declare function collectUpDestructive(files: MigrationFile[]): DestructiveOffender[];
 /**
  * Parse a migration filename into its components.
  * Expected format: YYYYMMDDHHMMSS_description.sql
@@ -164,6 +200,7 @@ export interface MigrationDeployPlan {
     pending: MigrationFile[];
     mismatches: ChecksumMismatch[];
 }
+export declare function formatChecksumMismatchError(mismatches: ChecksumMismatch[]): string;
 /**
  * Build a deploy plan from local migration files and applied migration rows.
  * This is pure file-system planning; callers with a database connection should
@@ -198,13 +235,7 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
     allowDestructive?: boolean;
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
-}): Promise<{
-    applied: MigrationFile[];
-    errors: Array<{
-        file: MigrationFile;
-        error: string;
-    }>;
-}>;
+}): Promise<MigrationRunResult>;
 /**
  * Production migration apply. This intentionally applies files as written and
  * never performs interactive destructive confirmation.
@@ -212,13 +243,8 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
 export declare function migrateDeploy(connectionString: string, migrationsDir: string, options?: {
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
-}): Promise<{
-    applied: MigrationFile[];
-    errors: Array<{
-        file: MigrationFile;
-        error: string;
-    }>;
-}>;
+    allowDrift?: boolean;
+}): Promise<MigrationRunResult>;
 /**
  * Rollback the last N migrations (DOWN).
  *