turbine-orm 0.27.1 → 0.28.1

package/dist/cjs/schema-sql.js

@@ -9,13 +9,39 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.referentialActionToSql = referentialActionToSql;
 exports.schemaToSQL = schemaToSQL;
+exports.buildAddForeignKeyStatement = buildAddForeignKeyStatement;
+exports.diffReferentialAction = diffReferentialAction;
+exports.diffEnumValues = diffEnumValues;
+exports.diffCheckConstraints = diffCheckConstraints;
 exports.schemaDiff = schemaDiff;
 exports.schemaPush = schemaPush;
 exports.schemaToSQLString = schemaToSQLString;
 const pg_1 = __importDefault(require("pg"));
 const dialect_js_1 = require("./dialect.js");
+const errors_js_1 = require("./errors.js");
+const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
+/** Map a {@link ReferentialAction} to its SQL keyword form. */
+function referentialActionToSql(action) {
+    switch (action) {
+        case 'cascade':
+            return 'CASCADE';
+        case 'restrict':
+            return 'RESTRICT';
+        case 'set null':
+            return 'SET NULL';
+        case 'set default':
+            return 'SET DEFAULT';
+        case 'no action':
+            return 'NO ACTION';
+    }
+}
+/** Single-quote-escape an enum label for a `CREATE TYPE ... AS ENUM` literal. */
+function quoteEnumLabel(label) {
+    return `'${label.replace(/'/g, "''")}'`;
+}
 /**
  * Whether a resolved column type is an auto-increment pseudo-type (SERIAL /
  * BIGSERIAL). These carry an implicit sequence default and NOT NULL, and their
@@ -25,6 +51,38 @@ const schema_js_1 = require("./schema.js");
 function isSerialType(type) {
     return type === 'SERIAL' || type === 'BIGSERIAL';
 }
+/** Whether any column in the schema is a pgvector column. */
+function schemaHasVectorColumn(schema) {
+    for (const table of Object.values(schema.tables)) {
+        for (const col of Object.values(table.columns)) {
+            if (col.vectorDimensions != null)
+                return true;
+        }
+    }
+    return false;
+}
+/** Build a `CREATE TYPE "<name>" AS ENUM ('a', 'b')` statement. */
+function generateCreateEnumType(enumName, labels, dialect) {
+    const values = labels.map(quoteEnumLabel).join(', ');
+    return `CREATE TYPE ${dialect.quoteIdentifier(enumName)} AS ENUM (${values});`;
+}
+/**
+ * Resolve the DDL type token for a column: an enum type name, a `vector(n)`
+ * literal, or the dialect's scalar type — with a trailing `[]` for arrays.
+ */
+function resolveDdlType(config, dialect) {
+    let base;
+    if (config.enumName) {
+        base = dialect.quoteIdentifier(config.enumName);
+    }
+    else if (config.vectorDimensions != null) {
+        base = `vector(${config.vectorDimensions})`;
+    }
+    else {
+        base = dialect.buildColumnType({ type: config.type, maxLength: config.maxLength });
+    }
+    return config.isArray ? `${base}[]` : base;
+}
 // ---------------------------------------------------------------------------
 // SQL Generation — SchemaDef → CREATE TABLE statements
 // ---------------------------------------------------------------------------
