turbine-orm 0.75.0 → 0.76.0

package/README.md

@@ -64,7 +64,7 @@ npx turbine generate              # introspect the DB, emit a typed client
 ```
 
 ```typescript
-import { turbine } from './generated/turbine';
+import { turbine } from './generated/turbine/index.js';
 
 const db = turbine({ connectionString: process.env.DATABASE_URL });
 
@@ -79,6 +79,8 @@ await db.disconnect();
 
 `generate` writes three files to `./generated/turbine/`: entity types, runtime schema metadata, and a typed client with a `turbine()` factory. The factory is generated (it is typed against your schema), so import it from your output directory, not from `'turbine-orm'`. ESM and CommonJS both work.
 
+The `/index.js` on that import is required under `moduleResolution: NodeNext` (a relative import needs an explicit extension, and there is no directory-index resolution). Under a bundler (`moduleResolution: bundler`, the Next.js and Vite default) `'./generated/turbine'` works too. `turbine generate` prints the spelling that matches your `tsconfig.json`.
+
 Full walkthrough, including the code-first `defineSchema` path for an empty database: [turbineorm.dev/quickstart](https://turbineorm.dev/quickstart).
 
 ## Queries
@@ -267,12 +269,12 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **85 kB brotli** (edge entry under **68 kB**) with `pg` external, enforced by `size-limit` in CI; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **87 kB brotli** (edge entry under **69 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { SCHEMA } from './generated/turbine/metadata';
+import { SCHEMA } from './generated/turbine/metadata.js';
 
 const db = turbineHttp(new Pool({ connectionString: process.env.DATABASE_URL }), SCHEMA);
 const users = await db.table('users').findMany({ with: { posts: true }, limit: 10 });
@@ -299,6 +301,45 @@ const db = turbineSqlite(':memory:', SCHEMA);
 const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
 ```
 
+That snippet assumes a Postgres database somewhere, because `SCHEMA` comes from
+`turbine generate` and `generate` reads a live Postgres catalog. **If SQLite is
+your only database, describe the schema in code instead.** `defineSchema` is the
+same declaration `push` and `migrate` consume, and two pure functions turn it
+into the DDL and the runtime metadata, with no database involved:
+
+```typescript
+import { defineSchema, schemaDefToMetadata, schemaToSQL } from 'turbine-orm';
+import { sqliteDialect, turbineSqlite } from 'turbine-orm/sqlite';
+
+const schema = defineSchema({
+  users: {
+    id: { type: 'serial', primaryKey: true },
+    email: { type: 'text', notNull: true, unique: true },
+  },
+  posts: {
+    id: { type: 'serial', primaryKey: true },
+    // "table.column" — this is what makes `with: { posts: true }` work below.
+    userId: { type: 'integer', notNull: true, references: 'users.id' },
+    title: { type: 'text', notNull: true },
+  },
+});
+
+const db = turbineSqlite(':memory:', schemaDefToMetadata(schema));
+for (const stmt of schemaToSQL(schema, { dialect: sqliteDialect })) {
+  await db.raw([stmt] as never);
+}
+
+const users = await db
+  .table('users')
+  .findMany({ with: { posts: true }, orderBy: { id: 'asc' }, limit: 10 });
+```
+
+`schemaToSQL` emits SQLite DDL (including the foreign key and its index) and
+`schemaDefToMetadata` derives the `posts` / `users` relations from the same
+`references:`, so nested `with` works without a code-generation step. The
+accessors are `db.table('users')` rather than `db.users`: the typed property
+accessors are what `turbine generate` emits, and this path skips it.
+
 Single-statement nested `with` works on all four SQL engines (`json_agg`, `json_group_array`, `JSON_ARRAYAGG`, `FOR JSON PATH`). Postgres-only features (pgvector, LISTEN/NOTIFY, RLS `sessionContext`, true cursor streaming) throw a typed `UnsupportedFeatureError` (`TURBINE_E017`) elsewhere instead of degrading silently. The `turbine generate` / `migrate` CLI is Postgres-only. Full capability matrix and per-engine notes: [turbineorm.dev/engines](https://turbineorm.dev/engines).
 
 **Migrating from Prisma?** `turbine migrate-from-prisma` reads your `schema.prisma` and emits a typed mapping; `turbine-orm/prisma-compat` then wraps a TurbineClient in a `PrismaClient`-shaped surface, so `prisma.user.findMany({ include })` keeps working while you port. [Guide](https://turbineorm.dev/migrate-from-prisma). Coming from Drizzle: [the mapping](https://turbineorm.dev/migrate-from-drizzle).
@@ -315,11 +356,11 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 |
-| **Main bundle (brotli)** | under 85 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
-| **Studio** | Read-only by default | Full CRUD, cloud-hosted | Free; hosted Gateway paid | None |
+| **Main bundle (brotli)** | under 87 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | 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, under 68 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, under 69 kB brotli (CI-enforced) | Driver adapter + WASM compiler | 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 per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
@@ -328,7 +369,7 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 | **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual |
 | **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
 
-Competitor columns last checked August 2026, against Prisma 7 and Drizzle 0.45. Features marked Preview may change; bundle sizes move release to release. The longer version of this argument, including what is not a reason to switch: [turbineorm.dev/why-turbine](https://turbineorm.dev/why-turbine).
+Competitor columns last checked 2026-08-22, against Prisma 7 and Drizzle 0.45 (the current `latest`; 1.0 is at rc.4). Cells that make a claim about someone else's pricing or licensing carry a link to that vendor's own page, because those are the cells that go stale silently: this table said Drizzle's Gateway was paid, which was true of the old Drizzle Studio subscription and is not true of Gateway, and nothing in the repo would have caught it. Features marked Preview may change; bundle sizes move release to release. The longer version of this argument, including what is not a reason to switch: [turbineorm.dev/why-turbine](https://turbineorm.dev/why-turbine).
 
 ## Limitations
 

package/dist/cjs/cli/compile-query.d.ts

@@ -67,8 +67,28 @@ export declare const SEALED_POOL: PgCompatPool;
  * rule: they return values, and this tool returns no values at all.
  */
 export declare const COLUMN_NAMING_ARG_KEYS: readonly string[];
-/** Does this args object carry a key that names a column? */
-export declare function carriesColumnNamingArg(args: Record<string, unknown>): boolean;
+/**
+ * Does this args object carry a key that names a column, AT ANY DEPTH?
+ *
+ * The depth is the whole point and it was missing until 0.76.0. This is the
+ * fail-closed test for the case where the PII tag file could not be read, so
+ * "no column-naming arg" is a claim that the query cannot be filtering on a
+ * hidden column. A top-level-only check makes that claim falsely:
+ * `{ with: { posts: { where: { secretNote: { not: null } } } } }` has no
+ * column-naming key at the top level and filters on a column two levels down,
+ * and the tool reported it as safe to compile.
+ *
+ * `with` is not itself a column-naming key (its keys are RELATION names, and
+ * `select` / `omit` are excluded on the guard's own rule that they return
+ * values, which this tool never does), but the OPTIONS inside a `with` entry
+ * are the full findMany surface, so the walk descends through them.
+ *
+ * It errs toward TRUE: an unrecognized object value is descended into rather
+ * than skipped, and the depth cap answers true rather than false. This function
+ * only ever gates a refusal, so a false positive costs a caller one message and
+ * a false negative is the disclosure it exists to prevent.
+ */
+export declare function carriesColumnNamingArg(args: Record<string, unknown>, depth?: number): boolean;
 /** One relation reached by the query's `with` clause. */
 export interface CompiledRelation {
     /** Dotted path from the queried table, e.g. `author.org`. */

package/dist/cjs/cli/compile-query.js

@@ -109,9 +109,47 @@ exports.COLUMN_NAMING_ARG_KEYS = [
     '_min',
     '_max',
 ];
-/** Does this args object carry a key that names a column? */
-function carriesColumnNamingArg(args) {
-    return exports.COLUMN_NAMING_ARG_KEYS.some((key) => args[key] !== undefined);
+/**
+ * Does this args object carry a key that names a column, AT ANY DEPTH?
+ *
+ * The depth is the whole point and it was missing until 0.76.0. This is the
+ * fail-closed test for the case where the PII tag file could not be read, so
+ * "no column-naming arg" is a claim that the query cannot be filtering on a
+ * hidden column. A top-level-only check makes that claim falsely:
+ * `{ with: { posts: { where: { secretNote: { not: null } } } } }` has no
+ * column-naming key at the top level and filters on a column two levels down,
+ * and the tool reported it as safe to compile.
+ *
+ * `with` is not itself a column-naming key (its keys are RELATION names, and
+ * `select` / `omit` are excluded on the guard's own rule that they return
+ * values, which this tool never does), but the OPTIONS inside a `with` entry
+ * are the full findMany surface, so the walk descends through them.
+ *
+ * It errs toward TRUE: an unrecognized object value is descended into rather
+ * than skipped, and the depth cap answers true rather than false. This function
+ * only ever gates a refusal, so a false positive costs a caller one message and
+ * a false negative is the disclosure it exists to prevent.
+ */
+function carriesColumnNamingArg(args, depth = 0) {
+    if (depth > pii_predicate_guard_js_1.PII_GUARD_MAX_DEPTH)
+        return true;
+    for (const [key, value] of Object.entries(args)) {
+        if (exports.COLUMN_NAMING_ARG_KEYS.includes(key) && value !== undefined)
+            return true;
+        // `select` / `omit` name columns but return them rather than filtering on
+        // them, and nothing is returned here; skipping them keeps this aligned with
+        // cli/pii-predicate-guard.ts, which makes the same call for the same reason.
+        if (key === 'select' || key === 'omit')
+            continue;
+        if (value && typeof value === 'object') {
+            for (const entry of Array.isArray(value) ? value : [value]) {
+                if (entry && typeof entry === 'object' && carriesColumnNamingArg(entry, depth + 1)) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
 }
 // ---------------------------------------------------------------------------
 // Compile
@@ -307,9 +345,15 @@ function walkWith(metadata, table, withClause, depth, prefix, out) {
         // statement and has no target table of its own.
         if (key === '_count')
             continue;
-        const relation = (0, utils_js_1.ownLookup)(table.relations, key);
-        if (!relation)
+        // Resolve the caller's spelling the way the compiler does: a relation declared
+        // `blogPosts` is also reachable as `blog_posts` (resolveRelation, since 0.72). An
+        // exact-match lookup here did not fail loudly, it silently dropped the relation from
+        // the report, so compile_query under-counted statements and skipped the correlation
+        // probes for exactly the relation the caller asked about.
+        const resolved = (0, utils_js_1.resolveRelation)(table.relations, key);
+        if (!resolved)
             continue;
+        const relation = resolved.def;
         const path = prefix ? `${prefix}.${relation.name}` : relation.name;
         out.push({
             path,

package/dist/cjs/cli/config.d.ts

@@ -172,6 +172,8 @@ export interface CliOverrides {
     url?: string;
     out?: string;
     schema?: string;
+    /** `--schema-file <path>`: the defineSchema() file, overriding config `schemaFile`. */
+    schemaFile?: string;
     include?: string[];
     exclude?: string[];
     importExtension?: 'js' | 'none' | 'auto';

package/dist/cjs/cli/config.js

@@ -211,7 +211,7 @@ function resolveConfig(fileConfig, overrides) {
         // `seedFile` is canonical (what the docs and `turbine init` use); `seed` is a
         // back-compat alias kept working for configs scaffolded before 0.50.
         seedFile: fileConfig.seedFile ?? fileConfig.seed,
-        schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
+        schemaFile: overrides.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/cjs/cli/destructive.js

@@ -288,37 +288,6 @@ function stripExecutingExplain(stmt) {
 }
 /** Statements whose dollar-quoted body is executable SQL rather than data. */
 const PROCEDURAL_STATEMENT = /^(DO\b|CREATE\s+(OR\s+REPLACE\s+)?(FUNCTION|PROCEDURE)\b)/i;
-/**
- * Candidate fragments inside a procedural body (a `DO $$ ... $$` block, a
- * function source, or a PG14+ `BEGIN ATOMIC` body). The body's own string
- * literals are NOT stripped: the whole point is dynamic SQL, whose payload
- * lives in a literal (`EXECUTE 'DROP TABLE users'`). Rules are anchored, so
- * every keyword-leading position in the body is offered as its own candidate.
- * This deliberately over-reports (a body that merely mentions "drop table" in a
- * message string is flagged) in keeping with the module's
- * false-positives-only asymmetry.
- *
- * Comments come out via the SHARED tokenizer, never a regex. The pair that used
- * to do it here, `/\/\*[\s\S]*?\*\//g` and `/--[^\n]*\/g`, was the exact
- * hand-written lexer the tokenizer was written to delete, still in place one
- * level down and on the path that exists specifically to catch dynamic SQL.
- * Neither pattern nests and neither respects string literals, so ONE earlier
- * literal containing `--` or an unclosed `/*` blanked every destructive
- * statement after it. Both of these reported an empty inventory and dropped the
- * table on PostgreSQL 16.14:
- *
- *   DO $$ DECLARE s text := 'x --'; BEGIN EXECUTE 'DROP TABLE users'; END $$;
- *   DO $$ DECLARE s text := 'a /*'; BEGIN EXECUTE 'DROP TABLE users';
- *          RAISE NOTICE '% b *\/', s; END $$;
- *
- * The `--` shape is the worse of the two because it is reachable by ACCIDENT:
- * any single-line body whose earlier literal holds a `--` (a date range, a
- * separator, a placeholder) hides everything that follows it.
- *
- * Tokenizing also bounds each candidate at its own statement instead of at the
- * end of the body, so a later `WHERE` can no longer talk the `update-without-
- * where` rule out of an earlier unrestricted UPDATE.
- */
 function proceduralCandidates(body) {
     const out = [];
     for (const statement of (0, sql_statements_js_1.tokenizeSql)(body)) {
@@ -329,7 +298,7 @@ function proceduralCandidates(body) {
         const re = /\b(?:DROP|TRUNCATE|DELETE|ALTER|UPDATE|MERGE)\s/gi;
         let m = re.exec(text);
         while (m !== null) {
-            out.push(text.slice(m.index));
+            out.push({ text: text.slice(m.index), before: text.slice(0, m.index) });
             m = re.exec(text);
         }
     }
@@ -367,12 +336,15 @@ function scanDestructiveSql(sql) {
         // belongs to which statement is no longer an offset calculation that can
         // disagree with the statement split.
         const procedural = PROCEDURAL_STATEMENT.test(stmt);
-        const proceduralTexts = [];
+        const proceduralParts = [];
         for (const block of procedural ? statement.blocks : []) {
-            for (const text of proceduralCandidates(block)) {
+            for (const part of proceduralCandidates(block)) {
                 // The body was blanked in `display`, so name the fragment that matched.
-                candidates.push({ text, display: `${display} [in block: ${text.replace(/\s+/g, ' ').slice(0, 60)}]` });
-                proceduralTexts.push(text);
+                candidates.push({
+                    text: part.text,
+                    display: `${display} [in block: ${part.text.replace(/\s+/g, ' ').slice(0, 60)}]`,
+                });
+                proceduralParts.push(part);
             }
         }
         let matched = false;
@@ -407,12 +379,12 @@ function scanDestructiveSql(sql) {
         // `RAISE NOTICE 'DROP the mic'` would prompt, and a guard that fires on
         // prose teaches operators to confirm without reading, which costs more than
         // it saves.
-        for (const text of proceduralTexts) {
-            const kind = dynamicDestructiveKind(text);
+        for (const part of proceduralParts) {
+            const kind = dynamicDestructiveKind(part);
             if (!kind)
                 continue;
             found.push({
-                statement: `${display} [in block: ${text.replace(/\s+/g, ' ').slice(0, 60)}]`,
+                statement: `${display} [in block: ${part.text.replace(/\s+/g, ' ').slice(0, 60)}]`,
                 kind,
                 target: exports.DYNAMIC_TARGET,
             });
@@ -423,8 +395,68 @@ function scanDestructiveSql(sql) {
 }
 /** Shown in place of an object name that does not exist until the block runs. */
 exports.DYNAMIC_TARGET = '<name assembled at run time>';
-/** `||`, `format(...)`, or a `quote_*` helper: the ways a body builds SQL. */
-const DYNAMIC_ASSEMBLY = /\|\||\bformat\s*\(|\bquote_(?:ident|literal|nullable)\s*\(|%[IsL]/;
+/**
+ * The concatenation operator, and `format()`'s placeholders. Case-sensitive on
+ * purpose: `%I`, `%s` and `%L` are the only specifiers `format()` accepts, and
+ * folding case here would also match `%i`, which is not one and does occur in
+ * prose.
+ */
+const DYNAMIC_ASSEMBLY = /\|\||%[IsL]/;
+/**
+ * Functions that BUILD a statement out of parts, looked for anywhere in the
+ * fragment (a proximity test, so the list stays tight).
+ *
+ * `concat` / `concat_ws` are the additions, and they are not a nicety: they are
+ * the function spelling of `||`, and the NULL-tolerant one, so they are exactly
+ * what an author reaches for when a name may be null. Their absence was
+ * fail-open in a safety guard, verified on PostgreSQL 16:
+ *
+ *   DO $$ BEGIN EXECUTE 'DROP TABLE ' || 'users'; END $$;       -> flagged
+ *   DO $$ BEGIN EXECUTE concat('DROP TABLE ', 'users'); END $$; -> NOT flagged
+ *
+ * Both drop the table. The second reported a clean inventory, so `migrate up`
+ * never armed its data-loss prompt and applied the drop with no confirmation
+ * and no `--allow-destructive`.
+ */
+const ASSEMBLY_FN = /\b(?:format|concat_ws|concat|quote_ident|quote_literal|quote_nullable)\s*\(/i;
+/**
+ * The same question asked of the text BEFORE the verb, and asked PRECISELY: an
+ * assembling call whose parenthesis is still OPEN where the verb appears, i.e.
+ * the verb is one of that call's arguments (`concat('DROP TABLE ', t)`). That
+ * is what `[^)]*$` says, and it is the whole reason a pre-verb test is safe to
+ * add at all: this is not "an assembly function is somewhere nearby", it is
+ * "the destructive verb is inside one".
+ *
+ * Being inside an assembling call is still not enough on its own, and the
+ * counter-example is not hypothetical, it appeared the first time this ran:
+ *
+ *   DO $$ BEGIN UPDATE t SET a = regexp_replace(a, 'DROP .*', '') WHERE id = 1; END $$;
+ *
+ * Nothing there is assembled and nothing is destroyed, but the verb does sit
+ * inside a call. So the pre-verb test ALSO requires an `EXECUTE` in the same
+ * statement, which is the keyword that turns assembled text into a running
+ * statement, and the one thing a data-cleanup expression never has. The
+ * statement bound comes free: {@link proceduralCandidates} builds `before` from
+ * the candidate's OWN statement, so an `EXECUTE` three statements earlier in
+ * the body cannot vouch for this one.
+ *
+ * Precision is also what lets this list be wider than {@link ASSEMBLY_FN}'s.
+ * `array_to_string` joins a list of names into one statement, the shape a
+ * drop-many loop collapses to; `replace` / `regexp_replace` are template
+ * substitution (`EXECUTE replace('DROP TABLE $t', '$t', name)`). Neither may go
+ * in the proximity list: there they would arm the dynamic pass on any body that
+ * both mentions a destructive verb and tidies a string, and a guard that fires
+ * on innocent migrations teaches operators to confirm without reading, which is
+ * this module's other failure mode and costs more than it saves.
+ *
+ * Deliberately left out entirely: `string_agg` (it aggregates over ROWS, and the
+ * per-row half it aggregates is itself a `||` or a `concat` these already
+ * catch), `overlay`, and `substr`/`left`/`right` (they cut text down, they do
+ * not assemble a statement out of parts).
+ */
+const WRAPPING_ASSEMBLY_FN = /\b(?:format|concat_ws|concat|quote_ident|quote_literal|quote_nullable|array_to_string|regexp_replace|replace)\s*\([^)]*$/i;
+/** Dynamic SQL only runs if something runs it. Scoped to the candidate's own statement. */
+const RUNS_DYNAMIC_SQL = /\bEXECUTE\b/i;
 /**
  * The kind a runtime-assembled procedural fragment should be reported as, or
  * `null` when it is not dynamic (so a rule already had its chance) or its verb
@@ -436,8 +468,11 @@ const DYNAMIC_ASSEMBLY = /\|\||\bformat\s*\(|\bquote_(?:ident|literal|nullable)\
  * decidable from a fragment whose tail is a runtime expression, so including
  * them would flag every dynamic `UPDATE ... WHERE` in the file.
  */
-function dynamicDestructiveKind(text) {
-    if (!DYNAMIC_ASSEMBLY.test(text))
+function dynamicDestructiveKind({ text, before }) {
+    const assembled = DYNAMIC_ASSEMBLY.test(text) ||
+        ASSEMBLY_FN.test(text) ||
+        (RUNS_DYNAMIC_SQL.test(before) && WRAPPING_ASSEMBLY_FN.test(before));
+    if (!assembled)
         return null;
     if (/^DROP\s+TABLE\b/i.test(text))
         return 'drop-table';

package/dist/cjs/cli/index.d.ts

@@ -6,7 +6,7 @@
  *   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 push                  - Apply schema-builder definitions to database (--schema-file, destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
  *   turbine migrate up           , Apply pending migrations
  *   turbine migrate deploy       , Apply pending migrations without prompts
@@ -34,6 +34,18 @@ export interface CliArgs {
     url?: string;
     out?: string;
     schema?: string;
+    /**
+     * `--schema-file <path>`: the defineSchema() FILE, the `schemaFile` config key
+     * as a flag.
+     *
+     * `--schema` is the Postgres NAMESPACE, and it has been mistaken for this one
+     * often enough to be its own class of bug: `turbine push --schema ./schema.ts`
+     * reported "Schema file not found: ./turbine/schema.ts", naming a path the
+     * user never typed while their schema file sat in the directory they ran it
+     * from. Labelling the mistake is not the whole fix; the mistake exists because
+     * one of the two ideas had a flag and the other did not.
+     */
+    schemaFile?: string;
     include?: string[];
     exclude?: string[];
     step?: number;
@@ -121,6 +133,41 @@ export interface CliArgs {
     /** `skill --dir <path>`: the skills root to install into (default `.claude/skills`). */
     dir?: string;
 }
+/**
+ * The canonical name of `command`, or undefined when nothing dispatches it.
+ *
+ * @internal exported for tests.
+ */
+export declare function canonicalCommand(command: string): string | undefined;
+/** Every command name a user could reasonably have meant, canonical spellings only. */
+export declare function knownCommands(): string[];
+/**
+ * The long flags `command` accepts (its own, then the global ones), or
+ * undefined when the command itself is unrecognized.
+ *
+ * An unknown command returns undefined rather than an empty list on purpose:
+ * `turbine genrate --url ...` should be told the COMMAND is misspelled, not
+ * handed a flag error for a flag that is perfectly valid on the command it
+ * meant.
+ *
+ * @internal exported for tests.
+ */
+export declare function flagsForCommand(command: string): {
+    own: readonly string[];
+    global: readonly string[];
+} | undefined;
+/**
+ * Every flag token any command accepts, long spellings and aliases alike.
+ *
+ * Exists for `src/test/cli-arg-safety.test.ts`, which cross-checks it against
+ * the `case` labels in {@link parseArgs} in both directions. A flag in the
+ * parser but in no command's list is unreachable (the validator rejects it
+ * before the case runs); a flag in a list with no case is accepted and then
+ * silently ignored, which is the bug this whole surface exists to end.
+ *
+ * @internal exported for tests.
+ */
+export declare function allFlagTokens(): Set<string>;
 export declare function parseArgs(argv?: string[]): CliArgs;
 /**
  * Does this invocation need a `turbine.config.*` file?
@@ -312,6 +359,12 @@ export interface InitPlanFlags {
  * skipped when there is no URL or the database is unreachable.
  */
 export declare function planInitSteps(state: InitPlanState, flags: InitPlanFlags): InitPlanStep[];
+/**
+ * Which starter schema to scaffold.
+ *
+ * @internal exported for tests.
+ */
+export declare function initSchemaTemplate(dbHasTables: boolean): string;
 /** What the secret-handling scaffold decided to do with one file. */
 export type EnvScaffoldAction = 'created' | 'appended' | 'unchanged';
 /** Detected state of the three files the scaffold touches (all IO by the caller). */
@@ -369,6 +422,24 @@ export declare function planEnvScaffold(state: EnvScaffoldState): EnvScaffoldPla
  * @internal exported for tests.
  */
 export declare function scaffoldEnvForUrl(url: string): EnvScaffoldPlan;
+/**
+ * The exact import line for the generated client, extension included.
+ *
+ * `import { turbine } from './generated/turbine'` is a hard TypeScript error
+ * (TS2834) under `moduleResolution: NodeNext`, which is what this package ships
+ * and what its own tsconfig uses: a relative import needs an explicit file
+ * extension, and NodeNext does no directory-index resolution either. The
+ * generator has always appended the extension to its OWN sibling imports; the
+ * line printed at the reader was the one place it never reached.
+ *
+ * The extension comes from {@link resolveImportExtension}, the same resolver the
+ * generator runs, so the printed line matches the files just written rather
+ * than a second guess about the consumer's tsconfig. Under bundler resolution
+ * it resolves to `''` and the directory form is correct as-is.
+ *
+ * @internal exported for tests.
+ */
+export declare function generatedClientImport(config: Pick<ResolvedConfig, 'out' | 'importExtension'>): string;
 /**
  * The one-line connection heads-up `turbine init` opens with.
  *
@@ -396,6 +467,29 @@ export declare function initEnvNotice(input: {
     flagUrl: string | undefined;
     configUrl: string | undefined;
 }): InitEnvNotice;
+/**
+ * Refuse a `schema` that is plainly a FILE PATH, on every command that reads it
+ * as a Postgres namespace.
+ *
+ * `--schema` / `-s` sets the namespace to introspect (default `public`). The
+ * defineSchema() file is a different idea entirely, and mistaking the two is
+ * silent on every command that used to accept it: `generate` introspects
+ * `WHERE table_schema = './turbine/schema.ts'` and matches nothing, and `push`
+ * reads `config.schemaFile` instead and reports
+ * "Schema file not found: ./turbine/schema.ts", naming a path the reader never
+ * typed while their schema file sits in the directory they ran it from.
+ *
+ * The check was written for `generate` and wired into `generate` alone, which is
+ * how `push`, the command whose flag name the mistake is actually about, kept
+ * the bad error. It is one function called from every `--schema` command now,
+ * for the same reason `resolveColumnName` is one function: two copies of a rule
+ * is how two commands come to disagree about whether an argument is valid.
+ *
+ * @internal exported for tests.
+ */
+export declare function refuseSchemaFilePath(config: Pick<ResolvedConfig, 'schema' | 'schemaFile'>, options?: {
+    escapeHatch?: string;
+}): void;
 /**
  * `turbine migrate-from-prisma --schema prisma/schema.prisma` parses a Prisma
  * schema, resolve its models/fields/relations/compound-uniques against the live