turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/cli/index.js

@@ -60,10 +60,17 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgs = parseArgs;
+exports.usesProjectConfig = usesProjectConfig;
+exports.bootstrapCliConfig = bootstrapCliConfig;
 exports.loadDotEnvForCli = loadDotEnvForCli;
 exports.dotEnvUrlConflictWarning = dotEnvUrlConflictWarning;
+exports.detectPackageManager = detectPackageManager;
+exports.tsxInstallCommand = tsxInstallCommand;
+exports.tsxRequiredNotice = tsxRequiredNotice;
 exports.detectConsumerModuleType = detectConsumerModuleType;
 exports.planInitSteps = planInitSteps;
+exports.initEnvNotice = initEnvNotice;
+exports.resolveMigrateFromPrismaUrl = resolveMigrateFromPrismaUrl;
 exports.buildMigrateDeployOptions = buildMigrateDeployOptions;
 exports.getSeedExecutionPlan = getSeedExecutionPlan;
 exports.isLoopbackHost = isLoopbackHost;
@@ -310,9 +317,49 @@ function failMissingTsLoader(filePath, reason) {
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
-// Helpers
+// Config bootstrap
 // ---------------------------------------------------------------------------
-function requireUrl(config) {
+/**
+ * Does this invocation need a `turbine.config.*` file?
+ *
+ * Everything does, with one deliberate exception: `turbine studio --demo` boots
+ * a seeded in-memory database, needs no `DATABASE_URL` and no config file, and
+ * is the very next command the quickstart suggests after `turbine init`.
+ * Resolving the config anyway means a freshly scaffolded directory (a
+ * `turbine.config.ts` with `tsx` not installed yet) dies with "Cannot load
+ * TypeScript file" before demo mode ever starts.
+ *
+ * @internal exported for tests.
+ */
+function usesProjectConfig(args) {
+    return !(args.command === 'studio' && args.demo === true);
+}
+/**
+ * Resolve the effective CLI config: register the tsx loader when the config file
+ * is TypeScript, import it, then merge it with env vars and CLI flags. Exits with
+ * the actionable "Cannot load TypeScript file" error when a `.ts` config cannot
+ * be loaded. Config-free invocations short-circuit without touching the disk.
+ *
+ * @internal exported for tests.
+ */
+async function bootstrapCliConfig(args, overrides) {
+    if (!usesProjectConfig(args)) {
+        return { config: (0, config_js_1.resolveConfig)({}, overrides), fileConfig: {}, skipped: true };
+    }
+    // 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 = (0, config_js_1.findConfigFile)();
+    if ((0, loader_js_1.needsTsLoader)(configPath)) {
+        const status = await (0, loader_js_1.registerTsLoader)();
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
+            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
+        }
+    }
+    const { config: fileConfig, loadError } = await (0, config_js_1.loadConfigResult)();
+    return { config: (0, config_js_1.resolveConfig)(fileConfig, overrides), fileConfig, loadError, skipped: false };
+}
+function requireUrl(config, options = {}) {
     if (!config.url) {
         (0, ui_js_1.error)('No database URL provided.');
         (0, ui_js_1.newline)();
@@ -322,6 +369,12 @@ function requireUrl(config) {
         const envFileNote = typeof process.loadEnvFile === 'function' ? '(auto-loaded)' : '(needs Node 20.12+ to auto-load)';
         console.log(`    ${(0, ui_js_1.dim)('2.')} Set ${(0, ui_js_1.cyan)('DATABASE_URL')} in your environment or a ${(0, ui_js_1.cyan)('.env')} file ${(0, ui_js_1.dim)(envFileNote)}`);
         console.log(`    ${(0, ui_js_1.dim)('3.')} Pass ${(0, ui_js_1.cyan)('--url')} flag`);
+        const vars = options.datasourceVars ?? [];
+        if (vars.length > 0) {
+            const list = vars.map((v) => (0, ui_js_1.cyan)(v)).join(', ');
+            const plural = vars.length > 1 ? 'these variables' : 'this variable';
+            console.log(`    ${(0, ui_js_1.dim)('4.')} Set ${list} ${(0, ui_js_1.dim)(`(${plural}, declared by your schema.prisma datasource, ${vars.length > 1 ? 'are' : 'is'} unset)`)}`);
+        }
         (0, ui_js_1.newline)();
         process.exit(1);
     }
@@ -473,6 +526,57 @@ function dotEnvUrlConflictWarning(input) {
         `(${(0, ui_js_1.redactUrl)(fileUrl)}). Using the .env value. Remove DATABASE_URL from .env, or unset the config url, ` +
         `to silence this.`);
 }
+/**
+ * Detect the consumer's package manager from its lockfile, defaulting to npm.
+ * Used only to print an exact, copy-pasteable install command.
+ *
+ * @internal exported for tests.
+ */
+function detectPackageManager(cwd = process.cwd()) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(cwd, 'yarn.lock')))
+        return 'yarn';
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(cwd, 'bun.lockb')) || (0, node_fs_1.existsSync)((0, node_path_1.join)(cwd, 'bun.lock')))
+        return 'bun';
+    return 'npm';
+}
+/**
+ * The exact "add tsx as a dev dependency" command for a package manager.
+ *
+ * @internal exported for tests.
+ */
+function tsxInstallCommand(pm) {
+    switch (pm) {
+        case 'pnpm':
+            return 'pnpm add -D tsx';
+        case 'yarn':
+            return 'yarn add -D tsx';
+        case 'bun':
+            return 'bun add -d tsx';
+        default:
+            return 'npm install --save-dev tsx';
+    }
+}
+/**
+ * The heads-up `turbine init` prints when it has just scaffolded TypeScript
+ * files and `tsx` is not resolvable: without it the CLI cannot load them, and
+ * the very next command the user runs dies on "Cannot load TypeScript file".
+ * Pure (returns the lines, prints nothing) so it can be asserted in tests.
+ *
+ * @internal exported for tests.
+ */
+function tsxRequiredNotice(tsFiles, installCommand) {
+    return [
+        `Turbine needs ${(0, ui_js_1.cyan)('tsx')} to load the TypeScript files just created:`,
+        ...tsFiles.map((f) => `    ${(0, ui_js_1.dim)(ui_js_1.symbols.dot)} ${(0, ui_js_1.cyan)(f)}`),
+        '',
+        `  ${(0, ui_js_1.dim)('Install it as a dev dependency:')}`,
+        `    ${(0, ui_js_1.cyan)(installCommand)}`,
+        '',
+        `  ${(0, ui_js_1.dim)('Without it, the next Turbine command fails with')} ${(0, ui_js_1.dim)('"Cannot load TypeScript file".')}`,
+    ];
+}
 /**
  * Read the consumer's `package.json` `"type"` field. Returns `'module'` for an
  * ESM project, `'commonjs'` for an explicit or absent (defaulted) CommonJS
@@ -798,6 +902,48 @@ function initPromptQuestion(step, config, seedFilePath) {
             return `Run ${initStepLabel(step.id)}?`;
     }
 }
+/**
+ * Decide which connection notice `turbine init` prints. Pure so the whole
+ * decision matrix is testable.
+ *
+ * "No DATABASE_URL found in environment" is reserved for the case where NO
+ * source supplied one: printing it while happily using `--url` (or a config
+ * `url`) reads like a failure the user then goes looking for.
+ *
+ * @internal exported for tests.
+ */
+function initEnvNotice(input) {
+    if (input.envUrl) {
+        return { kind: 'success', message: `Detected ${(0, ui_js_1.cyan)('DATABASE_URL')} in the environment` };
+    }
+    if (input.hasEnvFile && !input.canAutoLoadEnv) {
+        return {
+            kind: 'info',
+            message: `Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(this Node version cannot auto-load it. Upgrade to Node 20.12+ or export')} ${(0, ui_js_1.cyan)('DATABASE_URL')}${(0, ui_js_1.dim)(')')}`,
+        };
+    }
+    if (input.hasEnvFile) {
+        // .env exists but did not provide DATABASE_URL; if it had, the auto-load
+        // in main() would have populated envUrl above.
+        return {
+            kind: 'info',
+            message: `Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(no')} ${(0, ui_js_1.cyan)('DATABASE_URL')} ${(0, ui_js_1.dim)('set in it yet)')}`,
+        };
+    }
+    if (input.hasEnvLocal) {
+        return {
+            kind: 'info',
+            message: `Found ${(0, ui_js_1.cyan)('.env.local')} ${(0, ui_js_1.dim)('(note: Turbine only auto-loads')} ${(0, ui_js_1.cyan)('.env')}${(0, ui_js_1.dim)(')')}`,
+        };
+    }
+    if (input.flagUrl) {
+        return { kind: 'success', message: `Using the connection string passed with ${(0, ui_js_1.cyan)('--url')}` };
+    }
+    if (input.configUrl) {
+        return { kind: 'success', message: `Using the ${(0, ui_js_1.cyan)('url')} from your config file` };
+    }
+    return { kind: 'info', message: `No ${(0, ui_js_1.cyan)('DATABASE_URL')} found in environment` };
+}
 async function cmdInit(args, config) {
     (0, ui_js_1.banner)();
     (0, ui_js_1.header)('Initializing Turbine project');
@@ -810,23 +956,18 @@ async function cmdInit(args, config) {
     // On Node < 20.12 (no process.loadEnvFile) main() could not auto-load .env, so
     // we cannot claim it "has no DATABASE_URL"; we simply could not read it.
     const canAutoLoadEnv = typeof process.loadEnvFile === 'function';
-    if (envUrl) {
-        (0, ui_js_1.success)(`Detected ${(0, ui_js_1.cyan)('DATABASE_URL')} in the environment`);
-    }
-    else if (hasEnvFile && !canAutoLoadEnv) {
-        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(this Node version cannot auto-load it. Upgrade to Node 20.12+ or export')} ${(0, ui_js_1.cyan)('DATABASE_URL')}${(0, ui_js_1.dim)(')')}`);
-    }
-    else if (hasEnvFile) {
-        // .env exists but did not provide DATABASE_URL; if it had, the auto-load
-        // in main() would have populated envUrl above.
-        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('(no')} ${(0, ui_js_1.cyan)('DATABASE_URL')} ${(0, ui_js_1.dim)('set in it yet)')}`);
-    }
-    else if (hasEnvLocal) {
-        (0, ui_js_1.info)(`Found ${(0, ui_js_1.cyan)('.env.local')} ${(0, ui_js_1.dim)('(note: Turbine only auto-loads')} ${(0, ui_js_1.cyan)('.env')}${(0, ui_js_1.dim)(')')}`);
-    }
-    else {
-        (0, ui_js_1.info)(`No ${(0, ui_js_1.cyan)('DATABASE_URL')} found in environment`);
-    }
+    const envNotice = initEnvNotice({
+        envUrl,
+        hasEnvFile,
+        hasEnvLocal,
+        canAutoLoadEnv,
+        flagUrl: args.url,
+        configUrl: config.url,
+    });
+    if (envNotice.kind === 'success')
+        (0, ui_js_1.success)(envNotice.message);
+    else
+        (0, ui_js_1.info)(envNotice.message);
     (0, ui_js_1.newline)();
     // Heads-up (not an edit) about the consumer's module system. A CommonJS
     // project (`npm init -y` default, or no "type" field) works fine now that the
@@ -843,7 +984,9 @@ async function cmdInit(args, config) {
     const hasUrl = Boolean(url);
     const interactive = Boolean(process.stdin.isTTY);
     const yes = args.yes === true;
-    const seedFilePath = config.seedFile ?? './seed.ts';
+    // Where init scaffolds the seed file. A root-level ./seed.ts from an older
+    // init still counts, so a re-run never scaffolds a second seed file.
+    const seedFilePath = config.seedFile ?? ((0, node_fs_1.existsSync)('./seed.ts') ? './seed.ts' : config_js_1.DEFAULT_INIT_SEED_FILE);
     const configPath = (0, config_js_1.findConfigFile)();
     const state = {
         configExists: Boolean(configPath),
@@ -877,6 +1020,8 @@ async function cmdInit(args, config) {
     // Supporting dirs + .gitignore, regardless of prompts (unchanged behavior).
     ensureInitScaffoldDirs(config);
     (0, ui_js_1.newline)();
+    // TypeScript files this run actually created: they drive the tsx heads-up below.
+    const tsFilesWritten = [];
     // Execute the plan in order. `run` proceeds; `prompt` asks; `skip` reports.
     for (const step of plan) {
         if (step.action === 'skip') {
@@ -892,12 +1037,17 @@ async function cmdInit(args, 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');
                 break;
             case 'schema':
                 writeInitSchemaTemplate(config);
+                if ((0, loader_js_1.needsTsLoader)(config.schemaFile))
+                    tsFilesWritten.push(config.schemaFile);
                 break;
             case 'seed-file':
                 writeInitSeedTemplate(seedFilePath);
+                if ((0, loader_js_1.needsTsLoader)(seedFilePath))
+                    tsFilesWritten.push(seedFilePath);
                 break;
             case 'push':
                 await runInitPush(config, url);
@@ -910,6 +1060,17 @@ async function cmdInit(args, config) {
                 break;
         }
     }
+    // Scaffolding .ts files and staying silent about tsx is how a fresh project
+    // hits "Cannot load TypeScript file" on its very next command. Warn now, name
+    // the exact install command, and never install anything ourselves.
+    const tsxMissing = tsFilesWritten.length > 0 && !(0, loader_js_1.canResolveTsx)();
+    if (tsxMissing) {
+        (0, ui_js_1.newline)();
+        const [headline, ...rest] = tsxRequiredNotice(tsFilesWritten, tsxInstallCommand(detectPackageManager()));
+        (0, ui_js_1.warn)(headline ?? '');
+        for (const line of rest)
+            console.log(line);
+    }
     if (degraded) {
         (0, ui_js_1.newline)();
         (0, ui_js_1.info)('Non-interactive shell: interactive prompts were skipped.');
@@ -927,8 +1088,9 @@ async function cmdInit(args, config) {
             console.log(`     ${(0, ui_js_1.dim)('or create a')} ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('file with')} ${(0, ui_js_1.cyan)('DATABASE_URL=postgres://...')}`);
         }
         console.log(`  ${(0, ui_js_1.dim)('2.')} Run ${(0, ui_js_1.cyan)('npx turbine generate')} to introspect your DB`);
-        if (!(0, loader_js_1.canResolveTsx)()) {
-            console.log(`     ${(0, ui_js_1.dim)('Note: the TypeScript config requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('—')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        // Only when the fuller heads-up above did not already run (nothing scaffolded).
+        if (!tsxMissing && !(0, loader_js_1.canResolveTsx)()) {
+            console.log(`     ${(0, ui_js_1.dim)('Note: the TypeScript config requires')} ${(0, ui_js_1.cyan)('tsx')}: ${(0, ui_js_1.cyan)(tsxInstallCommand(detectPackageManager()))}`);
         }
     }
     else {
@@ -1053,20 +1215,30 @@ async function cmdGenerate(args, config) {
     console.log(`  ${(0, ui_js_1.dim)('const user = await db.users.findUnique({ where: { id: 1 } });')}`);
     (0, ui_js_1.newline)();
 }
-// ---------------------------------------------------------------------------
-// migrate-from-prisma
-// ---------------------------------------------------------------------------
 /**
- * `turbine migrate-from-prisma --schema prisma/schema.prisma` parses a Prisma
- * schema, resolve its models/fields/relations/compound-uniques against the live
- * database (unless `--no-db`), and emit (a) a Markdown resolution report and
- * (b) a typed `prisma-map.ts` name map next to the generated client.
+ * Pick the connection string for `migrate-from-prisma`.
  *
- * NOTE: within THIS command `--schema` names the Prisma schema FILE (not the
- * Postgres namespace, which the rest of the CLI's `--schema` means). The
- * Postgres namespace is `public` here; multi-schema (`@@schema`) is unsupported
- * in v1 and listed as a parser note in the report.
+ * `configUrl` is what {@link resolveConfig} already produced (`--url`, then
+ * `DATABASE_URL`, then `turbine.config.ts`) and always wins: an explicit flag
+ * must never be overridden by a value declared in someone else's schema file.
+ * Only when that is empty do we fall back to the `datasource` block, which
+ * removes the flag a project with a non-standard variable name would otherwise
+ * pass on every run.
  */
+function resolveMigrateFromPrismaUrl(configUrl, ast, env) {
+    const lookup = (0, prisma_schema_js_1.resolvePrismaDatasourceUrl)(ast, env);
+    if (configUrl)
+        return { url: configUrl, source: 'config', missingVariables: lookup.missingVariables };
+    if (lookup.resolved) {
+        return {
+            url: lookup.resolved.url,
+            source: 'datasource',
+            datasource: lookup.resolved,
+            missingVariables: lookup.missingVariables,
+        };
+    }
+    return { source: 'none', missingVariables: lookup.missingVariables };
+}
 async function cmdMigrateFromPrisma(args, config) {
     (0, ui_js_1.banner)();
     // `--schema` is the Prisma schema file path in this command.
@@ -1104,7 +1276,15 @@ async function cmdMigrateFromPrisma(args, config) {
         (0, ui_js_1.info)('Parse-only mode (--no-db): names will not be resolved.');
     }
     else {
-        url = requireUrl(config);
+        // The schema.prisma datasource is the LAST resort for the connection string,
+        // below `--url`, `DATABASE_URL`, and `turbine.config.ts`.
+        const resolvedUrl = resolveMigrateFromPrismaUrl(config.url, ast, process.env);
+        if (resolvedUrl.source === 'datasource' && resolvedUrl.datasource) {
+            const { variable, datasource: dsName, key } = resolvedUrl.datasource;
+            const origin = variable ? `${(0, ui_js_1.cyan)(variable)} via datasource "${dsName}"` : `datasource "${dsName}" ${key}`;
+            (0, ui_js_1.info)(`Using the connection string declared by your Prisma schema (${origin}).`);
+        }
+        url = resolvedUrl.url ?? requireUrl(config, { datasourceVars: resolvedUrl.missingVariables });
         (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
         const spinner = new ui_js_1.Spinner('Introspecting database schema').start();
         schemaMeta = await (0, introspect_js_1.introspect)({
@@ -2795,6 +2975,8 @@ function showMigrateFromPrismaHelp() {
     console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('prisma-map.ts')}              - typed PRISMA_MAP name map`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.dim)('Note:')} here ${(0, ui_js_1.cyan)('--schema')} names the Prisma FILE (not the Postgres namespace).`);
+    console.log(`  ${(0, ui_js_1.dim)('Note:')} with no ${(0, ui_js_1.cyan)('--url')} / ${(0, ui_js_1.cyan)('DATABASE_URL')} / config ${(0, ui_js_1.cyan)('url')}, the connection string`);
+    console.log(`        declared by your ${(0, ui_js_1.cyan)('datasource')} block is used (including its ${(0, ui_js_1.cyan)('env("...")')}).`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--schema')} ${(0, ui_js_1.dim)('<file>')}     Path to schema.prisma ${(0, ui_js_1.dim)('(default: prisma/schema.prisma)')}`);
@@ -3055,27 +3237,6 @@ async function main() {
         (0, ui_js_1.warn)(`Found ${(0, ui_js_1.cyan)('.env')} but this Node version cannot auto-load it. ` +
             `Upgrade to Node 20.12+ or export ${(0, ui_js_1.cyan)('DATABASE_URL')} yourself.`);
     }
-    // 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 = (0, config_js_1.findConfigFile)();
-    if ((0, loader_js_1.needsTsLoader)(configPath)) {
-        const status = await (0, loader_js_1.registerTsLoader)();
-        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
-            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
-        }
-    }
-    // Load config file. A config that exists but fails to import is surfaced
-    // loudly (with a name + the underlying error) instead of being swallowed and
-    // later misreported as a missing database URL.
-    const { config: fileConfig, loadError } = await (0, config_js_1.loadConfigResult)();
-    if (loadError && args.command !== 'init') {
-        const underlying = loadError.error instanceof Error ? loadError.error.message : String(loadError.error);
-        (0, ui_js_1.warn)(`Could not load ${(0, ui_js_1.cyan)(loadError.filename)}: ${underlying}`);
-        if (loadError.error instanceof Error)
-            printCjsHintIfApplicable(loadError.error);
-        (0, ui_js_1.newline)();
-    }
     const overrides = {
         url: args.url,
         out: args.out,
@@ -3086,7 +3247,18 @@ async function main() {
         keepColumnNames: args.keepColumnNames,
         legacyToManyUniques: args.legacyToManyUniques,
     };
-    const config = (0, config_js_1.resolveConfig)(fileConfig, overrides);
+    // Resolve the config file (skipped entirely for config-free invocations such
+    // as `studio --demo`). A config that exists but fails to import is surfaced
+    // loudly (with a name + the underlying error) instead of being swallowed and
+    // later misreported as a missing database URL.
+    const { config, fileConfig, loadError } = await bootstrapCliConfig(args, overrides);
+    if (loadError && args.command !== 'init') {
+        const underlying = loadError.error instanceof Error ? loadError.error.message : String(loadError.error);
+        (0, ui_js_1.warn)(`Could not load ${(0, ui_js_1.cyan)(loadError.filename)}: ${underlying}`);
+        if (loadError.error instanceof Error)
+            printCjsHintIfApplicable(loadError.error);
+        (0, ui_js_1.newline)();
+    }
     // Warn (don't change precedence) when an .env-sourced DATABASE_URL is silently
     // overriding a differing, non-empty url in the config file (a wrong-database
     // hazard for push/migrate/seed). Shell-exported DATABASE_URL stays silent.

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

@@ -0,0 +1,61 @@
+/**
+ * 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` is resolvable from the user's CWD.
+ *   2. Prefer tsx's supported programmatic API, `tsx/esm/api`'s `register()`.
+ *      Calling Node's `module.register('tsx/esm', ...)` directly throws
+ *      "tsx must be loaded with --import instead of --loader" on every Node
+ *      version that has `module.register()` (>= 20.6) — tsx's hook file
+ *      guards against being loaded that way. The `tsx/esm/api` entry point
+ *      is the documented path and works everywhere `module.register()` does.
+ *   3. Fall back to `module.register('tsx/esm', ...)` only for very old tsx
+ *      versions (< 4.0) that predate `tsx/esm/api`.
+ *   4. If tsx isn't installed, or registration genuinely fails, surface an
+ *      actionable error — including the REAL underlying error message, never
+ *      a misdiagnosed "tsx is not installed".
+ *
+ * `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' | 'failed';
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+export declare function getTsLoaderError(): string | null;
+/**
+ * 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) and tsx has
+ *                   no programmatic API to fall back to
+ *   - 'missing'     `tsx` is not installed in the user's project
+ *   - 'failed'      tsx IS installed but registration threw — see
+ *                   {@link getTsLoaderError} for the underlying message
+ */
+export declare function registerTsLoader(): Promise<TsLoaderStatus>;
+/** Reset the loader state — used by unit tests only. */
+export declare function _resetTsLoaderStateForTests(): void;

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

@@ -0,0 +1,42 @@
+import type { Readable, Writable } from 'node:stream';
+import { type ColumnMetadata, type RelationDef } from '../schema.js';
+export interface McpServerOptions {
+    url: string;
+    schema: string;
+    migrationsDir: string;
+    include?: string[];
+    exclude?: string[];
+    /**
+     * Directory holding generated Turbine metadata (`turbine generate`'s `out`).
+     * PII tags are code-first declarations that introspection never sets, so
+     * without this the server has nothing to redact against. Read as text;
+     * nothing from it is executed. See `pii-tags.ts`.
+     */
+    metadataDir?: string;
+}
+export interface McpTransport {
+    input?: Readable;
+    output?: Writable;
+}
+export interface McpServerHandle {
+    dispose(): Promise<void>;
+}
+export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
+interface ForeignKeyRow {
+    source_table: string;
+    source_column: string;
+    target_table: string;
+    target_column: string;
+    constraint_name: string;
+}
+/**
+ * Group raw FK rows into constraint-level entries and delegate relation
+ * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
+ * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
+ * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
+ * generate` derived DIFFERENT relation names from the same database (N-3).
+ * Exported for the parity unit test.
+ */
+export declare function buildRelations(tableNames: string[], columnsByTable: Map<string, ColumnMetadata[]>, pkByTable: Map<string, string[]>, rows: ForeignKeyRow[], enums?: Record<string, string[]>): Map<string, Record<string, RelationDef>>;
+export declare function runMcpServer(options: McpServerOptions): Promise<void>;
+export {};