@c9up/atlas 0.2.0 → 0.2.1

package/src/console/migrationCommands.ts

@@ -27,11 +27,40 @@ import {
 } from "../schema/MigrationRunner.js";
 import { getDb } from "../services/db.js";
 import { assertSafeName } from "../utils/safePath.js";
-import type { AtlasCommand } from "./schemaCheckCommand.js";
+import { type AtlasCommandClass, argument, flag } from "./contract.js";
+import {
+	generateSchemaFile,
+	type SchemaGenerateOptions,
+} from "./schemaGenerateCommand.js";
 
 export interface MigrationCommandOptions {
 	/** Directory holding the numbered migration files. */
 	migrationsDir: string;
+	/**
+	 * Sort migration files numerically (`2_x` before `10_x`). Adonis Lucid
+	 * `migrations.naturalSort`. Defaults to `false`.
+	 */
+	naturalSort?: boolean;
+	/**
+	 * Run every migration outside a transaction. Adonis Lucid
+	 * `migrations.disableTransactions`. A migration can also opt out with
+	 * `static disableTransactions = true`. Defaults to `false`.
+	 */
+	disableTransactions?: boolean;
+	/**
+	 * Regenerate the schema file after a mutating migration command
+	 * (run/rollback/reset/refresh/fresh) — Adonis Lucid's post-migration
+	 * `schema:generate`. Off unless an `outputPath` is given; on by default once
+	 * it is, unless `enabled: false`; suppress per-run with `--no-schema-generate`.
+	 */
+	schemaGeneration?: SchemaGenerateOptions;
+	/**
+	 * Default schema-dump path auto-loaded by `migration:run` / `migration:fresh`
+	 * when the target DB has no applied migrations (Adonis Lucid bootstraps from
+	 * the dump by default). Overridden per-run by `--schema-path`; a run never
+	 * loads it once migrations exist.
+	 */
+	schemaPath?: string;
 }
 
 /**
@@ -46,6 +75,9 @@ function toAdapter(conn: AsyncDatabaseConnection): DatabaseAdapter {
 		},
 		query: (sql, params) => conn.query(sql, params),
 		runInTransaction: (batch) => conn.runInTransaction(batch),
+		// Thread the connection's managed interactive transaction through so the
+		// runner can make this.defer() atomic and restore MySQL FK checks.
+		transaction: conn.transaction?.bind(conn),
 		close: async () => {},
 	};
 }
@@ -65,26 +97,42 @@ function resolveRunner(
 		process.exitCode = 1;
 		return undefined;
 	}
+	// Pass the connection's ACTUAL dialect — without it the runner defaults to
+	// sqlite and emits SQLite SQL (lock table, FK handling, DDL) against a
+	// Postgres/MySQL database.
 	return new MigrationRunner(toAdapter(db), {
 		migrationsDir: options.migrationsDir,
+		dialect: db.dialect,
+		naturalSort: options.naturalSort,
+		disableTransactions: options.disableTransactions,
 	});
 }
 
 /** `migration:run` — apply every pending migration. */
 export function migrationRunCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "migration:run",
-		description: "Run all pending migrations",
-		async run() {
+): AtlasCommandClass {
+	return class MigrationRun {
+		static commandName = "migration:run";
+		static description =
+			"Run all pending migrations (--schema-path to bootstrap from a dump)";
+		static options = { startApp: true };
+		static flags = [schemaPathOption(), noSchemaGenerateFlag()];
+
+		declare schemaPath?: string;
+		declare noSchemaGenerate: boolean;
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
-			const ran = await runner.migrate();
+			const ran = await runner.migrate({
+				schemaPath: this.schemaPath ?? options.schemaPath,
+			});
 			console.log(
 				ran.length ? `Migrated: ${ran.join(", ")}` : "Already up to date",
 			);
-		},
+			await maybeRegenSchema(options, this);
+		}
 	};
 }
 
