turbine-orm 0.40.1 → 0.41.0

package/dist/cjs/query/relations.js

@@ -89,10 +89,9 @@ const schema_js_1 = require("../schema.js");
 const batched_loader_js_1 = require("./batched-loader.js");
 const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./utils.js");
+const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
 const writesMod = __importStar(require("./writes.js"));
-/** Relations already warned about missing FK indexes (once per process, dev only). */
-const unindexedRelationWarned = new Set();
 /**
  * Resolve select/omit options into a list of snake_case column names.
  * Returns null if neither is provided (meaning all columns).
@@ -1397,10 +1396,13 @@ function buildRelationSubquery(qi, relDef, spec, params, parentRef, aliasCounter
     // instead of letting the slowness look like an ORM problem.
     if (process.env.NODE_ENV !== 'production') {
         const warnKey = `${relDef.from}.${relDef.name}`;
-        if (!unindexedRelationWarned.has(warnKey)) {
+        // Compute the (potentially costly) probe only for a key not yet warned, and
+        // claim the key through the process-wide registry ONLY when we actually warn,
+        // so a dual-package / HMR-reevaluated second module copy cannot re-warn the
+        // same relation, and indexed relations never consume the dedupe cap.
+        if (!(0, warn_registry_js_1.hasWarnedOnce)(warn_registry_js_1.WARN_NS.unindexedRelation, warnKey)) {
             const miss = (0, index_advisor_js_1.missingIndexForRelation)(qi.schema, relDef);
-            if (miss) {
-                unindexedRelationWarned.add(warnKey);
+            if (miss && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.unindexedRelation, warnKey)) {
                 console.warn(`[turbine] Relation "${relDef.name}" on "${relDef.from}" probes ` +
                     `"${miss.table}"(${miss.columns.join(', ')}) which has no covering index — ` +
                     `each parent row scans the full table. Fix: ${miss.createSql}; ` +

package/dist/cjs/query/warn-registry.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * turbine-orm, process-wide once-per-key dev-warning dedupe registry.
+ *
+ * Several dev-only diagnostics (the missing-FK-index warning in relations.ts,
+ * the `relationLoadStrategy: 'auto'` engagement note, the deep-`with` warning)
+ * must fire AT MOST ONCE per distinct key for the life of the process. A
+ * module-level `Set` almost does this, but it is defeated by the two field
+ * realities this package actually ships into:
+ *
+ *   1. **Dual-package loading.** Turbine ships ESM (`dist/`) AND CJS
+ *      (`dist/cjs/`). A mixed `require`/`import` graph (a compat layer, a tool
+ *      that loads both) instantiates the module twice, giving two independent
+ *      `Set`s that each warn once, a double warning.
+ *   2. **Bundler / HMR re-evaluation.** Under Next.js dev the module is
+ *      re-evaluated per recompile, resetting a module-level `Set` and making the
+ *      warning appear to fire every time.
+ *
+ * Hanging the registry off `globalThis` under a `Symbol.for(...)` key gives every
+ * module copy in the realm ONE shared registry (cross-copy identity without
+ * polluting enumerable globals), and `globalThis` survives webpack recompiles
+ * because the realm persists, which is exactly what fixes the every-recompile
+ * firing in dev servers. Per-process firing (worker threads, separate processes)
+ * is acceptable and stays.
+ *
+ * Bounded: each namespace stops recording AND stops warning once it reaches
+ * {@link WARN_ONCE_CAP} distinct keys. A schema with 500+ distinct unindexed
+ * relations has long since gotten the message, and the cap prevents unbounded
+ * growth if metadata objects are churned dynamically. (Clearing on overflow
+ * would be wrong, it would re-warn.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WARN_NS = exports.WARN_ONCE_CAP = void 0;
+exports.shouldWarnOnce = shouldWarnOnce;
+exports.hasWarnedOnce = hasWarnedOnce;
+exports.resetWarnOnce = resetWarnOnce;
+const REGISTRY_KEY = Symbol.for('turbine.warnOnce.registry');
+/** Per-namespace cap on distinct recorded keys (see module doc). */
+exports.WARN_ONCE_CAP = 500;
+function registry() {
+    const g = globalThis;
+    let reg = g[REGISTRY_KEY];
+    if (!reg) {
+        reg = Object.create(null);
+        g[REGISTRY_KEY] = reg;
+    }
+    return reg;
+}
+function namespaceSet(ns) {
+    const reg = registry();
+    let set = reg[ns];
+    if (!set) {
+        set = new Set();
+        reg[ns] = set;
+    }
+    return set;
+}
+/**
+ * Record `(ns, key)` and report whether THIS call is the first to see it
+ * process-wide. Returns `true` exactly once per distinct key (the caller should
+ * emit its warning then), `false` on every subsequent call for that key, and
+ * `false` once the namespace has recorded {@link WARN_ONCE_CAP} distinct keys
+ * (bounded growth; the warning simply stops rather than re-firing).
+ */
+function shouldWarnOnce(ns, key) {
+    const set = namespaceSet(ns);
+    if (set.has(key))
+        return false;
+    if (set.size >= exports.WARN_ONCE_CAP)
+        return false;
+    set.add(key);
+    return true;
+}
+/** True when `(ns, key)` has already been recorded (no mutation). */
+function hasWarnedOnce(ns, key) {
+    return namespaceSet(ns).has(key);
+}
+/**
+ * @internal Test-only: clear one namespace, or the whole registry when `ns` is
+ * omitted. Lets a single test process verify that a warning fires once and then
+ * re-verify after a reset without spawning a new process.
+ */
+function resetWarnOnce(ns) {
+    if (ns === undefined) {
+        globalThis[REGISTRY_KEY] = undefined;
+        return;
+    }
+    registry()[ns] = undefined;
+}
+/** Namespace constants so callers never typo a bare string. */
+exports.WARN_NS = {
+    /** Missing-FK-index runtime warning (relations.ts `buildRelationSubquery`). */
+    unindexedRelation: 'unindexedRelation',
+    /** `relationLoadStrategy: 'auto'` batched-fallback engagement note. */
+    autoStrategy: 'autoStrategy',
+    /** Deep-`with` (depth > 5) advisory (builder.ts `findMany`). */
+    deepWith: 'deepWith',
+};

