@c9up/atlas 0.3.4 → 0.3.6

package/src/console/index.ts

@@ -0,0 +1,202 @@
+/**
+ * `@c9up/atlas/commands` — every command atlas ships, configured from
+ * `config/database.ts`.
+ *
+ *   // reamrc.ts, written by `configure()`
+ *   commands: [() => import('@c9up/atlas/commands')]
+ *
+ * This is the shape Adonis Lucid ships (`@adonisjs/lucid/commands`, a module
+ * exporting `getMetaData` / `getCommand`), and it is the whole point: a package
+ * adds commands by shipping them, never by a change to the `ream` binary.
+ *
+ * Where the paths come from is Lucid's answer too — the connection's config
+ * (`migrations.paths`, `seeders.paths`, `schemaGeneration.outputPath`). Lucid
+ * reads it through the container; atlas reads it from its own locator, which
+ * the provider fills at boot, so nothing here imports `@c9up/ream`.
+ *
+ * The option objects below use getters on purpose. A command class is built
+ * when this module is imported — before the application boots — while every
+ * `options.x` is read inside `run()`, after it. A plain object would capture
+ * the config that did not exist yet.
+ */
+
+import {
+	connectionConfigFor,
+	getDatabaseConfig,
+	primaryConnectionName,
+} from "../services/db.js";
+import type { AtlasCommandClass } from "./contract.js";
+import {
+	type FactoryCommandOptions,
+	makeFactoryCommand,
+} from "./factoryCommands.js";
+import {
+	dbWipeCommand,
+	type MigrationCommandOptions,
+	makeMigrationCommand,
+	migrationFreshCommand,
+	migrationRefreshCommand,
+	migrationResetCommand,
+	migrationRollbackCommand,
+	migrationRunCommand,
+	migrationStatusCommand,
+	migrationUnlockCommand,
+} from "./migrationCommands.js";
+import { schemaCheckCommand } from "./schemaCheckCommand.js";
+import {
+	type SchemaDumpCommandOptions,
+	schemaDumpCommand,
+} from "./schemaDumpCommand.js";
+import {
+	type SchemaGenerateOptions,
+	schemaGenerateCommand,
+} from "./schemaGenerateCommand.js";
+import {
+	dbSeedCommand,
+	makeSeederCommand,
+	type SeederCommandOptions,
+} from "./seederCommands.js";
+
+/** Lucid's defaults, for a config that leaves the paths out. */
+const DEFAULT_MIGRATIONS_DIR = "database/migrations";
+const DEFAULT_SEEDERS_DIR = "database/seeders";
+const DEFAULT_FACTORIES_DIR = "database/factories";
+
+/** The default connection's config — per-connection first, then the top level. */
+function connection() {
+	return connectionConfigFor();
+}
+
+function migrationsDir(): string {
+	const migrations = connection().migrations;
+	return migrations?.paths?.[0] ?? migrations?.path ?? DEFAULT_MIGRATIONS_DIR;
+}
+
+const migrationOptions: MigrationCommandOptions = {
+	get migrationsDir() {
+		return migrationsDir();
+	},
+	get naturalSort() {
+		return connection().migrations?.naturalSort;
+	},
+	get disableTransactions() {
+		return connection().migrations?.disableTransactions;
+	},
+	get tableName() {
+		return connection().migrations?.tableName ?? connection().migrations?.table;
+	},
+	get disableRollbacksInProduction() {
+		return connection().migrations?.disableRollbacksInProduction;
+	},
+	get schemaGeneration() {
+		return connection().schemaGeneration;
+	},
+};
+
+const seederOptions: SeederCommandOptions = {
+	get seedersDir() {
+		return connection().seeders?.paths?.[0] ?? DEFAULT_SEEDERS_DIR;
+	},
+	get naturalSort() {
+		return connection().seeders?.naturalSort;
+	},
+};
+
+const factoryOptions: FactoryCommandOptions = {
+	get factoriesDir() {
+		return connection().factories?.path ?? DEFAULT_FACTORIES_DIR;
+	},
+};
+
+const schemaDumpOptions: SchemaDumpCommandOptions = {
+	get migrationsDir() {
+		return migrationsDir();
+	},
+	get schemaTableName() {
+		return connection().migrations?.tableName ?? connection().migrations?.table;
+	},
+};
+
+// `outputPath` has no sensible default — a command that guessed one would write
+// a generated file into a directory the project never chose. The command
+// reports the missing key itself; an empty string is what it checks for.
+const schemaGenerateOptions: SchemaGenerateOptions = {
+	get outputPath() {
+		return connection().schemaGeneration?.outputPath ?? "";
+	},
+	get excludeTables() {
+		return connection().schemaGeneration?.excludeTables;
+	},
+	get enabled() {
+		return connection().schemaGeneration?.enabled;
+	},
+	get rulesPaths() {
+		return connection().schemaGeneration?.rulesPaths;
+	},
+	get compact() {
+		return connection().schemaGeneration?.compact;
+	},
+	get schemas() {
+		return connection().schemaGeneration?.schemas;
+	},
+};
+
+const COMMANDS: readonly AtlasCommandClass[] = [
+	migrationRunCommand(migrationOptions),
+	migrationRollbackCommand(migrationOptions),
+	migrationStatusCommand(migrationOptions),
+	migrationResetCommand(migrationOptions),
+	migrationRefreshCommand(migrationOptions),
+	migrationFreshCommand(migrationOptions),
+	migrationUnlockCommand(migrationOptions),
+	makeMigrationCommand(migrationOptions),
+	dbWipeCommand(migrationOptions),
+	dbSeedCommand(seederOptions),
+	makeSeederCommand(seederOptions),
+	makeFactoryCommand(factoryOptions),
+	schemaDumpCommand(schemaDumpOptions),
+	schemaGenerateCommand(schemaGenerateOptions),
+	schemaCheckCommand(() => getDatabaseConfig()?.verifySchema?.entities ?? []),
+];
+
+/** What the kernel reads to list a command without importing it. */
+interface CommandMetaData {
+	commandName: string;
+	namespace: string | null;
+	description: string;
+	help?: string | string[];
+	aliases: string[];
+	options: Record<string, unknown>;
+	args: readonly unknown[];
+	flags: readonly unknown[];
+}
+
+function serialize(command: AtlasCommandClass): CommandMetaData {
+	const colon = command.commandName.indexOf(":");
+	return {
+		commandName: command.commandName,
+		namespace: colon === -1 ? null : command.commandName.slice(0, colon),
+		description: command.description,
+		help: command.help,
+		aliases: [],
+		options: { ...command.options },
+		args: command.args ?? [],
+		flags: command.flags ?? [],
+	};
+}
+
+export async function getMetaData(): Promise<CommandMetaData[]> {
+	return COMMANDS.map(serialize);
+}
+
+export async function getCommand(
+	metadata: CommandMetaData,
+): Promise<AtlasCommandClass | null> {
+	return (
+		COMMANDS.find((command) => command.commandName === metadata.commandName) ??
+		null
+	);
+}
+
+/** The connection these commands run against — Lucid `db.primaryConnectionName`. */
+export { primaryConnectionName };

