turbine-orm 0.27.0 → 0.28.0

package/dist/cli/index.js

@@ -8,12 +8,14 @@
  *   turbine push                  — Apply schema-builder definitions to database
  *   turbine migrate create <name> — Create a new SQL migration file
  *   turbine migrate up            — Apply pending migrations
+ *   turbine migrate deploy        — Apply pending migrations without prompts
  *   turbine migrate down          — Rollback last migration
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
+ *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
@@ -22,20 +24,21 @@
  *   npx turbine migrate create add_users_table
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { dirname, relative, resolve } from 'node:path';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
-import { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig } from './config.js';
+import { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, } from './config.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
-import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.js';
+import { runMcpServer } from './mcp.js';
+import { createMigration, inspectMigrationDeploy, listMigrationFiles, 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';
-function parseArgs() {
-    const args = process.argv.slice(2);
+export function parseArgs(argv = process.argv.slice(2)) {
+    const args = argv;
     const result = {
         command: args[0] ?? 'help',
         positional: [],
@@ -93,6 +96,12 @@ function parseArgs() {
             case '--fix':
                 result.fix = true;
                 break;
+            case '--zod':
+                result.zod = true;
+                break;
+            case '--include-views':
+                result.includeViews = true;
+                break;
             case '--allow-destructive':
                 result.allowDestructive = true;
                 break;
@@ -119,6 +128,9 @@ function parseArgs() {
             case '--no-open':
                 result.noOpen = true;
                 break;
+            case '--allow-remote':
+                result.allowRemote = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -297,34 +309,30 @@ async function cmdInit(args, config) {
         success(`Created ${cyan(`${config.out}/`)}`);
     }
     // Create seed file template
-    const seedDir = config.seedFile.substring(0, config.seedFile.lastIndexOf('/'));
-    if (!existsSync(config.seedFile)) {
+    const initSeedFile = config.seedFile ?? './seed.ts';
+    const seedDir = dirname(initSeedFile);
+    if (!existsSync(initSeedFile)) {
         if (!existsSync(seedDir)) {
             mkdirSync(seedDir, { recursive: true });
         }
-        writeFileSync(config.seedFile, `/**
+        writeFileSync(initSeedFile, `/**
  * Turbine seed file
  *
  * Run with: npx turbine seed
  */
 
-// import { turbine } from '${config.out.replace('./', '')}';
-//
-// const db = turbine({ connectionString: process.env.DATABASE_URL });
-//
-// async function seed() {
-//   console.log('Seeding database...');
-//
-//   // Add your seed data here:
-//   // await db.users.create({ data: { email: 'admin@example.com', name: 'Admin' } });
-//
-//   console.log('Done!');
-//   await db.disconnect();
-// }
-//
-// seed();
+import { defineSeed } from 'turbine-orm';
+
+export default defineSeed(async (db) => {
+  console.log('Seeding database...');
+
+  // Add your seed data here:
+  // await db.raw\`INSERT INTO users (email, name) VALUES (\${'admin@example.com'}, \${'Admin'})\`;
+
+  console.log('Done!');
+});
 `, 'utf-8');
-        success(`Created ${cyan(config.seedFile)}`);
+        success(`Created ${cyan(initSeedFile)}`);
     }
     // Create schema builder template
     if (!existsSync(config.schemaFile)) {
@@ -466,6 +474,7 @@ async function cmdGenerate(args, config) {
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
         exclude: config.exclude.length ? config.exclude : undefined,
+        includeViews: args.includeViews,
     });
     const tableNames = Object.keys(schema.tables);
     const totalColumns = Object.values(schema.tables).reduce((sum, t) => sum + t.columns.length, 0);
@@ -508,6 +517,7 @@ async function cmdGenerate(args, config) {
         schema,
         outDir: config.out,
         connectionString: url,
+        zod: args.zod,
     });
     genSpinner.succeed(`Generated ${bold(String(result.files.length))} files in ${elapsed(startTime)}`);
     // List files
@@ -621,6 +631,7 @@ async function cmdMigrate(args, config) {
         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('deploy')}                Apply pending migrations without prompts`);
         console.log(`    ${cyan('down')}                  Rollback last migration`);
         console.log(`    ${cyan('status')}                Show migration status`);
         newline();
@@ -634,6 +645,7 @@ async function cmdMigrate(args, config) {
         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 deploy --dry-run')}`);
         console.log(`    ${dim('npx turbine migrate down --step 2')}`);
         newline();
         return;
@@ -645,6 +657,9 @@ async function cmdMigrate(args, config) {
         case 'up':
             await cmdMigrateUp(args, config);
             break;
+        case 'deploy':
+            await cmdMigrateDeploy(args, config);
+            break;
         case 'down':
             await cmdMigrateDown(args, config);
             break;
@@ -803,6 +818,67 @@ async function cmdMigrateUp(args, config) {
     }
     newline();
 }
+export function buildMigrateDeployOptions(_args) {
+    return {
+        allowDrift: false,
+        allowDestructive: true,
+        step: undefined,
+    };
+}
+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})`)}`);
+            }
+            newline();
+            process.exit(1);
+        }
+        if (plan.pending.length === 0) {
+            spinner.succeed('No pending migrations');
+            newline();
+            return;
+        }
+        spinner.succeed(`${bold(String(plan.pending.length))} pending migration(s)`);
+        for (const file of plan.pending) {
+            console.log(`    ${yellow(symbols.dot)} ${file.filename}`);
+        }
+        newline();
+        return;
+    }
+    const spinner = new Spinner('Deploying migrations').start();
+    const result = await migrateDeploy(url, config.migrationsDir);
+    if (result.applied.length === 0 && result.errors.length === 0) {
+        spinner.succeed('0 applied — all migrations are up to date');
+        newline();
+        return;
+    }
+    if (result.applied.length > 0) {
+        spinner.succeed(`${bold(String(result.applied.length))} applied`);
+        for (const file of result.applied) {
+            console.log(`    ${green(symbols.check)} ${file.filename}`);
+        }
+    }
+    if (result.errors.length > 0) {
+        spinner.fail('Deploy failed');
+        for (const { file, error: msg } of result.errors) {
+            console.log(`    ${red(symbols.cross)} ${file.filename}`);
+            console.log(`      ${dim(msg)}`);
+        }
+        newline();
+        process.exit(1);
+    }
+    newline();
+}
 /** True when the error is migrate up/down's destructive-statement refusal. */
 function isDestructiveRefusal(err) {
     return err instanceof Error && err.message.includes('DESTRUCTIVE');
@@ -948,55 +1024,81 @@ async function cmdMigrateStatus(_args, config) {
         newline();
     }
 }
-// ---------------------------------------------------------------------------
-// Command: seed
-// ---------------------------------------------------------------------------
+export function getSeedExecutionPlan(seedFile) {
+    const ext = extname(seedFile).toLowerCase();
+    if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
+        return { kind: 'tsx', command: 'npx', args: ['tsx', seedFile] };
+    }
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+        return { kind: 'js', file: seedFile };
+    }
+    if (ext === '.sql') {
+        return { kind: 'sql', file: seedFile };
+    }
+    throw new Error(`Unsupported seed file extension: ${ext || '(none)'}. Use seed.ts, seed.js, or seed.sql.`);
+}
+async function runSeedPlan(plan, config) {
+    const oldDatabaseUrl = process.env.DATABASE_URL;
+    if (config.url)
+        process.env.DATABASE_URL = config.url;
+    try {
+        if (plan.kind === 'tsx') {
+            if (!canResolveTsx()) {
+                throw new Error('TypeScript seed files require tsx — install tsx or use seed.js/seed.sql.');
+            }
+            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,
+                },
+            });
+            return;
+        }
+        if (plan.kind === 'js') {
+            const mod = await import(pathToFileURL(plan.file).href);
+            if (typeof mod.default === 'function') {
+                await mod.default();
+            }
+            return;
+        }
+        const url = requireUrl(config);
+        const { default: pg } = await import('pg');
+        const client = new pg.Client({ connectionString: url });
+        await client.connect();
+        try {
+            await client.query(readFileSync(plan.file, 'utf-8'));
+        }
+        finally {
+            await client.end();
+        }
+    }
+    finally {
+        if (oldDatabaseUrl === undefined) {
+            delete process.env.DATABASE_URL;
+        }
+        else {
+            process.env.DATABASE_URL = oldDatabaseUrl;
+        }
+    }
+}
 async function cmdSeed(_args, config) {
     banner();
-    const seedFile = resolve(config.seedFile);
-    label('Seed file', config.seedFile);
+    const seedFile = resolveSeedFile(config);
+    label('Seed file', seedFile ? relative(process.cwd(), seedFile) || seedFile : '(not found)');
     newline();
-    if (!existsSync(seedFile)) {
-        error(`Seed file not found: ${config.seedFile}`);
+    if (!seedFile || !existsSync(seedFile)) {
+        error(`Seed file not found.`);
         newline();
-        console.log(`  ${dim('Create one with:')} ${cyan('npx turbine init')}`);
-        console.log(`  ${dim('Or set a custom path in')} ${cyan('turbine.config.ts')}`);
+        console.log(`  ${dim('Create one of:')} ${cyan('seed.ts')}${dim(',')} ${cyan('seed.js')}${dim(',')} ${cyan('seed.sql')}`);
+        console.log(`  ${dim('Or set')} ${cyan('seed')} ${dim('in')} ${cyan('turbine.config.ts')}`);
         newline();
         process.exit(1);
     }
     const spinner = new Spinner('Running seed file').start();
     try {
-        // Use child_process to run the seed file via tsx or node
-        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', args: ['tsx', seedFile], name: 'tsx' },
-            { cmd: 'node', args: ['--experimental-strip-types', seedFile], name: 'node' },
-        ];
-        let ran = false;
-        for (const runner of runners) {
-            try {
-                execFileSync(runner.cmd, runner.args, {
-                    stdio: 'inherit',
-                    env: {
-                        ...process.env,
-                        DATABASE_URL: config.url || process.env.DATABASE_URL,
-                    },
-                });
-                ran = true;
-                break;
-            }
-            catch (err) {
-                // If tsx not found, try next runner
-                if (err instanceof Error && 'status' in err && err.status === null) {
-                    continue;
-                }
-                throw err;
-            }
-        }
-        if (!ran) {
-            throw new Error('Could not find tsx or compatible Node.js version to run .ts files');
-        }
+        await runSeedPlan(getSeedExecutionPlan(seedFile), config);
         spinner.succeed('Seed completed');
     }
     catch (err) {
@@ -1137,6 +1239,17 @@ async function cmdDoctor(args, config) {
     }
 }
 // ---------------------------------------------------------------------------
+// Loopback host gate (Studio / Observe)
+// ---------------------------------------------------------------------------
+/**
+ * True when `host` is a loopback address Studio/Observe may bind without
+ * `--allow-remote`. Accepts IPv4, IPv6, and the common bracket form.
+ */
+export function isLoopbackHost(host) {
+    const h = host.trim().toLowerCase();
+    return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]';
+}
+// ---------------------------------------------------------------------------
 // Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