@@ -36,10 +94,25 @@ function isSerialType(type) {
  */
 function schemaToSQL(schema, options) {
     const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    const extensions = options?.extensions ?? 'auto';
     const statements = [];
     // Topologically sort tables by their foreign key references
     const sorted = topologicalSort(schema);
     const resolveRef = makeRefResolver(schema);
+    // pgvector extension line — only when a vector column exists. Postgres-only:
+    // a dialect that can't do pgvector must not silently emit broken DDL.
+    if (schemaHasVectorColumn(schema)) {
+        if (!dialect.supportsVector) {
+            throw new errors_js_1.UnsupportedFeatureError('vector columns', dialect.name, 'pgvector is a PostgreSQL-only feature.');
+        }
+        statements.push(extensions === 'manual'
+            ? '-- Requires the pgvector extension: run `CREATE EXTENSION IF NOT EXISTS vector;` before applying.'
+            : 'CREATE EXTENSION IF NOT EXISTS vector;');
+    }
+    // CREATE TYPE for every schema-level enum, before the tables that use them.
+    for (const [enumName, labels] of Object.entries(schema.enums ?? {})) {
+        statements.push(generateCreateEnumType(enumName, labels, dialect));
+    }
     // Generate CREATE TABLE statements
     for (const tableName of sorted) {
         const table = schema.tables[tableName];
@@ -156,6 +229,12 @@ function generateCreateTable(table, resolveRef, dialect = dialect_js_1.postgresD
         const cols = compositePk.map((c) => dialect.quoteIdentifier((0, schema_js_1.camelToSnake)(c)));
         columnDefs.push(dialect.buildPrimaryKeyConstraint(cols));
     }
+    // Table-level CHECK constraints (named → CONSTRAINT "name" CHECK (...)).
+    for (const chk of table.checks ?? []) {
+        columnDefs.push(chk.name
+            ? `CONSTRAINT ${dialect.quoteIdentifier(chk.name)} CHECK (${chk.expression})`
+            : `CHECK (${chk.expression})`);
+    }
     return dialect.buildCreateTableStatement({
         table: dialect.quoteIdentifier(tableName),
         definitions: columnDefs,
@@ -194,16 +273,33 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = dialect_js_1
             };
         }
     }
-    return dialect.buildColumnDefinition({
+    // Resolve the DDL type (enum name / vector(n) / scalar, plus [] for arrays).
+    // Passed as a fully-formed `type` token with no maxLength so the dialect
+    // doesn't re-apply VARCHAR(n) on top of it.
+    const ddlType = resolveDdlType(config, dialect);
+    let def = dialect.buildColumnDefinition({
         name: dialect.quoteIdentifier(snakeName),
-        type: config.type,
-        maxLength: config.maxLength,
+        type: ddlType,
+        maxLength: null,
         primaryKey: config.isPrimaryKey,
         unique: config.isUnique,
         notNull,
         defaultValue,
         references,
     });
+    // Referential actions follow the REFERENCES clause (which buildColumnDefinition
+    // emits last). Postgres omits ON DELETE/UPDATE for the default NO ACTION.
+    if (references) {
+        if (config.onDelete)
+            def += ` ON DELETE ${referentialActionToSql(config.onDelete)}`;
+        if (config.onUpdate)
+            def += ` ON UPDATE ${referentialActionToSql(config.onUpdate)}`;
+    }
+    // Column-level CHECK constraint (raw SQL expression, user-authored).
+    if (config.check) {
+        def += ` CHECK (${config.check})`;
+    }
+    return def;
 }
 /**
  * Normalize a default value from the user's schema definition to valid SQL.
@@ -258,6 +354,94 @@ function generateForeignKeyIndexes(table, dialect = dialect_js_1.postgresDialect
     }
     return indexes;
 }
+/**
+ * Build the `ADD CONSTRAINT ... FOREIGN KEY` statement for a FK with the given
+ * referential actions. Default (`no action`) clauses are omitted, matching how
+ * Postgres normalizes them, so re-diffing is stable.
+ */
+function buildAddForeignKeyStatement(table, constraintName, column, targetTable, targetColumn, onDelete, onUpdate, dialect = dialect_js_1.postgresDialect) {
+    const q = (s) => dialect.quoteIdentifier(s);
+    let sql = `ALTER TABLE ${q(table)} ADD CONSTRAINT ${q(constraintName)} FOREIGN KEY (${q(column)}) REFERENCES ${q(targetTable)}(${q(targetColumn)})`;
+    if (onDelete !== 'no action')
+        sql += ` ON DELETE ${referentialActionToSql(onDelete)}`;
+    if (onUpdate !== 'no action')
+        sql += ` ON UPDATE ${referentialActionToSql(onUpdate)}`;
+    return `${sql};`;
+}
+/**
+ * Decide whether a FK's referential actions changed. When they differ, returns
+ * the DROP + ADD CONSTRAINT statements (and their reverse) — Postgres has no
+ * `ALTER CONSTRAINT` for referential actions, so drop-and-recreate is the only
+ * path. Returns null when the actions already match.
+ */
+function diffReferentialAction(table, db, schemaOnDelete, schemaOnUpdate, dialect = dialect_js_1.postgresDialect) {
+    if (db.onDelete === schemaOnDelete && db.onUpdate === schemaOnUpdate)
+        return null;
+    const q = (s) => dialect.quoteIdentifier(s);
+    const drop = `ALTER TABLE ${q(table)} DROP CONSTRAINT ${q(db.constraintName)};`;
+    const add = buildAddForeignKeyStatement(table, db.constraintName, db.column, db.targetTable, db.targetColumn, schemaOnDelete, schemaOnUpdate, dialect);
+    const reverseAdd = buildAddForeignKeyStatement(table, db.constraintName, db.column, db.targetTable, db.targetColumn, db.onDelete, db.onUpdate, dialect);
+    return { statements: [drop, add], reverseStatements: [drop, reverseAdd] };
+}
+/**
+ * Compute append-only enum value changes. Returns `ALTER TYPE ... ADD VALUE`
+ * statements for labels present in the schema but not the DB (in order), plus a
+ * destructive warning for any DB label the schema dropped or any reorder —
+ * Postgres cannot remove or reorder enum values without recreating the type.
+ */
+function diffEnumValues(enumName, schemaLabels, dbLabels, dialect = dialect_js_1.postgresDialect) {
+    const statements = [];
+    const warnings = [];
+    const dbSet = new Set(dbLabels);
+    for (const label of schemaLabels) {
+        if (!dbSet.has(label)) {
+            statements.push(`ALTER TYPE ${dialect.quoteIdentifier(enumName)} ADD VALUE ${quoteEnumLabel(label)};`);
+        }
+    }
+    const schemaSet = new Set(schemaLabels);
+    const removed = dbLabels.filter((l) => !schemaSet.has(l));
+    if (removed.length > 0) {
+        warnings.push(`Enum "${enumName}": labels [${removed.join(', ')}] exist in the database but not the schema. ` +
+            `Postgres cannot remove enum values in place — recreate the type manually if intended.`);
+    }
+    return { statements, warnings };
+}
+/**
+ * Diff a table's CHECK constraints (matched by name). Adds constraints missing
+ * from the DB, drops DB constraints absent from the schema, and drop+adds when a
+ * same-named constraint's expression changed. Expression comparison is a naive
+ * whitespace-insensitive match — semantically-equal-but-different-spelled
+ * expressions may re-emit (documented; harmless drop+add).
+ */
+function diffCheckConstraints(table, schemaChecks, dbChecks, dialect = dialect_js_1.postgresDialect) {
+    const q = (s) => dialect.quoteIdentifier(s);
+    const statements = [];
+    const reverseStatements = [];
+    const dbByName = new Map(dbChecks.map((c) => [c.name, c]));
+    const schemaByName = new Map(schemaChecks.map((c) => [c.name, c]));
+    const norm = (e) => e.replace(/\s+/g, ' ').trim();
+    const addStmt = (c) => `ALTER TABLE ${q(table)} ADD CONSTRAINT ${q(c.name)} CHECK (${c.expression});`;
+    const dropStmt = (name) => `ALTER TABLE ${q(table)} DROP CONSTRAINT ${q(name)};`;
+    for (const sc of schemaChecks) {
+        const existing = dbByName.get(sc.name);
+        if (!existing) {
+            statements.push(addStmt(sc));
+            reverseStatements.push(dropStmt(sc.name));
+        }
+        else if (norm(existing.expression) !== norm(sc.expression)) {
+            // Expression changed → drop + add.
+            statements.push(dropStmt(sc.name), addStmt(sc));
+            reverseStatements.push(dropStmt(sc.name), addStmt(existing));
+        }
+    }
+    for (const dc of dbChecks) {
+        if (!schemaByName.has(dc.name)) {
+            statements.push(dropStmt(dc.name));
+            reverseStatements.push(addStmt(dc));
+        }
+    }
+    return { statements, reverseStatements };
+}
 /**
  * Compare a SchemaDef against a live Postgres database and return the diff.
  *
@@ -312,12 +496,78 @@ async function schemaDiff(schema, connectionString) {
                 dbUniques[row.table_name] = {};
             dbUniques[row.table_name][row.column_name] = row.constraint_name;
         }
+        // Existing enums (typname → ordered labels) for CREATE TYPE / ADD VALUE diff.
+        const enumResult = await client.query(`SELECT t.typname, e.enumlabel
+       FROM pg_type t
+       JOIN pg_enum e ON t.oid = e.enumtypid
+       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+       WHERE n.nspname = 'public'
+       ORDER BY t.typname, e.enumsortorder`);
+        const dbEnums = {};
+        for (const row of enumResult.rows) {
+            if (!dbEnums[row.typname])
+                dbEnums[row.typname] = [];
+            dbEnums[row.typname].push(row.enumlabel);
+        }
+        // Existing single-column FK referential actions, keyed by table → column.
+        const fkResult = await client.query(`SELECT rel.relname AS table_name, con.conname AS constraint_name,
+              att.attname AS column, tgt.relname AS target_table,
+              tatt.attname AS target_column, con.confdeltype, con.confupdtype
+       FROM pg_constraint con
+       JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+       JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
+       JOIN pg_catalog.pg_class tgt ON tgt.oid = con.confrelid
+       JOIN pg_catalog.pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = con.conkey[1]
+       JOIN pg_catalog.pg_attribute tatt ON tatt.attrelid = con.confrelid AND tatt.attnum = con.confkey[1]
+       WHERE con.contype = 'f' AND n.nspname = 'public'
+         AND array_length(con.conkey, 1) = 1`);
+        const dbForeignKeys = {};
+        for (const row of fkResult.rows) {
+            if (!dbForeignKeys[row.table_name])
+                dbForeignKeys[row.table_name] = {};
+            dbForeignKeys[row.table_name][row.column] = {
+                constraintName: row.constraint_name,
+                column: row.column,
+                targetTable: row.target_table,
+                targetColumn: row.target_column,
+                onDelete: (0, introspect_js_1.pgConfActionToReferential)(row.confdeltype),
+                onUpdate: (0, introspect_js_1.pgConfActionToReferential)(row.confupdtype),
+            };
+        }
+        // Existing CHECK constraints (contype='c'), keyed by table.
+        const checkResult = await client.query(`SELECT rel.relname AS table_name, con.conname, pg_get_constraintdef(con.oid) AS definition
+       FROM pg_constraint con
+       JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
+       JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+       WHERE con.contype = 'c' AND n.nspname = 'public'`);
+        const dbChecks = {};
+        for (const row of checkResult.rows) {
+            if (!dbChecks[row.table_name])
+                dbChecks[row.table_name] = [];
+            dbChecks[row.table_name].push({ name: row.conname, expression: (0, introspect_js_1.stripCheckWrapper)(row.definition) });
+        }
         // Build a set of DDL-facing snake_case table names that the schema defines.
         const schemaDdlNames = new Set();
         for (const def of Object.values(schema.tables))
             schemaDdlNames.add(def.name);
-        const result = { create: [], alter: [], drop: [], statements: [], reverseStatements: [] };
+        const result = { create: [], alter: [], drop: [], statements: [], reverseStatements: [], warnings: [] };
         const resolveRef = makeRefResolver(schema);
+        // --- Enums: CREATE TYPE for new enums (before tables), ADD VALUE for grown
+        //     ones, and a warning for any destructive removal/reorder. New CREATE
+        //     TYPEs go first so tables that reference them create cleanly. ---
+        for (const [enumName, labels] of Object.entries(schema.enums ?? {})) {
+            const existing = dbEnums[enumName];
+            if (!existing) {
+                result.statements.push(generateCreateEnumType(enumName, labels, dialect));
+                result.reverseStatements.unshift(`DROP TYPE IF EXISTS ${dialect.quoteIdentifier(enumName)};`);
+            }
+            else {
+                const { statements, warnings } = diffEnumValues(enumName, labels, existing, dialect);
+                result.statements.push(...statements);
+                result.warnings.push(...warnings);
+                // ADD VALUE cannot be reversed (Postgres can't drop enum values).
+            }
+        }
         // Tables to create (in schema but not in DB)
         const sorted = topologicalSort(schema);
         for (const tableKey of sorted) {
@@ -368,7 +618,9 @@ async function schemaDiff(schema, connectionString) {
                 // BIGSERIAL (int8) before 0.24.0 — `push` won't try to shrink them.
                 const expectedUdt = schemaTypeToUdt(config);
                 if (expectedUdt && !isSerialType(config.type) && dbCol.udtName !== expectedUdt) {
-                    const sqlType = config.type === 'VARCHAR' && config.maxLength ? `VARCHAR(${config.maxLength})` : config.type;
+                    // resolveDdlType handles enum names, vector(n), arrays, and VARCHAR(n) —
+                    // config.type alone would emit the internal ENUM/VECTOR sentinels here.
+                    const sqlType = resolveDdlType(config, dialect);
                     const oldSqlType = udtToSqlType(dbCol.udtName, dbCol.maxLength);
                     const sql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${sqlType} USING ${dialect.quoteIdentifier(snakeName)}::${sqlType};`;
                     const reverseSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${oldSqlType} USING ${dialect.quoteIdentifier(snakeName)}::${oldSqlType};`;
@@ -461,6 +713,54 @@ async function schemaDiff(schema, connectionString) {
             if (alterDef.columns.length > 0) {
                 result.alter.push(alterDef);
             }
+            // --- Referential action changes on existing single-column FKs ---
+            // Postgres has no ALTER CONSTRAINT for actions → DROP + ADD CONSTRAINT.
+            const tableFks = dbForeignKeys[tableName] ?? {};
+            for (const [fieldName, config] of Object.entries(tableDef.columns)) {
+                if (!config.referencesTarget)
+                    continue;
+                const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
+                const dbFk = tableFks[snakeName];
+                if (!dbFk)
+                    continue; // FK not present in DB yet (or composite) — skip
+                const change = diffReferentialAction(tableName, dbFk, config.onDelete ?? 'no action', config.onUpdate ?? 'no action', dialect);
+                if (change) {
+                    result.statements.push(...change.statements);
+                    for (const rev of change.reverseStatements.slice().reverse())
+                        result.reverseStatements.unshift(rev);
+                }
+            }
+            // --- Named table-level CHECK constraints ---
+            // Presence-only diffing: ADD checks whose NAME is missing from the DB.
+            // We do NOT auto-drop DB checks absent from the schema (column-level /
+            // inline checks carry auto-generated names the code-first schema never
+            // sees), and we do NOT drop+add on expression mismatch: pg_get_constraintdef
+            // canonicalizes expressions (casts, ANY(ARRAY[...]) rewrites), so authored
+            // text almost never string-matches the stored form — comparing would emit a
+            // spurious full-table-revalidating drop+add on every diff. An apparent
+            // mismatch surfaces as a warning instead; rename the constraint to
+            // intentionally replace its expression. Unnamed schema checks are skipped
+            // (no stable identity to diff on).
+            const namedSchemaChecks = (tableDef.checks ?? [])
+                .filter((c) => typeof c.name === 'string' && c.name.length > 0)
+                .map((c) => ({ name: c.name, expression: c.expression }));
+            const tableDbChecks = dbChecks[tableName] ?? [];
+            const dbCheckByName = new Map(tableDbChecks.map((c) => [c.name, c]));
+            const normExpr = (e) => e.replace(/\s+/g, ' ').trim();
+            for (const sc of namedSchemaChecks) {
+                const existing = dbCheckByName.get(sc.name);
+                const addSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ADD CONSTRAINT ${dialect.quoteIdentifier(sc.name)} CHECK (${sc.expression});`;
+                const dropSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} DROP CONSTRAINT ${dialect.quoteIdentifier(sc.name)};`;
+                if (!existing) {
+                    result.statements.push(addSql);
+                    result.reverseStatements.unshift(dropSql);
+                }
+                else if (normExpr(existing.expression) !== normExpr(sc.expression)) {
+                    result.warnings.push(`check constraint "${sc.name}" on "${tableName}": stored expression differs from the schema text ` +
+                        `(Postgres canonicalizes CHECK expressions, so this is usually cosmetic). ` +
+                        `To intentionally replace it, rename the constraint or drop/re-add it in a manual migration.`);
+                }
+            }
         }
         return result;
     }
@@ -472,6 +772,11 @@ async function schemaDiff(schema, connectionString) {
  * Map a schema column type to its expected PostgreSQL UDT name.
  */
 function schemaTypeToUdt(config) {
+    // Enum columns: udt is the enum type name. Vector columns: udt is `vector`.
+    if (config.enumName)
+        return config.enumName;
+    if (config.vectorDimensions != null)
+        return 'vector';
     const map = {
         SERIAL: 'int4',
         BIGSERIAL: 'int8',
@@ -490,7 +795,11 @@ function schemaTypeToUdt(config) {
         NUMERIC: 'numeric',
         BYTEA: 'bytea',
     };
-    return map[config.type] ?? null;
+    const base = map[config.type] ?? null;
+    // Postgres names an array type `_<element>` (e.g. `_text` for text[]).
+    if (base && config.isArray)
+        return `_${base}`;
+    return base;
 }
 /**
  * Reverse map: PostgreSQL UDT name → SQL type (for generating reverse ALTER TYPE).

package/dist/cjs/seed.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineSeed = defineSeed;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const client_js_1 = require("./client.js");
+const errors_js_1 = require("./errors.js");
+const emptySchema = { tables: {}, enums: {} };
+function entryUrl() {
+    const entry = process.argv[1];
+    if (!entry)
+        return null;
+    try {
+        return (0, node_url_1.pathToFileURL)((0, node_fs_1.realpathSync)(entry)).href;
+    }
+    catch {
+        return (0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(entry)).href;
+    }
+}
+function callerUrl() {
+    const stack = new Error().stack;
+    if (!stack)
+        return null;
+    for (const line of stack.split('\n').slice(2)) {
+        const fileUrl = line.match(/(file:\/\/\/[^):]+):\d+:\d+/)?.[1];
+        if (fileUrl && !fileUrl.endsWith('/seed.ts') && !fileUrl.endsWith('/seed.js'))
+            return fileUrl;
+        const filePath = line.match(/\(?((?:\/|[A-Za-z]:\\)[^):]+):\d+:\d+\)?/)?.[1];
+        if (filePath && !filePath.endsWith('/src/seed.ts') && !filePath.endsWith('\\src\\seed.ts')) {
+            return (0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(filePath)).href;
+        }
+    }
+    return null;
+}
+function isDirectSeedModule() {
+    const entry = entryUrl();
+    const caller = callerUrl();
+    return process.env.NODE_TEST_CONTEXT === undefined && !!entry && !!caller && entry === caller;
+}
+async function runSeed(fn) {
+    const connectionString = process.env.DATABASE_URL;
+    if (!connectionString) {
+        throw new errors_js_1.ConnectionError('[turbine] DATABASE_URL is required to run this seed.');
+    }
+    const db = new client_js_1.TurbineClient({ connectionString }, emptySchema);
+    try {
+        await fn(db);
+    }
+    finally {
+        await db.disconnect();
+    }
+}
+function defineSeed(fn) {
+    const run = () => runSeed(fn);
+    if (isDirectSeedModule()) {
+        queueMicrotask(() => {
+            run().catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(message);
+                process.exitCode = 1;
+            });
+        });
+    }
+    return run;
+}

package/dist/cli/config.d.ts

@@ -17,7 +17,9 @@ export interface TurbineCliConfig {
     exclude?: string[];
     /** Directory for migration files (default: ./turbine/migrations) */
     migrationsDir?: string;
-    /** Path to seed file (default: ./turbine/seed.ts) */
+    /** 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`. */
     seedFile?: string;
     /** Schema builder file path (for push command) */
     schemaFile?: string;
@@ -64,7 +66,7 @@ export interface ResolvedConfig {
     include: string[];
     exclude: string[];
     migrationsDir: string;
-    seedFile: string;
+    seedFile?: string;
     schemaFile: string;
 }
 export interface CliOverrides {
@@ -79,4 +81,9 @@ export interface CliOverrides {
  * 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 the root-level defaults are tried in order.
+ */
+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,6 +24,7 @@ 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'];
 // ---------------------------------------------------------------------------
 // Load config
 // ---------------------------------------------------------------------------
@@ -81,10 +82,25 @@ export function resolveConfig(fileConfig, overrides) {
         include: overrides.include ?? fileConfig.include ?? [],
         exclude: overrides.exclude ?? fileConfig.exclude ?? [],
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
-        seedFile: fileConfig.seedFile ?? './turbine/seed.ts',
+        seedFile: fileConfig.seed ?? fileConfig.seedFile,
         schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
     };
 }
+/**
+ * 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.
+ */
+export function resolveSeedFile(config, cwd = process.cwd()) {
+    const explicit = config.seed ?? config.seedFile;
+    if (explicit)
+        return resolve(cwd, explicit);
+    for (const candidate of DEFAULT_SEED_CANDIDATES) {
+        const filePath = resolve(cwd, candidate);
+        if (existsSync(filePath))
+            return filePath;
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // Config file template (for `turbine init`)
 // ---------------------------------------------------------------------------
@@ -113,8 +129,8 @@ ${urlLine}
   /** Directory for SQL migration files */
   migrationsDir: './turbine/migrations',
 
-  /** Path to seed file */
-  seedFile: './turbine/seed.ts',
+  /** Path to seed file (defaults: ./seed.ts, ./seed.js, ./seed.sql) */
+  seed: './seed.ts',
 
   /** Path to schema builder file (for turbine push) */
   schemaFile: './turbine/schema.ts',

package/dist/cli/index.d.ts

@@ -8,12 +8,14 @@
  *   turbine push                  — Apply schema-builder definitions to database
  *   turbine migrate create <name> — Create a new SQL migration file
  *   turbine migrate up            — Apply pending migrations
+ *   turbine migrate deploy        — Apply pending migrations without prompts
  *   turbine migrate down          — Rollback last migration
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
+ *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
@@ -21,4 +23,53 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-export {};
+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;
+    allowDrift?: boolean;
+    allowEmpty?: boolean;
+    allowDestructive?: boolean;
+    fix?: boolean;
+    zod?: boolean;
+    includeViews?: boolean;
+    port?: number;
+    host?: string;
+    noOpen?: boolean;
+    /** Opt-in to bind Studio/Observe on a non-loopback host. */
+    allowRemote?: boolean;
+}
+export declare function parseArgs(argv?: string[]): CliArgs;
+export declare function buildMigrateDeployOptions(_args: CliArgs): {
+    allowDrift: false;
+    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;