turbine-orm 0.49.0 → 0.50.0

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

@@ -0,0 +1,181 @@
+/**
+ * turbine-orm CLI — Configuration file support
+ *
+ * Loads turbine.config.ts (or .js/.mjs) via dynamic import.
+ * Falls back to CLI args and environment variables.
+ */
+export interface TurbineCliConfig {
+    /** Postgres connection string */
+    url?: string;
+    /** Output directory for generated files (default: ./generated/turbine) */
+    out?: string;
+    /** Postgres schema to introspect (default: public) */
+    schema?: string;
+    /** Tables to include (empty = all) */
+    include?: string[];
+    /** Tables to exclude */
+    exclude?: string[];
+    /**
+     * Extension for the generated `index.ts` sibling imports (F3):
+     * `'js'` (`./types.js`), `'none'` (`./types`), or `'auto'` (default:
+     * tsconfig-detected, falling back to `'js'`).
+     */
+    importExtension?: 'js' | 'none' | 'auto';
+    /**
+     * Keep raw database column names as generated field names (snake_case)
+     * instead of camelCase (F4). Opt-in; default `false`.
+     */
+    keepColumnNames?: boolean;
+    /**
+     * Opt OUT of the unique-FK → one-to-one (`hasOne`) introspection flip (F2),
+     * emitting the pre-0.41 `hasMany` shape for unique-covered child relations.
+     * Default `false` (detection on).
+     */
+    legacyToManyUniques?: boolean;
+    /** Directory for migration files (default: ./turbine/migrations) */
+    migrationsDir?: string;
+    /**
+     * Path to the seed file (canonical key). With no value, discovery falls back
+     * to seed.ts, seed.js, seed.sql, then the same three under `turbine/`.
+     */
+    seedFile?: string;
+    /**
+     * Path to the seed file. Back-compat alias for {@link TurbineCliConfig.seedFile}:
+     * older `turbine init` runs scaffolded this spelling. `seedFile` wins when both
+     * are set.
+     */
+    seed?: string;
+    /** Schema builder file path (for push command) */
+    schemaFile?: string;
+    /**
+     * Database adapter for PostgreSQL-compatible databases that need
+     * dialect-specific behavior (e.g. CockroachDB, YugabyteDB).
+     *
+     * @example
+     * ```ts
+     * import { cockroachdb } from 'turbine-orm/adapters';
+     * export default { url: process.env.DATABASE_URL, adapter: cockroachdb };
+     * ```
+     */
+    adapter?: import('../adapters/index.js').DatabaseAdapter;
+}
+/**
+ * Alias for {@link TurbineCliConfig}. Some docs and examples import the config
+ * type as `TurbineConfig`; both names refer to the same shape.
+ */
+export type TurbineConfig = TurbineCliConfig;
+/**
+ * Heuristic: does a configured `schema` value actually look like a schema FILE
+ * path rather than a Postgres schema name? `schema` is the Postgres namespace
+ * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
+ * A value containing a path separator or a JS/TS extension is almost certainly a
+ * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * silently matches zero tables. Used by `turbine generate` to fail loudly.
+ */
+export declare function looksLikeSchemaFilePath(schema: string): boolean;
+/**
+ * Where `turbine init` scaffolds the seed file, and the `seedFile` value it
+ * writes into the generated config. Kept next to the schema file so a new
+ * project's Turbine files live in one directory.
+ */
+export declare const DEFAULT_INIT_SEED_FILE = "./turbine/seed.ts";
+/** A config-file load attempt that failed, kept so the CLI can surface it. */
+export interface ConfigLoadError {
+    /** The config file whose import threw (e.g. `turbine.config.ts`). */
+    filename: string;
+    /** The underlying error thrown by the dynamic import. */
+    error: unknown;
+}
+/** Result of {@link loadConfigResult}: the resolved config plus any load failure. */
+export interface ConfigLoadResult {
+    config: TurbineCliConfig;
+    /**
+     * Set when a config file existed but failed to import. The config is still
+     * returned as `{}` so resolution falls through to env vars and CLI flags, but
+     * the CLI should surface this rather than let it masquerade as a missing URL.
+     */
+    loadError?: ConfigLoadError;
+}
+/**
+ * Unwrap the module object returned by `import(configFile)` down to the actual
+ * config value.
+ *
+ * With `"type": "commonjs"` in the consumer's package.json (the `npm init -y`
+ * default) plus the tsx loader, importing `turbine.config.ts` yields a
+ * CJS-interop DOUBLE-wrapped default: `mod.default` is itself `{ default: config }`.
+ * A naive `mod.default ?? mod` then reads every field as `undefined`, so every
+ * command fails with a misleading "No database URL provided".
+ *
+ * This prefers `default` when present (the historical behavior) and then keeps
+ * descending through any additional pure `{ default: … }` wrappers, so both the
+ * correct single-default shape and the double-wrapped shape resolve to the same
+ * config. A genuine config object (which has real fields, never a lone
+ * `default`) is returned untouched.
+ */
+export declare function unwrapModuleDefault(mod: unknown): unknown;
+/**
+ * {@link unwrapModuleDefault} specialized for config files: a non-object export
+ * collapses to `{}` so downstream resolution falls through to env vars/flags.
+ */
+export declare function unwrapConfigModule(mod: unknown): TurbineCliConfig;
+/**
+ * Attempt to load a turbine config file from the given directory, returning the
+ * resolved config together with any load failure so the caller can surface it.
+ *
+ * Candidates are tried in {@link CONFIG_FILES} priority order. The first one
+ * that imports successfully wins. If a candidate exists but throws (syntax
+ * error, ESM/CJS interop failure, etc.) we remember the first such error and
+ * keep trying lower-priority candidates; if none load, the remembered error is
+ * returned in `loadError` while `config` stays `{}` so env/flag resolution can
+ * still proceed.
+ */
+export declare function loadConfigResult(cwd?: string): Promise<ConfigLoadResult>;
+/**
+ * Attempt to load a turbine config file from the current directory.
+ * Returns the config if found, or an empty object. Load failures are swallowed
+ * here; callers that need to surface them should use {@link loadConfigResult}.
+ */
+export declare function loadConfig(cwd?: string): Promise<TurbineCliConfig>;
+/**
+ * Find the config file path (for display purposes).
+ * Returns null if no config file is found.
+ */
+export declare function findConfigFile(cwd?: string): string | null;
+export interface ResolvedConfig {
+    url: string;
+    out: string;
+    schema: string;
+    include: string[];
+    exclude: string[];
+    migrationsDir: string;
+    seedFile?: string;
+    schemaFile: string;
+    /** Resolved generator import-extension mode (F3). */
+    importExtension: 'js' | 'none' | 'auto';
+    /** Resolved keep-column-names generator flag (F4). */
+    keepColumnNames: boolean;
+    /** Resolved opt-out of the unique-FK → hasOne introspection flip (F2). */
+    legacyToManyUniques: boolean;
+}
+export interface CliOverrides {
+    url?: string;
+    out?: string;
+    schema?: string;
+    include?: string[];
+    exclude?: string[];
+    importExtension?: 'js' | 'none' | 'auto';
+    keepColumnNames?: boolean;
+    legacyToManyUniques?: boolean;
+}
+/**
+ * Merge config file values with CLI overrides and env vars.
+ * Priority: CLI flags > env vars > config file > defaults.
+ */
+export declare function resolveConfig(fileConfig: TurbineCliConfig, overrides: CliOverrides): ResolvedConfig;
+/**
+ * Resolve the seed file path. An explicit config value wins even if the file
+ * does not exist yet; otherwise {@link DEFAULT_SEED_CANDIDATES} is tried in
+ * order (root-level first, then the `turbine/` location `init` scaffolds).
+ */
+export declare function resolveSeedFile(config: Pick<TurbineCliConfig, 'seed' | 'seedFile'>, cwd?: string): string | null;
+export declare function configTemplate(connectionString?: string): string;