@@ -1149,11 +1262,18 @@ async function cmdStudio(args, config) {
         console.log(red(`✗ invalid port: ${args.port}`));
         process.exit(1);
     }
-    // Warn loudly when an explicit non-loopback --host is used — the user is
-    // opting in, so we proceed rather than refuse. Studio has no real
-    // authentication beyond a random session token, so exposing it on a LAN
-    // interface is foot-gun territory.
-    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+    // Non-loopback binds require an explicit --allow-remote opt-in. Studio has
+    // only a random session token — exposing it on a LAN interface is foot-gun
+    // territory, so we refuse rather than warn-and-proceed.
+    if (!isLoopbackHost(host)) {
+        if (!args.allowRemote) {
+            error(`Studio refuses to bind to ${yellow(host)} without ${cyan('--allow-remote')}.`);
+            newline();
+            console.log(`  ${dim('Loopback only by default')} ${dim('(127.0.0.1, localhost, ::1).')}`);
+            console.log(`  ${dim('Pass')} ${cyan('--allow-remote')} ${dim('to opt in to network exposure.')}`);
+            newline();
+            process.exit(1);
+        }
         console.log(warn(`Studio is binding to ${yellow(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your database.`));
     }
@@ -1205,6 +1325,19 @@ async function cmdStudio(args, config) {
     });
 }
 // ---------------------------------------------------------------------------
