@stacksjs/database 0.70.204 → 0.70.206

package/dist/index.d.ts

@@ -105,6 +105,9 @@ export * from './defaults';
 // Dialect classification for the committed migration corpus, so a corpus
 // emitted for one database fails loudly before a single statement runs.
 export * from './migration-dialect';
+// Model resolution for the generator: userland + framework defaults, flattened
+// because bun-query-builder's loadModels reads only the top level of a dir.
+export * from './model-sources';
 // Database bootstrap: probe the target, and create it over a maintenance
 // connection we open ourselves rather than through bun-query-builder, whose
 // connection string is rebuilt from process.env and cannot be redirected.

package/dist/index.js

@@ -29,6 +29,7 @@ export { migrateRbacTables } from "./rbac-tables";
 export * from "./sql-helpers";
 export * from "./defaults";
 export * from "./migration-dialect";
+export * from "./model-sources";
 export * from "./ensure-database";
 export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from "./fk-audit";
 export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from "./unique-audit";

package/dist/migration-dialect.js

@@ -97,8 +97,9 @@ export function formatMigrationDialectError(audit, target, dir) {
     "Nothing was migrated, so the database is unchanged.",
     "",
     "Stacks ships one set of migration files, and they are emitted for a single database.",
-    `To use ${target}, regenerate them from your models against ${target}, or point`,
-    "DB_CONNECTION back at the database they were written for.",
+    "Regenerate them from your models:",
+    `  ./buddy migrate:regenerate ${target}`,
+    "or point DB_CONNECTION back at the database they were written for.",
     "",
     `If you know this corpus is correct, re-run with ${DIALECT_OVERRIDE_ENV}=1 to proceed anyway.`
   ].join(`

package/dist/migrations.d.ts

@@ -45,6 +45,27 @@ export declare function preprocessSqliteMigrations(): void;
 export declare function ensureDatabaseReady(): Promise<void>;
 /** Test seam: forget that the bootstrap already ran. */
 export declare function resetDatabaseBootstrapCache(): void;
+/**
+ * Count how many migrations have been recorded as applied in the
+ * `migrations` table. Returns 0 when the table doesn't exist yet
+ * (fresh database, first ever migration) — bun-query-builder
+ * creates the table during the first `executeMigration` call.
+ *
+ * Used by {@link runDatabaseMigration} before + after the migration
+ * run so the caller can report `applied = afterCount - beforeCount`
+ * — distinguishes the "nothing to migrate" path from a real apply
+ * in the CLI outro (user-reported messaging gap).
+ */
+/**
+ * How many migrations the target database has already recorded.
+ *
+ * Exported because regeneration must refuse to renumber a corpus that a live
+ * database has bookkeeping against: the migrations table keys on the FILENAME,
+ * so renaming files makes an applied migration look pending. One of them,
+ * 0000000098-revoke-legacy-long-lived-tokens.sql, is a hard
+ * `DELETE FROM oauth_access_tokens`, so a careless renumber re-runs a data wipe.
+ */
+export declare function countAppliedMigrations(): Promise<number>;
 export declare function runDatabaseMigration(): Promise<Result<string, Error>>;
 /**
  * Reset the database (drop all tables)
@@ -58,6 +79,38 @@ export declare function resetDatabase(): Promise<Result<string, Error>>;
  */
 export declare function previewPendingMigrations(options?: GenerateMigrationsOptions): Promise<MigrationOperation[]>;
 export declare function generateMigrations(options?: GenerateMigrationsOptions): Promise<Result<string, Error>>;
+/**
+ * Write generated SQL to `database/migrations/` so the runner picks it up.
+ * Returns the number of files written.
+ */
+/**
+ * Enum types a generated corpus USES but never DEFINES.
+ *
+ * Postgres enums have to exist before a column can be typed with them, so a
+ * dangling reference is a guaranteed mid-migration failure rather than a
+ * cosmetic problem.
+ */
+export declare function findDanglingTypeReferences(statements: string[]): string[];
+/**
+ * Rebuild the whole migration corpus for one dialect, from the models.
+ *
+ * This is the fix for a corpus that cannot run on the configured database.
+ * Translating the committed SQLite DDL was never viable: the emission threw
+ * away varchar lengths, numeric scale and every foreign key (40 of them are
+ * `SELECT 1;` stubs). All of that still exists in the model definitions, so
+ * regenerating recovers the intent instead of guessing at it.
+ *
+ * Unlike `persistGeneratedMigrations`, which appends a diff on top of what is
+ * already committed, this produces a COMPLETE corpus numbered from 1 and
+ * replaces what is there. Callers are responsible for confirming that with the
+ * user, and for refusing when the target database already has migrations
+ * recorded against the old filenames.
+ */
+export declare function regenerateMigrationCorpus(options?: {
+  dialect?: string
+  dir?: string
+  dryRun?: boolean
+}): Promise<Result<RegeneratedCorpus, Error>>;
 /**
  * Group generated SQL by the migration filename style the runner already
  * uses for hand-written files: `create-<table>-table`,
@@ -85,6 +138,13 @@ export declare interface GenerateMigrationsOptions {
   applyRenames?: boolean
   fromDb?: boolean
 }
+export declare interface RegeneratedCorpus {
+  dialect: string
+  models: number
+  files: Array<{ name: string, statements: number }>
+  removed: string[]
+  dir: string
+}
 declare interface GeneratedGroup {
   label: string
   statements: string[]

package/dist/migrations.js

@@ -1,4 +1,4 @@
-var {require}=import.meta;import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+var {require}=import.meta;import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { log as _log } from "@stacksjs/logging";
 const log = {
@@ -29,6 +29,7 @@ import {
   probeTargetDatabase,
   resolveConnectionTarget
 } from "./ensure-database";
+import { resolveModelSources } from "./model-sources";
 import { frameworkManagedColumns, withoutManagedColumnDrops, withoutManagedColumnDropSql } from "./managed-columns";
 import { acquireMigrationLock } from "./migration-lock";
 import { env as envVars } from "@stacksjs/env";
@@ -303,7 +304,7 @@ async function restoreHiddenMigrations(hidden) {
       await fs.rename(h, original);
     } catch {}
 }
-async function countAppliedMigrations() {
+export async function countAppliedMigrations() {
   try {
     const row = await db.selectFrom("migrations").select((eb) => eb.fn.count("id").as("n")).executeTakeFirst();
     if (!row)
@@ -492,9 +493,11 @@ export async function previewPendingMigrations(options = {}) {
     return [];
   }
 }
+function snapshotDirLabel() {
+  return qbConfig?.snapshotDir || QB_SNAPSHOT_DIR;
+}
 function resolveSnapshotDir() {
-  const configured = qbConfig?.snapshotDir;
-  return join(process.cwd(), configured || QB_SNAPSHOT_DIR);
+  return join(process.cwd(), snapshotDirLabel());
 }
 function detectSnapshotDialectMismatch(dialect) {
   const qbDir = resolveSnapshotDir();
@@ -519,8 +522,10 @@ export async function generateMigrations(options = {}) {
     log.debug("Generating migrations...");
     configureQueryBuilder();
     const dialect = getDialect(), mismatch = detectSnapshotDialectMismatch(dialect);
-    if (mismatch)
-      return err(Error(`Refusing to generate migrations: resolved dialect "${dialect}" has no snapshot in .qb/, but "${mismatch}" does. DB_CONNECTION is likely unset or wrong (missing .env?) \u2014 ` + `generating now would write a full duplicate migration set in the wrong dialect. Set DB_CONNECTION=${mismatch} (or your intended dialect) and retry. To intentionally start a new dialect from scratch, remove .qb/model-snapshot.${mismatch}.json first.`));
+    if (mismatch) {
+      const snapshotDir = snapshotDirLabel();
+      return err(Error(`Refusing to generate migrations: resolved dialect "${dialect}" has no snapshot in ${snapshotDir}/, but "${mismatch}" does. DB_CONNECTION is likely unset or wrong ` + "(missing .env?) \u2014 generating now would write a full duplicate migration set in the " + `wrong dialect. Set DB_CONNECTION=${mismatch} (or your intended dialect) and retry. To intentionally start a new dialect from scratch, remove ${snapshotDir}/model-snapshot.${mismatch}.json first.`));
+    }
     const { modelsDir, skip } = prepareMigrationModelsDir();
     if (skip) {
       log.debug("No app/Models directory found; using committed framework migrations");
@@ -550,6 +555,72 @@ export async function generateMigrations(options = {}) {
     return err(handleError("Migration generation failed", error));
   }
 }
+export function findDanglingTypeReferences(statements) {
+  const defined = new Set, referenced = new Set;
+  for (const statement of statements) {
+    for (const match of statement.matchAll(/CREATE\s+TYPE\s+"([^"]+)"/gi))
+      defined.add(match[1]);
+    for (const match of statement.matchAll(/\bTYPE\s+"([^"]+)"/gi))
+      referenced.add(match[1]);
+  }
+  return [...referenced].filter((name) => !defined.has(name)).sort();
+}
+export async function regenerateMigrationCorpus(options = {}) {
+  try {
+    configureQueryBuilder();
+    const dialect = options.dialect ?? getQbDialect(), dir = options.dir ?? join(process.cwd(), "database", "migrations"), sources = resolveModelSources();
+    if (!sources)
+      return err(Error("No models found. Define models in app/Models, or ensure the framework defaults at storage/framework/defaults/app/Models are present."));
+    try {
+      writeFileSync(join(sources.dir, `.qb-migrations.${dialect}.json`), JSON.stringify({ plan: { dialect, tables: [] } }));
+    } catch {}
+    const snapshotPath = join(resolveSnapshotDir(), `model-snapshot.${dialect}.json`), parkedSnapshot = `${snapshotPath}.regenerating`;
+    let snapshotParked = !1;
+    if (existsSync(snapshotPath))
+      try {
+        renameSync(snapshotPath, parkedSnapshot);
+        snapshotParked = !0;
+      } catch {}
+    let result;
+    try {
+      result = await qbGenerateMigration(sources.dir, { dialect, dryRun: !0 });
+    } finally {
+      if (snapshotParked)
+        try {
+          renameSync(parkedSnapshot, snapshotPath);
+        } catch {}
+    }
+    const statements = result.sqlStatements ?? [];
+    if (statements.length === 0)
+      return err(Error(`The generator produced no SQL for dialect "${dialect}".`));
+    const dangling = findDanglingTypeReferences(statements);
+    if (dangling.length > 0)
+      return err(Error(`The generator emitted ${dangling.length} reference(s) to enum type(s) it never creates: ${dangling.slice(0, 5).join(", ")}${dangling.length > 5 ? `, +${dangling.length - 5} more` : ""}. Writing this corpus would fail partway through a migration. This is a bug in the migration generator, not in your models.`));
+    const groups = groupGeneratedStatements(statements);
+    let existing = [];
+    try {
+      existing = readdirSync(dir).filter((f) => f.endsWith(".sql")).sort();
+    } catch {}
+    const files = groups.map((group, index) => ({
+      name: `${String(index + 1).padStart(10, "0")}-${group.label}.sql`,
+      statements: group.statements.length
+    }));
+    if (options.dryRun)
+      return ok({ dialect, models: sources.models.length, files, removed: existing, dir });
+    mkdirSync(dir, { recursive: !0 });
+    for (const file of existing)
+      unlinkSync(join(dir, file));
+    groups.forEach((group, index) => {
+      const body = `${group.statements.map((s) => s.trim().replace(/;\s*$/, "")).join(`;
+`)};
+`;
+      writeFileSync(join(dir, files[index].name), body);
+    });
+    return ok({ dialect, models: sources.models.length, files, removed: existing, dir });
+  } catch (error) {
+    return err(handleError("Migration regeneration failed", error));
+  }
+}
 function persistGeneratedMigrations(sqlStatements) {
   if (!sqlStatements?.length)
     return 0;

package/dist/model-sources.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where the flattened copy lives. Under the framework runtime directory rather
+ * than the OS temp dir so it is inspectable when a generation goes wrong, and
+ * so it lands on the same filesystem as the source.
+ */
+export declare function modelStagingDir(): string;
+/**
+ * Resolve models from userland and framework defaults.
+ *
+ * Returns `null` when neither root holds a model, which callers should treat as
+ * "nothing to generate from" rather than as an error: it is the legitimate
+ * state of a project that has not defined any models yet.
+ */
+export declare function resolveModelSources(options?: { userRoot?: string, frameworkRoot?: string }): ResolvedModelSources | null;
+/** Remove the staging directory. Safe to call when it was never created. */
+export declare function cleanupModelStaging(): void;
+export declare interface ModelSource {
+  file: string
+  name: string
+  origin: 'user' | 'framework'
+}
+export declare interface ResolvedModelSources {
+  dir: string
+  models: ModelSource[]
+  roots: string[]
+  staged: boolean
+}

package/dist/model-sources.js

@@ -0,0 +1,76 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { path } from "@stacksjs/path";
+function collectModels(root, origin) {
+  if (!existsSync(root))
+    return [];
+  const out = [], walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: !0 });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith(".ts"))
+        continue;
+      if (entry.name.startsWith(".") || entry.name.startsWith("index"))
+        continue;
+      out.push({ file: full, name: entry.name.replace(/\.ts$/, ""), origin });
+    }
+  };
+  walk(root);
+  return out;
+}
+export function modelStagingDir() {
+  return path.frameworkRuntimePath("model-sources");
+}
+function stage(models) {
+  const dir = modelStagingDir();
+  try {
+    rmSync(dir, { recursive: !0, force: !0 });
+  } catch {}
+  mkdirSync(dir, { recursive: !0 });
+  for (const model of models) {
+    const target = join(dir, `${model.name}.ts`);
+    try {
+      symlinkSync(model.file, target);
+    } catch {
+      try {
+        writeFileSync(target, readFileSync(model.file));
+      } catch {}
+    }
+  }
+  return dir;
+}
+export function resolveModelSources(options = {}) {
+  const userRoot = options.userRoot ?? path.userModelsPath(), frameworkRoot = options.frameworkRoot ?? path.frameworkPath("defaults/app/Models"), user = collectModels(userRoot, "user"), framework = collectModels(frameworkRoot, "framework");
+  if (user.length === 0 && framework.length === 0)
+    return null;
+  const byName = new Map;
+  for (const model of framework)
+    byName.set(model.name, model);
+  for (const model of user)
+    byName.set(model.name, model);
+  const models = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)), roots = [];
+  if (user.length > 0)
+    roots.push(userRoot);
+  if (framework.length > 0)
+    roots.push(frameworkRoot);
+  const onlyUser = framework.length === 0, allFlat = models.every((m) => basename(join(m.file, "..")) === basename(onlyUser ? userRoot : frameworkRoot));
+  if (roots.length === 1 && allFlat)
+    return { dir: roots[0], models, roots, staged: !1 };
+  return { dir: stage(models), models, roots, staged: !0 };
+}
+export function cleanupModelStaging() {
+  const dir = modelStagingDir();
+  try {
+    if (existsSync(dir) && lstatSync(dir).isDirectory())
+      rmSync(dir, { recursive: !0, force: !0 });
+  } catch {}
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.204",
+  "version": "0.70.206",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,19 +56,19 @@
   },
   "dependencies": {
     "@stacksjs/ts-validation": "^0.5.0",
-    "bun-query-builder": "^0.1.59",
+    "bun-query-builder": "^0.1.63",
     "dynamodb-tooling": "^0.3.2"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.204",
-    "@stacksjs/config": "0.70.204",
-    "@stacksjs/logging": "0.70.204",
-    "@stacksjs/router": "0.70.204",
+    "@stacksjs/cli": "0.70.206",
+    "@stacksjs/config": "0.70.206",
+    "@stacksjs/logging": "0.70.206",
+    "@stacksjs/router": "0.70.206",
     "better-dx": "^0.2.17",
-    "@stacksjs/path": "0.70.204",
-    "@stacksjs/query-builder": "0.70.204",
-    "@stacksjs/storage": "0.70.204",
-    "@stacksjs/strings": "0.70.204",
-    "@stacksjs/utils": "0.70.204"
+    "@stacksjs/path": "0.70.206",
+    "@stacksjs/query-builder": "0.70.206",
+    "@stacksjs/storage": "0.70.206",
+    "@stacksjs/strings": "0.70.206",
+    "@stacksjs/utils": "0.70.206"
   }
 }