turbine-orm 0.39.0 → 0.40.0

package/dist/cjs/cli/migrate.js

@@ -24,6 +24,7 @@ exports.getPendingMigrations = getPendingMigrations;
 exports.listMigrationFiles = listMigrationFiles;
 exports.parseMigrationContent = parseMigrationContent;
 exports.parseMigrationSQL = parseMigrationSQL;
+exports.buildDiffMigrationBody = buildDiffMigrationBody;
 exports.createMigration = createMigration;
 exports.deriveLockId = deriveLockId;
 exports.planMigrationDeploy = planMigrationDeploy;
@@ -223,6 +224,84 @@ exports.MIGRATION_RECIPES = {
         build: buildBackfillRecipe,
     },
 };
+/** Loud file-level banner prepended when a diff migration contains destructive statements. */
+const DESTRUCTIVE_MIGRATION_BANNER = [
+    '-- ============================================================',
+    '-- WARNING: this migration contains DESTRUCTIVE statement(s).',
+    '-- Each one is flagged inline below. `turbine migrate up` refuses',
+    '-- destructive statements by default: it asks you to confirm',
+    '-- interactively, or you must pass --allow-destructive. Review',
+    '-- every flagged statement carefully before running.',
+    '-- ============================================================',
+];
+/**
+ * Annotate a list of SQL statements: scan each for data-destroying operations
+ * (via {@link scanDestructiveSql}) and prefix any offender with loud, commented
+ * warnings. Statements are left intact so the existing `migrate up` gate still
+ * refuses them by default; the comments just make the danger visible on review.
+ */
+function annotateDiffStatements(statements) {
+    const destructive = [];
+    const out = [];
+    for (const raw of statements) {
+        const stmt = raw.trim();
+        if (!stmt)
+            continue;
+        const hits = (0, destructive_js_1.scanDestructiveSql)(stmt);
+        if (hits.length > 0) {
+            destructive.push(...hits);
+            for (const h of hits) {
+                out.push(`-- !! DESTRUCTIVE [${h.kind}] ${h.target}: ${destructive_js_1.DESTRUCTIVE_KIND_LABEL[h.kind]}`);
+            }
+            out.push('-- !! Refused by default. Confirm interactively or pass --allow-destructive to run it.');
+        }
+        out.push(stmt.endsWith(';') ? stmt : `${stmt};`);
+    }
+    return { text: out.join('\n'), destructive };
+}
+/**
+ * Build a migration UP/DOWN body from a `schemaDiff()` result.
+ *
+ * - UP is the diff's forward statements. DOWN is the diff's reverse statements
+ *   when derivable, otherwise a clearly-commented "irreversible" placeholder.
+ * - Destructive statements in EITHER direction (a lossy `ALTER COLUMN ... TYPE`
+ *   in UP, a `DROP TABLE`/`DROP COLUMN` reverse in DOWN) are flagged inline and,
+ *   when any exist, a loud file-level banner is prepended to UP.
+ * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
+ *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ *
+ * Pure and DB-free, so it is unit-testable from a synthesized diff.
+ */
+function buildDiffMigrationBody(diff) {
+    const up = annotateDiffStatements(diff.statements);
+    const hasReverse = diff.reverseStatements.length > 0;
+    const down = hasReverse
+        ? annotateDiffStatements(diff.reverseStatements)
+        : { text: '', destructive: [] };
+    const upParts = [];
+    if (up.destructive.length > 0 || down.destructive.length > 0) {
+        upParts.push(...DESTRUCTIVE_MIGRATION_BANNER, '');
+    }
+    if (diff.warnings && diff.warnings.length > 0) {
+        for (const w of diff.warnings)
+            upParts.push(`-- NOTE: ${w}`);
+        upParts.push('');
+    }
+    upParts.push(up.text || '-- (no statements: schema already matches the database)');
+    const downText = hasReverse
+        ? down.text
+        : [
+            '-- irreversible, write manually',
+            '-- The diff produced no reversible statements for this change. Write the',
+            '-- rollback SQL by hand, or leave this section empty for a one-way migration.',
+        ].join('\n');
+    return {
+        up: upParts.join('\n'),
+        down: downText,
+        destructiveUp: up.destructive,
+        destructiveDown: down.destructive,
+    };
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------

package/dist/cjs/client.js

@@ -374,6 +374,7 @@ class TurbineClient {
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
+            sqlCacheSize: config.sqlCacheSize,
             dialect: config.dialect,
             // Non-SQL backends (PowDB) inject a factory that builds their own query
             // interface (PowqlInterface) instead of the SQL QueryInterface. SQL engines

package/dist/cjs/powql.js

@@ -749,7 +749,7 @@ class PowqlInterface {
     buildOrder(orderBy, params, alias) {
         if (!orderBy)
             return '';
-        const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
+        const keys = (0, filters_js_1.orderByEntries)(orderBy).filter(([, dir]) => dir !== undefined);
         if (!keys.length)
             return '';
         const parts = keys.map(([field, dir]) => {
@@ -2204,7 +2204,11 @@ class PowqlInterface {
             }
             const having = this.buildHaving(args.having, params, aggInner);
             const order = this.buildGroupOrder(args.orderBy, byOrderExprs, aggOrderExprs);
-            const powql = `${this.qt}${filter} group ${groupExprs.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            // LIMIT / OFFSET over the result groups, applied after ORDER BY (mirrors
+            // the SQL groupBy). offset 0 is a no-op, matching findMany.
+            const limitClause = args.limit !== undefined ? ` limit ${this.param(args.limit, params)}` : '';
+            const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
+            const powql = `${this.qt}${filter} group ${groupExprs.join(', ')}${having}${order}${limitClause}${offsetClause} { ${proj.join(', ')} }`;
             const { rows, native: resultNative } = await this.exec(powql, params, args.timeout, 'groupBy');
             // Reshape: group keys → user fields (coerced / null-disambiguated),
             // aggregates → nested `{ _sum: { field } }`; discriminators are stripped.
@@ -2310,7 +2314,7 @@ class PowqlInterface {
             return keys.join(', ') || '(none)';
         };
         const parts = [];
-        for (const [key, value] of Object.entries(orderBy)) {
+        for (const [key, value] of (0, filters_js_1.orderByEntries)(orderBy)) {
             if (value === undefined)
                 continue;
             if (aggBlocks.has(key)) {

package/dist/cjs/query/aggregates.js

@@ -210,6 +210,16 @@ function buildGroupBy(qi, args) {
         if (orderSql)
             sql += ` ORDER BY ${orderSql}`;
     }
+    // LIMIT / OFFSET over the result groups, applied AFTER ORDER BY. Routed
+    // through the dialect pagination hook (parameterized on PG/SQLite/SQL Server,
+    // inlined on MySQL); params append after the WHERE/HAVING/ORDER BY params, so
+    // no `$n` renumbering. `offset` without a deterministic `orderBy` yields an
+    // arbitrary window (same caveat as findMany).
+    if (args.limit !== undefined || args.offset !== undefined) {
+        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params) : undefined;
+        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params) : undefined;
+        sql += qi.buildPagination(limitPh, offsetPh, args.orderBy !== undefined);
+    }
     return {
         sql,
         params,
@@ -297,7 +307,7 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
         return keys.join(', ') || '(none)';
     };
     const parts = [];
-    for (const [key, value] of Object.entries(orderBy)) {
+    for (const [key, value] of (0, filters_js_1.orderByEntries)(orderBy)) {
         if (value === undefined)
             continue;
         // Aggregate ordering blocks.

package/dist/cjs/query/builder.js

@@ -185,8 +185,12 @@ class QueryInterface {
     table;
     schema;
     tableMeta;
-    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
-    sqlTemplateCache = new utils_js_1.LRUCache(1000);
+    /**
+     * SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name).
+     * Capacity is set once in the constructor from `options.sqlCacheSize`
+     * (default 1000). See {@link QueryInterfaceOptions.sqlCacheSize}.
+     */
+    sqlTemplateCache;
     /**
      * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
      * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
@@ -314,7 +318,13 @@ class QueryInterface {
                 : warnOpt !== false;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
-        this.sqlCacheEnabled = options?.sqlCache !== false;
+        // SQL template cache capacity. `sqlCacheSize: 0` disables caching entirely
+        // (mirrors `sqlCache: false`); any positive integer sets the LRU bound;
+        // undefined keeps the historical 1000-entry default. A negative value is
+        // treated as the default rather than throwing.
+        const sqlCacheSize = options?.sqlCacheSize;
+        this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
+        this.sqlTemplateCache = new utils_js_1.LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? dialect_js_1.postgresDialect;
         this.relationLoadStrategy = options?.relationLoadStrategy ?? 'join';
         this.jsonEncoding = options?.jsonEncoding ?? 'object';
@@ -1110,7 +1120,7 @@ class QueryInterface {
         // Checked BEFORE the SQL cache so build and warm-cache paths throw
         // identically (same rule as the vector guard inside the distinct branch).
         if (args?.distinct && args.distinct.length > 0 && args.orderBy) {
-            for (const d of Object.values(args.orderBy)) {
+            for (const [, d] of (0, filters_js_1.orderByEntries)(args.orderBy)) {
                 if (this.isRelationOrderByValue(d)) {
                     throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with relation orderBy (pick-row, `_count`, or ' +
                         'to-one relation ordering): the outer re-order cannot reference the parent table.');
@@ -1129,8 +1139,13 @@ class QueryInterface {
         // Build fingerprint for cache lookup
         const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const withFp = args?.with ? this.withFingerprint(args.with) : '';
+        // Flatten via orderByEntries so the object form (`{ a, b }`) and the
+        // Prisma-style array form (`[{ a }, { b }]`) fingerprint from the SAME
+        // ordered entry list the build/collect paths consume. An array's element
+        // order is authoritative and preserved here, so a permuted array is a
+        // distinct key (correct, it emits a different ORDER BY).
         const orderFp = args?.orderBy
-            ? Object.entries(args.orderBy)
+            ? (0, filters_js_1.orderByEntries)(args.orderBy)
                 .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, (0, utils_js_1.ownLookup)(this.tableMeta.relations, k)?.to)}`)
                 .join(',')
             : '';
@@ -1199,11 +1214,15 @@ class QueryInterface {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = (0, filters_js_1.sortedEntries)(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
+                    // Resolve the seek direction per cursor field from the flattened
+                    // orderBy entries (last wins, matching object-key semantics), so both
+                    // the object and array orderBy forms drive the cursor comparison.
+                    const orderDirByKey = new Map((0, filters_js_1.orderByEntries)(args.orderBy));
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
                         // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
-                        const dir = args.orderBy?.[k];
+                        const dir = orderDirByKey.get(k);
                         const desc = (0, filters_js_1.isOrderBySpec)(dir) ? dir.sort === 'desc' : dir === 'desc';
                         const op = desc ? '<' : '>';
                         freshParams.push(v);
@@ -1224,7 +1243,7 @@ class QueryInterface {
                 // need two levels: inner DISTINCT ON ordered by the distinct columns then
                 // the user's order (picks the right representative row), outer re-ordered
                 // by the user's order alone.
-                if (Object.values(args.orderBy).some((d) => (0, filters_js_1.isVectorOrderBy)(d))) {
+                if ((0, filters_js_1.orderByEntries)(args.orderBy).some(([, d]) => (0, filters_js_1.isVectorOrderBy)(d))) {
                     throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
                 const userOrder = this.buildOrderBy(args.orderBy, freshParams);
@@ -1638,6 +1657,14 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // groupBy (with aggregate functions)
     // -------------------------------------------------------------------------
+    /**
+     * Group rows and compute per-group aggregates (Prisma-style). The result row
+     * type is INFERRED from the args: each `by` field carries its entity field
+     * type, `_count` is always a number, and each requested `_sum` / `_avg` /
+     * `_min` / `_max` block maps its fields to properly typed values (see
+     * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
+     * that cannot be typed, so those columns are not projected onto the row type.
+     */
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
@@ -1804,7 +1831,7 @@ class QueryInterface {
      * order exactly so the cached-SQL param re-collection stays in lockstep.
      */
     collectOrderByParams(orderBy, params) {
-        for (const [key, dir] of Object.entries(orderBy)) {
+        for (const [key, dir] of (0, filters_js_1.orderByEntries)(orderBy)) {
             if ((0, filters_js_1.isVectorOrderBy)(dir)) {
                 const rawColumn = this.toColumn(key);
                 // Re-run the same validation as buildOrderBy so the collect path can

package/dist/cjs/query/filters.js

@@ -28,6 +28,7 @@ exports.isVectorOrderBy = isVectorOrderBy;
 exports.isOrderBySpec = isOrderBySpec;
 exports.isJsonPathOrderBy = isJsonPathOrderBy;
 exports.isRelationPickOrderBy = isRelationPickOrderBy;
+exports.orderByEntries = orderByEntries;
 exports.normalizeOrderBy = normalizeOrderBy;
 const errors_js_1 = require("../errors.js");
 const utils_js_1 = require("./utils.js");
@@ -356,6 +357,38 @@ function isRelationPickOrderBy(value) {
     }
     return true;
 }
+/**
+ * Flatten an orderBy input into an ordered list of `[field, value]` entries.
+ *
+ * Accepts BOTH the classic single-object form (`{ a: 'asc', b: 'desc' }`,
+ * whose insertion order is authoritative) and the Prisma-style array form
+ * (`[{ a: 'asc' }, { b: 'desc' }]`, whose array order is authoritative). The
+ * array form removes the reliance on JS object key iteration order for
+ * multi-key sorts. Each array element may carry one or more keys; they expand
+ * left-to-right. `undefined`/non-object elements are skipped.
+ *
+ * Undefined-VALUED entries are preserved (mirroring `Object.entries`) so each
+ * consumer keeps its own `dir !== undefined` filtering exactly as before. This
+ * is THE single flattening authority: every ORDER BY compile / collect /
+ * fingerprint path routes through it so the array and object forms stay in
+ * lockstep across build, param-collect, and cache-key fingerprint.
+ */
+function orderByEntries(orderBy) {
+    if (Array.isArray(orderBy)) {
+        const entries = [];
+        for (const element of orderBy) {
+            if (element !== null && typeof element === 'object' && !Array.isArray(element)) {
+                for (const kv of Object.entries(element))
+                    entries.push(kv);
+            }
+        }
+        return entries;
+    }
+    if (orderBy !== null && typeof orderBy === 'object') {
+        return Object.entries(orderBy);
+    }
+    return [];
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/cjs/query/relations.js

@@ -199,7 +199,7 @@ function withFingerprint(qi, withClause, table, depth = 0) {
         // orderBy shape (OrderBySpec nulls placement changes the SQL, so fingerprint it)
         if (opts.orderBy) {
             const targetRels = qi.schema.tables[relDef.to]?.relations;
-            const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${orderByEntryFingerprint(qi, d, targetRels?.[k]?.to)}`);
+            const oEntries = (0, filters_js_1.orderByEntries)(opts.orderBy).map(([k, d]) => `${k}:${orderByEntryFingerprint(qi, d, targetRels?.[k]?.to)}`);
             subParts.push(`o=${oEntries.join(',')}`);
         }
         // limit presence, but on inline-pagination engines (MySQL) the literal
@@ -262,7 +262,7 @@ function collectRelationSubqueryParams(qi, relDef, spec, params, _parentRef, dep
     //   orderBy params → where params → limit param → nested-with params
     //   (always, both paths).
     if (relDef.type === 'manyToMany') {
-        const m2mOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const m2mOrderEntries = spec.orderBy ? (0, filters_js_1.orderByEntries)(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         if (nativeOrderPath && m2mOrderEntries.length > 0) {
             collectRelationOrderParams(qi, targetTable, targetMeta, m2mOrderEntries, params);
         }
@@ -284,7 +284,7 @@ function collectRelationSubqueryParams(qi, relDef, spec, params, _parentRef, dep
         return;
     }
     // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
-    const relOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec.orderBy ? (0, filters_js_1.orderByEntries)(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const hasOrder = relOrderEntries.length > 0;
     const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
     // Non-wrapped path: nested relations BEFORE where/limit
@@ -388,7 +388,7 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
     // orderBy keys (object values that are neither a vector nor an OrderBySpec)
     // are validated in the relation branch below, so skip them here.
     if (process.env.NODE_ENV !== 'production') {
-        for (const [key, value] of Object.entries(orderBy)) {
+        for (const [key, value] of (0, filters_js_1.orderByEntries)(orderBy)) {
             if (isRelationOrderByValue(qi, value) && (0, utils_js_1.ownLookup)(qi.tableMeta.relations, key))
                 continue;
             const snakeKey = (0, schema_js_1.camelToSnake)(key);
@@ -400,7 +400,7 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
     }
     const meta = qi.schema.tables[qi.table];
     let relOrdCounter = 0;
-    return Object.entries(orderBy)
+    return (0, filters_js_1.orderByEntries)(orderBy)
         .map(([key, value]) => {
         // Vector KNN ordering: { distance: { to, metric, direction? } }
         if ((0, filters_js_1.isVectorOrderBy)(value)) {
@@ -1452,7 +1452,7 @@ function buildRelationSubquery(qi, relDef, spec, params, parentRef, aliasCounter
     // An orderBy with no defined entries (`orderBy: {}`) is treated as absent —
     // it must neither trigger the wrap (dropping nested relations) nor render a
     // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
-    const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec !== true && spec.orderBy ? (0, filters_js_1.orderByEntries)(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || relOrderEntries.length > 0);
     // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
     // where, orderBy, and select/omit are handled there (the target alias is the
@@ -1623,7 +1623,7 @@ function buildManyToManySubquery(qi, relDef, spec, params, parentRef, aliasCount
     // `orderBy: {}` (no defined entries) is treated as absent: it must not
     // render a dangling `ORDER BY `. Param pushes here land BEFORE the
     // spec.where params, mirrored by collectRelationSubqueryParams' m2m branch.
-    const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec !== true && spec.orderBy ? (0, filters_js_1.orderByEntries)(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     let orderClause = '';
     if (relOrderEntries.length > 0) {
         orderClause = buildRelationOrderClause(qi, targetTable, targetMeta, talias, relOrderEntries, params);

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 push                  - Apply schema-builder definitions to database (destructive ops gated)
- *   turbine migrate create <name> - Create a new SQL migration file (--auto | --recipe <name>)
+ *   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
  *   turbine migrate down          — Rollback last migration
@@ -38,12 +38,24 @@ export interface CliArgs {
     verbose?: boolean;
     help?: boolean;
     auto?: boolean;
+    /** `migrate create --from-diff`: scaffold UP/DOWN from the schema diff, destructive statements flagged. */
+    fromDiff?: boolean;
     allowDrift?: boolean;
     allowEmpty?: boolean;
     allowDestructive?: boolean;
     /** `migrate create --recipe <name>` scaffold selector. */
     recipe?: string;
     fix?: boolean;
+    /** `init --yes`/`-y`: accept every step's default non-interactively. */
+    yes?: boolean;
+    /** `init --skip-schema`: don't scaffold the schema file. */
+    skipSchema?: boolean;
+    /** `init --skip-seed`: don't scaffold the seed file or offer to run it. */
+    skipSeed?: boolean;
+    /** `init --skip-push`: don't offer to push the schema to the database. */
+    skipPush?: boolean;
+    /** `init --skip-generate`: don't offer to generate the typed client. */
+    skipGenerate?: boolean;
     zod?: boolean;
     includeViews?: boolean;
     /** Omit the `Generated at:` header line for reproducible (diff-stable) output. */
@@ -129,6 +141,54 @@ export declare function dotEnvUrlConflictWarning(input: {
  * project, and `'none'` when there is no readable/parseable package.json.
  */
 export declare function detectConsumerModuleType(cwd?: string): 'module' | 'commonjs' | 'none';
+/** A single step in the `turbine init` flow. */
+export type InitStepId = 'config' | 'schema' | 'seed-file' | 'push' | 'generate' | 'seed-run';
+/** What the planner decided to do with a step. */
+export type InitStepAction = 'run' | 'prompt' | 'skip';
+/** Why a step was skipped (only set when `action` is `skip`). */
+export type InitStepSkipReason = 'exists' | 'flag' | 'no-url' | 'unreachable' | 'no-seed-file' | 'non-interactive' | 'default-no';
+export interface InitPlanStep {
+    id: InitStepId;
+    action: InitStepAction;
+    /** Prompt default; also the value used to decide auto-run under `--yes`. */
+    defaultYes: boolean;
+    skipReason?: InitStepSkipReason;
+}
+/** Detected project state (all IO done by the caller). */
+export interface InitPlanState {
+    configExists: boolean;
+    schemaExists: boolean;
+    seedFileExists: boolean;
+    hasUrl: boolean;
+    dbReachable: boolean;
+}
+/** Effective flags for the planner. */
+export interface InitPlanFlags {
+    yes: boolean;
+    force: boolean;
+    interactive: boolean;
+    skipSchema: boolean;
+    skipSeed: boolean;
+    skipPush: boolean;
+    skipGenerate: boolean;
+}
+/**
+ * Pure step planner for `turbine init`. Given the detected project state and the
+ * effective flags, decide for each step whether to run it, prompt for it, or
+ * skip it (and why). No IO: every input is precomputed by the caller: so the
+ * whole decision matrix is unit-testable without a TTY or a database.
+ *
+ * Three modes:
+ *  - `prompt`      (interactive TTY, no `--yes`): scaffold + DB steps are prompted.
+ *  - `auto-yes`    (`--yes`): accept each step's default; the yes-defaults run.
+ *  - `auto-legacy` (non-TTY, no `--yes`): reproduce the pre-existing init
+ *    behavior. Scaffold files + generate run; push + seed-run do not.
+ *
+ * Steps that create files (config, schema, seed) are skipped when the file
+ * already exists, so re-runs are safe. DB steps (push, generate, seed-run) are
+ * skipped when there is no URL or the database is unreachable.
+ */
+export declare function planInitSteps(state: InitPlanState, flags: InitPlanFlags): InitPlanStep[];
 export declare function buildMigrateDeployOptions(_args: CliArgs): {
     allowDrift: false;
     allowDestructive: true;