package/src/console/migrationCommands.ts

@@ -61,6 +61,18 @@ export interface MigrationCommandOptions {
 	 * loads it once migrations exist.
 	 */
 	schemaPath?: string;
+	/**
+	 * Migration bookkeeping table — Adonis Lucid `migrations.tableName`. Must
+	 * match what the application boots with: a command tracking migrations in a
+	 * different table than the app would re-apply every migration it cannot see.
+	 * Defaults to the runner's `"ream_migrations"`.
+	 */
+	tableName?: string;
+	/**
+	 * Refuse rollback/reset/refresh/fresh/wipe in production unless `--force`
+	 * (Adonis Lucid `migrations.disableRollbacksInProduction`). On by default.
+	 */
+	disableRollbacksInProduction?: boolean;
 }
 
 /**
@@ -105,6 +117,11 @@ function resolveRunner(
 		dialect: db.dialect,
 		naturalSort: options.naturalSort,
 		disableTransactions: options.disableTransactions,
+		// Without the table name the runner falls back to its default while the
+		// application tracks migrations in the configured one — the command would
+		// then see an empty history and re-apply everything.
+		tableName: options.tableName,
+		disableRollbacksInProduction: options.disableRollbacksInProduction,
 	});
 }
 

package/src/console/schemaCheckCommand.ts

@@ -21,10 +21,12 @@ type Constructor = new (...args: unknown[]) => unknown;
 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 as `ream atlas:check`; `--warn` reports drift without a
- * non-zero exit (useful for an advisory CI step).
+ * Build the `atlas:check` command for the given models.
+ *
+ * Most applications do not call this: `@c9up/atlas/commands` ships the command
+ * already, reading the models from `verifySchema.entities`. Call it directly to
+ * verify a different set — pass a function when the list is only known once the
+ * application has booted.
  *
  * @example
  *   // commands/atlas-check.ts
@@ -35,7 +37,7 @@ export type { AtlasCommandClass } from "./contract.js";
  *   // run:  ream atlas:check --warn
  */
 export function schemaCheckCommand(
-	entities: readonly Constructor[],
+	entities: readonly Constructor[] | (() => readonly Constructor[]),
 ): AtlasCommandClass {
 	return class SchemaCheck {
 		static commandName = "atlas:check";
@@ -58,7 +60,18 @@ export function schemaCheckCommand(
 				process.exitCode = 1;
 				return;
 			}
-			const code = await runSchemaCheck(entities, db, getAtlasDialect());
+			// Resolved here, not at registration: the shipped command reads the
+			// models from `verifySchema.entities`, which only exists once the
+			// application has booted its config.
+			const models = typeof entities === "function" ? entities() : entities;
+			if (models.length === 0) {
+				console.error(
+					"[atlas:check] no models to verify — list them under `verifySchema.entities` in config/database.ts.",
+				);
+				process.exitCode = 1;
+				return;
+			}
+			const code = await runSchemaCheck(models, db, getAtlasDialect());
 			// `--warn` downgrades drift to advisory (exit 0); default fails CI.
 			if (code !== 0 && !this.warn) process.exitCode = code;
 		}

package/src/services/db.ts

@@ -13,7 +13,10 @@
  * container hooks).
  */
 