+// Command: mcp — read-only JSON-RPC stdio server
+// ---------------------------------------------------------------------------
+async function cmdMcp(_args, config) {
+    const url = requireUrl(config);
+    await runMcpServer({
+        url,
+        schema: config.schema,
+        migrationsDir: config.migrationsDir,
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    });
+}
+// ---------------------------------------------------------------------------
 // Command: observe
 // ---------------------------------------------------------------------------
 async function cmdObserve(args) {
@@ -1225,9 +1358,17 @@ async function cmdObserve(args) {
         console.log(red(`✗ invalid port: ${args.port}`));
         process.exit(1);
     }
-    // Warn loudly when an explicit non-loopback --host is used — the user is
-    // opting in, so we proceed rather than refuse.
-    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+    // Non-loopback binds require an explicit --allow-remote opt-in (same model
+    // as Studio). Refuse without the flag; warn loudly when opted in.
+    if (!isLoopbackHost(host)) {
+        if (!args.allowRemote) {
+            error(`Observe refuses to bind to ${yellow(host)} without ${cyan('--allow-remote')}.`);
+            newline();
+            console.log(`  ${dim('Loopback only by default')} ${dim('(127.0.0.1, localhost, ::1).')}`);
+            console.log(`  ${dim('Pass')} ${cyan('--allow-remote')} ${dim('to opt in to network exposure.')}`);
+            newline();
+            process.exit(1);
+        }
         console.log(warn(`Observe is binding to ${yellow(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your metrics.`));
     }
@@ -1278,6 +1419,7 @@ function showSubcommandHelp(command) {
         migration: showMigrateHelp,
         seed: showSeedHelp,
         status: showStatusHelp,
+        mcp: showMcpHelp,
     };
     const fn = helpMap[command];
     if (fn) {
@@ -1312,6 +1454,7 @@ function showGenerateHelp() {
     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`);
+    console.log(`    ${dim('•')} ${cyan('zod.ts')}      — Zod schemas ${dim('(with --zod)')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}       Postgres connection string`);
@@ -1319,6 +1462,8 @@ function showGenerateHelp() {
     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`);
+    console.log(`    ${cyan('--zod')}                 Also emit ${cyan('zod.ts')} validation schemas ${dim('(needs the zod dep)')}`);
+    console.log(`    ${cyan('--include-views')}       Include views + materialized views as read-only entities`);
     console.log(`    ${cyan('--allow-empty')}         Generate even when introspection matches 0 tables`);
     newline();
 }
@@ -1348,6 +1493,7 @@ function showMigrateHelp() {
     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('deploy')}          Apply pending migrations without prompts`);
     console.log(`    ${cyan('down')}            Rollback last migration`);
     console.log(`    ${cyan('status')}          Show applied/pending migrations`);
     newline();
@@ -1364,6 +1510,7 @@ function showMigrateHelp() {
     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 deploy --dry-run`);
     console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
     console.log(`    ${dim('$')} npx turbine migrate status`);
     newline();