package/dist/cjs/query/writes.js

@@ -66,6 +66,7 @@ exports.fingerprintSet = fingerprintSet;
 exports.collectSetParams = collectSetParams;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
+const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
 const whereMod = __importStar(require("./where.js"));
 /**
@@ -187,7 +188,10 @@ function buildUpdate(qi, args) {
     qi.currentSkip = args.skipGlobalFilters;
     const dataObj = args.data;
     assertNoGeneratedColumns(qi, dataObj, 'update');
-    const userWhere = args.where;
+    // Prisma compound-unique selector (e.g. `{ orgId_userId: { orgId, userId } }`)
+    // → the column conjunction, before the empty-`where` guard so the expanded
+    // members count as a real predicate.
+    const userWhere = (0, compound_unique_js_1.expandCompoundUniqueWhere)(qi.tableMeta, args.where);
     const lock = args.optimisticLock;
     // The empty-`where` guard checks the USER predicate only — a global filter
     // must never turn an unguarded mass update into an allowed one.
@@ -293,9 +297,11 @@ function buildUpdate(qi, args) {
 function buildDelete(qi, args) {
     assertWritable(qi, 'delete');
     qi.currentSkip = args.skipGlobalFilters;
+    // Prisma compound-unique selector → the column conjunction (before the guard).
+    const userWhere = (0, compound_unique_js_1.expandCompoundUniqueWhere)(qi.tableMeta, args.where);
     // Guard the USER predicate (a global filter must not satisfy the guard).
-    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
-    const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
+    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', args.allowFullTableScan);
+    const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
     const params = [];
@@ -346,6 +352,8 @@ function buildUpsert(qi, args) {
     assertNoGeneratedColumns(qi, args.create, 'upsert');
     assertNoGeneratedColumns(qi, args.update, 'upsert');
     qi.currentSkip = args.skipGlobalFilters;
+    // Prisma compound-unique selector on the conflict target → its member columns.
+    const upsertWhere = (0, compound_unique_js_1.expandCompoundUniqueWhere)(qi.tableMeta, args.where);
     // Build the INSERT part from create data
     const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
     const columns = createEntries.map(([k]) => qi.toSqlColumn(k));
@@ -353,7 +361,7 @@ function buildUpsert(qi, args) {
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
     const placeholders = createEntries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     // The conflict target comes from `where` keys — must be unique/PK columns
-    const conflictKeys = Object.keys(args.where).filter((k) => args.where[k] !== undefined);
+    const conflictKeys = Object.keys(upsertWhere).filter((k) => upsertWhere[k] !== undefined);
     const conflictColumns = conflictKeys.map((k) => qi.toSqlColumn(k));
     // Build the UPDATE SET part
     const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
@@ -404,7 +412,7 @@ function buildUpsert(qi, args) {
         reselect: qi.dialect.resultStrategy === 'reselect'
             ? async (exec) => {
                 await exec(sql, params);
-                const sel = buildReselectByWhere(qi, (whereMod.mergeGlobalFilter(qi, args.where) ?? {}));
+                const sel = buildReselectByWhere(qi, (whereMod.mergeGlobalFilter(qi, upsertWhere) ?? {}));
                 return exec(sel.sql, sel.params);
             }
             : undefined,

package/dist/cjs/schema.js

@@ -14,6 +14,7 @@ exports.snakeToCamel = snakeToCamel;
 exports.camelToSnake = camelToSnake;
 exports.snakeToPascal = snakeToPascal;
 exports.singularize = singularize;
+exports.withDbFieldNames = withDbFieldNames;
 // ---------------------------------------------------------------------------
 // Helpers for composite key handling
 // ---------------------------------------------------------------------------
@@ -156,3 +157,49 @@ function singularize(s) {
         return s.slice(0, -1);
     return s;
 }
+// ---------------------------------------------------------------------------
+// keepColumnNames transform (F4)
+// ---------------------------------------------------------------------------
+/**
+ * Return a copy of `schema` in which every column's TypeScript **field** name is
+ * the raw database column name (snake_case) instead of the camelCased default,
+ * i.e. `user_id` stays `user_id` rather than becoming `userId`.
+ *
+ * This is a PURE, generate-time transform with ZERO runtime changes: it only
+ * rewrites `column.field` and rebuilds each table's `columnMap` /
+ * `reverseColumnMap` as IDENTITY maps (`user_id → user_id`). Because every
+ * runtime surface resolves column names through those maps (`toColumn`,
+ * `parseRow`, relation `json_build_object` keys, batched-loader stitching,
+ * positional decoding, aggregate/groupBy naming), the generated client returns
+ * rows keyed by DB column names and accepts DB column names in
+ * `where`/`orderBy`/`select` with no code path aware of the difference.
+ *
+ * Deliberately left untouched (the flag is literally about column names):
+ *   - `name`, `allColumns`, `dateColumns`, `dialectTypes`, `pgTypes`,
+ *     `primaryKey`, `uniqueColumns`, `indexes`, `checks`, `isView` (all already
+ *     keyed by snake_case column names);
+ *   - `relations` (relation PROPERTY names are synthetic introspection names
+ *     with no DB column equivalent, and `foreignKey`/`referenceKey`/`through`
+ *     already hold DB column names);
+ *   - entity type names, table accessors, and `enums`.
+ *
+ * Every non-PII field of each {@link ColumnMetadata} (`pii`, `pgType`,
+ * `dialectType`, `nullable`, …) is preserved. Exported from the package root so
+ * runtime-introspection and serverless users can apply the same identity mapping
+ * to a schema they build at runtime, e.g. `turbineHttp(pool,
+ * withDbFieldNames(schema))`.
+ */
+function withDbFieldNames(schema) {
+    const tables = {};
+    for (const [tableKey, table] of Object.entries(schema.tables)) {
+        const columns = table.columns.map((col) => ({ ...col, field: col.name }));
+        const columnMap = {};
+        const reverseColumnMap = {};
+        for (const col of columns) {
+            columnMap[col.name] = col.name;
+            reverseColumnMap[col.name] = col.name;
+        }
+        tables[tableKey] = { ...table, columns, columnMap, reverseColumnMap };
+    }
+    return { ...schema, tables };
+}

