turbine-orm 0.60.1 → 0.62.0

package/dist/cjs/cli/index.js

@@ -69,11 +69,15 @@ exports.tsxInstallCommand = tsxInstallCommand;
 exports.tsxRequiredNotice = tsxRequiredNotice;
 exports.detectConsumerModuleType = detectConsumerModuleType;
 exports.planInitSteps = planInitSteps;
+exports.gitignoreIgnoresEnv = gitignoreIgnoresEnv;
+exports.planEnvScaffold = planEnvScaffold;
+exports.scaffoldEnvForUrl = scaffoldEnvForUrl;
 exports.initEnvNotice = initEnvNotice;
 exports.resolveMigrateFromPrismaUrl = resolveMigrateFromPrismaUrl;
 exports.buildMigrateDeployOptions = buildMigrateDeployOptions;
 exports.getSeedExecutionPlan = getSeedExecutionPlan;
 exports.isLoopbackHost = isLoopbackHost;
+exports.showSubcommandHelp = showSubcommandHelp;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -98,6 +102,21 @@ const prisma_resolve_js_1 = require("./prisma-resolve.js");
 const prisma_schema_js_1 = require("./prisma-schema.js");
 const studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
+/**
+ * Fail an argument-parse error the way every other CLI failure looks: banner,
+ * red error line, then indented hint lines. The flag validators used to call
+ * `console.error` directly, so a typo in `--recipe` printed one bare unstyled
+ * sentence with no banner and no hint, which reads like an internal crash
+ * rather than "you forgot the recipe name".
+ */
+function failArg(message, ...hints) {
+    (0, ui_js_1.banner)();
+    (0, ui_js_1.error)(message);
+    for (const hint of hints)
+        console.log(`  ${(0, ui_js_1.dim)(hint)}`);
+    (0, ui_js_1.newline)();
+    process.exit(1);
+}
 function parseArgs(argv = process.argv.slice(2)) {
     const args = argv;
     const result = {
@@ -158,6 +177,9 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--skip-schema':
                 result.skipSchema = true;
                 break;
+            case '--with-schema':
+                result.withSchema = true;
+                break;
             case '--skip-seed':
                 result.skipSeed = true;
                 break;
@@ -211,8 +233,7 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--import-ext':
             case '--import-extension':
                 if (next !== 'js' && next !== 'none' && next !== 'auto') {
-                    console.error(`--import-ext requires one of: js, none, auto (got ${next ?? '(nothing)'})`);
-                    process.exit(1);
+                    failArg(`${(0, ui_js_1.cyan)('--import-ext')} requires one of: js, none, auto ${(0, ui_js_1.dim)(`(got ${next ?? 'nothing'})`)}`, 'Example: npx turbine generate --import-ext none');
                 }
                 result.importExtension = next;
                 i++;
@@ -228,8 +249,7 @@ function parseArgs(argv = process.argv.slice(2)) {
                 break;
             case '--recipe':
                 if (next === undefined || next.startsWith('-')) {
-                    console.error('--recipe requires a name (e.g. --recipe backfill)');
-                    process.exit(1);
+                    failArg(`${(0, ui_js_1.cyan)('--recipe')} requires a recipe name.`, `Known recipes: ${Object.keys(migrate_js_1.MIGRATION_RECIPES).join(', ') || '(none)'}`, 'Example: npx turbine migrate create backfill_full_name --recipe backfill');
                 }
                 result.recipe = next;
                 i++;
@@ -633,6 +653,23 @@ function planInitSteps(state, flags) {
             return { id, action: 'skip', defaultYes: true, skipReason: 'flag' };
         if (exists)
             return { id, action: 'skip', defaultYes: true, skipReason: 'exists' };
+        // An EMPTY code-first schema file written next to a database that ALREADY
+        // has tables is what makes the very next `turbine push` announce "Schema
+        // defines 0 tables" and list every real table under "Extra tables in
+        // database (not dropped automatically)", which reads like imminent data
+        // loss. For these projects the database is the source of truth
+        // (`turbine generate`), so the default flips to "don't scaffold it":
+        // prompted (default no) on a TTY, skipped with an explanation otherwise.
+        //
+        // `--with-schema` opts back in and returns this step to the normal path. A
+        // code-first project bootstrapping in CI against a populated database is a
+        // real case, and a default that no flag can override is a behavior change
+        // with no way out, not a safety rail.
+        if (id === 'schema' && state.dbHasTables === true && !flags.withSchema) {
+            return mode === 'prompt'
+                ? { id, action: 'prompt', defaultYes: false }
+                : { id, action: 'skip', defaultYes: false, skipReason: 'db-has-tables' };
+        }
         return { id, action: mode === 'prompt' ? 'prompt' : 'run', defaultYes: true };
     };
     steps.push(scaffold('schema', state.schemaExists, flags.skipSchema));
@@ -687,17 +724,33 @@ async function promptYesNo(question, defaultYes) {
         rl.close();
     }
 }
-/** Probe database reachability with a short-lived connection. Never throws. */
-async function probeDatabase(url) {
+/**
+ * Probe database reachability (and how populated it is) with a short-lived
+ * connection. Never throws: an unreachable database is a normal init state.
+ */
+async function probeDatabase(url, schema) {
     try {
         const { default: pg } = await Promise.resolve().then(() => __importStar(require('pg')));
         const client = new pg.Client({ connectionString: url });
         await client.connect();
+        let tableCount = 0;
+        try {
+            const res = await client.query(`SELECT count(*)::text AS count
+           FROM information_schema.tables
+          WHERE table_schema = $1
+            AND table_type = 'BASE TABLE'
+            AND table_name NOT LIKE '\\_turbine\\_%'`, [schema]);
+            tableCount = Number.parseInt(res.rows[0]?.count ?? '0', 10) || 0;
+        }
+        catch {
+            // Reachable but the catalog read failed (permissions, odd engine). Treat
+            // it as "unknown", not "empty": tableCount 0 only suppresses a scaffold.
+        }
         await client.end();
-        return true;
+        return { reachable: true, tableCount };
     }
     catch {
-        return false;
+        return { reachable: false, tableCount: 0 };
     }
 }
 const INIT_SEED_TEMPLATE = `/**
@@ -738,6 +791,132 @@ export default defineSchema({
   // },
 });
 `;
+/**
+ * Does this `.gitignore` text already ignore `.env`?
+ *
+ * Line-based rather than a substring search: a `.gitignore` mentioning
+ * `.env.example` (a very common line, since the example file is the one you DO
+ * commit) contains the text `.env` while ignoring nothing of the kind, and
+ * treating that as covered is how the password would stay committable.
+ * Negations (`!.env`) are honored as a later line overriding an earlier one,
+ * exactly as git resolves them.
+ *
+ * @internal exported for tests.
+ */
+function gitignoreIgnoresEnv(content) {
+    let ignored = false;
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const negated = line.startsWith('!');
+        // A leading `/` anchors to the repo root, a trailing `/` means directory.
+        const pattern = (negated ? line.slice(1) : line).replace(/^\//, '').replace(/\/$/, '');
+        // The patterns that actually match a root-level `.env` file.
+        if (pattern === '.env' || pattern === '.env*' || pattern === '*.env' || pattern === '**/.env') {
+            ignored = !negated;
+        }
+    }
+    return ignored;
+}
+/**
+ * Decide what the `--url`-carries-a-password scaffold writes. Pure, so the whole
+ * matrix (fresh project, existing `.env`, existing `.gitignore`, re-run) is
+ * testable without a filesystem.
+ *
+ * An existing `DATABASE_URL` in `.env` is NEVER rewritten: it is the value the
+ * project already runs against, and silently repointing it at the `--url` from
+ * one command line is a worse failure than printing a notice.
+ *
+ * @internal exported for tests.
+ */
+function planEnvScaffold(state) {
+    return {
+        env: !state.envExists ? 'created' : state.envHasDatabaseUrl ? 'unchanged' : 'appended',
+        envExample: state.envExampleExists ? 'unchanged' : 'created',
+        // No `.gitignore` at all means nothing is ignored, so the `.env` we just
+        // wrote is committable. Create one rather than warn about it.
+        gitignore: !state.gitignoreExists ? 'created' : state.gitignoreIgnoresEnv ? 'unchanged' : 'appended',
+    };
+}
+const ENV_EXAMPLE_TEMPLATE = `# Copy this file to .env and fill in your own values.
+# This file is committed; .env is not.
+DATABASE_URL=postgres://user:password@localhost:5432/database
+`;
+/**
+ * Move a password-bearing `--url` out of `turbine.config.ts` and into `.env`.
+ *
+ * `turbine init --url postgres://user:PASSWORD@host/db` is the documented
+ * one-liner, and it used to inline that string verbatim into a file projects
+ * commit, with no `.gitignore` written at all. The config template now refuses
+ * to inline a secret (see `configTemplate`), so the real value has to land
+ * somewhere the config can read it from: this writes `.env`, scaffolds the
+ * committable `.env.example` next to it, and makes sure `.gitignore` covers
+ * `.env` BEFORE the secret is on disk long enough to be staged.
+ *
+ * Paths are cwd-relative, exactly like the rest of the init scaffold.
+ *
+ * @internal exported for tests.
+ */
+function scaffoldEnvForUrl(url) {
+    const envPath = '.env';
+    const envExamplePath = '.env.example';
+    const gitignorePath = '.gitignore';
+    const envExists = (0, node_fs_1.existsSync)(envPath);
+    const plan = planEnvScaffold({
+        envExists,
+        envHasDatabaseUrl: envExists ? /^\s*(export\s+)?DATABASE_URL\s*=/m.test((0, node_fs_1.readFileSync)(envPath, 'utf-8')) : false,
+        envExampleExists: (0, node_fs_1.existsSync)(envExamplePath),
+        gitignoreExists: (0, node_fs_1.existsSync)(gitignorePath),
+        gitignoreIgnoresEnv: (0, node_fs_1.existsSync)(gitignorePath) ? gitignoreIgnoresEnv((0, node_fs_1.readFileSync)(gitignorePath, 'utf-8')) : false,
+    });
+    // .gitignore FIRST: the ignore rule has to exist before the file holding the
+    // password does, or a `git add -A` in between commits it.
+    if (plan.gitignore === 'created')
+        (0, node_fs_1.writeFileSync)(gitignorePath, '# Local environment (secrets)\n.env\n', 'utf-8');
+    else if (plan.gitignore === 'appended')
+        (0, node_fs_1.appendFileSync)(gitignorePath, '\n# Local environment (secrets)\n.env\n');
+    if (plan.env === 'created') {
+        // 0600 on CREATION only. The whole point of this scaffold is moving a live
+        // password out of a committed file, and the default 0644 would leave it
+        // world-readable to every account on a shared box or CI runner. `mode` is
+        // applied by the OS only when the open() actually creates the file, so if
+        // one appeared since the existsSync above we write into it without widening
+        // or narrowing whatever mode its owner chose.
+        (0, node_fs_1.writeFileSync)(envPath, `# Turbine database connection. Never commit this file.\nDATABASE_URL=${url}\n`, {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+    }
+    else if (plan.env === 'appended') {
+        (0, node_fs_1.appendFileSync)(envPath, `\n# Added by turbine init\nDATABASE_URL=${url}\n`);
+    }
+    if (plan.envExample === 'created')
+        (0, node_fs_1.writeFileSync)(envExamplePath, ENV_EXAMPLE_TEMPLATE, 'utf-8');
+    return plan;
+}
+/** Say exactly what was written where, so nobody has to guess where the password went. */
+function reportEnvScaffold(plan, url) {
+    (0, ui_js_1.warn)(`The connection string passed to ${(0, ui_js_1.cyan)('--url')} contains a password.`);
+    console.log(`  ${(0, ui_js_1.dim)('It was NOT written into')} ${(0, ui_js_1.cyan)('turbine.config.ts')}${(0, ui_js_1.dim)(': that file reads')} ${(0, ui_js_1.cyan)('process.env.DATABASE_URL')}${(0, ui_js_1.dim)('.')}`);
+    if (plan.env === 'created')
+        (0, ui_js_1.success)(`Wrote the connection string to ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)(`(${(0, ui_js_1.redactUrl)(url)})`)}`);
+    else if (plan.env === 'appended')
+        (0, ui_js_1.success)(`Appended ${(0, ui_js_1.cyan)('DATABASE_URL')} to your existing ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)(`(${(0, ui_js_1.redactUrl)(url)})`)}`);
+    else
+        (0, ui_js_1.info)(`Your ${(0, ui_js_1.cyan)('.env')} already sets ${(0, ui_js_1.cyan)('DATABASE_URL')}: left untouched. The ${(0, ui_js_1.cyan)('--url')} value was not saved anywhere.`);
+    if (plan.envExample === 'created')
+        (0, ui_js_1.success)(`Created ${(0, ui_js_1.cyan)('.env.example')} ${(0, ui_js_1.dim)('(safe to commit)')}`);
+    if (plan.gitignore === 'created')
+        (0, ui_js_1.success)(`Created ${(0, ui_js_1.cyan)('.gitignore')} ignoring ${(0, ui_js_1.cyan)('.env')}`);
+    else if (plan.gitignore === 'appended')
+        (0, ui_js_1.success)(`Added ${(0, ui_js_1.cyan)('.env')} to ${(0, ui_js_1.cyan)('.gitignore')}`);
+    else
+        (0, ui_js_1.info)(`${(0, ui_js_1.cyan)('.gitignore')} already ignores ${(0, ui_js_1.cyan)('.env')}`);
+    if (plan.env !== 'unchanged') {
+        console.log(`  ${(0, ui_js_1.dim)('The password is now in')} ${(0, ui_js_1.cyan)('.env')}${(0, ui_js_1.dim)('. If it was ever pushed to a shared history, rotate it.')}`);
+    }
+}
 /** Create supporting directories + .gitignore entries (unconditional, unprompted). */
 function ensureInitScaffoldDirs(config) {
     const migrDir = config.migrationsDir;
@@ -892,15 +1071,27 @@ function reportInitSkip(step) {
         case 'default-no':
             console.log(`  ${(0, ui_js_1.dim)(`${ui_js_1.symbols.dot} ${label} skipped (default no)`)}`);
             break;
+        case 'db-has-tables':
+            (0, ui_js_1.info)(`${label} not created: your database already has tables ${(0, ui_js_1.dim)('- skipped')}`);
+            console.log(`  ${(0, ui_js_1.dim)('An empty')} ${(0, ui_js_1.cyan)('defineSchema()')} ${(0, ui_js_1.dim)('file would make')} ${(0, ui_js_1.cyan)('turbine push')} ${(0, ui_js_1.dim)('report every existing')}`);
+            console.log(`  ${(0, ui_js_1.dim)('table as "extra". Your database is the source of truth here: run')} ${(0, ui_js_1.cyan)('turbine generate')}`);
+            console.log(`  ${(0, ui_js_1.dim)('to produce the typed client from it. For a code-first schema instead, re-run')}`);
+            console.log(`  ${(0, ui_js_1.dim)('with')} ${(0, ui_js_1.cyan)('--with-schema')} ${(0, ui_js_1.dim)('to scaffold')} ${(0, ui_js_1.cyan)('turbine/schema.ts')} ${(0, ui_js_1.dim)('anyway, then use')} ${(0, ui_js_1.cyan)('turbine push')}${(0, ui_js_1.dim)('.')}`);
+            break;
         default:
             console.log(`  ${(0, ui_js_1.dim)(`${ui_js_1.symbols.dot} ${label} skipped`)}`);
     }
 }
 /** The interactive prompt question for a promptable step. */
-function initPromptQuestion(step, config, seedFilePath) {
+function initPromptQuestion(step, config, seedFilePath, dbTableCount = 0) {
     switch (step.id) {
         case 'schema':
-            return `Create a starter schema file (${config.schemaFile})?`;
+            // Ask the honest question when the database is already populated: the
+            // file would be EMPTY, and `turbine push` reports every existing table as
+            // extra until it is filled in by hand.
+            return dbTableCount > 0
+                ? `Your database already has ${dbTableCount} table(s). Create an EMPTY code-first schema file anyway (${config.schemaFile})?`
+                : `Create a starter schema file (${config.schemaFile})?`;
         case 'seed-file':
             return `Create a starter seed file (${seedFilePath})?`;
         case 'push':
@@ -1009,11 +1200,18 @@ async function cmdInit(args, config) {
     // Probe the database once, up front, so the planner can decide the DB steps.
     // Skip the probe entirely when every DB step is already flag-skipped.
     const anyDbStepPossible = !(args.skipPush && args.skipGenerate && args.skipSeed);
+    let dbTableCount = 0;
     if (hasUrl && anyDbStepPossible) {
         const probe = new ui_js_1.Spinner('Checking database connection').start();
-        state.dbReachable = await probeDatabase(url);
-        if (state.dbReachable)
-            probe.succeed('Database is reachable');
+        const probed = await probeDatabase(url, config.schema);
+        state.dbReachable = probed.reachable;
+        dbTableCount = probed.tableCount;
+        state.dbHasTables = probed.tableCount > 0;
+        if (state.dbReachable) {
+            probe.succeed(dbTableCount > 0
+                ? `Database is reachable ${(0, ui_js_1.dim)(`(${dbTableCount} table(s) in schema "${config.schema}")`)}`
+                : 'Database is reachable');
+        }
         else
             probe.info('Database not reachable: push / generate / seed steps will be skipped');
     }
@@ -1022,6 +1220,7 @@ async function cmdInit(args, config) {
         force: args.force === true,
         interactive,
         skipSchema: args.skipSchema === true,
+        withSchema: args.withSchema === true,
         skipSeed: args.skipSeed === true,
         skipPush: args.skipPush === true,
         skipGenerate: args.skipGenerate === true,
@@ -1039,17 +1238,26 @@ async function cmdInit(args, config) {
             reportInitSkip(step);
             continue;
         }
-        const shouldRun = step.action === 'run' ? true : await promptYesNo(initPromptQuestion(step, config, seedFilePath), step.defaultYes);
+        const shouldRun = step.action === 'run'
+            ? true
+            : await promptYesNo(initPromptQuestion(step, config, seedFilePath, dbTableCount), step.defaultYes);
         if (!shouldRun) {
             (0, ui_js_1.info)(`Skipped ${initStepLabel(step.id)}`);
             continue;
         }
         switch (step.id) {
-            case 'config':
+            case 'config': {
                 (0, node_fs_1.writeFileSync)('turbine.config.ts', (0, config_js_1.configTemplate)(args.url ?? undefined), 'utf-8');
                 (0, ui_js_1.success)(state.configExists ? `Overwrote ${(0, ui_js_1.cyan)('turbine.config.ts')}` : `Created ${(0, ui_js_1.cyan)('turbine.config.ts')}`);
                 tsFilesWritten.push('turbine.config.ts');
+                // A `--url` with a password is never inlined by configTemplate, so the
+                // real value has to be put somewhere the config can read it from.
+                if (args.url && (0, config_js_1.connectionStringHasPassword)(args.url)) {
+                    (0, ui_js_1.newline)();
+                    reportEnvScaffold(scaffoldEnvForUrl(args.url), args.url);
+                }
                 break;
+            }
             case 'schema':
                 writeInitSchemaTemplate(config);
                 if ((0, loader_js_1.needsTsLoader)(config.schemaFile))
@@ -1777,6 +1985,41 @@ async function cmdMigrateCreate(args, config) {
     console.log(`  ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
     (0, ui_js_1.newline)();
 }
+/**
+ * Print the SQL a `migrate up` / `migrate down` WOULD run, and execute nothing.
+ *
+ * `--dry-run` was parsed and then read by `push` and `deploy` only, so on
+ * `migrate up` it was silently inert: the flag was accepted, no warning was
+ * printed, and the migrations were applied. A flag whose whole purpose is
+ * "show me what this would do to the database" that instead does it, against
+ * whatever `--url` was passed, is the most dangerous shape a CLI bug can take.
+ *
+ * Reads through the same `parseMigrationContent` the executor uses, so what is
+ * printed is what would run, rather than a second rendering that can drift.
+ */
+function printMigrationDryRun(files, section) {
+    const verb = section === 'up' ? 'apply' : 'roll back';
+    if (files.length === 0) {
+        (0, ui_js_1.info)(`Dry run: nothing to ${verb}.`);
+        (0, ui_js_1.newline)();
+        return;
+    }
+    (0, ui_js_1.info)(`Dry run: would ${verb} ${(0, ui_js_1.bold)(String(files.length))} migration(s). Nothing was executed.`);
+    (0, ui_js_1.newline)();
+    for (const file of files) {
+        const parsed = (0, migrate_js_1.parseMigrationContent)((0, node_fs_1.readFileSync)(file.path, 'utf-8'));
+        const sql = section === 'up' ? parsed.up : parsed.down;
+        console.log(`  ${(0, ui_js_1.cyan)(file.filename)}${parsed.noTransaction ? (0, ui_js_1.dim)('  (no transaction)') : ''}`);
+        if (sql.trim().length === 0) {
+            console.log(`    ${(0, ui_js_1.dim)(`(empty ${section.toUpperCase()} section)`)}`);
+        }
+        else {
+            for (const line of sql.split('\n'))
+                console.log(`    ${(0, ui_js_1.dim)(line)}`);
+        }
+        (0, ui_js_1.newline)();
+    }
+}
 async function cmdMigrateUp(args, config) {
     (0, ui_js_1.banner)();
     const url = requireUrl(config);
@@ -1790,6 +2033,14 @@ async function cmdMigrateUp(args, config) {
         (0, ui_js_1.newline)();
         return;
     }
+    if (args.dryRun) {
+        const status = await (0, migrate_js_1.migrateStatus)(url, config.migrationsDir);
+        let pending = status.filter((st) => !st.applied).map((st) => st.file);
+        if (args.step != null && args.step > 0)
+            pending = pending.slice(0, args.step);
+        printMigrationDryRun(pending, 'up');
+        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) {
@@ -2011,6 +2262,14 @@ async function cmdMigrateDown(args, config) {
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Migrations', config.migrationsDir);
     (0, ui_js_1.newline)();
+    if (args.dryRun) {
+        const status = await (0, migrate_js_1.migrateStatus)(url, config.migrationsDir);
+        // Rollback order is newest-applied first, and a migration whose file is
+        // missing has no DOWN section to show.
+        const applied = status.filter((st) => st.applied && !st.missingFile).map((st) => st.file);
+        printMigrationDryRun(applied.reverse().slice(0, args.step ?? 1), 'down');
+        return;
+    }
     const spinner = new ui_js_1.Spinner('Rolling back migration(s)').start();
     let result;
     try {
@@ -3087,8 +3346,10 @@ async function cmdStudio(args, config) {
             (0, ui_js_1.newline)();
             process.exit(1);
         }
-        console.log((0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)}, this is NOT loopback. ` +
-            `Anyone on your network who can reach this port + guess the session token can read your database.`));
+        // warn() prints; it returns void. Wrapping it in console.log() printed a
+        // literal grey "undefined" line under every one of these SAFETY warnings.
+        (0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)}, this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your database.`);
     }
     const spinner = new ui_js_1.Spinner(demo ? 'Seeding demo dataset' : 'Introspecting database').start();
     let studio;
@@ -3134,12 +3395,12 @@ async function cmdStudio(args, config) {
         // Loud startup warnings for the opt-in modes that widen Studio's surface.
         if (args.write) {
             (0, ui_js_1.newline)();
-            console.log((0, ui_js_1.warn)('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
-                `${(0, ui_js_1.redactUrl)(url)}. Every change is committed directly to your database.`));
+            (0, ui_js_1.warn)('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
+                `${(0, ui_js_1.redactUrl)(url)}. Every change is committed directly to your database.`);
         }
         if (args.showPii) {
             (0, ui_js_1.newline)();
-            console.log((0, ui_js_1.warn)('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
+            (0, ui_js_1.warn)('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.');
         }
         // PII tags are a code-first declaration; introspection never infers them.
         // Say plainly whether any reached this session, so nobody assumes a
@@ -3150,9 +3411,9 @@ async function cmdStudio(args, config) {
                 console.log(`  ${(0, ui_js_1.dim)('PII redaction:')} ${studio.piiTags.applied} tagged column(s) from ${(0, ui_js_1.dim)(studio.piiTags.path)}`);
             }
             else {
-                console.log((0, ui_js_1.warn)('No PII-tagged columns found, so nothing will be redacted. Tags are declared in code ' +
+                (0, ui_js_1.warn)('No PII-tagged columns found, so nothing will be redacted. Tags are declared in code ' +
                     `(defineSchema \`pii: true\`) and read from generated metadata in ${config.out}; ` +
-                    'introspection alone never infers them. Run `turbine generate` after tagging.'));
+                    'introspection alone never infers them. Run `turbine generate` after tagging.');
             }
         }
         (0, ui_js_1.newline)();
@@ -3232,8 +3493,9 @@ async function cmdObserve(args) {
             (0, ui_js_1.newline)();
             process.exit(1);
         }
-        console.log((0, ui_js_1.warn)(`Observe is binding to ${(0, ui_js_1.yellow)(host)}, this is NOT loopback. ` +
-            `Anyone on your network who can reach this port + guess the session token can read your metrics.`));
+        // warn() prints and returns void; see the same guard in cmdStudio.
+        (0, ui_js_1.warn)(`Observe is binding to ${(0, ui_js_1.yellow)(host)}, this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your metrics.`);
     }
     const spinner = new ui_js_1.Spinner('Connecting to metrics database').start();
     let handle;
@@ -3272,6 +3534,13 @@ async function cmdObserve(args) {
 // ---------------------------------------------------------------------------
 // Subcommand help
 // ---------------------------------------------------------------------------
+/**
+ * Print `<command> --help` for a command that has real help, returning whether
+ * one existed. Falling through to the GLOBAL help is the failure mode this map
+ * guards against, and it is silent, so the coverage is asserted in tests.
+ *
+ * @internal exported for tests.
+ */
 function showSubcommandHelp(command) {
     const helpMap = {
         init: showInitHelp,
@@ -3283,6 +3552,8 @@ function showSubcommandHelp(command) {
         migration: showMigrateHelp,
         seed: showSeedHelp,
         status: showStatusHelp,
+        doctor: showDoctorHelp,
+        studio: showStudioHelp,
         mcp: showMcpHelp,
     };
     const fn = helpMap[command];
@@ -3312,6 +3583,7 @@ function showInitHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}        Overwrite existing config file`);
     console.log(`    ${(0, ui_js_1.cyan)('--yes, -y')}          Accept every step's default (non-interactive)`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-schema')}      Don't create the starter schema file`);
+    console.log(`    ${(0, ui_js_1.cyan)('--with-schema')}      Create it even if the database already has tables`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-seed')}        Don't create the seed file or run the seed`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-push')}        Don't push the schema to the database`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-generate')}    Don't generate the typed client`);
@@ -3464,6 +3736,83 @@ function showStatusHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}   Postgres schema ${(0, ui_js_1.dim)('(default: public)')}`);
     (0, ui_js_1.newline)();
 }
+function showDoctorHelp() {
+    (0, ui_js_1.banner)();
+    console.log(`  ${(0, ui_js_1.bold)('turbine doctor')}, Index + cached-plan triage`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
+    console.log(`    npx turbine doctor ${(0, ui_js_1.dim)('[options]')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  Introspects your schema and live statistics, then reports:`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} relation probes with no usable index ${(0, ui_js_1.dim)('(ranked by estimated cost)')}`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} INVALID indexes ${(0, ui_js_1.dim)('(left behind by a failed CREATE INDEX CONCURRENTLY)')}`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} columns whose value distribution can flip a cached plan`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} with ${(0, ui_js_1.cyan)('--unused')}: never-scanned and redundant indexes, with DROP suggestions`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('Read-only: doctor never writes to your database. Only')} ${(0, ui_js_1.cyan)('--fix')} ${(0, ui_js_1.dim)('writes')}`);
+    console.log(`  ${(0, ui_js_1.dim)('anything at all, and only a migration FILE you review and run yourself.')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}       Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}   Postgres schema ${(0, ui_js_1.dim)('(default: public)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--include')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to include`);
+    console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to exclude`);
+    console.log(`    ${(0, ui_js_1.cyan)('--fix')}                 Write an add-index migration for the missing-index findings`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-concurrently')}     With ${(0, ui_js_1.cyan)('--fix')}: emit plain CREATE INDEX ${(0, ui_js_1.dim)('(default: CONCURRENTLY, no transaction)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--json')}                Emit the versioned machine-readable report and nothing else`);
+    console.log(`    ${(0, ui_js_1.cyan)('--unused')}              Also report never-scanned / redundant indexes ${(0, ui_js_1.dim)('(no --fix)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--audit')}               Scope the unused report to doctor's own suggested index names`);
+    console.log(`    ${(0, ui_js_1.cyan)('--min-scans')} ${(0, ui_js_1.dim)('<n>')}       idx_scan below this counts as never-scanned ${(0, ui_js_1.dim)('(default: 1)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--metrics-url')} ${(0, ui_js_1.dim)('<url>')}   Read ${(0, ui_js_1.cyan)('_turbine_metrics')} for the table-heat boost from a separate DB`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-plan-divergence')}  Skip the cached-plan divergence section ${(0, ui_js_1.dim)('(and its pg_stats read)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine doctor`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine doctor --fix`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine doctor --unused --min-scans 5`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine doctor --json > doctor.json`);
+    (0, ui_js_1.newline)();
+}
+function showStudioHelp() {
+    (0, ui_js_1.banner)();
+    console.log(`  ${(0, ui_js_1.bold)('turbine studio')}, Launch the local database UI`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
+    console.log(`    npx turbine studio ${(0, ui_js_1.dim)('[options]')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  A local web UI with Query / Data / Schema tabs. There is no raw-SQL`);
+    console.log(`  surface: the Query tab is a visual ${(0, ui_js_1.cyan)('findMany')} builder and every`);
+    console.log(`  identifier is validated against the introspected schema.`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Defaults are the safe ones:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} read-only ${(0, ui_js_1.dim)('(reads run inside BEGIN READ ONLY)')}`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} PII-tagged column values redacted server-side`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} bound to 127.0.0.1, behind a random per-session token`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}       Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}   Postgres schema ${(0, ui_js_1.dim)('(default: public)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--out, -o')} ${(0, ui_js_1.dim)('<dir>')}       Generated-metadata dir, source of the PII tags`);
+    console.log(`    ${(0, ui_js_1.cyan)('--include')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to include`);
+    console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to exclude`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}            HTTP port ${(0, ui_js_1.dim)('(default: 4983)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}         Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-open')}             Don't auto-open the browser`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-remote')}        Allow a non-loopback ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('(refused without it)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--write')}               Enable single-row update / insert / delete`);
+    console.log(`    ${(0, ui_js_1.cyan)('--show-pii')}            Show PII-tagged values unredacted`);
+    console.log(`    ${(0, ui_js_1.cyan)('--demo')}                Seeded in-memory sample database ${(0, ui_js_1.dim)('(no DATABASE_URL)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine studio`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine studio --demo`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine studio --write --port 5000`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('--write commits every change directly to the database, and')} ${(0, ui_js_1.cyan)('--show-pii')}`);
+    console.log(`  ${(0, ui_js_1.dim)('reveals values Studio otherwise never sends to the browser. Both print a')}`);
+    console.log(`  ${(0, ui_js_1.dim)('startup warning and a persistent in-UI banner. Demo mode saves nothing.')}`);
+    (0, ui_js_1.newline)();
+}
 function showMcpHelp() {
     (0, ui_js_1.banner)();
     console.log(`  ${(0, ui_js_1.bold)('turbine mcp')}, Start read-only MCP server over stdio`);
@@ -3528,6 +3877,7 @@ function showHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Init options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--yes, -y')}            Accept every step's default (non-interactive)`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-schema')}        Don't scaffold the schema file`);
+    console.log(`    ${(0, ui_js_1.cyan)('--with-schema')}        Scaffold it even if the database already has tables`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-seed')}          Don't scaffold or run the seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-push')}          Don't offer to push the schema to the database`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-generate')}      Don't offer to generate the typed client`);

package/dist/cjs/cli/mcp.d.ts

@@ -1,4 +1,5 @@
 import type { Readable, Writable } from 'node:stream';
+import pg from 'pg';
 import { type ColumnMetadata, type RelationDef } from '../schema.js';
 export interface McpServerOptions {
     url: string;
@@ -17,6 +18,13 @@ export interface McpServerOptions {
 export interface McpTransport {
     input?: Readable;
     output?: Writable;
+    /**
+     * Pre-built pool, used ONLY by the perimeter tests so they can drive the real
+     * JSON-RPC line handler and the real tool handlers with no database (the same
+     * reason Studio exports `handleRequest`). Production never sets it: the
+     * server builds its own pool from `options.url`.
+     */
+    pool?: pg.Pool;
 }
 export interface McpServerHandle {
     dispose(): Promise<void>;