@getstrata/core 2.2.18 → 2.2.21

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @getstrata/core changelog
 
+## 2.2.21
+
+Make registered queue/outbox workers discoverable in CLI help and generated startup guidance. Announce polling after boot and when it stops without claiming dependency health, printing secrets, or starting workers automatically. Preserve explicit process ownership, delivery semantics and graceful lifecycle; cover idle, boot/runtime/cleanup failures and real SIGTERM draining.
+
+## 2.2.20
+
+Validate complete migration definitions before callbacks, locks or database effects; reject malformed exports and duplicate names with source diagnostics. Refuse fresh with missing applied definitions and rollback with incomplete latest batches; preserve partial forward migration and remove blanket history deletion. Cover physical schema/data/history preservation and reset recovery on real Postgres, MySQL and SQLite, plus loader and preflight regressions; document safe missing-file recovery and unchanged atomicity limits.
+
+## 2.2.19
+
+Fix explicit development fresh resets with unfinished outbox deliveries while preserving ordinary rollback guards. Record each completed reset down immediately so later refusal leaves recoverable migration progress; document partial-DDL/crash limits and old-history reconciliation. Add independent outbox-state and reset failure/migrate/retry regressions on real Postgres, MySQL and SQLite, history-write/reapplication fault injection, and a documented stateful regression review flow.
+
 ## 2.2.18
 
 Add optional typed guardMigrationRollback for application-owned rollback history predicates; skip history reads only during explicit development fresh resets, propagate predicate failures, and reuse the contract for encryption-checkpoint archival protection. Document guard placement and unchanged reset/rollback safety; cover type, runner and real SQLite history regressions.

package/dist/entries/database/migrations.js

@@ -275,6 +275,28 @@ async function guardMigrationRollback(context, guard) {
 
 // ../../src/core/database/migrations/runner.ts
 var MIGRATIONS_TABLE = "framework_migrations";
+function validateMigrations(migrations, sources) {
+  if (!Array.isArray(migrations))
+    throw new Error("Migrations must be an array of definitions.");
+  const names = new Map;
+  for (const [index, migration] of migrations.entries()) {
+    const source = sources?.[index] ?? `migration at index ${index}`;
+    if (!migration || typeof migration !== "object" || Array.isArray(migration) || typeof migration.name !== "string" || migration.name.trim().length === 0 || typeof migration.up !== "function" || typeof migration.down !== "function") {
+      throw new Error(`Invalid ${source}: expected a migration with a non-empty string name and up/down functions.`);
+    }
+    const previous = names.get(migration.name);
+    if (previous !== undefined)
+      throw new Error(`Duplicate migration name "${migration.name}" in ${previous} and ${source}.`);
+    names.set(migration.name, source);
+  }
+}
+function requireMigrationDefinitions(applied, migrations, operation) {
+  const names = new Set(migrations.map(({ name }) => name));
+  const missing = applied.filter(({ name }) => !names.has(name)).map(({ name }) => name);
+  if (missing.length > 0) {
+    throw new Error(`Cannot ${operation}: missing applied migration definitions: ${missing.join(", ")}. Restore the migration files before retrying; history has not been removed.`);
+  }
+}
 function migrationsNameColumn() {
   return currentSqlDialect().driver === "mysql" ? "VARCHAR(255) PRIMARY KEY" : "TEXT PRIMARY KEY";
 }
@@ -316,15 +338,17 @@ async function getAppliedMigrations(db) {
 }
 async function loadMigrationsFromDirectory(directory) {
   const entries = await readdir(directory);
-  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && entry !== "types.ts" && entry !== "index.ts" && entry !== "runner.ts").sort();
+  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && !entry.endsWith(".d.ts") && !["types", "index", "runner", "advisoryLock", "migrationDatabase"].some((name) => entry === `${name}.ts` || entry === `${name}.js`)).sort();
   const loadedMigrations = await Promise.all(migrationFiles.map(async (fileName) => {
     const moduleUrl = pathToFileURL(join(directory, fileName)).href;
     const module = await import(moduleUrl);
     return module.default;
   }));
