turbine-orm 0.19.0 → 0.19.2

package/README.md

@@ -12,8 +12,8 @@ npm install turbine-orm
 
 Prisma ships a 1.6 MB WASM query engine. Drizzle ships zero runtime but no Studio, no typed errors, no migration checksums. Turbine ships **one dependency (`pg`) and no engine binary**, and bundles six things no other TS ORM has together:
 
-1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~30 KB gzipped (~109 KB minified); the edge entry to ~21 KB gzipped. Prisma's WASM query engine alone is 1.6 MB.
-2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and a statement-stacking guard. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
+1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~31 kB brotli (~109 KB minified); the edge entry to ~22 kB brotli. Prisma's WASM query engine alone is 1.6 MB.
+2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
 3. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
 4. **SQL-first migrations with drift detection.** Write real SQL. SHA-256 checksums catch modified migration files. `pg_try_advisory_lock()` prevents concurrent runs. Each migration in its own transaction. No shadow database, no magic DSL.
 5. **Edge-native — one import swap.** `turbineHttp(pool, schema)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
@@ -343,6 +343,8 @@ const db = turbine({
 
 ### Middleware
 
+Middleware wraps every query. It runs **after SQL generation**, so it can observe what's about to execute (`params.model`, `params.action`, `params.args`), measure timing, and transform the result returned by `next()` — but it cannot change the query itself.
+
 ```typescript
 // Query timing
 db.$use(async (params, next) => {
@@ -352,15 +354,33 @@ db.$use(async (params, next) => {
   return result;
 });
 
-// Soft-delete filter
+// Result transformation — redact a field on the way out
 db.$use(async (params, next) => {
-  if (params.action === 'findMany' || params.action === 'findUnique') {
-    params.args.where = { ...params.args.where, deletedAt: null };
+  const result = await next(params);
+  if (params.model === 'users' && Array.isArray(result)) {
+    for (const row of result as { email?: string }[]) row.email = '[redacted]';
   }
-  return next(params);
+  return result;
 });
 ```
 
+> **Warning:** `params.args` is a read-only snapshot — mutating it does not change the executed SQL. The query is fully built and parameterized before middleware runs.
+
+Because middleware can't rewrite queries, cross-cutting filters like **soft deletes** belong in the query itself — either explicitly or via a small scoped helper:
+
+```typescript
+import type { WhereClause } from 'turbine-orm';
+
+// Explicit filter
+const users = await db.users.findMany({ where: { deletedAt: null } });
+
+// Scoped helper that always applies the filter
+const activeUsers = (where: WhereClause<User> = {}) =>
+  db.users.findMany({ where: { ...where, deletedAt: null } });
+
+const rows = await activeUsers({ orgId: 1 });
+```
+
 ### Error handling
 
 Turbine throws typed errors you can catch programmatically:
@@ -557,6 +577,7 @@ Commands:
   seed                         Run seed file
   status                       Show database schema summary
   studio                       Launch local read-only Studio web UI
+  observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
 Options:
   --url, -u <url>       Postgres connection string
@@ -614,7 +635,7 @@ npx turbine migrate status
 
 ## Studio
 
-The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, no way around the transaction guard.
+The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, and since v0.19 **no raw-SQL surface at all**: every query is composed visually in the ORM and compiled by the same validated query builder your application uses.
 
 ```bash
 DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
@@ -624,19 +645,55 @@ npx turbine studio --port 5173 --host 127.0.0.1 --no-open
 
 **Features**
 
-- **Data / Schema / SQL / Builder tabs.** Browse rows, inspect tables and relations, run ad-hoc `SELECT`s, or compose queries visually with a live TypeScript preview.
-- **Saved queries.** Named SQL snippets persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
+- **Query / Data / Schema tabs.** Compose queries visually, browse rows, and inspect tables and relations.
+- **ORM-native query composer.** The Query tab builds a real `findMany` — drill into relations (`with`) to any depth, pick fields (`select`/`omit`), add filters (`where`), `orderBy`, and `limit` at every level — with a live TypeScript preview of the exact call to copy into your codebase.
+- **Saved queries.** Named builder queries persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
 - **Cmd+K command palette.** Jump to any table, tab, or saved query in one keystroke.
 - **Full-text search across rows.** The Data tab supports substring search across every text column of the current table.
-- **Visual query composer.** The Builder tab lets you click together `where` / `orderBy` / `with` / `limit` clauses and renders the matching `db.table.findMany(...)` TypeScript in real time — copy it into your codebase.
 
 **Security posture (read-only by design)**
 
+- **No SQL input surface.** There is nothing to inject into — builder requests are validated identifier-by-identifier against the introspected schema, and every value is bound as a `$N` parameter.
 - **Loopback by default** (`127.0.0.1`) with a loud warning if you bind to a non-loopback address.
 - **Per-process auth token** — 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
-- **Every query runs inside `BEGIN READ ONLY` + `SET LOCAL statement_timeout = '30s'`.** Writes are physically impossible at the transaction level.
-- **SELECT/WITH-only SQL parser** strips comments and rejects non-trailing semicolons, blocking statement-stacking attacks.
-- **Security headers on every response** — `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`.
+- **Every query runs inside `BEGIN READ ONLY`** with a 30s transaction-local statement timeout (parameterized `set_config`). Writes are physically impossible at the transaction level.
+- **Security headers on every response** — CSP, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` — plus per-session rate limiting and cross-origin refusal.
+
+## Observability
+
+Built-in query metrics with zero new dependencies. `$observe` buffers per-query timings in memory and flushes **per-minute aggregates** — count, avg, p50, p95, p99, and error count per `model:action` — to a `_turbine_metrics` table in a **separate database**, over its own 1-connection pool so metrics writes never contend with your application pool.
+
+```typescript
+const handle = await db.$observe({
+  connectionString: process.env.TURBINE_OBSERVE_URL!, // metrics DB (not your app DB)
+  flushIntervalMs: 60_000, // default: 60s
+  retentionDays: 30,       // default: 30 — older buckets are pruned on flush
+});
+
+// Later, to flush remaining metrics and close the metrics pool
+await handle.stop();
+```
+
+`$observe` creates the `_turbine_metrics` table if it doesn't exist. Flushes are fire-and-forget (`INSERT ... ON CONFLICT` additive merge) and never throw into your application. If the `TURBINE_OBSERVE_URL` environment variable is set, the client starts observing automatically on construction — no code needed.
+
+For your own instrumentation, subscribe to query events with `$on('query')` — each event carries `sql`, `params`, `duration` (ms), `model`, `action`, `rows`, `timestamp`, and `error` (if the query failed):
+
+```typescript
+db.$on('query', (e) => {
+  if (e.duration > 200) {
+    console.warn(`slow query: ${e.model}.${e.action} (${e.duration.toFixed(1)}ms, ${e.rows} rows)`);
+  }
+});
+```
+
+View the collected metrics in a local dashboard:
+
+```bash
+TURBINE_OBSERVE_URL=postgres://... npx turbine observe
+# Flags: --port (default 4984), --host (default 127.0.0.1), --no-open
+```
+
+Same security model as Studio: loopback binding by default, per-process random auth token in an `HttpOnly` cookie, CSP headers, and read-only access to the metrics table.
 
 ## Serverless / Edge
 
@@ -761,11 +818,11 @@ Turbine maps Postgres types to TypeScript:
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + 1.6 MB WASM engine | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
-| **Main bundle (gzip)** | ~30 KB | dominated by 1.6 MB WASM | ~7 KB core | small |
+| **Main bundle (brotli)** | ~31 kB | dominated by 1.6 MB WASM | ~7 KB core | small |
 | **Studio** | Read-only, 192-bit auth | Full CRUD, cloud-hosted | Paid tier | None |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None |
-| **Edge runtime** | One import swap, ~21 KB gzip | 1.6 MB WASM adapter | Native | Native |
+| **Edge runtime** | One import swap, ~22 kB brotli | 1.6 MB WASM adapter | Native | Native |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None |
 | **Nested relations** | 1 query, deep type inference | 1 query, shallow inference | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
@@ -818,6 +875,17 @@ Turbine is focused and opinionated. Here's what it doesn't do:
 - PostgreSQL >= 14
 - Works with both ESM (`import`) and CommonJS (`require`)
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the test strategy, and the PR checklist. The unit suite runs without a database:
+
+```bash
+npm install
+npm run test:unit
+```
+
+Integration tests need a PostgreSQL instance via `DATABASE_URL` (see CONTRIBUTING.md for a one-command seeded setup).
+
 ## License
 
 MIT

package/dist/adapters/index.d.ts

@@ -55,8 +55,9 @@ export interface DatabaseAdapter {
     introspectionOverrides?: Partial<IntrospectionOverrides>;
     /**
      * Generate the SQL to set a statement timeout within a transaction.
-     * PostgreSQL uses `SET LOCAL statement_timeout = $1`.
-     * CockroachDB uses `SET transaction_timeout = $1` (v23.1+).
+     * PostgreSQL uses `SELECT set_config('statement_timeout', $1, true)`.
+     * CockroachDB uses `SELECT set_config('transaction_timeout', $1, true)` (v23.1+).
+     * (`SET LOCAL ... = $1` is a syntax error — SET takes no bind params.)
      *
      * @param seconds — timeout in seconds
      * @returns an object with the parameterized SQL and its bound values

package/dist/cjs/cli/index.js

@@ -167,6 +167,15 @@ function failMissingTsLoader(filePath, reason) {
         console.log(`  ${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
         console.log(`  ${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
     }
+    else if (reason === 'failed') {
+        // tsx IS installed but registering its loader threw. Report the real
+        // cause — telling the user to install tsx here would be a misdiagnosis.
+        console.log(`  ${(0, ui_js_1.dim)('tsx is installed, but registering its TypeScript loader failed:')}`);
+        (0, ui_js_1.newline)();
+        console.log(`    ${(0, loader_js_1.getTsLoaderError)() ?? '(unknown error)'}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Try upgrading tsx:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx@latest')}${(0, ui_js_1.dim)(', or rename your file to')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+    }
     else {
         console.log(`  ${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
         (0, ui_js_1.newline)();
@@ -210,7 +219,7 @@ async function loadSchemaFile(schemaFile) {
     // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
     if ((0, loader_js_1.needsTsLoader)(absPath)) {
         const status = await (0, loader_js_1.registerTsLoader)();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(schemaFile, status);
         }
     }
@@ -346,7 +355,7 @@ export default defineSchema({
   //   id: { type: 'serial', primaryKey: true },
   //   email: { type: 'text', notNull: true, unique: true },
   //   name: { type: 'text', notNull: true },
-  //   created_at: { type: 'timestamptz', default: 'NOW()' },
+  //   created_at: { type: 'timestamp', default: 'NOW()' },
   // },
 });
 `, 'utf-8');
@@ -409,6 +418,9 @@ export default defineSchema({
             console.log(`     ${(0, ui_js_1.dim)('or create a')} ${(0, ui_js_1.cyan)('.env')} ${(0, ui_js_1.dim)('file with')} ${(0, ui_js_1.cyan)('DATABASE_URL=postgres://...')}`);
         }
         console.log(`  ${(0, ui_js_1.dim)('2.')} Run ${(0, ui_js_1.cyan)('npx turbine generate')} to introspect your DB`);
+        if (!(0, loader_js_1.canResolveTsx)()) {
+            console.log(`     ${(0, ui_js_1.dim)('Note: the TypeScript config requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('—')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        }
     }
     else {
         console.log(`  ${(0, ui_js_1.dim)('1.')} Import the generated client:`);
@@ -1152,13 +1164,15 @@ function showMigrateHelp() {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create only)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}    Number of migrations to apply/rollback`);
-    console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
-    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}      Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}      Show detailed output`);
+    console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}         Show SQL without executing`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}     Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}     Show detailed output`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_users_table`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_email_index --auto`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate up`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate down --step 2`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate status`);
@@ -1203,16 +1217,17 @@ function showHelp() {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Commands:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('init')}               Initialize a Turbine project`);
-    console.log(`    ${(0, ui_js_1.cyan)('generate')} ${(0, ui_js_1.dim)('| pull')}   Introspect database ${ui_js_1.symbols.arrow} generate types`);
+    console.log(`    ${(0, ui_js_1.cyan)('generate')} ${(0, ui_js_1.dim)('| pull')}    Introspect database ${ui_js_1.symbols.arrow} generate types`);
     console.log(`    ${(0, ui_js_1.cyan)('push')}               Apply schema definitions to database`);
-    console.log(`    ${(0, ui_js_1.cyan)('migrate')} ${(0, ui_js_1.dim)('<sub>')}     SQL migration management`);
-    console.log(`      ${(0, ui_js_1.dim)('create <name>')}     Create a new migration file`);
+    console.log(`    ${(0, ui_js_1.cyan)('migrate')} ${(0, ui_js_1.dim)('<sub>')}      SQL migration management`);
+    console.log(`      ${(0, ui_js_1.dim)('create <name>')}    Create a new migration file`);
     console.log(`      ${(0, ui_js_1.dim)('up')}               Apply pending migrations`);
     console.log(`      ${(0, ui_js_1.dim)('down')}             Rollback last migration`);
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
-    console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}     Show schema summary`);
+    console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
+    console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
@@ -1224,8 +1239,13 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}        Show detailed output`);
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}          Overwrite existing files`);
     (0, ui_js_1.newline)();