@@ -94,39 +142,57 @@ export function migrationRunCommand(
  */
 export function migrationRollbackCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "migration:rollback",
-		description: "Roll back the latest batch (or --batch=N)",
-		async run(_args, flags) {
+): AtlasCommandClass {
+	return class MigrationRollback {
+		static commandName = "migration:rollback";
+		static description =
+			"Roll back the latest batch (or --batch=N; --force in prod)";
+		static options = { startApp: true };
+		static flags = [
+			flag("batch", "number", {
+				description: "Roll back everything applied after batch N (0 = all)",
+			}),
+			forceFlag(),
+			noSchemaGenerateFlag(),
+		];
+
+		declare batch?: number;
+		declare force: boolean;
+		declare noSchemaGenerate: boolean;
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
-			const batch = parseBatchFlag(flags.batch);
+			const batch = parseBatchFlag(this.batch);
 			if (batch === "invalid") {
 				console.error("[atlas] --batch must be a non-negative integer");
 				process.exitCode = 1;
 				return;
 			}
+			const force = this.force === true;
 			const rolled = await runner.rollback(
-				batch === undefined ? {} : { batch },
+				batch === undefined ? { force } : { batch, force },
 			);
 			console.log(
 				rolled.length
 					? `Rolled back: ${rolled.join(", ")}`
 					: "Nothing to roll back",
 			);
-		},
+			await maybeRegenSchema(options, this);
+		}
 	};
 }
 
 /** `migration:status` — list every migration and whether it is applied. */
 export function migrationStatusCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "migration:status",
-		description: "Show applied and pending migrations",
-		async run() {
+): AtlasCommandClass {
+	return class MigrationStatus {
+		static commandName = "migration:status";
+		static description = "Show applied and pending migrations";
+		static options = { startApp: true };
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
 			const rows = await runner.status();
@@ -138,57 +204,135 @@ export function migrationStatusCommand(
 				const batch = row.batch === undefined ? "" : ` (batch ${row.batch})`;
 				console.log(`${row.status.padEnd(8)} ${row.name}${batch}`);
 			}
-		},
+		}
 	};
 }
 
 /** `migration:reset` — roll back every applied migration. */
 export function migrationResetCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "migration:reset",
-		description: "Roll back all migrations",
-		async run() {
+): AtlasCommandClass {
+	return class MigrationReset {
+		static commandName = "migration:reset";
+		static description =
+			"Roll back all migrations (--force to override prod guard)";
+		static options = { startApp: true };
+		static flags = [forceFlag(), noSchemaGenerateFlag()];
+
+		declare force: boolean;
+		declare noSchemaGenerate: boolean;
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
-			const rolled = await runner.reset();
+			const rolled = await runner.reset({ force: this.force === true });
 			console.log(
 				rolled.length
 					? `Rolled back: ${rolled.join(", ")}`
 					: "Nothing to reset",
 			);
-		},
+			await maybeRegenSchema(options, this);
+		}
+	};
+}
+
+/** `migration:unlock` — force-clear a stuck migration lock (Lucid `migration:unlock`). */
+export function migrationUnlockCommand(
+	options: MigrationCommandOptions,
+): AtlasCommandClass {
+	return class MigrationUnlock {
+		static commandName = "migration:unlock";
+		static description = "Force-clear a stuck migration lock";
+		static options = { startApp: true };
+
+		async run(): Promise<void> {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const cleared = await runner.forceUnlock();
+			console.log(
+				cleared ? "Migration lock cleared" : "No migration lock was held",
+			);
+		}
+	};
+}
+
+/** `migration:fresh` — drop every table, then re-run all migrations (Lucid `migration:fresh`). */
+export function migrationFreshCommand(
+	options: MigrationCommandOptions,
+): AtlasCommandClass {
+	return class MigrationFresh {
+		static commandName = "migration:fresh";
+		static description =
+			"Drop all tables, then re-run every migration (--force to override prod guard)";
+		static options = { startApp: true };
+		static flags = [forceFlag(), schemaPathOption(), noSchemaGenerateFlag()];
+
+		declare force: boolean;
+		declare schemaPath?: string;
+		declare noSchemaGenerate: boolean;
+
+		async run(): Promise<void> {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const { executed } = await runner.fresh({
+				force: this.force === true,
+				schemaPath: this.schemaPath ?? options.schemaPath,
+			});
+			console.log(
+				executed.length
+					? `Dropped all tables, re-ran: ${executed.join(", ")}`
+					: "Dropped all tables (no migrations to run)",
+			);
+			await maybeRegenSchema(options, this);
+		}
 	};
 }
 
 /** `migration:refresh` — roll everything back, then re-run all migrations. */
 export function migrationRefreshCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "migration:refresh",
