turbine-orm 0.5.0 → 0.7.1

package/dist/cli/index.js

@@ -19,15 +19,16 @@
  *   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 { needsTsLoader, registerTsLoader } from './loader.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 +76,12 @@ function parseArgs() {
             case '--dry-run':
                 result.dryRun = true;
                 break;
+            case '--auto':
+                result.auto = true;
+                break;
+            case '--allow-drift':
+                result.allowDrift = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -83,6 +90,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);
@@ -93,6 +104,36 @@ function parseArgs() {
     return result;
 }
 // ---------------------------------------------------------------------------
+// TypeScript loader — user-facing error helper
+// ---------------------------------------------------------------------------
+/**
+ * Print a friendly error explaining how to install tsx, then exit.
+ * Called when we know we need to load a `.ts` file but the loader isn't available.
+ */
+function failMissingTsLoader(filePath, reason) {
+    newline();
+    error(`Cannot load TypeScript file: ${filePath}`);
+    newline();
+    if (reason === 'unsupported') {
+        console.log(`  ${dim('Your Node.js version does not support')} ${cyan('module.register()')}.`);
+        console.log(`  ${dim('Upgrade to Node.js')} ${cyan('20.6+')} ${dim('or use a')} ${cyan('.js')} ${dim('/')} ${cyan('.mjs')} ${dim('config file.')}`);
+    }
+    else {
+        console.log(`  ${dim('Loading .ts config / schema files requires')} ${cyan('tsx')} ${dim('to be installed.')}`);
+        newline();
+        console.log(`  ${dim('Install it as a dev dependency:')}`);
+        console.log(`    ${cyan('npm install --save-dev tsx')}`);
+        console.log(`    ${dim('or')}`);
+        console.log(`    ${cyan('pnpm add -D tsx')}`);
+        console.log(`    ${dim('or')}`);
+        console.log(`    ${cyan('yarn add -D tsx')}`);
+        newline();
+        console.log(`  ${dim('Alternatively, rename your file to')} ${cyan('.js')} ${dim('or')} ${cyan('.mjs')}.`);
+    }
+    newline();
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function requireUrl(config) {
@@ -115,6 +156,15 @@ async function loadSchemaFile(schemaFile) {
         console.log(`  ${dim('Create one with:')} ${cyan('turbine init')}`);
         process.exit(1);
     }
+    // If this is a TypeScript file, ensure the tsx ESM loader is registered
+    // before we attempt the dynamic import. Without this, Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    if (needsTsLoader(absPath)) {
+        const status = await registerTsLoader();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(schemaFile, status);
+        }
+    }
     try {
         const fileUrl = pathToFileURL(absPath).href;
         const mod = await import(fileUrl);
@@ -129,6 +179,11 @@ async function loadSchemaFile(schemaFile) {
         error(`Failed to load schema file: ${schemaFile}`);
         if (err instanceof Error) {
             console.log(`  ${dim(err.message)}`);
+            // If the error is the classic ERR_UNKNOWN_FILE_EXTENSION, give a hint.
+            if (err.message.includes('ERR_UNKNOWN_FILE_EXTENSION') || err.message.includes('Unknown file extension')) {
+                newline();
+                console.log(`  ${dim('Hint: install')} ${cyan('tsx')} ${dim('to load .ts files:')} ${cyan('npm install --save-dev tsx')}`);
+            }
         }
         process.exit(1);
     }
@@ -140,7 +195,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 +234,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 +242,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 +286,7 @@ async function cmdInit(args, config) {
  * Define your database schema in TypeScript.
  * Use \`npx turbine push\` to sync it to your database.
  *
- * @see https://batadata.com/docs/turbine/schema
+ * @see https://turbineorm.dev
  */
 
 import { defineSchema } from 'turbine-orm';
@@ -282,15 +337,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
@@ -366,7 +421,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();
@@ -414,9 +469,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}`);
             }
         }
@@ -470,17 +527,21 @@ 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('--step, -n')}     Number of migrations to apply/rollback`);
-        console.log(`    ${cyan('--dry-run')}      Show SQL without executing`);
+        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`);
+        console.log(`    ${cyan('--allow-drift')}    Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
         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();
@@ -514,9 +575,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)}`);
@@ -540,9 +653,18 @@ async function cmdMigrateUp(args, config) {
         newline();
         return;
     }
