turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/serverless.d.ts

@@ -0,0 +1,142 @@
+/**
+ * turbine-orm/serverless — edge / serverless driver integration
+ *
+ * Turbine runs on any Postgres driver that speaks the node-postgres API.
+ * This module exposes a thin factory (`turbineHttp`) that binds an external
+ * pg-compatible pool to a schema, so you can use Turbine on Vercel Edge,
+ * Cloudflare Workers, Deno Deploy, Netlify Edge, or any other environment
+ * where a direct TCP connection is unavailable.
+ *
+ * ## Supported drivers
+ *
+ * Any driver whose `Pool` satisfies `PgCompatPool` will work. The ones
+ * below are verified:
+ *
+ * - **Neon** (`@neondatabase/serverless`) — HTTP and WebSocket transports
+ * - **Vercel Postgres** (`@vercel/postgres`) — wraps Neon
+ * - **Cloudflare Hyperdrive** — exposes a pg-compatible driver
+ * - **Supabase** — use the regular `pg` package; Supabase is Postgres-native
+ *
+ * Turbine does NOT bundle any of these — install whichever you need and
+ * pass its pool directly.
+ *
+ * ## Limitations over HTTP
+ *
+ * - **Streaming cursors** (`findManyStream`, `findManyCursor`) require
+ *   server-side `DECLARE CURSOR`, which most HTTP drivers do not support.
+ *   If you call these on an HTTP pool the underlying driver will error.
+ * - **LISTEN/NOTIFY** is not available over HTTP.
+ * - **Transactions** are supported but each transaction holds an HTTP
+ *   connection for its duration — keep them short.
+ *
+ * ## Example — Neon on Vercel Edge
+ *
+ * ```ts
+ * // app/api/users/route.ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { SCHEMA } from '../../generated/turbine/metadata';
+ *
+ * export const runtime = 'edge';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, SCHEMA);
+ *
+ * export async function GET() {
+ *   const users = await db.table('users').findMany({ limit: 10 });
+ *   return Response.json(users);
+ * }
+ * ```
+ *
+ * ## Example — Supabase (direct Postgres, no HTTP proxy needed)
+ *
+ * ```ts
+ * import { TurbineClient } from 'turbine-orm';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = new TurbineClient({
+ *   connectionString: process.env.SUPABASE_DB_URL,
+ *   ssl: { rejectUnauthorized: false },
+ * }, SCHEMA);
+ * ```
+ *
+ * ## Example — Cloudflare Workers
+ *
+ * ```ts
+ * // Use the Neon HTTP driver which works in Workers runtime
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { SCHEMA } from './generated/turbine/metadata';
+ *
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const pool = new Pool({ connectionString: env.DATABASE_URL });
+ *     const db = turbineHttp(pool, SCHEMA);
+ *     const users = await db.table('users').findMany({ limit: 10 });
+ *     return Response.json(users);
+ *   }
+ * };
+ * ```
+ */
+import { type PgCompatPool, TurbineClient, type TurbineConfig } from './client.js';
+import type { SchemaMetadata } from './schema.js';
+export type { PgCompatPool, PgCompatPoolClient, PgCompatQueryResult } from './client.js';
+/**
+ * Options for `turbineHttp()`. Mirrors the fields of `TurbineConfig`
+ * that are relevant for externally-managed pools.
+ */
+export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+}
+/**
+ * Create a TurbineClient bound to an external pg-compatible pool.
+ *
+ * Use this for serverless/edge environments where Turbine should NOT
+ * manage its own `pg.Pool`. The caller retains ownership of the pool's
+ * lifecycle — `db.disconnect()` is a no-op.
+ *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
+ * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
+ * @param schema - Introspected or hand-written schema metadata
+ * @param options - Optional logging / defaultLimit / warnOnUnlimited
+ * @returns A TurbineClient instance (typed as `TClient`)
+ *
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, SCHEMA);
+ * const users = await db.table('users').findMany({ limit: 10 });
+ * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
+ */
+export declare function turbineHttp<TClient extends TurbineClient = TurbineClient>(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TClient;

package/dist/cjs/sqlite.d.ts

@@ -0,0 +1,143 @@
+/**
+ * turbine-orm/sqlite — zero-dependency SQLite engine
+ *
+ * Binds Turbine to SQLite via Node's built-in `node:sqlite` driver
+ * (`DatabaseSync`), so SQLite is a **zero new dependency** engine: the root
+ * package's runtime dependency stays exactly `pg`. This is the in-process
+ * test / edge / "try it in 10 seconds" engine — `:memory:` databases run
+ * entirely in-process with no service container.
+ *
+ * ## Driver
+ *
+ * - **Primary:** `node:sqlite` `DatabaseSync` (Node ≥ 22.5, experimental). Emits
+ *   an `ExperimentalWarning` — harmless. No native build, no extra dependency.
+ * - **Fallback:** `better-sqlite3` for Node < 22.5. Not bundled and not required;
+ *   wrap a `better-sqlite3` handle in the same `PgCompatPool` shape if needed.
+ *
+ * ## Capabilities & limits (vs PostgreSQL)
+ *
+ * - `RETURNING` + `ON CONFLICT … DO UPDATE` (SQLite ≥ 3.35) → create / upsert /
+ *   update / delete return real rows in a single statement (`resultStrategy =
+ *   'returning'`, same as Postgres).
+ * - **Single-writer:** one connection / one write transaction at a time;
+ *   concurrent writers get `SQLITE_BUSY` (treated as retryable). `journal_mode =
+ *   WAL` is enabled for file databases to allow concurrent readers.
+ * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
+ *   LISTEN/NOTIFY (`$listen` / `$notify`), RLS `sessionContext`. Advisory-lock
+ *   migration locking is unavailable — SQLite is single-writer, so migrations
+ *   serialize naturally.
+ * - **Type affinity caveats:** SQLite has no native `BOOLEAN` (0/1 integers) or
+ *   `DATE` (TEXT/INTEGER). Booleans bind as 1/0; `Date` values bind as ISO-8601
+ *   text; columns declared `TIMESTAMP`/`DATETIME`/`DATE` are coerced back to
+ *   `Date`. Integers wider than `Number.MAX_SAFE_INTEGER` come back as strings
+ *   (the same safe-int policy Turbine uses for Postgres `int8`).
+ * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
+ *   (no Unicode case folding).
+ *
+ * ## Example — `:memory:` database
+ *
+ * ```ts
+ * import { turbineSqlite } from 'turbine-orm/sqlite';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = turbineSqlite(':memory:', SCHEMA);
+ * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect, type IntrospectOptions } from './dialect.js';
+import { type SchemaMetadata, type TableMetadata } from './schema.js';
+/** pg-style query argument: a SQL string or a `{ text, values }` config object. */
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A `PgCompatPool` backed by a single `node:sqlite` `DatabaseSync` connection.
+ * SQLite is single-connection by nature (a `:memory:` database is per-handle),
+ * so `connect()` hands back a client over the **same** handle — transactions
+ * (`BEGIN`/`COMMIT`/`ROLLBACK`, `SAVEPOINT` nesting) just run on it. Queries are
+ * serialized; this is the documented single-writer model.
+ */
+export declare class SqlitePool implements PgCompatPool {
+    /** The underlying `node:sqlite` handle — exposed as an escape hatch (seed/DDL). */
+    readonly db: DatabaseSync;
+    private closed;
+    constructor(db: DatabaseSync);
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/**
+ * Map a SQLite declared column type (type affinity) to a TypeScript type.
+ * SQLite is dynamically typed; we read the declared `PRAGMA table_info` type.
+ */
+export declare function sqliteTypeToTs(declaredType: string, nullable: boolean): string;
+/**
+ * SQLite implementation of the {@link Dialect} contract. Standardizes on `"…"`
+ * identifier quoting and positional `?` placeholders, uses `json_object` /
+ * `json_group_array` for the single-query nested-relation engine (with the
+ * critical `json(...)` subresult wrap so nested objects are real JSON, not
+ * SQLite's strings-of-strings double-encoding), keeps `RETURNING` + `ON CONFLICT`
+ * (SQLite ≥ 3.35), and disables the Postgres-only capabilities (vector,
+ * LISTEN/NOTIFY, RLS, advisory locks).
+ */
+export declare const sqliteDialect: Dialect;
+/**
+ * Read a live SQLite database (an open `DatabaseSync` handle) into the same
+ * {@link SchemaMetadata} shape the Postgres catalog introspector produces.
+ * Exposed directly so callers (and tests) can introspect an in-process
+ * `:memory:` database without round-tripping through a file path.
+ */
+export declare function introspectSqliteDatabase(db: DatabaseSync, options?: {
+    include?: string[];
+    exclude?: string[];
+}): {
+    tables: Record<string, TableMetadata>;
+    enums: {};
+};
+/**
+ * Open the SQLite database named by `options.connectionString` (a file path or
+ * `':memory:'`), introspect it, and close it. Wraps
+ * {@link introspectSqliteDatabase} for the {@link DialectIntrospector} seam used
+ * by `introspect()` / `npx turbine generate`.
+ *
+ * Note: introspecting `':memory:'` opens a *fresh, empty* database (memory DBs
+ * are per-handle), so codegen should target a real file.
+ */
+export declare function introspectSqlite(options: IntrospectOptions): Promise<SchemaMetadata>;
+/** Options for {@link turbineSqlite}. Mirrors the relevant {@link TurbineConfig} fields. */
+export interface TurbineSqliteOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /**
+     * Enable WAL journal mode for file databases (better read concurrency).
+     * Ignored for `':memory:'`. Default: `true`.
+     */
+    wal?: boolean;
+    /** `PRAGMA busy_timeout` in ms — how long a writer waits on `SQLITE_BUSY`. Default: 5000. */
+    busyTimeoutMs?: number;
+    /** Enable `PRAGMA foreign_keys` enforcement. Default: `true`. */
+    foreignKeys?: boolean;
+}
+/**
+ * Create a {@link TurbineClient} bound to SQLite via `node:sqlite`.
+ *
+ * Pass a file path, `':memory:'`, or an already-open `DatabaseSync` handle (so
+ * you can seed / introspect it first and reuse the same connection). The
+ * returned client uses {@link sqliteDialect} and disables prepared-statement
+ * names (SQLite caches plans internally).
+ *
+ * @param target  A SQLite file path, `':memory:'`, or an open `DatabaseSync`.
+ * @param schema  Introspected or hand-written {@link SchemaMetadata}.
+ * @param options Optional pragmas + logging / defaultLimit / warnOnUnlimited.
+ *
+ * @example
+ * ```ts
+ * import { turbineSqlite } from 'turbine-orm/sqlite';
+ * const db = turbineSqlite(':memory:', SCHEMA);
+ * ```
+ */
+export declare function turbineSqlite(target: string | DatabaseSync, schema: SchemaMetadata, options?: TurbineSqliteOptions): TurbineClient;
+export {};

package/dist/cjs/sqlite.js

@@ -462,6 +462,10 @@ exports.sqliteDialect = {
     buildUpsertStatement(input) {
         return (`INSERT INTO ${input.table} (${input.insertColumns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})` +
             ` ON CONFLICT (${input.conflictColumns.join(', ')}) DO UPDATE SET ${input.updateSetClauses.join(', ')}` +
+            // SQLite's upsert takes the same trailing conflict-UPDATE predicate as
+            // Postgres, so `supportsUpsertUpdateWhere` (inherited true) is honest and
+            // global filters restrict the UPDATE branch here too.
+            (input.updateWhere ? ` WHERE ${input.updateWhere}` : '') +
             this.buildReturningClause(input.returning));
     },
     buildInsensitiveLike(column, paramRef) {

package/dist/cjs/typed-sql.d.ts

@@ -0,0 +1,102 @@
+/**
+ * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ *
+ * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
+ * a generic tagged template where the caller supplies the row shape, and the
+ * builder yields a typed result that can be awaited as an array of rows, or
+ * narrowed to a single row (`.one()`) or a single scalar value (`.scalar()`).
+ *
+ * Design goals & guarantees:
+ *
+ *  1. **Compile-time only types.** `T` is supplied by the caller and never
+ *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
+ *     is a convenience for autocomplete and downstream type-checking.
+ *
+ *  2. **Mandatory parameterization.** Only the *static* string segments of the
+ *     template literal ever reach the SQL text. Every interpolated `${value}`
+ *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     impossible to string-concatenate a value into the query through this API.
+ *     This is the whole point of the tagged-template shape: the literal segments
+ *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
+ *     get a runtime value into the query is via `${...}`, which we bind.
+ *
+ *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
+ *     existing `client.raw()` behavior: a typed raw query is a literal escape
+ *     hatch, so the result columns are whatever your `SELECT` names them. Alias
+ *     columns in SQL (`SELECT created_at AS "createdAt"`) if you want camelCase.
+ *
+ * @example
+ * ```ts
+ * // Awaited directly -> rows
+ * const rows = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE org_id = ${orgId}
+ * `;
+ * //    ^? { id: number; name: string }[]
+ *
+ * // .one() -> single row or null
+ * const user = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE id = ${userId}
+ * `.one();
+ * //    ^? { id: number; name: string } | null
+ *
+ * // .scalar() -> first column of first row, or null
+ * const total = await db.sql<{ count: number }>`
+ *   SELECT COUNT(*)::int AS count FROM users WHERE org_id = ${orgId}
+ * `.scalar();
+ * //    ^? number | null
+ * ```
+ */
+import type { PgCompatPool } from './client.js';
+import { type Dialect } from './dialect.js';
+/**
+ * Build a `(sql, params)` pair from a tagged-template invocation.
+ *
+ * Each interpolated value is replaced by a positional placeholder (the active
+ * dialect's `paramPlaceholder`, `$N` for PostgreSQL) and pushed to the params
+ * array in order. The static string segments are the only thing concatenated
+ * into the SQL text. This is the single point that guarantees parameterization
+ * for the entire typed-SQL surface.
+ *
+ * Exported for unit testing the parameterization invariant without a database.
+ */
+export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[], dialect?: Pick<Dialect, 'paramPlaceholder'>): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * A pending typed raw SQL query. Implements the thenable contract, so it can be
+ * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
+ *
+ * The query is executed lazily and exactly once per terminal call (`then`,
+ * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * an escape hatch, not a cached query object, so don't call two terminals on
+ * the same builder expecting a single round-trip; build a fresh template each
+ * time (the common pattern is `await db.sql\`...\`` inline).
+ */
+export declare class TypedSqlQuery<T extends Record<string, unknown>> implements PromiseLike<T[]> {
+    private readonly pool;
+    private readonly sql;
+    private readonly params;
+    private readonly logging;
+    constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean);
+    /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
+    private run;
+    /**
+     * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.
+     */
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Execute and return the first row, or `null` if the query returns no rows.
+     * Use for queries you expect to match at most one row.
+     */
+    one(): Promise<T | null>;
+    /**
+     * Execute and return the first column of the first row, or `null` if there
+     * are no rows. Useful for `SELECT COUNT(*)`, `SELECT EXISTS(...)`, etc.
+     *
+     * The generic `V` defaults to the value type of `T`'s first property, but you
+     * can override it: `db.sql<{ count: number }>\`...\`.scalar<number>()`.
+     */
+    scalar<V = T[keyof T]>(): Promise<V | null>;
+}

package/dist/cli/config.d.ts

@@ -34,10 +34,17 @@ export interface TurbineCliConfig {
     legacyToManyUniques?: boolean;
     /** Directory for migration files (default: ./turbine/migrations) */
     migrationsDir?: string;
-    /** Path to seed file. Defaults are resolved from seed.ts, seed.js, then seed.sql. */
-    seed?: string;
-    /** Path to seed file. Deprecated alias for `seed`. */
+    /**
+     * 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;
     /**
@@ -66,6 +73,12 @@ export type TurbineConfig = TurbineCliConfig;
  * 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`). */
@@ -161,7 +174,8 @@ export interface CliOverrides {
 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 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).
  */
 export declare function resolveSeedFile(config: Pick<TurbineCliConfig, 'seed' | 'seedFile'>, cwd?: string): string | null;
 export declare function configTemplate(connectionString?: string): string;

package/dist/cli/config.js

@@ -24,7 +24,28 @@ export 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.
+ */
+export const DEFAULT_INIT_SEED_FILE = './turbine/seed.ts';
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -139,7 +160,9 @@ export 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,
@@ -148,10 +171,12 @@ export 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).
  */
 export 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 resolve(cwd, explicit);
     for (const candidate of DEFAULT_SEED_CANDIDATES) {
@@ -189,8 +214,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: '${DEFAULT_INIT_SEED_FILE}',
 
   /** Path to schema builder file (for turbine push) */
   schemaFile: './turbine/schema.ts',

package/dist/cli/index.d.ts

@@ -24,6 +24,8 @@
  *   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;
@@ -96,6 +98,43 @@ export interface CliArgs {
     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}. */
@@ -158,6 +197,30 @@ export declare function dotEnvUrlConflictWarning(input: {
     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
@@ -212,6 +275,66 @@ export interface InitPlanFlags {
  * 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;