package/dist/cjs/cli/config.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INIT_SEED_FILE = void 0;
 exports.looksLikeSchemaFilePath = looksLikeSchemaFilePath;
 exports.unwrapModuleDefault = unwrapModuleDefault;
 exports.unwrapConfigModule = unwrapConfigModule;
@@ -68,7 +69,28 @@ function looksLikeSchemaFilePath(schema) {
 // Config file names, in priority order
 // ---------------------------------------------------------------------------
 const CONFIG_FILES = ['turbine.config.ts', 'turbine.config.mts', 'turbine.config.js', 'turbine.config.mjs'];
-const DEFAULT_SEED_CANDIDATES = ['seed.ts', 'seed.js', 'seed.sql'];
+/**
+ * Config-less fallback locations for the seed file, in priority order.
+ *
+ * Root-level candidates stay FIRST so no project that already relies on
+ * `./seed.ts` changes behavior. The `turbine/` candidates are appended so a
+ * project that drops the `seedFile` key can still auto-discover the file
+ * `turbine init` scaffolds (see {@link DEFAULT_INIT_SEED_FILE}).
+ */
+const DEFAULT_SEED_CANDIDATES = [
+    'seed.ts',
+    'seed.js',
+    'seed.sql',
+    'turbine/seed.ts',
+    'turbine/seed.js',
+    'turbine/seed.sql',
+];
+/**
+ * Where `turbine init` scaffolds the seed file, and the `seedFile` value it
+ * writes into the generated config. Kept next to the schema file so a new
+ * project's Turbine files live in one directory.
+ */
+exports.DEFAULT_INIT_SEED_FILE = './turbine/seed.ts';
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -183,7 +205,9 @@ function resolveConfig(fileConfig, overrides) {
         include: overrides.include ?? fileConfig.include ?? [],
         exclude: overrides.exclude ?? fileConfig.exclude ?? [],
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
-        seedFile: fileConfig.seed ?? fileConfig.seedFile,
+        // `seedFile` is canonical (what the docs and `turbine init` use); `seed` is a
+        // back-compat alias kept working for configs scaffolded before 0.50.
+        seedFile: fileConfig.seedFile ?? fileConfig.seed,
         schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
         importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
         keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
@@ -192,10 +216,12 @@ function resolveConfig(fileConfig, overrides) {
 }
 /**
  * Resolve the seed file path. An explicit config value wins even if the file
- * does not exist yet; otherwise the root-level defaults are tried in order.
+ * does not exist yet; otherwise {@link DEFAULT_SEED_CANDIDATES} is tried in
+ * order (root-level first, then the `turbine/` location `init` scaffolds).
  */
 function resolveSeedFile(config, cwd = process.cwd()) {
-    const explicit = config.seed ?? config.seedFile;
+    // Canonical `seedFile` first, then the back-compat `seed` alias (see resolveConfig).
+    const explicit = config.seedFile ?? config.seed;
     if (explicit)
         return (0, node_path_1.resolve)(cwd, explicit);
     for (const candidate of DEFAULT_SEED_CANDIDATES) {
@@ -233,8 +259,8 @@ ${urlLine}
   /** Directory for SQL migration files */
   migrationsDir: './turbine/migrations',
 
-  /** Path to seed file (defaults: ./seed.ts, ./seed.js, ./seed.sql) */
-  seed: './seed.ts',
+  /** Path to seed file (defaults: ./seed.ts, ./seed.js, ./seed.sql, ./turbine/seed.ts) */
+  seedFile: '${exports.DEFAULT_INIT_SEED_FILE}',
 
   /** Path to schema builder file (for turbine push) */
   schemaFile: './turbine/schema.ts',

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

@@ -0,0 +1,38 @@
+/**
+ * Destructive-migration detection.
+ *
+ * `migrate up`/`down` execute user-authored SQL files verbatim, which is the
+ * one place data loss can hide: a `DROP TABLE` or a `DELETE FROM` in a
+ * migration runs with no ceremony. This module scans migration SQL for
+ * statements that can destroy data so the CLI can force an explicit,
+ * interactive confirmation (and the programmatic API can refuse by default).
+ *
+ * Deliberately conservative in BOTH directions:
+ *   - comments and string literals are stripped first, so `-- DROP TABLE foo`
+ *     or `INSERT ... VALUES ('DROP TABLE x')` never false-positive;
+ *   - anything that removes rows, columns, tables, or schemas, or rewrites a
+ *     column's type (a potentially lossy cast), is flagged. `DROP INDEX`,
+ *     `DROP CONSTRAINT`, and `DROP TRIGGER` are NOT flagged (recreatable
+ *     structures; no row data lost).
+ *
+ * Row removal hides in more than a leading `DELETE`, so the scan also covers:
+ * the optional-`COLUMN` shorthand (`ALTER TABLE t DROP email`), data-modifying
+ * CTEs (`WITH d AS (DELETE ...) SELECT ...`), `MERGE ... THEN DELETE`, dynamic
+ * SQL inside a `DO`/function body, and an `UPDATE` whose only WHERE sits inside
+ * a subquery (which restricts nothing).
+ */
+export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type' | 'merge-delete';
+export interface DestructiveStatement {
+    /** The offending SQL statement (trimmed, possibly long — display truncated) */
+    statement: string;
+    kind: DestructiveKind;
+    /** Best-effort extracted object name (table, schema, or table.column) */
+    target: string;
+}
+/** Human explanation per kind, used in CLI output. */
+export declare const DESTRUCTIVE_KIND_LABEL: Record<DestructiveKind, string>;
+/**
+ * Scan SQL (one file's worth; may contain many `;`-separated statements) and
+ * return every statement that can destroy data.
+ */
+export declare function scanDestructiveSql(sql: string): DestructiveStatement[];

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

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * turbine-orm CLI
+ *
+ * Commands:
+ *   turbine init                  — Initialize a Turbine project
+ *   turbine generate | pull       — Introspect database and generate TypeScript types
+ *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
+ *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
+ *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
+ *   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                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently, --unused, --audit)
+ *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
+ *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *
+ * Usage:
+ *   DATABASE_URL=postgres://... npx turbine generate
+ *   npx turbine init --url postgres://...
+ *   npx turbine migrate create add_users_table
+ */
+import type { CliOverrides, ConfigLoadError, ResolvedConfig, TurbineCliConfig } from './config.js';
+import { type PrismaSchemaAst, type ResolvedPrismaDatasourceUrl } from './prisma-schema.js';
+export interface CliArgs {
+    command: string;
+    subcommand?: string;
+    positional: string[];
+    url?: string;
+    out?: string;
+    schema?: string;
+    include?: string[];
+    exclude?: string[];
+    step?: number;
+    dryRun?: boolean;
+    force?: boolean;
+    verbose?: boolean;
+    help?: boolean;
+    auto?: boolean;
+    /** `migrate create --from-diff`: scaffold UP/DOWN from the schema diff, destructive statements flagged. */
+    fromDiff?: boolean;
+    allowDrift?: boolean;
+    allowEmpty?: boolean;
+    allowDestructive?: boolean;
+    /** `migrate create --recipe <name>` scaffold selector. */
+    recipe?: string;
+    fix?: boolean;
+    /** `doctor --json`: emit a stable, versioned machine-readable report. */
+    json?: boolean;
+    /** `doctor --fix --no-concurrently`: emit plain CREATE INDEX instead of the CONCURRENTLY + no-transaction form. */
+    noConcurrently?: boolean;
+    /** `doctor --unused`: report-only never-scanned / redundant / invalid indexes with DROP suggestions. */
+    unused?: boolean;
+    /** `doctor --audit`: unused report scoped to doctor's own previously-suggested index names. */
+    audit?: boolean;
+    /** `doctor --min-scans <n>`: idx_scan below this counts as never-scanned (default 1 = idx_scan 0). */
+    minScans?: number;
+    /** `doctor --metrics-url <url>`: read _turbine_metrics for the table-heat boost from a separate DB. */
+    metricsUrl?: string;
+    /** `init --yes`/`-y`: accept every step's default non-interactively. */
+    yes?: boolean;
+    /** `init --skip-schema`: don't scaffold the schema file. */
+    skipSchema?: boolean;
+    /** `init --skip-seed`: don't scaffold the seed file or offer to run it. */
+    skipSeed?: boolean;
+    /** `init --skip-push`: don't offer to push the schema to the database. */
+    skipPush?: boolean;
+    /** `init --skip-generate`: don't offer to generate the typed client. */
+    skipGenerate?: boolean;
+    zod?: boolean;
+    includeViews?: boolean;
+    /** Omit the `Generated at:` header line for reproducible (diff-stable) output. */
+    noTimestamp?: boolean;
+    /** `generate --import-ext <js|none|auto>`: sibling-import extension mode (F3). */
+    importExtension?: 'js' | 'none' | 'auto';
+    /** `generate --keep-column-names`: keep raw DB column names as field names (F4). */
+    keepColumnNames?: boolean;
+    /** `generate --legacy-to-many-uniques`: opt out of the unique-FK → hasOne flip (F2). */
+    legacyToManyUniques?: boolean;
+    port?: number;
+    host?: string;
+    noOpen?: boolean;
+    /** Opt-in to bind Studio/Observe on a non-loopback host. */
+    allowRemote?: boolean;
+    /** Opt-in to Studio single-row write mode (`studio --write`). */
+    write?: boolean;
+    /** Reveal PII-tagged column values in Studio instead of redacting (`--show-pii`). */
+    showPii?: boolean;
+    /** Launch Studio with a seeded in-memory sample database (`studio --demo`). */
+    demo?: boolean;
+    /** `migrate-from-prisma --allow-partial`: exit 0 even when some items are UNRESOLVED. */
+    allowPartial?: boolean;
+    /** `migrate-from-prisma --no-db`: parse-only, skip database resolution. */
+    noDb?: boolean;
+}
+export declare function parseArgs(argv?: string[]): CliArgs;
+/**
+ * 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.
+ */
+export declare function usesProjectConfig(args: Pick<CliArgs, 'command' | 'demo'>): boolean;
+/**
+ * Outcome of {@link bootstrapCliConfig}.
+ *
+ * @internal exported for tests.
+ */
+export interface CliConfigBootstrap {
+    /** Merged config: CLI flags > env vars > config file > defaults. */
+    config: ResolvedConfig;
+    /** The raw config-file contents (`{}` when none was loaded). */
+    fileConfig: TurbineCliConfig;
+    /** Set when a config file existed but failed to import. */
+    loadError?: ConfigLoadError;
+    /** True when config resolution was deliberately skipped (see {@link usesProjectConfig}). */
+    skipped: boolean;
+}
+/**
+ * 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.
+ */
+export declare function bootstrapCliConfig(args: Pick<CliArgs, 'command' | 'demo'>, overrides: CliOverrides): Promise<CliConfigBootstrap>;
+/** Where a resolved `DATABASE_URL` came from, after the `.env` load. */
+export type DotEnvProvenance = 'shell' | 'dotenv' | 'none';
+/** Structured outcome of {@link loadDotEnvForCli}. */
+export interface DotEnvLoadResult {
+    /** A `.env` file was present in the working directory. */
+    fileExists: boolean;
+    /** The `.env` was actually read into the environment. */
+    loaded: boolean;
+    /** A `.env` exists but this runtime cannot auto-load it (Node < 20.12). */
+    unsupported: boolean;
+    /** Where `DATABASE_URL` ended up coming from once the load settled. */
+    databaseUrlProvenance: DotEnvProvenance;
+    /** Set when the loader threw (e.g. EACCES / a directory named `.env`). */
+    loadError?: string;
+}
+/**
+ * Load a local `.env` into `process.env` for the CLI, mirroring what
+ * `node --env-file=.env` does. Loaded UNCONDITIONALLY when a `.env` is present,
+ * so every variable it defines (not just `DATABASE_URL`) reaches the config
+ * file and user scripts.
+ *
+ * A pre-existing variable ALWAYS wins: `process.loadEnvFile()` never overrides
+ * an already-set variable, so a real shell/CI `DATABASE_URL` beats the file.
+ * Provenance is tracked so callers can warn when an `.env`-sourced
+ * `DATABASE_URL` silently overrides a differing `url` in `turbine.config.ts`:
+ * `DATABASE_URL` is `'dotenv'`-sourced only when it was absent before the load
+ * and present after.
+ *
+ * `process.loadEnvFile` is Node 20.12+. Turbine's engines allow `>=20.0.0`, so
+ * on older runtimes this no-ops with `unsupported: true` (never throws). A
+ * loader that throws (unreadable file, a directory named `.env`) is caught and
+ * surfaced as `loadError`, never a raw unhandled rejection. Deliberately
+ * CLI-only: the library must never read files.
+ *
+ * Dependencies are injectable purely so this is unit-testable without mutating
+ * the real process environment.
+ */
+export declare function loadDotEnvForCli(deps?: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fileExists?: (path: string) => boolean;
+    loadEnvFile?: ((path: string) => void) | null;
+}): DotEnvLoadResult;
+/**
+ * Decide whether to warn that an `.env`-sourced `DATABASE_URL` is overriding a
+ * differing, non-empty `url` in the config file. Pure so it is unit-testable.
+ *
+ * Precedence is unchanged (`.env` `DATABASE_URL` still wins), this only decides
+ * whether that override is silent or loud. We warn ONLY when all hold:
+ *   - no CLI `--url` override (an explicit override is the user's clear intent),
+ *   - `DATABASE_URL` came from `.env` (shell-exported stays silent, as before),
+ *   - the config file has a non-empty `url`, and
+ *   - the two URLs actually differ.
+ *
+ * Returns the warning message (URLs redacted), or `null` for no warning.
+ */
+export declare function dotEnvUrlConflictWarning(input: {
+    provenance: DotEnvProvenance;
+    envUrl: string | undefined;
+    fileConfigUrl: string | undefined;
+    overrideUrl: string | undefined;
+}): string | null;
+/** Package managers we can name an exact install command for. */
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+/**
+ * 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.
+ */
+export declare function detectPackageManager(cwd?: string): PackageManager;
+/**
+ * The exact "add tsx as a dev dependency" command for a package manager.
+ *
+ * @internal exported for tests.
+ */
+export declare function tsxInstallCommand(pm: PackageManager): string;
+/**
+ * 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.
+ */
+export declare function tsxRequiredNotice(tsFiles: string[], installCommand: string): string[];
+/**
+ * Read the consumer's `package.json` `"type"` field. Returns `'module'` for an
+ * ESM project, `'commonjs'` for an explicit or absent (defaulted) CommonJS
+ * project, and `'none'` when there is no readable/parseable package.json.
+ */
+export declare function detectConsumerModuleType(cwd?: string): 'module' | 'commonjs' | 'none';
+/** A single step in the `turbine init` flow. */
+export type InitStepId = 'config' | 'schema' | 'seed-file' | 'push' | 'generate' | 'seed-run';
+/** What the planner decided to do with a step. */
+export type InitStepAction = 'run' | 'prompt' | 'skip';
+/** Why a step was skipped (only set when `action` is `skip`). */
+export type InitStepSkipReason = 'exists' | 'flag' | 'no-url' | 'unreachable' | 'no-seed-file' | 'non-interactive' | 'default-no';
+export interface InitPlanStep {
+    id: InitStepId;
+    action: InitStepAction;
+    /** Prompt default; also the value used to decide auto-run under `--yes`. */
+    defaultYes: boolean;
+    skipReason?: InitStepSkipReason;
+}
+/** Detected project state (all IO done by the caller). */
+export interface InitPlanState {
+    configExists: boolean;
+    schemaExists: boolean;
+    seedFileExists: boolean;
+    hasUrl: boolean;
+    dbReachable: boolean;
+}
+/** Effective flags for the planner. */
+export interface InitPlanFlags {
+    yes: boolean;
+    force: boolean;
+    interactive: boolean;
+    skipSchema: boolean;
+    skipSeed: boolean;
+    skipPush: boolean;
+    skipGenerate: boolean;
+}
+/**
+ * Pure step planner for `turbine init`. Given the detected project state and the
+ * effective flags, decide for each step whether to run it, prompt for it, or
+ * skip it (and why). No IO: every input is precomputed by the caller: so the
+ * whole decision matrix is unit-testable without a TTY or a database.
+ *
+ * Three modes:
+ *  - `prompt`      (interactive TTY, no `--yes`): scaffold + DB steps are prompted.
+ *  - `auto-yes`    (`--yes`): accept each step's default; the yes-defaults run.
+ *  - `auto-legacy` (non-TTY, no `--yes`): reproduce the pre-existing init
+ *    behavior. Scaffold files + generate run; push + seed-run do not.
+ *
+ * Steps that create files (config, schema, seed) are skipped when the file
+ * already exists, so re-runs are safe. DB steps (push, generate, seed-run) are
+ * skipped when there is no URL or the database is unreachable.
+ */
+export declare function planInitSteps(state: InitPlanState, flags: InitPlanFlags): InitPlanStep[];
+/**
+ * The one-line connection heads-up `turbine init` opens with.
+ *
+ * @internal exported for tests.
+ */
+export interface InitEnvNotice {
+    kind: 'success' | 'info';
+    message: string;
+}
+/**
+ * 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.
+ */
+export declare function initEnvNotice(input: {
+    envUrl: string | undefined;
+    hasEnvFile: boolean;
+    hasEnvLocal: boolean;
+    canAutoLoadEnv: boolean;
+    flagUrl: string | undefined;
+    configUrl: string | undefined;
+}): InitEnvNotice;
+/**
+ * `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.
+ *
+ * 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.
+ */
+/** Outcome of {@link resolveMigrateFromPrismaUrl}. */
+export interface MigrateFromPrismaUrl {
+    /** The connection string to use, or undefined when none could be found. */
+    url?: string;
+    /** Where it came from: the normal CLI resolution, or the Prisma datasource. */
+    source: 'config' | 'datasource' | 'none';
+    /** Datasource detail, set only when `source` is `'datasource'`. */
+    datasource?: ResolvedPrismaDatasourceUrl;
+    /** Datasource `env(...)` variable names that were declared but unset. */
+    missingVariables: string[];
+}
+/**
+ * Pick the connection string for `migrate-from-prisma`.
+ *
+ * `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.
+ */
+export declare function resolveMigrateFromPrismaUrl(configUrl: string | undefined, ast: Pick<PrismaSchemaAst, 'datasources'>, env: Record<string, string | undefined>): MigrateFromPrismaUrl;
+export declare function buildMigrateDeployOptions(args: CliArgs): {
+    allowDrift: boolean;
+    allowDestructive: true;
+    step: undefined;
+};
+export type SeedExecutionPlan = {
+    kind: 'tsx';
+    command: 'npx';
+    args: string[];
+} | {
+    kind: 'js';
+    file: string;
+} | {
+    kind: 'sql';
+    file: string;
+};
+export declare function getSeedExecutionPlan(seedFile: string): SeedExecutionPlan;
+/**
+ * True when `host` is a loopback address Studio/Observe may bind without
+ * `--allow-remote`. Accepts IPv4, IPv6, and the common bracket form.
+ */
+export declare function isLoopbackHost(host: string): boolean;