@c9up/atlas 0.1.19 → 0.2.1

package/src/console/contract.ts

@@ -0,0 +1,96 @@
+/**
+ * The console command contract, declared locally.
+ *
+ * Atlas stays framework-agnostic: it must not import `@c9up/ream`, so it
+ * describes the shape Ream's console kernel dispatches against rather than
+ * importing it. Same reasoning as the previous `AtlasCommand` interface — only
+ * the shape changed, from a plain object to a class carrying its inputs as
+ * metadata.
+ *
+ * Ream's decorators (`@args` / `@flags`) live in the framework, so the helpers
+ * below build the same metadata without them.
+ */
+
+export interface CommandOptions {
+	/** Boot the application before `run()`. Off by default. */
+	startApp?: boolean;
+	staysAlive?: boolean;
+	allowUnknownFlags?: boolean;
+}
+
+export interface ArgumentMetaData {
+	type: "string" | "spread";
+	propertyName: string;
+	argumentName: string;
+	description?: string;
+	required: boolean;
+	default?: string | string[];
+}
+
+export interface FlagMetaData {
+	type: "string" | "boolean" | "number" | "array";
+	propertyName: string;
+	flagName: string;
+	description?: string;
+	alias: string[];
+	default?: string | string[] | number | boolean;
+	required: boolean;
+}
+
+/** The static side the kernel reads. */
+export interface AtlasCommandClass {
+	new (): { run(): Promise<void> | void };
+	commandName: string;
+	description: string;
+	options?: CommandOptions;
+	args?: readonly ArgumentMetaData[];
+	flags?: readonly FlagMetaData[];
+	help?: string | string[];
+}
+
+/** `startServer` → `start-server`, matching the framework's decorators. */
+function dashCase(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+export function flag(
+	propertyName: string,
+	type: FlagMetaData["type"],
+	options: {
+		flagName?: string;
+		description?: string;
+		alias?: string[];
+		default?: FlagMetaData["default"];
+		required?: boolean;
+	} = {},
+): FlagMetaData {
+	return {
+		type,
+		propertyName,
+		flagName: options.flagName ?? dashCase(propertyName),
+		description: options.description,
+		alias: options.alias ?? [],
+		default: options.default,
+		required: options.required ?? false,
+	};
+}
+
+export function argument(
+	propertyName: string,
+	options: {
+		type?: ArgumentMetaData["type"];
+		argumentName?: string;
+		description?: string;
+		required?: boolean;
+		default?: ArgumentMetaData["default"];
+	} = {},
+): ArgumentMetaData {
+	return {
+		type: options.type ?? "string",
+		propertyName,
+		argumentName: options.argumentName ?? dashCase(propertyName),
+		description: options.description,
+		required: options.required ?? options.default === undefined,
+		default: options.default,
+	};
+}

package/src/console/factoryCommands.ts

@@ -0,0 +1,73 @@
+/**
+ * Factory console command — `make:factory` (Adonis Lucid). Scaffolds a model
+ * factory file. Same shape as the migration/seeder commands: a plain
+ * `{ name, description, run }` object registered in `reamrc.commands`.
+ *
+ * @example
+ *   // commands/make-factory.ts
+ *   import { makeFactoryCommand } from '@c9up/atlas'
+ *   export default makeFactoryCommand({ factoriesDir: 'database/factories' })
+ *   // run:  <console-entry> make:factory User
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { camelToSnake } from "../utils/casing.js";
+import { assertSafeName } from "../utils/safePath.js";
+import { type AtlasCommandClass, argument } from "./contract.js";
+
+export interface FactoryCommandOptions {
+	/** Directory the factory files are scaffolded into. */
+	factoriesDir: string;
+}
+
+/** Scaffold body for a fresh factory (`make:factory <Model>`). */
+function factoryStub(model: string): string {
+	return `import { factory } from '@c9up/atlas'
+import ${model} from '#models/${model.toLowerCase()}'
+
+export const ${model}Factory = factory(${model}, ({ faker }) => ({
+  // email: faker.internet.email(),
+}))
+`;
+}
+
+/**
+ * `make:factory <Model>` — scaffold `<Model>Factory.ts` in `factoriesDir`. The
+ * name is validated (no path separators / traversal) and written with `wx` so an
+ * existing factory is never clobbered.
+ */
+export function makeFactoryCommand(
+	options: FactoryCommandOptions,
+): AtlasCommandClass {
+	return class MakeFactory {
+		static commandName = "make:factory";
+		static description = "Scaffold a new model factory file";
+		// Pure filesystem work: no reason to boot the app and open a connection.
+		static options = { startApp: false };
+		static args = [
+			argument("model", { description: "Model the factory is built for" }),
+		];
+
+		declare model: string;
+
+		async run(): Promise<void> {
+			// A missing model is caught by the kernel before `run()` — it reports
+			// the required argument by name, so there is no usage check here.
+			// Lucid convention: `make:factory User` → `user_factory.ts`
+			// (`BlogPost` → `blog_post_factory.ts`).
+			const fileName = `${camelToSnake(this.model)}_factory.ts`;
+			try {
+				assertSafeName(fileName, "FACTORY_INVALID", "factory");
+			} catch {
+				console.error(`[atlas] invalid factory name: ${this.model}`);
+				process.exitCode = 1;
+				return;
+			}
+			const filePath = path.join(options.factoriesDir, fileName);
+			await fsp.mkdir(options.factoriesDir, { recursive: true });
+			await fsp.writeFile(filePath, factoryStub(this.model), { flag: "wx" });
+			console.log(`Created ${filePath}`);
+		}
+	};
+}