-import type { ConnectionConfig } from "../AtlasProvider.js";
+import type {
+	AtlasDatabaseConfig,
+	ConnectionConfig,
+} from "../AtlasProvider.js";
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
 import { ConnectionManager } from "../ConnectionManager.js";
 import {
@@ -171,6 +174,86 @@ export function getDb(): AsyncDatabaseConnection | undefined {
 	return instance;
 }
 
+// The config the provider booted with. Commands need it: `migration:run` has to
+// know where the migration files are, and Lucid answers that from the config
+// too (`connection.config.migrations.paths`, read through `lucid.db`). Atlas has
+// no framework container to read, so the provider records it here.
+let databaseConfig:
+	| { config: AtlasDatabaseConfig; defaultName: string }
+	| undefined;
+
+/** @internal Record the booted config (called by AtlasProvider). */
+export function setDatabaseConfig(
+	config: AtlasDatabaseConfig,
+	defaultName: string,
+): void {
+	databaseConfig = { config, defaultName };
+}
+
+/**
+ * @internal Forget the config IF it is still the one `config` describes.
+ * Ownership-guarded for the same reason {@link clearDb} is: a second provider
+ * may have rebound it, and the older provider's shutdown must not clear the
+ * newer binding.
+ */
+export function clearDatabaseConfig(config: AtlasDatabaseConfig): void {
+	if (databaseConfig?.config === config) databaseConfig = undefined;
+}
+
+/** The config the application booted with, or `undefined` before boot. */
+export function getDatabaseConfig(): AtlasDatabaseConfig | undefined {
+	return databaseConfig?.config;
+}
+
+/** The default connection's name — Lucid `db.primaryConnectionName`. */
+export function primaryConnectionName(): string {
+	return databaseConfig?.defaultName ?? "primary";
+}
+
+/**
+ * One connection's config, by name (default connection when unnamed).
+ *
+ * Read from the manager's node first — that is where Lucid keeps `migrations`,
+ * `seeders` and `schemaGeneration`, and the shape we mirror. The top level is
+ * the fallback, because the single-connection form IS the connection config,
+ * and because an app that set `migrations` there before these keys were
+ * per-connection must keep working.
+ */
+export function connectionConfigFor(name?: string): ConnectionConfig {
+	const resolved = name ?? primaryConnectionName();
+	const top = databaseConfig?.config;
+	// The manager knows a connection once the provider has registered it; before
+	// that — a command running against a config nobody opened yet — the declared
+	// `connections` entry is the same information.
+	const declared =
+		manager.get(resolved)?.config ?? top?.connections?.[resolved];
+	if (top === undefined) return declared ?? {};
+	if (declared === undefined) return top;
+	return {
+		...top,
+		...declared,
+		// These three are merged a level down rather than replaced: the top level
+		// is the single-connection form of the same config, so a connection that
+		// names only its paths must not drop a `tableName` set beside it.
+		migrations: mergeOrUndefined(top.migrations, declared.migrations),
+		seeders: mergeOrUndefined(top.seeders, declared.seeders),
+		schemaGeneration: mergeOrUndefined(
+			top.schemaGeneration,
+			declared.schemaGeneration,
+		),
+	};
+}
+
+/** `{...a, ...b}`, or `undefined` when neither side has anything to merge. */
+function mergeOrUndefined<T extends object>(
+	base: T | undefined,
+	override: T | undefined,
+): T | undefined {
+	if (base === undefined) return override;
+	if (override === undefined) return base;
+	return { ...base, ...override };
+}
+
 // The shared connection manager (Lucid `db.manager`) — the single owner of named
 // connections. Backs `BaseModel.connection = 'analytics'` so a model resolves a
 // non-default connection from a plain import (AdonisJS `static connection`).