turbine-orm 0.32.0 → 0.32.1

package/dist/cjs/query/builder.js

@@ -56,6 +56,105 @@ const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./utils.js");
 /** Relations already warned about missing FK indexes (once per process, dev only). */
 const unindexedRelationWarned = new Set();
+/**
+ * Dev-mode SQL-cache lockstep cross-check gate.
+ *
+ * The SQL template cache requires three code paths to enumerate where-clause
+ * keys identically: `fingerprintWhere` (builds the cache key),
+ * `buildWhereClause` (builds SQL + `$N` params on a MISS), and
+ * `collectWhereParams` (re-collects params on a HIT without rebuilding). They
+ * are synchronized only by convention, and drift has shipped silent
+ * wrong-results bugs before (permuted where-key order; an orderBy fingerprint
+ * collision). This check catches such drift loudly the moment a cache HIT
+ * happens by rebuilding the SQL + params fresh and comparing them against what
+ * the cache-hit path produced.
+ *
+ * Enabled only when `NODE_ENV !== 'production'` (same convention as the other
+ * dev-only guards in this file) AND `TURBINE_DISABLE_CACHE_CHECK !== '1'`. The
+ * env vars are read inline (not captured once) so tests and perf-sensitive dev
+ * traffic can toggle them per process. In production the check never runs, so
+ * the hot path is unchanged.
+ */
+function cacheCrossCheckEnabled() {
+    return process.env.NODE_ENV !== 'production' && process.env.TURBINE_DISABLE_CACHE_CHECK !== '1';
+}
+/**
+ * Strict structural equality for a single SQL parameter value. Handles the
+ * value shapes Turbine binds: primitives (incl. `NaN` and `bigint`), `null`/
+ * `undefined`, `Date` (by time), `Buffer`/typed arrays (by bytes), arrays
+ * (`in` lists, pgvector arrays), and plain objects (JSON filter payloads).
+ */
+function cacheParamValueEqual(a, b) {
+    if (a === b)
+        return true; // identical ref or equal primitive (covers matching null/undefined)
+    if (a === null || b === null || a === undefined || b === undefined)
+        return false;
+    const ta = typeof a;
+    if (ta !== typeof b)
+        return false;
+    if (ta !== 'object') {
+        // Primitives that failed `===`: only NaN is legitimately "equal" to itself.
+        return typeof a === 'number' && Number.isNaN(a) && Number.isNaN(b);
+    }
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    const aView = ArrayBuffer.isView(a);
+    const bView = ArrayBuffer.isView(b);
+    if (aView || bView) {
+        if (!aView || !bView)
+            return false;
+        const ua = a;
+        const ub = b;
+        if (ua.byteLength !== ub.byteLength)
+            return false;
+        const va = new Uint8Array(ua.buffer, ua.byteOffset, ua.byteLength);
+        const vb = new Uint8Array(ub.buffer, ub.byteOffset, ub.byteLength);
+        for (let i = 0; i < va.length; i++) {
+            if (va[i] !== vb[i])
+                return false;
+        }
+        return true;
+    }
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr || bArr) {
+        if (!aArr || !bArr)
+            return false;
+        const arrA = a;
+        const arrB = b;
+        if (arrA.length !== arrB.length)
+            return false;
+        for (let i = 0; i < arrA.length; i++) {
+            if (!cacheParamValueEqual(arrA[i], arrB[i]))
+                return false;
+        }
+        return true;
+    }
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const k of keysA) {
+        if (!Object.hasOwn(objB, k))
+            return false;
+        if (!cacheParamValueEqual(objA[k], objB[k]))
+            return false;
+    }
+    return true;
+}
+/** Element-wise strict equality of two SQL parameter arrays. */
+function cacheParamsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!cacheParamValueEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 class QueryInterface {
     pool;
@@ -64,6 +163,15 @@ class QueryInterface {
     tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     sqlTemplateCache = new utils_js_1.LRUCache(1000);
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    lastCacheHit = false;
     middlewares;
     defaultLimit;
     warnOnUnlimited;
@@ -382,24 +490,84 @@ class QueryInterface {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     acquireSql(cacheKey, build) {
         if (!this.sqlCacheEnabled) {
-            const sql = build();
+            this.lastCacheHit = false;
+            const sql = build([]);
             this.cacheMisses++;
             return { sql, name: (0, utils_js_1.sqlToPreparedName)(sql) };
         }
         const cached = this.sqlTemplateCache.get(cacheKey);
         if (cached) {
             this.cacheHits++;
+            this.lastCacheHit = true;
             return cached;
         }
-        const sql = build();
+        this.lastCacheHit = false;
+        const sql = build([]);
         const entry = { sql, name: (0, utils_js_1.sqlToPreparedName)(sql) };
         this.sqlTemplateCache.set(cacheKey, entry);
         this.cacheMisses++;
         return entry;
     }
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    crossCheckCache(op, cacheKey, entry, build, collectedParams) {
+        if (!this.lastCacheHit)
+            return;
+        if (!cacheCrossCheckEnabled())
+            return;
+        const freshParams = [];
+        const freshSql = build(freshParams);
+        const sqlOk = freshSql === entry.sql;
+        const paramsOk = cacheParamsEqual(collectedParams, freshParams);
+        if (sqlOk && paramsOk)
+            return;
+        const truncate = (s) => (s.length > 300 ? `${s.slice(0, 300)}… (${s.length} chars total)` : s);
+        const details = [];
+        if (!sqlOk) {
+            details.push(`cached SQL and freshly-built SQL diverge:\n  cached = <${truncate(entry.sql)}>\n  fresh  = <${truncate(freshSql)}>`);
+        }
+        if (!paramsOk) {
+            details.push(`cache-hit params and freshly-built params diverge (collected ${collectedParams.length}, built ${freshParams.length})`);
+        }
+        throw new errors_js_1.ValidationError(`[turbine] SQL cache lockstep violation on ${op} (fingerprint "${cacheKey}"). ` +
+            `This is a Turbine internal invariant violation, please report it at ` +
+            `https://github.com/zvndev/turbine-orm/issues. The fingerprint, SQL-build, and ` +
+            `param-collect paths must enumerate where-clause keys identically.\n${details.join('\n')}`);
+    }
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -598,19 +766,22 @@ class QueryInterface {
             });
         // Simple path: plain equality, no operators/null/OR
         if (!args.with && isSimpleWhere) {
-            const entry = this.acquireSql(ck, () => {
+            const buildSql = (freshParams) => {
                 const qt = this.q(this.table);
-                const tempParams = whereKeys.map((k) => whereObj[k]);
-                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = ${this.p(i + 1)}`);
+                const whereClauses = whereKeys.map((k, i) => {
+                    freshParams.push(whereObj[k]);
+                    return `${this.toSqlColumn(k)} = ${this.p(i + 1)}`;
+                });
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
-                void tempParams; // params are positional, SQL is value-invariant
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params (same order as build)
             for (const k of whereKeys) {
                 params.push(whereObj[k]);
             }
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -624,16 +795,17 @@ class QueryInterface {
         }
         // General path (with operators, null, OR, with clause)
         if (!args.with) {
-            const entry = this.acquireSql(ck, () => {
-                const freshParams = [];
+            const buildSql = (freshParams) => {
                 const clause = this.buildWhereClause(whereObj, freshParams);
                 const whereSql = clause ? ` WHERE ${clause}` : '';
                 const qt = this.q(this.table);
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params
             this.collectWhereParams(whereObj, params);
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -650,16 +822,17 @@ class QueryInterface {
         //   1. buildWhere pushes where params
         //   2. buildSelectWithRelations pushes relation params to same array
         // We must preserve this exact order.
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
             return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
         this.collectWithParams(args.with, params);
+        this.crossCheckCache('findUnique', ck, entry, buildSql, params);
         const parseWith = this.makeNestedParser(args.with);
         return {
             sql: entry.sql,
@@ -724,7 +897,7 @@ class QueryInterface {
         if (this.warnedTables.has(this.table))
             return;
         this.warnedTables.add(this.table);
-        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit: this will fetch every row. ` +
             'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
     /**
@@ -781,15 +954,24 @@ class QueryInterface {
                 .sort()
                 .join(',')
             : '';
-        const distinctFp = args?.distinct ? args.distinct.slice().sort().join(',') : '';
+        // distinct must fingerprint in USER order: the SQL emits `DISTINCT ON` in
+        // the caller's column order, so a permuted array rebuilds different SQL and
+        // must not collapse onto the same cache entry (would trip the cross-check).
+        const distinctFp = args?.distinct ? args.distinct.join(',') : '';
         const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
-        const limitFp = effectiveLimit !== undefined ? '1' : '0';
-        const offsetFp = args?.offset !== undefined ? '1' : '0';
+        // On engines that inline the literal LIMIT/OFFSET into the SQL text
+        // (dialect.inlineLimitOffset, MySQL), the value is part of the SQL, not the
+        // params, so it MUST be part of the fingerprint or two different limits share
+        // one cached statement (silent wrong row counts). Parameterized engines
+        // (PG/SQLite/SQL Server, whose buildLimitOffset uses placeholders) keep the
+        // presence-only fingerprint so the cache is not needlessly fragmented.
+        const inlinePagination = this.dialect.inlineLimitOffset === true;
+        const limitFp = effectiveLimit !== undefined ? (inlinePagination ? `v${effectiveLimit}` : '1') : '0';
+        const offsetFp = args?.offset !== undefined ? (inlinePagination ? `v${args.offset}` : '1') : '0';
         const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            // Fresh build — generates SQL and populates freshParams
-            const freshParams = [];
+        const buildSql = (freshParams) => {
+            // Fresh build: generates SQL and populates freshParams
             const { sql: freshWhereSql } = hasWhere
                 ? (() => {
                     const clause = this.buildWhereClause(whereObj, freshParams);
@@ -869,7 +1051,8 @@ class QueryInterface {
             }
             sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
             return sql;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order:
         // 1. WHERE params (includes the AND-merged global filter, if any)
         if (hasWhere) {
@@ -900,6 +1083,7 @@ class QueryInterface {
         if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(args.offset));
         }
+        this.crossCheckCache('findMany', ck, entry, buildSql, params);
         // Build the row parser once (positional shapes are computed here, not per row).
         const parseWith = args?.with ? this.makeNestedParser(args.with) : null;
         return {
@@ -1225,8 +1409,7 @@ class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = lock ? null : `u:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const buildSql = () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             if (lock) {
@@ -1250,13 +1433,15 @@ class QueryInterface {
         };
         let sql;
         let preparedName;
+        let cacheEntry;
         if (ck) {
-            const entry = this.acquireSql(ck, buildSql);
-            sql = entry.sql;
-            preparedName = entry.name;
+            cacheEntry = this.acquireSql(ck, buildSql);
+            sql = cacheEntry.sql;
+            preparedName = cacheEntry.name;
         }
         else {
-            sql = buildSql();
+            // optimisticLock path: value-variant version check → uncacheable, no cross-check.
+            sql = buildSql([]);
         }
         // Collect params: SET first, then WHERE, then version check (same order as fresh build)
         this.collectSetParams(dataObj, params);
@@ -1264,6 +1449,9 @@ class QueryInterface {
         if (lock) {
             params.push(lock.expected);
         }
+        if (ck && cacheEntry) {
+            this.crossCheckCache('update', ck, cacheEntry, buildSql, params);
+        }
         return {
             sql,
             params,
@@ -1395,8 +1583,7 @@ class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `d:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
@@ -1404,8 +1591,10 @@ class QueryInterface {
             return this.dialect.buildDeleteStatement
                 ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
                 : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('delete', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1533,16 +1722,17 @@ class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `um:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
             return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectSetParams(dataObj, params);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('updateMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1569,13 +1759,14 @@ class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `dm:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `DELETE FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('deleteMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1602,15 +1793,16 @@ class QueryInterface {
         const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const ck = `cnt:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = hasWhere ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         if (hasWhere) {
             this.collectWhereParams(whereObj, params);
         }
+        this.crossCheckCache('count', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -2939,9 +3131,11 @@ class QueryInterface {
                 const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, targetRels?.[k]?.to)}`);
                 subParts.push(`o=${oEntries.join(',')}`);
             }
-            // limit presence
+            // limit presence, but on inline-pagination engines (MySQL) the literal
+            // value is baked into the subquery SQL, so fingerprint the value there or
+            // `{limit:3}` and `{limit:5}` would share one cached statement.
             if (opts.limit !== undefined) {
-                subParts.push('l=1');
+                subParts.push(this.dialect.inlineLimitOffset ? `l=${opts.limit}` : 'l=1');
             }
             // nested with (recurse)
             if (opts.with) {

package/dist/cli/config.d.ts

@@ -49,9 +49,61 @@ export type TurbineConfig = TurbineCliConfig;
  * silently matches zero tables. Used by `turbine generate` to fail loudly.
  */
 export declare function looksLikeSchemaFilePath(schema: string): boolean;
+/** 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.
+ * 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>;
 /**

package/dist/cli/config.js

@@ -25,15 +25,66 @@ export function looksLikeSchemaFilePath(schema) {
 // ---------------------------------------------------------------------------
 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
-// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
- * Attempt to load a turbine config file from the current directory.
- * Returns the config if found, or an empty object.
+ * True when `value` is a pure ESM/CJS-interop wrapper: an object whose only
+ * meaningful export is `default` (the `__esModule` marker is ignored). No
+ * Turbine config field is named `default`, so a real config never matches.
  */
-export async function loadConfig(cwd) {
+function isPureDefaultWrapper(value) {
+    const keys = Object.keys(value).filter((k) => k !== '__esModule');
+    return keys.length === 1 && keys[0] === 'default';
+}
+/**
+ * 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 function unwrapModuleDefault(mod) {
+    // Step 1: prefer `default` at the top level (mirrors `mod.default ?? mod`).
+    let value = isPlainObject(mod) && mod.default != null ? mod.default : mod;
+    // Step 2: peel off any further pure interop wrappers, bounded to avoid a
+    // pathological self-referential object spinning forever.
+    for (let depth = 0; depth < 10 && isPlainObject(value) && isPureDefaultWrapper(value); depth++) {
+        value = value.default;
+    }
+    return value;
+}
+/**
+ * {@link unwrapModuleDefault} specialized for config files: a non-object export
+ * collapses to `{}` so downstream resolution falls through to env vars/flags.
+ */
+export function unwrapConfigModule(mod) {
+    const value = unwrapModuleDefault(mod);
+    return isPlainObject(value) ? value : {};
+}
+/**
+ * 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 async function loadConfigResult(cwd) {
     const dir = cwd ?? process.cwd();
+    let loadError;
     for (const filename of CONFIG_FILES) {
         const filePath = join(dir, filename);
         if (!existsSync(filePath))
@@ -41,21 +92,27 @@ export async function loadConfig(cwd) {
         try {
             const absPath = resolve(filePath);
             const fileUrl = pathToFileURL(absPath).href;
-            // For .ts files, we need to rely on Node's --experimental-strip-types
-            // or the tsx loader. Dynamic import handles .js/.mjs natively.
+            // For .ts files, we rely on the tsx loader being registered by the CLI
+            // before this runs. Dynamic import handles .js/.mjs natively.
             const mod = await import(fileUrl);
-            const config = mod.default ?? mod;
-            return config;
+            return { config: unwrapConfigModule(mod) };
         }
         catch (err) {
-            // If importing a .ts file fails, try the next one
-            if (filename.endsWith('.ts') || filename.endsWith('.mts')) {
-                continue;
-            }
-            throw new Error(`Failed to load config from ${filename}: ${err instanceof Error ? err.message : String(err)}`);
+            // Remember the first real load failure but keep trying lower-priority
+            // candidates (e.g. a working .js next to a broken .ts).
+            if (!loadError)
+                loadError = { filename, error: err };
         }
     }
-    return {};
+    return loadError ? { config: {}, loadError } : { config: {} };
+}
+/**
+ * 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 async function loadConfig(cwd) {
+    return (await loadConfigResult(cwd)).config;
 }
 /**
  * Find the config file path (for display purposes).