-  return loadedMigrations.filter((migration) => migration?.name !== undefined);
+  validateMigrations(loadedMigrations, migrationFiles.map((file) => join(directory, file)));
+  return loadedMigrations;
 }
 async function getMigrationStatus(db, migrations) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedByName = new Map(applied.map(({ name, batch }) => [name, Number(batch)]));
   return migrations.map(({ name }) => ({
@@ -334,6 +358,7 @@ async function getMigrationStatus(db, migrations) {
   }));
 }
 async function runPendingMigrations(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedNames = new Set(applied.map(({ name }) => name));
   const nextBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0) + 1;
@@ -349,6 +374,7 @@ async function runPendingMigrations(db, migrations, options = {}) {
   return pendingMigrations.length;
 }
 async function migrateDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const { advisoryLock = false, onMigration } = options;
   if (advisoryLock) {
     return withMigrationLock(db, () => runPendingMigrations(db, migrations, { onMigration }));
@@ -356,11 +382,13 @@ async function migrateDatabase(db, migrations, options = {}) {
   return runPendingMigrations(db, migrations, { onMigration });
 }
 async function rollbackDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   if (applied.length === 0) {
     return 0;
   }
   const lastBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0);
+  requireMigrationDefinitions(applied.filter(({ batch }) => Number(batch) === lastBatch), migrations, "roll back latest batch");
   const migrationsToRollback = new Set(applied.filter(({ batch }) => Number(batch) === lastBatch).map(({ name }) => name));
   let rolledBack = 0;
   for (const migration of [...migrations].reverse()) {
@@ -378,8 +406,10 @@ async function freshDatabase(db, migrations, options = {}) {
   if (options.destructive && isProductionEnv()) {
     throw new Error("Destructive migration reset is only available in development/test environments.");
   }
+  validateMigrations(migrations);
   const runFresh = async () => {
     const applied = await getAppliedMigrations(db);
+    requireMigrationDefinitions(applied, migrations, "reset database");
     const appliedNames = new Set(applied.map(({ name }) => name));
     const appliedMigrations = migrations.filter(({ name }) => appliedNames.has(name));
     for (const migration of [...appliedMigrations].reverse()) {
@@ -388,9 +418,7 @@ async function freshDatabase(db, migrations, options = {}) {
         await migration.down(db, { operation: "fresh" });
       else
         await migration.down(db);
-    }
-    if (appliedMigrations.length > 0) {
-      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE}`);
+      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE} WHERE name = ${currentSqlDialect().placeholder(1)}`, [migration.name]);
     }
     await runPendingMigrations(db, migrations, options);
   };

package/dist/index.js

@@ -7541,6 +7541,28 @@ import { join } from "path";
 import { pathToFileURL } from "url";
 init_dialect();
 var MIGRATIONS_TABLE = "framework_migrations";
+function validateMigrations(migrations, sources) {
+  if (!Array.isArray(migrations))
+    throw new Error("Migrations must be an array of definitions.");
+  const names = new Map;
+  for (const [index, migration] of migrations.entries()) {
+    const source = sources?.[index] ?? `migration at index ${index}`;
+    if (!migration || typeof migration !== "object" || Array.isArray(migration) || typeof migration.name !== "string" || migration.name.trim().length === 0 || typeof migration.up !== "function" || typeof migration.down !== "function") {
+      throw new Error(`Invalid ${source}: expected a migration with a non-empty string name and up/down functions.`);
+    }
+    const previous = names.get(migration.name);
+    if (previous !== undefined)
+      throw new Error(`Duplicate migration name "${migration.name}" in ${previous} and ${source}.`);
+    names.set(migration.name, source);
+  }
+}
+function requireMigrationDefinitions(applied, migrations, operation) {
+  const names = new Set(migrations.map(({ name }) => name));
+  const missing = applied.filter(({ name }) => !names.has(name)).map(({ name }) => name);
+  if (missing.length > 0) {
+    throw new Error(`Cannot ${operation}: missing applied migration definitions: ${missing.join(", ")}. Restore the migration files before retrying; history has not been removed.`);
+  }
+}
 function migrationsNameColumn() {
   return currentSqlDialect().driver === "mysql" ? "VARCHAR(255) PRIMARY KEY" : "TEXT PRIMARY KEY";
 }
@@ -7582,15 +7604,17 @@ async function getAppliedMigrations(db) {
 }
 async function loadMigrationsFromDirectory(directory) {
   const entries = await readdir(directory);
-  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && entry !== "types.ts" && entry !== "index.ts" && entry !== "runner.ts").sort();
+  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && !entry.endsWith(".d.ts") && !["types", "index", "runner", "advisoryLock", "migrationDatabase"].some((name) => entry === `${name}.ts` || entry === `${name}.js`)).sort();
   const loadedMigrations = await Promise.all(migrationFiles.map(async (fileName) => {
     const moduleUrl = pathToFileURL(join(directory, fileName)).href;
     const module = await import(moduleUrl);
     return module.default;
   }));