package/src/console/migrationCommands.ts

@@ -0,0 +1,448 @@
+/**
+ * Migration console commands — the Ream-idiomatic CLI for running, rolling back,
+ * inspecting, and wiping migrations. Same shape and contract as
+ * {@link schemaCheckCommand}: plain `{ name, description, run }` objects
+ * registered in `reamrc.commands` and dispatched by the console kernel.
+ *
+ * Each command resolves the live connection from atlas's OWN service locator
+ * (`getDb`), never importing `@c9up/ream`, and drives the already-tested
+ * {@link MigrationRunner}. Atlas has no global config registry (Lucid parity —
+ * you pass your own paths), so every factory takes the `migrationsDir`.
+ *
+ * @example
+ *   // commands/migrate.ts
+ *   import { migrationRunCommand } from '@c9up/atlas'
+ *   export default migrationRunCommand({ migrationsDir: 'database/migrations' })
+ *
+ *   // reamrc.ts → commands: [() => import('./commands/migrate.js')]
+ *   // run:  <console-entry> migration:run
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import {
+	type DatabaseAdapter,
+	MigrationRunner,
+} from "../schema/MigrationRunner.js";
+import { getDb } from "../services/db.js";
+import { assertSafeName } from "../utils/safePath.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;
+}
+
+/**
+ * Adapt the shared singleton connection to the runner's {@link DatabaseAdapter}.
+ * `close()` is intentionally a no-op — the console kernel owns the connection's
+ * lifecycle, so a command must not tear down a connection other commands share.
+ */
+function toAdapter(conn: AsyncDatabaseConnection): DatabaseAdapter {
+	return {
+		execute: async (sql, params) => {
+			await conn.execute(sql, params);
+		},
+		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 () => {},
+	};
+}
+
+/**
+ * Resolve a runner from the live connection, or report and set a failing exit
+ * code when no connection is registered (mirrors `schemaCheckCommand`).
+ */
+function resolveRunner(
+	options: MigrationCommandOptions,
+): MigrationRunner | undefined {
+	const db = getDb();
+	if (!db) {
+		console.error(
+			"[atlas] no database connection — is AtlasProvider registered?",
+		);
+		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,
+): 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({
+				schemaPath: this.schemaPath ?? options.schemaPath,
+			});
+			console.log(
+				ran.length ? `Migrated: ${ran.join(", ")}` : "Already up to date",
+			);
+			await maybeRegenSchema(options, this);
+		}
+	};
+}
+
+/**
+ * `migration:rollback` — undo the latest batch, or with `--batch=N` roll back
+ * everything applied after batch N (`--batch=0` rolls back all).
+ */
+export function migrationRollbackCommand(
+	options: MigrationCommandOptions,
+): 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(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 ? { 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,
+): 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();
+			if (rows.length === 0) {
+				console.log("No migrations found");
+				return;
+			}
+			for (const row of rows) {
+				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,
+): 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({ 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,
+): 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({
+				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,
+): 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({ force: this.force === true });
+			console.log("Dropped all tables");
+		}
+	};
+}
+
+/** Scaffold body for a fresh migration (`make:migration`). */
+const MIGRATION_STUB = `import { Migration } from '@c9up/atlas'
+
+export default class extends Migration {
+  async up() {
+    // this.schema.createTable('table_name', (table) => {
+    //   table.increments('id')
+    // })
+  }
+
+  async down() {
+    // this.schema.dropTable('table_name')
+  }
+}
+`;
+
+/**
+ * `make:migration <name>` — scaffold a timestamped migration file in
+ * `migrationsDir`. The `Date.now()` prefix keeps files in creation order under
+ * the runner's lexicographic sort (same convention as AdonisJS/Lucid). The name
+ * is validated (no path separators / traversal) and the file is written with
+ * `wx` so an existing migration is never clobbered.
+ */
+export function makeMigrationCommand(
+	options: MigrationCommandOptions,
+): 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(this.name, "MIGRATION_INVALID", "migration");
+			} catch {
+				console.error(`[atlas] invalid migration name: ${this.name}`);
+				process.exitCode = 1;
+				return;
+			}
+			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: number | undefined,
+): number | undefined | "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;
+		}
 	};
 }