turbine-orm 0.75.0 → 0.76.0

package/dist/cjs/sqlite.js

@@ -35,7 +35,7 @@
  * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
  *   (no Unicode case folding).
  *
- * ## Example, `:memory:` database
+ * ## Example, `:memory:` database, from a generated schema
  *
  * ```ts
  * import { turbineSqlite } from 'turbine-orm/sqlite';
@@ -45,6 +45,38 @@
  * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
  * await db.disconnect();
  * ```
+ *
+ * ## Example, SQLite with no Postgres anywhere
+ *
+ * The snippet above needs `turbine generate`, which reads a live **Postgres**
+ * catalog, so it is the wrong starting point if SQLite is your only database.
+ * Describe the schema in code instead: `schemaToSQL` emits the DDL and
+ * `schemaDefToMetadata` derives the runtime metadata (relations included, from
+ * the same `references:`), both pure functions with no database involved.
+ *
+ * ```ts
+ * 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 } },
+ *   posts: {
+ *     id: { type: 'serial', primaryKey: true },
+ *     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);
+ * }
+ *
+ * // `db.table(...)`, not `db.users`: the typed property accessors are emitted
+ * // by `turbine generate`, and this path skips it.
+ * const users = await db.table('users').findMany({ with: { posts: true }, orderBy: { id: 'asc' } });
+ * await db.disconnect();
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sqliteDialect = exports.SqlitePool = void 0;
@@ -248,8 +280,24 @@ function statementReturnsRows(sql) {
  * recognizable SQLite error.
  *
  * `wrapPgError` is invoked downstream (in the query executor and the
- * transaction proxy), so we only annotate here, we never throw a `new`
- * Turbine error from the driver itself.
+ * transaction proxy), so annotation is the preferred half of the job: every
+ * failure whose meaning Postgres already has a SQLSTATE for is expressed as
+ * that SQLSTATE and typed by the one classifier.
+ *
+ * ONE family cannot be handled that way, and it was the family a new user hits
+ * first. `SQLITE_ERROR` (primary code 1, "SQL logic error") covers
+ * `no such table: users`, `no such column: emial`, and a plain syntax error;
+ * Postgres reports the same three as 42P01 / 42703 / 42601, and `wrapPgError`
+ * classifies none of them, on either engine. So on SQLite they reached the
+ * caller as a bare `Error` with `code: 'ERR_SQLITE_ERROR'`: no `TURBINE_E0NN`,
+ * no `.docsUrl`, not a `TurbineError` at all, in a library whose typed-error
+ * table is a headline feature. {@link sqliteLogicError} builds the
+ * `ValidationError` for them here, the way `wrapPowdbError` builds its errors
+ * for a driver with no SQLSTATEs to annotate.
+ *
+ * Everything else stays annotation, so the two engines cannot drift: fixing a
+ * constraint classification in `wrapPgError` fixes it for SQLite in the same
+ * commit.
  */
 function augmentSqliteError(err) {
     if (!err || typeof err !== 'object')
@@ -297,10 +345,43 @@ function augmentSqliteError(err) {
             if (primary === 5 || primary === 6) {
                 // Map to serialization_failure so withRetry()/$retry() retry it.
                 target.code = '40001';
+                return err;
             }
+            // SQLITE_ERROR (1): the statement itself is wrong. See the note above.
+            if (primary === 1)
+                return sqliteLogicError(message, err);
             return err;
     }
 }
+/**
+ * The `ValidationError` for a `SQLITE_ERROR`, with a hint for the two spellings
+ * that account for nearly all of them.
+ *
+ * The driver's own text IS the diagnosis (`no such table: users` names the
+ * table), so it is kept verbatim rather than replaced.
+ *
+ * The original error IS attached as `cause`, and safe mode is not a reason not
+ * to: `TurbineError` runs every cause it is given through `redactCauseForMode`,
+ * so attaching one goes THROUGH the redaction rather than around it. It also
+ * discloses nothing new here, because the driver's message is already quoted
+ * verbatim into the message above it. What it buys is the stack: without it a
+ * `no such table` surfaces with Turbine's frames and none of the driver's.
+ */
+function sqliteLogicError(message, cause) {
+    const missingTable = /^no such table:\s*(\S+)/i.exec(message);
+    if (missingTable) {
+        return new errors_js_1.ValidationError(`[turbine] SQLite has no table "${missingTable[1]}": ${message}. ` +
+            'Create it first (run your migrations, or execute the CREATE TABLE statements for this schema); ' +
+            'an in-memory database starts empty on every connection.', { cause });
+    }
+    const missingColumn = /^no such column:\s*(\S+)/i.exec(message);
+    if (missingColumn) {
+        return new errors_js_1.ValidationError(`[turbine] SQLite has no column "${missingColumn[1]}": ${message}. ` +
+            'Check the spelling against the table as it exists in this database, ' +
+            'and re-run `turbine generate` if the schema has changed.', { cause });
+    }
+    return new errors_js_1.ValidationError(`[turbine] SQLite rejected the statement: ${message}`, { cause });
+}
 function normalizeQueryArgs(arg, values) {
     if (typeof arg === 'string')
         return { text: arg, params: values ?? [] };

package/dist/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/cli/compile-query.js

@@ -36,7 +36,7 @@
 import { TurbineError } from '../errors.js';
 import { missingIndexForRelation } from '../index-advisor.js';
 import { QueryInterface } from '../query/index.js';
-import { ownLookup } from '../query/utils.js';
+import { ownLookup, resolveRelation } from '../query/utils.js';
 import { explainErrorCode } from './error-catalog.js';
 import { PII_GUARD_MAX_DEPTH } from './pii-predicate-guard.js';
 /**
@@ -102,9 +102,47 @@ export const COLUMN_NAMING_ARG_KEYS = [
     '_min',
     '_max',
 ];
-/** Does this args object carry a key that names a column? */
-export function carriesColumnNamingArg(args) {
-    return 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.
+ */
+export function carriesColumnNamingArg(args, depth = 0) {
+    if (depth > PII_GUARD_MAX_DEPTH)
+        return true;
+    for (const [key, value] of Object.entries(args)) {
+        if (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
@@ -300,9 +338,15 @@ function walkWith(metadata, table, withClause, depth, prefix, out) {
         // statement and has no target table of its own.
         if (key === '_count')
             continue;
-        const relation = 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 = resolveRelation(table.relations, key);
+        if (!resolved)
             continue;
+        const relation = resolved.def;
         const path = prefix ? `${prefix}.${relation.name}` : relation.name;
         out.push({
             path,

package/dist/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/cli/config.js

@@ -165,7 +165,7 @@ export 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/cli/destructive.js

@@ -284,37 +284,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 tokenizeSql(body)) {
@@ -325,7 +294,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);
         }
     }
@@ -363,12 +332,15 @@ export 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;
@@ -403,12 +375,12 @@ export 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: DYNAMIC_TARGET,
             });
@@ -419,8 +391,68 @@ export function scanDestructiveSql(sql) {
 }
 /** Shown in place of an object name that does not exist until the block runs. */
 export const 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
@@ -432,8 +464,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/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