-    console.log(`  ${(0, ui_js_1.bold)('Studio options:')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983)')}`);
+    console.log(`  ${(0, ui_js_1.bold)('Migrate options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--auto')}               Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}       Number of migrations to apply/rollback`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}        Bypass checksum validation on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Studio / observe options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983 studio, 4984 observe)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}        Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--no-open')}            Don't auto-open the browser`);
     (0, ui_js_1.newline)();
@@ -1249,7 +1269,17 @@ function showVersion() {
     // Using process.argv[1] instead of import.meta.url so the same code compiles
     // cleanly for both the ESM and CJS builds.
     try {
-        let dir = (0, node_path_1.dirname)(process.argv[1] ?? '');
+        // Resolve symlinks first: `npx turbine` runs via node_modules/.bin/turbine,
+        // a symlink whose dirname would walk the CONSUMER's tree and never find
+        // turbine-orm's package.json (printing no version number at all).
+        let entry = process.argv[1] ?? '';
+        try {
+            entry = (0, node_fs_1.realpathSync)(entry);
+        }
+        catch {
+            // keep the raw path if realpath fails (e.g. deleted cwd)
+        }
+        let dir = (0, node_path_1.dirname)(entry);
         for (let i = 0; i < 6; i++) {
             const candidate = (0, node_path_1.resolve)(dir, 'package.json');
             if ((0, node_fs_1.existsSync)(candidate)) {
@@ -1297,7 +1327,7 @@ async function main() {
     const configPath = (0, config_js_1.findConfigFile)();
     if ((0, loader_js_1.needsTsLoader)(configPath)) {
         const status = await (0, loader_js_1.registerTsLoader)();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
         }
     }

package/dist/cjs/cli/loader.js

@@ -9,9 +9,18 @@
  *
  * Strategy:
  *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
- *      probe whether `tsx/esm` is resolvable from the user's CWD.
- *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
- *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *      probe whether `tsx` is resolvable from the user's CWD.
+ *   2. Prefer tsx's supported programmatic API, `tsx/esm/api`'s `register()`.
+ *      Calling Node's `module.register('tsx/esm', ...)` directly throws
+ *      "tsx must be loaded with --import instead of --loader" on every Node
+ *      version that has `module.register()` (>= 20.6) — tsx's hook file
+ *      guards against being loaded that way. The `tsx/esm/api` entry point
+ *      is the documented path and works everywhere `module.register()` does.
+ *   3. Fall back to `module.register('tsx/esm', ...)` only for very old tsx
+ *      versions (< 4.0) that predate `tsx/esm/api`.
+ *   4. If tsx isn't installed, or registration genuinely fails, surface an
+ *      actionable error — including the REAL underlying error message, never
+ *      a misdiagnosed "tsx is not installed".
  *
  * `tsx` is intentionally NOT a runtime dependency — many projects already
  * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
@@ -52,6 +61,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.needsTsLoader = needsTsLoader;
 exports.canResolveTsx = canResolveTsx;
+exports.getTsLoaderError = getTsLoaderError;
 exports.registerTsLoader = registerTsLoader;
 exports._resetTsLoaderStateForTests = _resetTsLoaderStateForTests;
 const node_module_1 = require("node:module");
@@ -89,6 +99,14 @@ function canResolveTsx(resolver) {
     }
 }
 let tsLoaderState = null;
+let tsLoaderError = null;
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+function getTsLoaderError() {
+    return tsLoaderError;
+}
 /**
  * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
  * work. Safe to call multiple times — internal flag prevents double registration.
@@ -96,17 +114,51 @@ let tsLoaderState = null;
  * Returns:
  *   - 'registered'  loader was successfully registered this call
  *   - 'already'     a loader was previously registered (idempotent)
- *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6) and tsx has
+ *                   no programmatic API to fall back to
  *   - 'missing'     `tsx` is not installed in the user's project
+ *   - 'failed'      tsx IS installed but registration threw — see
+ *                   {@link getTsLoaderError} for the underlying message
  */
 async function registerTsLoader() {
     if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
         return 'already';
     }
+    const userRequire = (0, node_module_1.createRequire)(`${process.cwd()}/`);
+    // Preferred: tsx's supported programmatic API (tsx >= 4.0).
+    let apiPath = null;
+    try {
+        apiPath = userRequire.resolve('tsx/esm/api');
+    }
+    catch {
+        apiPath = null;
+    }
+    if (apiPath) {
+        try {
+            const api = (await Promise.resolve(`${(0, node_url_1.pathToFileURL)(apiPath).href}`).then(s => __importStar(require(s))));
+            if (typeof api.register !== 'function') {
+                throw new Error(`tsx/esm/api resolved at ${apiPath} but exports no register() function`);
+            }
+            api.register();
+            tsLoaderState = 'registered';
+            tsLoaderError = null;
+            return 'registered';
+        }
+        catch (err) {
+            tsLoaderState = 'failed';
+            tsLoaderError = err instanceof Error ? err.message : String(err);
+            return 'failed';
+        }
+    }
+    // tsx/esm/api not resolvable — is tsx installed at all?
     if (!canResolveTsx()) {
         tsLoaderState = 'missing';
         return 'missing';
     }
+    // Legacy fallback for tsx < 4.0 (no tsx/esm/api): Node's module.register.
+    // On tsx >= 4.19 this path throws ("tsx must be loaded with --import
+    // instead of --loader") — but those versions all ship tsx/esm/api, so we
+    // only land here for genuinely old installs.
     try {
         const mod = await Promise.resolve().then(() => __importStar(require('node:module')));
         const register = mod.register;
@@ -116,14 +168,17 @@ async function registerTsLoader() {
         }
         register('tsx/esm', (0, node_url_1.pathToFileURL)(`${process.cwd()}/`));
         tsLoaderState = 'registered';
+        tsLoaderError = null;
         return 'registered';
     }
-    catch {
-        tsLoaderState = 'missing';
-        return 'missing';
+    catch (err) {
+        tsLoaderState = 'failed';
+        tsLoaderError = err instanceof Error ? err.message : String(err);
+        return 'failed';
     }
 }
 /** Reset the loader state — used by unit tests only. */
 function _resetTsLoaderStateForTests() {
     tsLoaderState = null;
+    tsLoaderError = null;
 }