+    // Big, loud warning when bypassing drift detection — this is a deliberately
+    // dangerous operation and the user should see it on every invocation.
+    if (args.allowDrift) {
+        warn('--allow-drift is set — checksum validation is DISABLED for this run.');
+        console.log(`  ${dim('Applied migrations may have been modified or deleted on disk.')}`);
+        console.log(`  ${dim('Proceed only if you are intentionally rewriting migration history.')}`);
+        newline();
+    }
     const spinner = new Spinner('Applying migrations').start();
     const result = await migrateUp(url, config.migrationsDir, {
         step: args.step,
+        allowDrift: args.allowDrift,
     });
     if (result.applied.length === 0 && result.errors.length === 0) {
         spinner.succeed('All migrations are up to date');
@@ -598,7 +720,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));
@@ -628,19 +750,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('—'),
         ];
     });
@@ -654,7 +779,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);
@@ -670,22 +795,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' },
         ];
-        // Shell-escape the seed file path to prevent injection
-        const escapedSeedFile = seedFile.replace(/'/g, "'\\''");
         let ran = false;
         for (const runner of runners) {
             try {
-                execSync(`${runner.cmd} '${escapedSeedFile}'`, {
+                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;
@@ -707,7 +830,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);
@@ -717,7 +840,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));
@@ -735,7 +858,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];
@@ -744,7 +867,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) {
@@ -777,11 +900,139 @@ async function cmdStudio(_args, _config) {
         'A local web UI for browsing your database,',
         'exploring relations, and managing data.',
         '',
-        `Follow ${cyan('@batadata')} 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('--allow-drift')}      Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
+    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() {
@@ -840,10 +1091,27 @@ 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;
     }
+    // If the user has a TypeScript config file, register the tsx ESM loader
+    // before we attempt to import it. Otherwise Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    const configPath = findConfigFile();
+    if (needsTsLoader(configPath)) {
+        const status = await registerTsLoader();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
+        }
+    }
     // Load config file
     let fileConfig = {};
     try {
@@ -905,7 +1173,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`);
@@ -915,25 +1183,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/loader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * turbine-orm CLI — TypeScript loader registration
+ *
+ * The CLI loads user-supplied config and schema files via dynamic `import()`.
+ * Plain Node has no built-in `.ts` loader, so importing `turbine.config.ts`
+ * blows up with `ERR_UNKNOWN_FILE_EXTENSION` unless we register a TypeScript
+ * loader first.
+ *
+ * Strategy:
+ *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
+ *      probe whether `tsx/esm` is resolvable from the user's CWD.
+ *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
+ *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *
+ * `tsx` is intentionally NOT a runtime dependency — many projects already
+ * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
+ */
+/**
+ * Detect whether a config / schema file path needs the tsx ESM loader.
+ * Returns true for `.ts`, `.mts`, and `.cts` files; false for `.js`, `.mjs`,
+ * `.cjs`, `.json`, missing paths, or anything else.
+ */
+export declare function needsTsLoader(filePath: string | null | undefined): boolean;
+/**
+ * Probe whether `tsx/esm` is resolvable from the user's current working
+ * directory. Returns true if `tsx` is installed in the user's project.
+ *
+ * Accepts an injected `resolver` so unit tests don't need a real filesystem.
+ */
+export declare function canResolveTsx(resolver?: (id: string) => string): boolean;
+export type TsLoaderStatus = 'registered' | 'already' | 'unsupported' | 'missing';
+/**
+ * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
+ * work. Safe to call multiple times — internal flag prevents double registration.
+ *
+ * Returns:
+ *   - 'registered'  loader was successfully registered this call
+ *   - 'already'     a loader was previously registered (idempotent)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'missing'     `tsx` is not installed in the user's project
+ */
+export declare function registerTsLoader(): Promise<TsLoaderStatus>;
+/** Reset the loader state — used by unit tests only. */
+export declare function _resetTsLoaderStateForTests(): void;
+//# sourceMappingURL=loader.d.ts.map