@@ -1376,7 +1523,9 @@ function showSeedHelp() {
     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)')}`);
+    console.log(`  ${dim('or the first default candidate: ./seed.ts, ./seed.js, ./seed.sql')}`);
+    newline();
+    console.log(`  ${dim('TypeScript seeds run with')} ${cyan('npx tsx')} ${dim('and can export')} ${cyan('defineSeed(fn)')}${dim('.')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
@@ -1397,6 +1546,23 @@ function showStatusHelp() {
     console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}   Postgres schema ${dim('(default: public)')}`);
     newline();
 }
+function showMcpHelp() {
+    banner();
+    console.log(`  ${bold('turbine mcp')} — Start read-only MCP server over stdio`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine mcp ${dim('[options]')}`);
+    newline();
+    console.log(`  Speaks newline-delimited JSON-RPC 2.0 on stdin/stdout and exposes`);
+    console.log(`  schema, migration status, doctor, EXPLAIN, and sample-row tools.`);
+    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)')}`);
+    console.log(`    ${cyan('--include')} ${dim('<tables>')}    Comma-separated tables to include`);
+    console.log(`    ${cyan('--exclude')} ${dim('<tables>')}    Comma-separated tables to exclude`);
+    newline();
+}
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
@@ -1412,12 +1578,14 @@ function showHelp() {
     console.log(`    ${cyan('migrate')} ${dim('<sub>')}      SQL migration management`);
     console.log(`      ${dim('create <name>')}    Create a new migration file`);
     console.log(`      ${dim('up')}               Apply pending migrations`);
+    console.log(`      ${dim('deploy')}           Apply pending migrations without prompts`);
     console.log(`      ${dim('down')}             Rollback last migration`);
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
     console.log(`    ${cyan('doctor')}             Check relations for missing FK indexes ${dim('(--fix emits migration)')}`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
+    console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
@@ -1439,6 +1607,7 @@ function showHelp() {
     console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983 studio, 4984 observe)')}`);
     console.log(`    ${cyan('--host')} ${dim('<addr>')}        Bind address ${dim('(default: 127.0.0.1)')}`);
     console.log(`    ${cyan('--no-open')}            Don't auto-open the browser`);
+    console.log(`    ${cyan('--allow-remote')}       Allow non-loopback --host ${dim('(refused without this flag)')}`);
     newline();
     console.log(`  ${bold('Config file:')}`);
     console.log(`    ${dim('Create')} ${cyan('turbine.config.ts')} ${dim('with')} ${cyan('npx turbine init')}`);
@@ -1449,6 +1618,7 @@ function showHelp() {
     console.log(`    ${dim('$')} DATABASE_URL=postgres://... npx turbine generate`);
     console.log(`    ${dim('$')} npx turbine migrate create add_users_table`);
     console.log(`    ${dim('$')} npx turbine migrate up`);
+    console.log(`    ${dim('$')} npx turbine migrate deploy --dry-run`);
     console.log(`    ${dim('$')} npx turbine push --dry-run`);
     newline();
 }
@@ -1575,6 +1745,9 @@ async function main() {
             case 'studio':
                 await cmdStudio(args, config);
                 break;
+            case 'mcp':
+                await cmdMcp(args, config);
+                break;
             case 'observe':
                 await cmdObserve(args);
                 break;
@@ -1625,4 +1798,29 @@ async function main() {
         process.exit(1);
     }
 }
-main();
+function isCliEntry() {
+    // Decide from process.argv[1] instead of import.meta.url so the same code
+    // compiles cleanly for both the ESM and CJS builds (see showVersion above).
+    // The CLI runs via the bin shim ("turbine"), the built output
+    // (dist/[cjs/]cli/index.{js,cjs}), or tsx on the source (src/cli/index.ts).
+    // Test files import this module with their own path in argv[1], which never
+    // matches these shapes.
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    let real = entry;
+    try {
+        real = realpathSync(entry);
+    }
+    catch {
+        real = resolve(entry);
+    }
+    const base = basename(real);
+    if (base === 'turbine' || base === 'turbine-orm')
+        return true;
+    const isIndexFile = base === 'index.js' || base === 'index.cjs' || base === 'index.ts';
+    return isIndexFile && basename(dirname(real)) === 'cli';
+}
+if (isCliEntry()) {
+    void main();
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { Readable, Writable } from 'node:stream';
+export interface McpServerOptions {
+    url: string;
+    schema: string;
+    migrationsDir: string;
+    include?: string[];
+    exclude?: string[];
+}
+export interface McpTransport {
+    input?: Readable;
+    output?: Writable;
+}
+export interface McpServerHandle {
+    dispose(): Promise<void>;
+}
+export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
+export declare function runMcpServer(options: McpServerOptions): Promise<void>;