turbine-orm 0.4.0 → 0.7.0

package/dist/cli/index.js

@@ -19,15 +19,15 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from 'node:fs';
-import { resolve, relative } from 'node:path';
-import { introspect } from '../introspect.js';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
+import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
-import { loadConfig, resolveConfig, findConfigFile, configTemplate } from './config.js';
-import { createMigration, migrateUp, migrateDown, migrateStatus, listMigrationFiles, } from './migrate.js';
-import { bold, dim, red, green, yellow, blue, cyan, gray, magenta, greenBright, cyanBright, yellowBright, symbols, box, table as formatTable, Spinner, header, success, error, warn, info, label, newline, divider, banner, elapsed, redactUrl, } from './ui.js';
-import { pathToFileURL } from 'node:url';
+import { configTemplate, findConfigFile, loadConfig, resolveConfig } from './config.js';
+import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.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';
 function parseArgs() {
     const args = process.argv.slice(2);
     const result = {
@@ -75,6 +75,9 @@ function parseArgs() {
             case '--dry-run':
                 result.dryRun = true;
                 break;
+            case '--auto':
+                result.auto = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -83,6 +86,10 @@ function parseArgs() {
             case '-v':
                 result.verbose = true;
                 break;
+            case '--help':
+            case '-h':
+                result.help = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -140,7 +147,7 @@ async function cmdInit(args, config) {
     banner();
     header('Initializing Turbine project');
     // Detect environment
-    const envUrl = process.env['DATABASE_URL'];
+    const envUrl = process.env.DATABASE_URL;
     const hasEnvFile = existsSync('.env');
     const hasEnvLocal = existsSync('.env.local');
     if (envUrl) {
@@ -179,7 +186,7 @@ async function cmdInit(args, config) {
         mkdirSync(migrDir, { recursive: true });
         // Create .gitkeep
         writeFileSync(`${migrDir}/.gitkeep`, '', 'utf-8');
-        success(`Created ${cyan(migrDir + '/')}`);
+        success(`Created ${cyan(`${migrDir}/`)}`);
     }
     else {
         info(`Migrations dir already exists: ${dim(migrDir)}`);
@@ -187,7 +194,7 @@ async function cmdInit(args, config) {
     // Create output directory
     if (!existsSync(config.out)) {
         mkdirSync(config.out, { recursive: true });
-        success(`Created ${cyan(config.out + '/')}`);
+        success(`Created ${cyan(`${config.out}/`)}`);
     }
     // Create seed file template
     const seedDir = config.seedFile.substring(0, config.seedFile.lastIndexOf('/'));
@@ -231,7 +238,7 @@ async function cmdInit(args, config) {
  * Define your database schema in TypeScript.
  * Use \`npx turbine push\` to sync it to your database.
  *
- * @see https://github.com/zvndev/turbine-orm
+ * @see https://turbineorm.dev
  */
 
 import { defineSchema } from 'turbine-orm';
@@ -248,13 +255,20 @@ export default defineSchema({
 `, 'utf-8');
         success(`Created ${cyan(config.schemaFile)}`);
     }
-    // Add .gitignore entry for generated output
+    // Add .gitignore entries for generated output and config (may contain connection strings)
     const gitignorePath = '.gitignore';
     if (existsSync(gitignorePath)) {
         const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+        const additions = [];
         if (!gitignoreContent.includes('generated/turbine')) {
-            appendFileSync(gitignorePath, '\n# Turbine generated client\ngenerated/turbine/\n');
-            success(`Added ${cyan('generated/turbine/')} to ${cyan('.gitignore')}`);
+            additions.push('generated/turbine/');
+        }
+        if (!gitignoreContent.includes('turbine.config.ts')) {
+            additions.push('turbine.config.ts');
+        }
+        if (additions.length > 0) {
+            appendFileSync(gitignorePath, `\n# Turbine generated client & config\n${additions.join('\n')}\n`);
+            success(`Added ${cyan(additions.join(', '))} to ${cyan('.gitignore')}`);
         }
     }
     // If we have a URL, run initial generate
@@ -275,15 +289,15 @@ export default defineSchema({
             spinner.succeed(`Found ${bold(String(tableCount))} tables`);
             const genSpinner = new Spinner('Generating TypeScript client').start();
             const result = generate({ schema, outDir: config.out, connectionString: url });
-            genSpinner.succeed(`Generated ${bold(String(result.files.length))} files to ${cyan(config.out + '/')}`);
+            genSpinner.succeed(`Generated ${bold(String(result.files.length))} files to ${cyan(`${config.out}/`)}`);
         }
         catch (err) {
             spinner.fail('Could not connect to database');
             if (err instanceof Error) {
-                console.log(`  ${dim(err.message)}`);
+                console.log(`  ${dim(redactUrl(err.message))}`);
             }
             newline();
-            info('You can run generation later with: ' + cyan('npx turbine generate'));
+            info(`You can run generation later with: ${cyan('npx turbine generate')}`);
         }
     }
     // Next steps
@@ -359,7 +373,7 @@ async function cmdGenerate(args, config) {
     genSpinner.succeed(`Generated ${bold(String(result.files.length))} files in ${elapsed(startTime)}`);
     // List files
     for (const file of result.files) {
-        console.log(`    ${dim(symbols.teeEnd)} ${cyan(result.outDir + '/' + file)}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${cyan(`${result.outDir}/${file}`)}`);
     }
     // Usage hint
     newline();
@@ -407,9 +421,11 @@ async function cmdPush(args, config) {
         for (const a of diff.alter) {
             console.log(`    ${yellow(symbols.arrowRight)} ${a.table}`);
             for (const col of a.columns) {
-                const actionLabel = col.action === 'add' ? green('+ add') :
-                    col.action === 'drop' ? red('- drop') :
-                        yellow('~ ' + col.action.replace('_', ' '));
+                const actionLabel = col.action === 'add'
+                    ? green('+ add')
+                    : col.action === 'drop'
+                        ? red('- drop')
+                        : yellow(`~ ${col.action.replace('_', ' ')}`);
                 console.log(`      ${actionLabel} ${col.column}`);
             }
         }
@@ -463,17 +479,20 @@ async function cmdMigrate(args, config) {
         console.log(`  ${bold('turbine migrate')} ${dim('— SQL-first migration system')}`);
         newline();
         console.log(`  ${bold('Commands:')}`);
-        console.log(`    ${cyan('create <name>')}  Create a new migration file`);
-        console.log(`    ${cyan('up')}             Apply pending migrations`);
-        console.log(`    ${cyan('down')}           Rollback last migration`);
-        console.log(`    ${cyan('status')}         Show migration status`);
+        console.log(`    ${cyan('create <name>')}         Create a new migration file`);
+        console.log(`    ${cyan('create <name> --auto')}  Auto-generate from schema diff`);
+        console.log(`    ${cyan('up')}                    Apply pending migrations`);
+        console.log(`    ${cyan('down')}                  Rollback last migration`);
+        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('--step, -n')}     Number of migrations to apply/rollback`);
         console.log(`    ${cyan('--dry-run')}      Show SQL without executing`);
         newline();
         console.log(`  ${bold('Examples:')}`);
         console.log(`    ${dim('npx turbine migrate create add_users_table')}`);
+        console.log(`    ${dim('npx turbine migrate create add_email_index --auto')}`);
         console.log(`    ${dim('npx turbine migrate up')}`);
         console.log(`    ${dim('npx turbine migrate down --step 2')}`);
         newline();
@@ -507,9 +526,61 @@ async function cmdMigrateCreate(args, config) {
         newline();
         console.log(`  ${dim('Usage:')} ${cyan('npx turbine migrate create <name>')}`);
         console.log(`  ${dim('Example:')} ${cyan('npx turbine migrate create add_users_table')}`);
+        console.log(`  ${dim('Auto:')}    ${cyan('npx turbine migrate create my_change --auto')}`);
         newline();
         process.exit(1);
     }
+    if (args.auto) {
+        // Auto-generate migration from schema diff
+        const url = requireUrl(config);
+        label('Database', redactUrl(url));
+        label('Schema file', config.schemaFile);
+        newline();
+        const schemaDef = await loadSchemaFile(config.schemaFile);
+        const diffSpinner = new Spinner('Computing schema diff').start();
+        const diff = await schemaDiff(schemaDef, url);
+        if (diff.statements.length === 0) {
+            diffSpinner.succeed('Database is already in sync — nothing to migrate');
+            newline();
+            return;
+        }
+        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 });
+        const relPath = relative(process.cwd(), file.path);
+        success(`Created auto-migration: ${bold(file.filename)}`);
+        newline();
+        console.log(`  ${dim('File:')} ${cyan(relPath)}`);
+        newline();
+        // Show summary of changes
+        if (diff.create.length > 0) {
+            console.log(`  ${green('+ Create')} ${diff.create.length} table(s): ${diff.create.map((t) => t.name).join(', ')}`);
+        }
+        if (diff.alter.length > 0) {
+            console.log(`  ${yellow('~ Alter')} ${diff.alter.length} table(s):`);
+            for (const a of diff.alter) {
+                for (const col of a.columns) {
+                    const actionLabel = col.action === 'add'
+                        ? green('+ add')
+                        : col.action === 'drop'
+                            ? red('- drop')
+                            : col.action === 'add_unique'
+                                ? green('+ unique')
+                                : col.action === 'drop_unique'
+                                    ? red('- unique')
+                                    : yellow(`~ ${col.action.replace(/_/g, ' ')}`);
+                    console.log(`    ${actionLabel} ${a.table}.${col.column}`);
+                }
+            }
+        }
+        newline();
+        console.log(`  ${dim('Review the migration, then run:')}`);
+        console.log(`  ${cyan('npx turbine migrate up')}`);
+        newline();
+        return;
+    }
     const file = createMigration(config.migrationsDir, name);
     const relPath = relative(process.cwd(), file.path);
     success(`Created migration: ${bold(file.filename)}`);
@@ -591,7 +662,7 @@ async function cmdMigrateDown(args, config) {
     }
     newline();
 }
-async function cmdMigrateStatus(args, config) {
+async function cmdMigrateStatus(_args, config) {
     banner();
     const url = requireUrl(config);
     label('Database', redactUrl(url));
@@ -621,19 +692,22 @@ async function cmdMigrateStatus(args, config) {
     const rows = statuses.map((s) => {
         let status;
         if (s.applied && s.checksumValid === false) {
-            status = red(symbols.warning + ' Drifted');
+            status = red(`${symbols.warning} Drifted`);
         }
         else if (s.applied) {
-            status = green(symbols.check + ' Applied');
+            status = green(`${symbols.check} Applied`);
         }
         else {
-            status = yellow(symbols.dot + ' Pending');
+            status = yellow(`${symbols.dot} Pending`);
         }
         return [
             status,
             s.file.filename,
             s.appliedAt
-                ? dim(s.appliedAt.toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC'))
+                ? dim(s.appliedAt
+                    .toISOString()
+                    .replace('T', ' ')
+                    .replace(/\.\d+Z$/, ' UTC'))
                 : dim('—'),
         ];
     });
@@ -647,7 +721,7 @@ async function cmdMigrateStatus(args, config) {
 // ---------------------------------------------------------------------------
 // Command: seed
 // ---------------------------------------------------------------------------
-async function cmdSeed(args, config) {
+async function cmdSeed(_args, config) {
     banner();
     const seedFile = resolve(config.seedFile);
     label('Seed file', config.seedFile);
@@ -663,20 +737,20 @@ async function cmdSeed(args, config) {
     const spinner = new Spinner('Running seed file').start();
     try {
         // Use child_process to run the seed file via tsx or node
-        const { execSync } = await import('node:child_process');
+        const { execFileSync } = await import('node:child_process');
         // Try tsx first (most compatible with .ts files), fall back to node --experimental-strip-types
         const runners = [
-            { cmd: 'npx tsx', name: 'tsx' },
-            { cmd: 'node --experimental-strip-types', name: 'node' },
+            { cmd: 'npx', args: ['tsx', seedFile], name: 'tsx' },
+            { cmd: 'node', args: ['--experimental-strip-types', seedFile], name: 'node' },
         ];
         let ran = false;
         for (const runner of runners) {
             try {
-                execSync(`${runner.cmd} ${seedFile}`, {
+                execFileSync(runner.cmd, runner.args, {
                     stdio: 'inherit',
                     env: {
                         ...process.env,
-                        DATABASE_URL: config.url || process.env['DATABASE_URL'],
+                        DATABASE_URL: config.url || process.env.DATABASE_URL,
                     },
                 });
                 ran = true;
@@ -698,7 +772,7 @@ async function cmdSeed(args, config) {
     catch (err) {
         spinner.fail('Seed failed');
         if (err instanceof Error) {
-            console.log(`  ${dim(err.message)}`);
+            console.log(`  ${dim(redactUrl(err.message))}`);
         }
         newline();
         process.exit(1);
@@ -708,7 +782,7 @@ async function cmdSeed(args, config) {
 // ---------------------------------------------------------------------------
 // Command: status
 // ---------------------------------------------------------------------------
-async function cmdStatus(args, config) {
+async function cmdStatus(_args, config) {
     banner();
     const url = requireUrl(config);
     label('Database', redactUrl(url));
@@ -726,7 +800,7 @@ async function cmdStatus(args, config) {
     newline();
     for (const tbl of Object.values(schema.tables)) {
         const relCount = Object.keys(tbl.relations).length;
-        const pk = tbl.primaryKey.join(', ') || dim('(none)');
+        const _pk = tbl.primaryKey.join(', ') || dim('(none)');
         console.log(`  ${bold(cyan(tbl.name))}`);
         for (let i = 0; i < tbl.columns.length; i++) {
             const col = tbl.columns[i];
@@ -735,7 +809,7 @@ async function cmdStatus(args, config) {
             const nullable = col.nullable ? dim('?') : '';
             const def = col.hasDefault ? dim(' (default)') : '';
             const pkLabel = tbl.primaryKey.includes(col.name) ? ` ${magenta('PK')}` : '';
-            console.log(`    ${dim(prefix)} ${col.field}${nullable}: ${green(col.tsType)}${pkLabel}${def}  ${gray(symbols.arrow + ' ' + col.pgType)}`);
+            console.log(`    ${dim(prefix)} ${col.field}${nullable}: ${green(col.tsType)}${pkLabel}${def}  ${gray(`${symbols.arrow} ${col.pgType}`)}`);
         }
         const rels = Object.entries(tbl.relations);
         if (rels.length > 0) {
@@ -768,11 +842,138 @@ async function cmdStudio(_args, _config) {
         'A local web UI for browsing your database,',
         'exploring relations, and managing data.',
         '',
-        `Follow ${cyan('@zvndev')} for updates.`,
+        `Follow ${cyan('@turbineorm')} for updates.`,
     ].join('\n'), { title: bold(cyan('Studio')), padding: 2 }));
     newline();
 }
 // ---------------------------------------------------------------------------
+// Subcommand help
+// ---------------------------------------------------------------------------
+function showSubcommandHelp(command) {
+    const helpMap = {
+        init: showInitHelp,
+        generate: showGenerateHelp,
+        pull: showGenerateHelp,
+        push: showPushHelp,
+        migrate: showMigrateHelp,
+        migration: showMigrateHelp,
+        seed: showSeedHelp,
+        status: showStatusHelp,
+    };
+    const fn = helpMap[command];
+    if (fn) {
+        fn();
+        return true;
+    }
+    return false;
+}
+function showInitHelp() {
+    banner();
+    console.log(`  ${bold('turbine init')} — Initialize a Turbine project`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine init ${dim('[options]')}`);
+    newline();
+    console.log(`  Creates ${cyan('turbine.config.ts')}, migrations directory, seed file template,`);
+    console.log(`  and schema file template.`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string to embed in config`);
+    console.log(`    ${cyan('--force, -f')}        Overwrite existing config file`);
+    newline();
+}
+function showGenerateHelp() {
+    banner();
+    console.log(`  ${bold('turbine generate')} — Introspect database and generate TypeScript types`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine generate ${dim('[options]')}`);
+    newline();
+    console.log(`  Connects to your database, reads the schema, and generates:`);
+    console.log(`    ${dim('•')} ${cyan('types.ts')}    — Entity interfaces, Create/Update input types`);
+    console.log(`    ${dim('•')} ${cyan('metadata.ts')} — Runtime schema metadata`);
+    console.log(`    ${dim('•')} ${cyan('index.ts')}    — Configured client with typed table accessors`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}       Postgres connection string`);
+    console.log(`    ${cyan('--out, -o')} ${dim('<dir>')}       Output directory ${dim('(default: ./generated/turbine)')}`);
+    console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}   Postgres schema ${dim('(default: public)')}`);
+    console.log(`    ${cyan('--include')} ${dim('<tables>')}    Comma-separated tables to include`);
+    console.log(`    ${cyan('--exclude')} ${dim('<tables>')}    Comma-separated tables to exclude`);
+    newline();
+}
+function showPushHelp() {
+    banner();
+    console.log(`  ${bold('turbine push')} — Apply schema-builder definitions to database`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine push ${dim('[options]')}`);
+    newline();
+    console.log(`  Reads your ${cyan('turbine/schema.ts')} file, diffs against the live database,`);
+    console.log(`  and applies CREATE/ALTER statements.`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
+    newline();
+}
+function showMigrateHelp() {
+    banner();
+    console.log(`  ${bold('turbine migrate')} — SQL migration management`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine migrate ${cyan('<subcommand>')} ${dim('[options]')}`);
+    newline();
+    console.log(`  ${bold('Subcommands:')}`);
+    console.log(`    ${cyan('create')} ${dim('<name>')}   Create a new migration file`);
+    console.log(`    ${cyan('up')}              Apply pending migrations`);
+    console.log(`    ${cyan('down')}            Rollback last migration`);
+    console.log(`    ${cyan('status')}          Show applied/pending migrations`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    console.log(`    ${cyan('--step, -n')} ${dim('<N>')}    Number of migrations to apply/rollback`);
+    console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
+    newline();
+    console.log(`  ${bold('Examples:')}`);
+    console.log(`    ${dim('$')} npx turbine migrate create add_users_table`);
+    console.log(`    ${dim('$')} npx turbine migrate up`);
+    console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
+    console.log(`    ${dim('$')} npx turbine migrate status`);
+    newline();
+}
+function showSeedHelp() {
+    banner();
+    console.log(`  ${bold('turbine seed')} — Run seed file`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine seed ${dim('[options]')}`);
+    newline();
+    console.log(`  Runs the seed file specified in ${cyan('turbine.config.ts')}`);
+    console.log(`  ${dim('(default: ./turbine/seed.ts)')}`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    newline();
+}
+function showStatusHelp() {
+    banner();
+    console.log(`  ${bold('turbine status')} — Show database schema summary`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine status ${dim('[options]')}`);
+    newline();
+    console.log(`  Introspects your database and displays tables, columns,`);
+    console.log(`  types, relations, and indexes.`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}       Postgres connection string`);
+    console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}   Postgres schema ${dim('(default: public)')}`);
+    newline();
+}
+// ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
 function showHelp() {
@@ -819,8 +1020,7 @@ function showHelp() {
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
-    // Read version from package.json at build time
-    console.log(`turbine-orm v0.3.0`);
+    console.log(`turbine-orm v0.5.0`);
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -832,6 +1032,13 @@ async function main() {
         showHelp();
         return;
     }
+    // Subcommand help: e.g. `turbine migrate --help`
+    if (args.help) {
+        if (showSubcommandHelp(args.command))
+            return;
+        showHelp();
+        return;
+    }
     if (args.command === 'version' || args.command === '--version' || args.command === '-V') {
         showVersion();
         return;
@@ -897,7 +1104,7 @@ async function main() {
             if (err.message.includes('ECONNREFUSED') || err.message.includes('connection')) {
                 newline();
                 error(`Could not connect to database`);
-                console.log(`  ${dim(err.message)}`);
+                console.log(`  ${dim(redactUrl(err.message))}`);
                 newline();
                 console.log(`  ${dim('Check that:')}`);
                 console.log(`    ${dim('1.')} Your database is running`);
@@ -907,25 +1114,25 @@ async function main() {
             else if (err.message.includes('authentication')) {
                 newline();
                 error(`Authentication failed`);
-                console.log(`  ${dim(err.message)}`);
+                console.log(`  ${dim(redactUrl(err.message))}`);
             }
             else if (err.message.includes('does not exist')) {
                 newline();
                 error(`Database or schema not found`);
-                console.log(`  ${dim(err.message)}`);
+                console.log(`  ${dim(redactUrl(err.message))}`);
             }
             else {
                 newline();
-                error(err.message);
+                error(redactUrl(err.message));
                 if (args.verbose && err.stack) {
                     newline();
-                    console.log(dim(err.stack));
+                    console.log(dim(redactUrl(err.stack)));
                 }
             }
         }
         else {
             newline();
-            error(`Unexpected error: ${String(err)}`);
+            error(`Unexpected error: ${redactUrl(String(err))}`);
         }
         newline();
         process.exit(1);

package/dist/cli/migrate.d.ts

@@ -12,16 +12,14 @@
  *   DROP TABLE users;
  */
 export interface MigrationFile {
-    /** Full filename (e.g. "20260325_001_create_users.sql") */
+    /** Full filename (e.g. "20260325120000_create_users.sql") */
     filename: string;
     /** Absolute path to the file */
     path: string;
-    /** Extracted name portion (e.g. "create_users") */
+    /** Extracted name portion (e.g. "20260325120000_create_users") */
     name: string;
-    /** Timestamp prefix (e.g. "20260325") */
+    /** Timestamp prefix (e.g. "20260325120000") — YYYYMMDDHHMMSS */
     timestamp: string;
-    /** Sequence number (e.g. "001") */
-    sequence: string;
 }
 export interface AppliedMigration {
     id: number;
@@ -36,10 +34,36 @@ export interface MigrationStatus {
     /** True if the file checksum matches the stored checksum (only set for applied migrations) */
     checksumValid?: boolean;
 }
+/**
+ * Parse a migration filename into its components.
+ * Expected format: YYYYMMDDHHMMSS_description.sql
+ */
+export declare function parseMigrationFilename(filename: string): MigrationFile | null;
+/**
+ * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
+ */
+export declare function sanitizeName(name: string): string;
+/**
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ */
+export declare function formatTimestamp(date: Date): string;
+/**
+ * Get pending migration files — those not yet applied.
+ * Returns files sorted by timestamp (ascending).
+ */
+export declare function getPendingMigrations(migrationsDir: string, applied: string[]): MigrationFile[];
 /**
  * List all migration files in the migrations directory, sorted by name.
  */
 export declare function listMigrationFiles(migrationsDir: string): MigrationFile[];
+/**
+ * Parse migration content string into UP and DOWN sections.
+ * Exported for unit testing.
+ */
+export declare function parseMigrationContent(content: string): {
+    up: string;
+    down: string;
+};
 /**
  * Parse a migration file into UP and DOWN sections.
  */
@@ -49,8 +73,12 @@ export declare function parseMigrationSQL(filePath: string): {
 };
 /**
  * Create a new migration file.
+ * If `autoContent` is provided, the UP/DOWN sections are pre-populated with the given SQL.
  */
-export declare function createMigration(migrationsDir: string, name: string): MigrationFile;
+export declare function createMigration(migrationsDir: string, name: string, autoContent?: {
+    up: string;
+    down: string;
+}): MigrationFile;
 /**
  * Apply all pending migrations (UP).
  *
@@ -62,6 +90,7 @@ export declare function createMigration(migrationsDir: string, name: string): Mi
  */
 export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
     step?: number;
+    force?: boolean;
 }): Promise<{
     applied: MigrationFile[];
     errors: Array<{