package/dist/cjs/sqlite.js

@@ -558,15 +558,10 @@ function pragma(db, sql) {
  */
 function introspectSqliteDatabase(db, options = {}) {
     // ----- Tables (skip SQLite internal + the migration tracking table) -----
-    let tableNames = pragma(db, "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").map((r) => r.name);
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    const candidateTables = pragma(db, "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").map((r) => r.name);
+    // include / exclude + default bookkeeping-table exclusions (F12), shared with
+    // every other introspector via applyTableFilters.
+    const tableNames = (0, introspect_js_1.applyTableFilters)(candidateTables, options);
     const tableSet = new Set(tableNames);
     const columnsByTable = new Map();
     const pkByTable = new Map();

package/dist/cli/config.d.ts

@@ -15,6 +15,23 @@ export interface TurbineCliConfig {
     include?: string[];
     /** Tables to exclude */
     exclude?: string[];
+    /**
+     * Extension for the generated `index.ts` sibling imports (F3):
+     * `'js'` (`./types.js`), `'none'` (`./types`), or `'auto'` (default:
+     * tsconfig-detected, falling back to `'js'`).
+     */
+    importExtension?: 'js' | 'none' | 'auto';
+    /**
+     * Keep raw database column names as generated field names (snake_case)
+     * instead of camelCase (F4). Opt-in; default `false`.
+     */
+    keepColumnNames?: boolean;
+    /**
+     * Opt OUT of the unique-FK → one-to-one (`hasOne`) introspection flip (F2),
+     * emitting the pre-0.41 `hasMany` shape for unique-covered child relations.
+     * Default `false` (detection on).
+     */
+    legacyToManyUniques?: boolean;
     /** Directory for migration files (default: ./turbine/migrations) */
     migrationsDir?: string;
     /** Path to seed file. Defaults are resolved from seed.ts, seed.js, then seed.sql. */
@@ -120,6 +137,12 @@ export interface ResolvedConfig {
     migrationsDir: string;
     seedFile?: string;
     schemaFile: string;
+    /** Resolved generator import-extension mode (F3). */
+    importExtension: 'js' | 'none' | 'auto';
+    /** Resolved keep-column-names generator flag (F4). */
+    keepColumnNames: boolean;
+    /** Resolved opt-out of the unique-FK → hasOne introspection flip (F2). */
+    legacyToManyUniques: boolean;
 }
 export interface CliOverrides {
     url?: string;
@@ -127,6 +150,9 @@ export interface CliOverrides {
     schema?: string;
     include?: string[];
     exclude?: string[];
+    importExtension?: 'js' | 'none' | 'auto';
+    keepColumnNames?: boolean;
+    legacyToManyUniques?: boolean;
 }
 /**
  * Merge config file values with CLI overrides and env vars.

package/dist/cli/config.js

@@ -141,6 +141,9 @@ export function resolveConfig(fileConfig, overrides) {
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
         seedFile: fileConfig.seed ?? fileConfig.seedFile,
         schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
+        importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
+        keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
+        legacyToManyUniques: overrides.legacyToManyUniques ?? fileConfig.legacyToManyUniques ?? false,
     };
 }
 /**

package/dist/cli/index.d.ts

@@ -5,6 +5,7 @@
  * Commands:
  *   turbine init                  — Initialize a Turbine project
  *   turbine generate | pull       — Introspect database and generate TypeScript types
+ *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
  *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
  *   turbine migrate up            — Apply pending migrations
@@ -60,6 +61,12 @@ export interface CliArgs {
     includeViews?: boolean;
     /** Omit the `Generated at:` header line for reproducible (diff-stable) output. */
     noTimestamp?: boolean;
+    /** `generate --import-ext <js|none|auto>`: sibling-import extension mode (F3). */
+    importExtension?: 'js' | 'none' | 'auto';
+    /** `generate --keep-column-names`: keep raw DB column names as field names (F4). */
+    keepColumnNames?: boolean;
+    /** `generate --legacy-to-many-uniques`: opt out of the unique-FK → hasOne flip (F2). */
+    legacyToManyUniques?: boolean;
     port?: number;
     host?: string;
     noOpen?: boolean;
@@ -71,6 +78,10 @@ export interface CliArgs {
     showPii?: boolean;
     /** Launch Studio with a seeded in-memory sample database (`studio --demo`). */
     demo?: boolean;
+    /** `migrate-from-prisma --allow-partial`: exit 0 even when some items are UNRESOLVED. */
+    allowPartial?: boolean;
+    /** `migrate-from-prisma --no-db`: parse-only, skip database resolution. */
+    noDb?: boolean;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
 /** Where a resolved `DATABASE_URL` came from, after the `.env` load. */

package/dist/cli/index.js

@@ -5,6 +5,7 @@
  * Commands:
  *   turbine init                  — Initialize a Turbine project
  *   turbine generate | pull       — Introspect database and generate TypeScript types
+ *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
  *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
  *   turbine migrate up            — Apply pending migrations
@@ -27,7 +28,7 @@ import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realp
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { generate } from '../generate.js';
+import { generate, generatePrismaMap } from '../generate.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
@@ -37,6 +38,9 @@ import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from
 import { runMcpServer } from './mcp.js';
 import { buildDiffMigrationBody, collectUpDestructive, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
 import { startObserve } from './observe.js';
+import { formatPrismaReport, summaryLines } from './prisma-report.js';
+import { DEFAULT_EXCLUDED_TABLES, resolvePrismaSchema } from './prisma-resolve.js';
+import { PrismaParseError, parsePrismaSchema } from './prisma-schema.js';
 import { startStudio } from './studio.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
 export function parseArgs(argv = process.argv.slice(2)) {
@@ -126,6 +130,21 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--no-timestamp':
                 result.noTimestamp = true;
                 break;
+            case '--import-ext':
+            case '--import-extension':
+                if (next !== 'js' && next !== 'none' && next !== 'auto') {
+                    console.error(`--import-ext requires one of: js, none, auto (got ${next ?? '(nothing)'})`);
+                    process.exit(1);
+                }
+                result.importExtension = next;
+                i++;
+                break;
+            case '--keep-column-names':
+                result.keepColumnNames = true;
+                break;
+            case '--legacy-to-many-uniques':
+                result.legacyToManyUniques = true;
+                break;
             case '--allow-destructive':
                 result.allowDestructive = true;
                 break;
@@ -172,6 +191,12 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--demo':
                 result.demo = true;
                 break;
+            case '--allow-partial':
+                result.allowPartial = true;
+                break;
+            case '--no-db':
+                result.noDb = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -887,17 +912,25 @@ async function cmdGenerate(args, config) {
     newline();
     // Introspect
     const spinner = new Spinner('Introspecting database schema').start();
+    const skippedInternalTables = [];
     const schema = await introspect({
         connectionString: url,
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
         exclude: config.exclude.length ? config.exclude : undefined,
         includeViews: args.includeViews,
+        legacyToManyUniques: config.legacyToManyUniques,
+        onDefaultTableExclusion: (tables) => skippedInternalTables.push(...tables),
     });
     const tableNames = Object.keys(schema.tables);
     const totalColumns = Object.values(schema.tables).reduce((sum, t) => sum + t.columns.length, 0);
     const totalRelations = Object.values(schema.tables).reduce((sum, t) => sum + Object.keys(t.relations).length, 0);
     spinner.succeed(`Found ${bold(String(tableNames.length))} tables, ${bold(String(totalColumns))} columns, ${bold(String(totalRelations))} relations`);
+    // F12: make the default bookkeeping-table exclusions discoverable rather than
+    // silent. `include` re-adds any of them byte-for-byte.
+    for (const t of skippedInternalTables) {
+        console.log(`    ${dim(`${symbols.teeEnd} skipped internal table ${t} (add it to include to keep it)`)}`);
+    }
     // Guard: zero tables means the generated client would be empty. That is almost
     // always a misconfiguration (wrong `schema`, an include/exclude that filtered
     // everything, or a database with no tables yet) rather than intent. Fail loudly
@@ -937,6 +970,8 @@ async function cmdGenerate(args, config) {
         connectionString: url,
         zod: args.zod,
         noTimestamp: args.noTimestamp,
+        importExtension: config.importExtension,
+        keepColumnNames: config.keepColumnNames,
     });
     genSpinner.succeed(`Generated ${bold(String(result.files.length))} files in ${elapsed(startTime)}`);
     // List files
@@ -955,6 +990,112 @@ async function cmdGenerate(args, config) {
     newline();
 }
 // ---------------------------------------------------------------------------
+// migrate-from-prisma
+// ---------------------------------------------------------------------------
+/**
+ * `turbine migrate-from-prisma --schema prisma/schema.prisma` parses a Prisma
+ * schema, resolve its models/fields/relations/compound-uniques against the live
+ * database (unless `--no-db`), and emit (a) a Markdown resolution report and
+ * (b) a typed `prisma-map.ts` name map next to the generated client.
+ *
+ * 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.
+ */
+async function cmdMigrateFromPrisma(args, config) {
+    banner();
+    // `--schema` is the Prisma schema file path in this command.
+    const prismaPath = resolve(args.schema ?? 'prisma/schema.prisma');
+    if (!existsSync(prismaPath)) {
+        error(`Prisma schema file not found: ${cyan(prismaPath)}`);
+        newline();
+        console.log(`  ${dim('Point at it with')} ${cyan('--schema <path/to/schema.prisma>')} ${dim('(default: prisma/schema.prisma).')}`);
+        newline();
+        process.exit(1);
+    }
+    // Parse (fatal only on a construct we must understand).
+    const source = readFileSync(prismaPath, 'utf-8');
+    let ast;
+    try {
+        ast = parsePrismaSchema(source);
+    }
+    catch (err) {
+        if (err instanceof PrismaParseError) {
+            newline();
+            error(`Could not parse ${cyan(prismaPath)}`);
+            console.log(`  ${red(err.message)}`);
+            newline();
+            process.exit(1);
+        }
+        throw err;
+    }
+    label('Prisma schema', prismaPath);
+    label('Models', String(ast.models.length));
+    label('Enums', String(ast.enums.length));
+    // Resolve against the live database, unless --no-db (parse-only).
+    let schemaMeta = null;
+    if (args.noDb) {
+        info('Parse-only mode (--no-db): names will not be resolved.');
+    }
+    else {
+        const url = requireUrl(config);
+        label('Database', redactUrl(url));
+        const spinner = new Spinner('Introspecting database schema').start();
+        schemaMeta = await introspect({
+            connectionString: url,
+            // The Postgres NAMESPACE is fixed to `public` here (`--schema` names the
+            // Prisma file, not the namespace).
+            schema: 'public',
+            // Prisma `view` models resolve against introspected views.
+            includeViews: true,
+            // Inherit the shared bookkeeping-table exclusions (Turbine + Prisma).
+            exclude: [...new Set([...config.exclude, ...DEFAULT_EXCLUDED_TABLES])],
+        });
+        spinner.succeed(`Introspected ${bold(String(Object.keys(schemaMeta.tables).length))} tables`);
+    }
+    newline();
+    const result = resolvePrismaSchema(ast, schemaMeta);
+    // Console summary.
+    header('Resolution');
+    for (const line of summaryLines(result)) {
+        const marker = line.includes('[UNRESOLVED]') ? red(symbols.cross) : green(symbols.check);
+        console.log(`  ${marker} ${line}`);
+    }
+    newline();
+    // Write outputs into the generate outDir.
+    const outDir = resolve(config.out);
+    const rel = relative(process.cwd(), outDir);
+    if (rel.startsWith('..') || resolve(rel) !== outDir) {
+        error(`Output directory must be within the project root. Got: ${config.out}`);
+        newline();
+        process.exit(1);
+    }
+    mkdirSync(outDir, { recursive: true });
+    const reportPath = join(outDir, 'prisma-migration-report.md');
+    writeFileSync(reportPath, formatPrismaReport(result, { schemaPath: prismaPath, noTimestamp: args.noTimestamp }), 'utf-8');
+    console.log(`  ${dim(symbols.teeEnd)} ${cyan(reportPath)} ${dim('(report)')}`);
+    if (!args.noDb) {
+        const mapPath = join(outDir, 'prisma-map.ts');
+        writeFileSync(mapPath, generatePrismaMap(result.map, { noTimestamp: args.noTimestamp }), 'utf-8');
+        console.log(`  ${dim(symbols.teeEnd)} ${cyan(mapPath)} ${dim('(typed name map)')}`);
+    }
+    newline();
+    // Exit non-zero when anything is UNRESOLVED, unless --allow-partial.
+    if (result.hasUnresolved && !args.allowPartial) {
+        warn('Some items could not be resolved (see the report). Re-run with --allow-partial to accept a partial map.');
+        newline();
+        process.exit(1);
+    }
+    if (args.noDb) {
+        info(`Parse-only report written. Re-run without ${cyan('--no-db')} against your database to resolve names.`);
+    }
+    else {
+        success('Prisma name map generated.');
+    }
+    newline();
+}
+// ---------------------------------------------------------------------------
 // Command: push
 // ---------------------------------------------------------------------------
 async function cmdPush(args, config) {
@@ -2121,6 +2262,7 @@ function showSubcommandHelp(command) {
         init: showInitHelp,
         generate: showGenerateHelp,
         pull: showGenerateHelp,
+        'migrate-from-prisma': showMigrateFromPrismaHelp,
         push: showPushHelp,
         migrate: showMigrateHelp,
         migration: showMigrateHelp,
@@ -2182,9 +2324,39 @@ function showGenerateHelp() {
     console.log(`    ${cyan('--zod')}                 Also emit ${cyan('zod.ts')} validation schemas ${dim('(needs the zod dep)')}`);
     console.log(`    ${cyan('--include-views')}       Include views + materialized views as read-only entities`);
     console.log(`    ${cyan('--no-timestamp')}        Omit the ${dim('Generated at:')} header line ${dim('(reproducible, diff-stable output)')}`);
+    console.log(`    ${cyan('--import-ext')} ${dim('<mode>')}    Sibling-import extension: ${cyan('js')} / ${cyan('none')} / ${cyan('auto')} ${dim('(default: auto)')}`);
+    console.log(`    ${cyan('--keep-column-names')}   Keep raw DB column names as field names ${dim('(snake_case, not camelCase)')}`);
+    console.log(`    ${cyan('--legacy-to-many-uniques')} Emit ${cyan('hasMany')} for unique-FK children ${dim('(pre-0.41 shape; default flips to hasOne)')}`);
     console.log(`    ${cyan('--allow-empty')}         Generate even when introspection matches 0 tables`);
     newline();
 }
+function showMigrateFromPrismaHelp() {
+    banner();
+    console.log(`  ${bold('turbine migrate-from-prisma')} - Map a Prisma schema onto a Turbine client`);
+    newline();
+    console.log(`  ${bold('Usage:')}`);
+    console.log(`    npx turbine migrate-from-prisma ${dim('--schema prisma/schema.prisma [options]')}`);
+    newline();
+    console.log(`  Parses your ${cyan('schema.prisma')}, resolves models/fields/relations/compound`);
+    console.log(`  uniques against the live database, and writes into the output directory:`);
+    console.log(`    ${dim('•')} ${cyan('prisma-migration-report.md')} - per-model resolution + unresolved items`);
+    console.log(`    ${dim('•')} ${cyan('prisma-map.ts')}              - typed PRISMA_MAP name map`);
+    newline();
+    console.log(`  ${dim('Note:')} here ${cyan('--schema')} names the Prisma FILE (not the Postgres namespace).`);
+    newline();
+    console.log(`  ${bold('Options:')}`);
+    console.log(`    ${cyan('--schema')} ${dim('<file>')}     Path to schema.prisma ${dim('(default: prisma/schema.prisma)')}`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}     Postgres connection string ${dim('(unless --no-db)')}`);
+    console.log(`    ${cyan('--out, -o')} ${dim('<dir>')}     Output directory ${dim('(default: ./generated/turbine)')}`);
+    console.log(`    ${cyan('--no-db')}             Parse-only: write the report without resolving names`);
+    console.log(`    ${cyan('--allow-partial')}     Exit 0 even when some items are UNRESOLVED`);
+    console.log(`    ${cyan('--no-timestamp')}      Omit the ${dim('Generated:')} lines ${dim('(reproducible output)')}`);
+    newline();
+    console.log(`  ${bold('Examples:')}`);
+    console.log(`    ${dim('$')} DATABASE_URL=postgres://... npx turbine migrate-from-prisma --schema prisma/schema.prisma`);
+    console.log(`    ${dim('$')} npx turbine migrate-from-prisma --schema prisma/schema.prisma --no-db`);
+    newline();
+}
 function showPushHelp() {
     banner();
     console.log(`  ${bold('turbine push')} — Apply schema-builder definitions to database`);
@@ -2297,6 +2469,7 @@ function showHelp() {
     console.log(`  ${bold('Commands:')}`);
     console.log(`    ${cyan('init')}               Initialize a Turbine project`);
     console.log(`    ${cyan('generate')} ${dim('| pull')}    Introspect database ${symbols.arrow} generate types`);
+    console.log(`    ${cyan('migrate-from-prisma')} Map a schema.prisma onto Turbine ${dim('(report + typed name map)')}`);
     console.log(`    ${cyan('push')}               Apply schema definitions to database`);
     console.log(`    ${cyan('migrate')} ${dim('<sub>')}      SQL migration management`);
     console.log(`      ${dim('create <name>')}    Create a new migration file`);
@@ -2457,6 +2630,9 @@ async function main() {
         schema: args.schema,
         include: args.include,
         exclude: args.exclude,
+        importExtension: args.importExtension,
+        keepColumnNames: args.keepColumnNames,
+        legacyToManyUniques: args.legacyToManyUniques,
     };
     const config = resolveConfig(fileConfig, overrides);
     // Warn (don't change precedence) when an .env-sourced DATABASE_URL is silently
@@ -2483,6 +2659,9 @@ async function main() {
             case 'pull':
                 await cmdGenerate(args, config);
                 break;
+            case 'migrate-from-prisma':
+                await cmdMigrateFromPrisma(args, config);
+                break;
             case 'push':
                 await cmdPush(args, config);
                 break;

package/dist/cli/prisma-report.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Render a {@link ResolutionResult} into the `prisma-migration-report.md`
+ * artifact and a short console summary. Pure leaf - string in, string out.
+ */
+import type { ResolutionResult } from './prisma-resolve.js';
+export interface ReportOptions {
+    /** Path the Prisma schema was read from (for the report header). */
+    schemaPath?: string;
+    /** Omit the volatile `Generated: <ISO>` line for reproducible output. */
+    noTimestamp?: boolean;
+}
+/**
+ * Build the full Markdown migration report.
+ */
+export declare function formatPrismaReport(result: ResolutionResult, options?: ReportOptions): string;
+/** Flat list of unresolved item descriptions across the whole result. */
+export declare function collectUnresolved(result: ResolutionResult): string[];
+/** A one-line-per-model console summary for the CLI. */
+export declare function summaryLines(result: ResolutionResult): string[];