-		description: "Roll back all migrations, then re-run them",
-		async run() {
+): AtlasCommandClass {
+	return class MigrationRefresh {
+		static commandName = "migration:refresh";
+		static description =
+			"Roll back all migrations, then re-run them (--force to override prod guard)";
+		static options = { startApp: true };
+		static flags = [forceFlag(), noSchemaGenerateFlag()];
+
+		declare force: boolean;
+		declare noSchemaGenerate: boolean;
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
-			const { rolled, executed } = await runner.refresh();
+			const { rolled, executed } = await runner.refresh({
+				force: this.force === true,
+			});
 			console.log(`Rolled back: ${rolled.length}, re-ran: ${executed.length}`);
-		},
+			await maybeRegenSchema(options, this);
+		}
 	};
 }
 
 /** `db:wipe` — drop every table, including the migrations bookkeeping table. */
-export function dbWipeCommand(options: MigrationCommandOptions): AtlasCommand {
-	return {
-		name: "db:wipe",
-		description: "Drop all tables (including the migrations table)",
-		async run() {
+export function dbWipeCommand(
+	options: MigrationCommandOptions,
+): AtlasCommandClass {
+	return class DbWipe {
+		static commandName = "db:wipe";
+		static description =
+			"Drop all tables including the migrations table (--force to override prod guard)";
+		static options = { startApp: true };
+		static flags = [forceFlag()];
+
+		declare force: boolean;
+
+		async run(): Promise<void> {
 			const runner = resolveRunner(options);
 			if (!runner) return;
-			await runner.wipe();
+			await runner.wipe({ force: this.force === true });
 			console.log("Dropped all tables");
-		},
+		}
 	};
 }
 
@@ -217,42 +361,88 @@ export default class extends Migration {
  */
 export function makeMigrationCommand(
 	options: MigrationCommandOptions,
-): AtlasCommand {
-	return {
-		name: "make:migration",
-		description: "Scaffold a new timestamped migration file",
-		async run(args) {
-			const name = args[0];
-			if (!name) {
-				console.error("[atlas] usage: make:migration <name>");
-				process.exitCode = 1;
-				return;
-			}
+): AtlasCommandClass {
+	return class MakeMigration {
+		static commandName = "make:migration";
+		static description = "Scaffold a new timestamped migration file";
+		// Filesystem only — no connection needed.
+		static options = { startApp: false };
+		static args = [argument("name", { description: "Migration file name" })];
+
+		declare name: string;
+
+		async run(): Promise<void> {
+			// A missing name never reaches here: the kernel reports the required
+			// argument by name before `run()`.
 			try {
-				assertSafeName(name, "MIGRATION_INVALID", "migration");
+				assertSafeName(this.name, "MIGRATION_INVALID", "migration");
 			} catch {
-				console.error(`[atlas] invalid migration name: ${name}`);
+				console.error(`[atlas] invalid migration name: ${this.name}`);
 				process.exitCode = 1;
 				return;
 			}
-			const fileName = `${Date.now()}_${name}.ts`;
+			const fileName = `${Date.now()}_${this.name}.ts`;
 			const filePath = path.join(options.migrationsDir, fileName);
 			await fsp.mkdir(options.migrationsDir, { recursive: true });
 			await fsp.writeFile(filePath, MIGRATION_STUB, { flag: "wx" });
 			console.log(`Created ${filePath}`);
-		},
+		}
 	};
 }
 
+/**
+ * Flags shared by several migration commands.
+ *
+ * Declared per command rather than inherited: `migration:status` takes neither
+ * `--force` nor `--schema-path`, and listing them anyway would put flags in its
+ * help that it ignores.
+ */
+const forceFlag = () =>
+	flag("force", "boolean", {
+		description: "Override the production guard",
+	});
+
+const schemaPathOption = () =>
+	flag("schemaPath", "string", {
+		description: "Bootstrap from a schema dump before migrating",
+	});
+
+const noSchemaGenerateFlag = () =>
+	flag("noSchemaGenerate", "boolean", {
+		description: "Skip regenerating the schema file afterwards",
+	});
+
+/**
+ * Regenerate the schema file after a mutating migration command (Adonis Lucid's
+ * post-migration `schema:generate`) — unless it's disabled, has no `outputPath`,
+ * or the run passed `--no-schema-generate`.
+ */
+async function maybeRegenSchema(
+	options: MigrationCommandOptions,
+	command: { noSchemaGenerate?: boolean },
+): Promise<void> {
+	const cfg = options.schemaGeneration;
+	// Opt-in by configuring an outputPath; then ON unless explicitly disabled —
+	// Adonis Lucid presents `enabled: false` as the OFF switch (default on).
+	if (!cfg?.outputPath || cfg.enabled === false) return;
+	if (command.noSchemaGenerate === true) return;
+	const db = getDb();
+	if (!db) return;
+	const n = await generateSchemaFile(db, cfg);
+	console.log(
+		`Regenerated ${cfg.outputPath} (${n} table${n === 1 ? "" : "s"})`,
+	);
+}
+
 /**
  * Parse the `--batch` flag: absent → undefined (default rollback), a
  * non-negative integer string → that number, anything else → `"invalid"`.
  */
 function parseBatchFlag(
-	value: string | boolean | undefined,
+	value: number | undefined,
 ): number | undefined | "invalid" {
-	if (value === undefined || value === true) return undefined;
-	if (value === false) return "invalid";
-	const n = Number(value);
-	return Number.isInteger(n) && n >= 0 ? n : "invalid";
+	// The kernel already rejected a non-numeric `--batch`; what is left to check
+	// is that the number is a non-negative integer.
+	if (value === undefined) return undefined;
+	return Number.isInteger(value) && value >= 0 ? value : "invalid";
 }

package/src/console/schemaCheckCommand.ts

@@ -1,33 +1,29 @@
 /**
  * `atlas:check` console command — the Ream-idiomatic CLI for schema
- * verification. Ream commands are plain `{ name, description, run }` objects
- * registered in `reamrc.commands` and dispatched by the console kernel
- * (`new Ignitor(...).console().handle(argv)`).
+ * verification. Ream commands are classes carrying their name, description and
+ * inputs as statics; the console kernel discovers them in `commands/` or reads
+ * them from `reamrc.commands`.
  *
  * Stays framework-agnostic: resolves the live connection + dialect from atlas's
  * OWN service locators (`getDb` / `getAtlasDialect`), never importing
- * `@c9up/ream`. The {@link AtlasCommand} shape structurally matches Ream's
- * `Command` interface, so the console kernel accepts it without a type
- * dependency in either direction.
+ * `@c9up/ream`. The {@link AtlasCommandClass} shape structurally matches Ream's
+ * command contract, so the console kernel accepts it without a type dependency
+ * in either direction.
  */
 
 import { getAtlasDialect } from "../query/native.js";
 import { runSchemaCheck } from "../schema/SchemaCheck.js";
 import { getDb } from "../services/db.js";
+import { type AtlasCommandClass, flag } from "./contract.js";
 
 type Constructor = new (...args: unknown[]) => unknown;
 
-/** Structural match of Ream's console `Command` (no `@c9up/ream` import). */
-export interface AtlasCommand {
-	name: string;
-	description: string;
-	run(args: string[], flags: Record<string, string | boolean>): Promise<void>;
-}
+export type { AtlasCommandClass } from "./contract.js";
 
 /**
  * Build the `atlas:check` command for the given models. Register it in
  * `reamrc.commands` (atlas has no global entity registry — list your models,
- * as in Lucid). Run it via the console kernel; `--warn` reports drift without a
+ * as in Lucid). Run it as `ream atlas:check`; `--warn` reports drift without a
  * non-zero exit (useful for an advisory CI step).
  *
  * @example
@@ -36,16 +32,24 @@ export interface AtlasCommand {
  *   import { User } from '#models/user'
  *   export default schemaCheckCommand([User])
  *
- *   // reamrc.ts → commands: [() => import('./commands/atlas-check.js')]
- *   // run:  <console-entry> atlas:check
+ *   // run:  ream atlas:check --warn
  */
 export function schemaCheckCommand(
 	entities: readonly Constructor[],
-): AtlasCommand {
-	return {
-		name: "atlas:check",
-		description: "Verify models match the live database schema",
-		async run(_args, flags) {
+): AtlasCommandClass {
+	return class SchemaCheck {
+		static commandName = "atlas:check";
+		static description = "Verify models match the live database schema";
+		static options = { startApp: true };
+		static flags = [
+			flag("warn", "boolean", {
+				description: "Report drift without failing (exit 0)",
+			}),
+		];
+
+		declare warn: boolean;
+
+		async run(): Promise<void> {
 			const db = getDb();
 			if (!db) {
 				console.error(
@@ -56,7 +60,7 @@ export function schemaCheckCommand(
 			}
 			const code = await runSchemaCheck(entities, db, getAtlasDialect());
 			// `--warn` downgrades drift to advisory (exit 0); default fails CI.
-			if (code !== 0 && !flags.warn) process.exitCode = code;
-		},
+			if (code !== 0 && !this.warn) process.exitCode = code;
+		}
 	};
 }

package/src/console/schemaDumpCommand.ts

@@ -0,0 +1,96 @@
+/**
+ * `schema:dump` — serialise the live database's schema to a `.sql` dump + a
+ * `.meta.json` manifest (Adonis Lucid `schema:dump` / `SchemaDumper`), so a
+ * fresh database can be rebuilt from the dump via `migration:run --schema-path`
+ * instead of replaying every migration.
+ *
+ * @example
+ *   // commands/schema-dump.ts
+ *   import { schemaDumpCommand } from '@c9up/atlas'
+ *   export default schemaDumpCommand({ migrationsDir: 'database/migrations' })
+ *   // run:  <console-entry> schema:dump            → database/schema/default-schema.sql
+ *          //                 schema:dump --prune   → also squashes the migration files
+ */
+
+import { SchemaDumper } from "../schema/SchemaDumper.js";
+import { getConnection, getDb } from "../services/db.js";
+import { type AtlasCommandClass, flag } from "./contract.js";
+
+export interface SchemaDumpCommandOptions {
+	/** Directory the dump + manifest are written to. Default `"database/schema"`. */
+	outputDir?: string;
+	/** Migration directory — required for `--prune` (the files it collapses). */
+	migrationsDir?: string;
+	/** Migration bookkeeping table name. Default `"ream_migrations"`. */
+	schemaTableName?: string;
+	/**
+	 * Timestamp string for the manifest. `Date.now()`/`new Date()` are unavailable
+	 * in some atlas contexts, so pass one in when you need a deterministic value.
+	 */
+	generatedAt?: string;
+}
+
+/** `schema:dump` — dump the schema; `--prune` squashes migrations, `--connection` targets one. */
+export function schemaDumpCommand(
+	options: SchemaDumpCommandOptions = {},
+): AtlasCommandClass {
+	return class SchemaDump {
+		static commandName = "schema:dump";
+		static description =
+			"Dump the database schema to a .sql file + manifest (--prune, --connection, --path)";
+		static options = { startApp: true };
+		static flags = [
+			flag("connection", "string", {
+				description: "Named connection to dump (defaults to the primary one)",
+			}),
+			flag("prune", "boolean", {
+				description: "Squash the migrations the dump replaces",
+			}),
+			flag("path", "string", {
+				description: "Destination .sql file (not a directory)",
+			}),
+		];
+
+		declare connection?: string;
+		declare prune: boolean;
+		declare path?: string;
+
+		async run(): Promise<void> {
+			const connName = this.connection;
+			const db = connName ? getConnection(connName) : getDb();
+			if (!db) {
+				console.error(
+					connName
+						? `[atlas] no connection registered under '${connName}'`
+						: "[atlas] no database connection — is AtlasProvider registered?",
+				);
+				process.exitCode = 1;
+				return;
+			}
+			// Typed by the kernel now — no string/boolean coercion to redo here.
+			const prune = this.prune === true;
+			// `--path <file>` is the SQL dump FILE path (Adonis Lucid), not a dir.
+			const dumpPath = this.path;
+			const dumper = new SchemaDumper(db, {
+				connectionName: connName ?? "default",
+				dumpPath,
+				outputDir: options.outputDir,
+				migrationsDir: options.migrationsDir,
+				schemaTableName: options.schemaTableName,
+				prune,
+				generatedAt: options.generatedAt,
+			});
+			await dumper.run();
+			if (dumper.error) {
+				console.error(`[atlas] schema:dump failed: ${dumper.error.message}`);
+				process.exitCode = 1;
+				return;
+			}
+			const r = dumper.result;
+			console.log(
+				`Dumped ${r?.tableCount ?? 0} table(s) → ${r?.dumpPath}` +
+					(prune ? " (migrations squashed)" : ""),
+			);
+		}
+	};
+}