-  return loadedMigrations.filter((migration) => migration?.name !== undefined);
+  validateMigrations(loadedMigrations, migrationFiles.map((file) => join(directory, file)));
+  return loadedMigrations;
 }
 async function getMigrationStatus(db, migrations) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedByName = new Map(applied.map(({ name, batch }) => [name, Number(batch)]));
   return migrations.map(({ name }) => ({
@@ -7600,6 +7624,7 @@ async function getMigrationStatus(db, migrations) {
   }));
 }
 async function runPendingMigrations(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedNames = new Set(applied.map(({ name }) => name));
   const nextBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0) + 1;
@@ -7615,6 +7640,7 @@ async function runPendingMigrations(db, migrations, options = {}) {
   return pendingMigrations.length;
 }
 async function migrateDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const { advisoryLock = false, onMigration } = options;
   if (advisoryLock) {
     return withMigrationLock(db, () => runPendingMigrations(db, migrations, { onMigration }));
@@ -7622,11 +7648,13 @@ async function migrateDatabase(db, migrations, options = {}) {
   return runPendingMigrations(db, migrations, { onMigration });
 }
 async function rollbackDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   if (applied.length === 0) {
     return 0;
   }
   const lastBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0);
+  requireMigrationDefinitions(applied.filter(({ batch }) => Number(batch) === lastBatch), migrations, "roll back latest batch");
   const migrationsToRollback = new Set(applied.filter(({ batch }) => Number(batch) === lastBatch).map(({ name }) => name));
   let rolledBack = 0;
   for (const migration of [...migrations].reverse()) {
@@ -7644,8 +7672,10 @@ async function freshDatabase(db, migrations, options = {}) {
   if (options.destructive && isProductionEnv()) {
     throw new Error("Destructive migration reset is only available in development/test environments.");
   }
+  validateMigrations(migrations);
   const runFresh = async () => {
     const applied = await getAppliedMigrations(db);
+    requireMigrationDefinitions(applied, migrations, "reset database");
     const appliedNames = new Set(applied.map(({ name }) => name));
     const appliedMigrations = migrations.filter(({ name }) => appliedNames.has(name));
     for (const migration of [...appliedMigrations].reverse()) {
@@ -7654,9 +7684,7 @@ async function freshDatabase(db, migrations, options = {}) {
         await migration.down(db, { operation: "fresh" });
       else
         await migration.down(db);
-    }
-    if (appliedMigrations.length > 0) {
-      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE}`);
+      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE} WHERE name = ${currentSqlDialect().placeholder(1)}`, [migration.name]);
     }
     await runPendingMigrations(db, migrations, options);
   };
@@ -10312,10 +10340,14 @@ function createOutboxMigration(name, driver, options = {}) {
           SELECT 1 FROM strata_outbox_event WHERE id = strata_outbox_delivery.event_id))`);
       }
     },
-    async down(db) {
-      const [row] = await db.unsafe("SELECT COUNT(*) AS pending FROM strata_outbox_delivery WHERE status <> 'completed'");
-      if (Number(row?.pending) > 0)
-        throw new Error("Cannot drop outbox tables while undelivered events remain.");
+    async down(db, context) {
+      await guardMigrationRollback(context, {
+        async hasHistory() {
+          const [row] = await db.unsafe("SELECT COUNT(*) AS pending FROM strata_outbox_delivery WHERE status <> 'completed'");
+          return Number(row?.pending) > 0;
+        },
+        message: "Cannot drop outbox tables while undelivered events remain."
+      });
       await db.unsafe("DROP TABLE strata_outbox_delivery");
       await db.unsafe("DROP TABLE strata_outbox_event");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.18",
+  "version": "2.2.21",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",