@zerotal/orm 1.0.0

package/src/commands/MakeMigrationCommand.ts

@@ -0,0 +1,109 @@
+import { Command, Str } from "@zerotal/core";
+
+export type MigrationFileResult = {
+  path: string;
+  created: boolean;
+};
+
+/**
+ * Converts a migration name (e.g. `create_posts_table`) into a PascalCase
+ * class name (e.g. `CreatePostsTable`) for use in the generated stub.
+ */
+export function toMigrationClassName(name: string): string {
+  return Str.pascalCase(name);
+}
+
+/**
+ * Returns the source text of a blank migration file whose default-exported
+ * class is named `className`.
+ */
+export function migrationStub(className: string): string {
+  return `import { Migration, Schema } from '@zerotal/orm';
+
+export default class ${className} extends Migration {
+  override async up(): Promise<void> {
+    await Schema.create('table_name', (table) => {
+      table.increments('id');
+      table.timestamps();
+    });
+  }
+
+  override async down(): Promise<void> {
+    await Schema.drop('table_name');
+  }
+}
+`;
+}
+
+/**
+ * Lists the existing `database/migrations/*.ts` file paths, used to derive the
+ * next zero-padded numeric prefix.
+ *
+ * @internal
+ */
+async function listMigrationFiles(): Promise<string[]> {
+  const glob = new Bun.Glob("database/migrations/*.ts");
+  const files: string[] = [];
+  for await (const file of glob.scan({ cwd: process.cwd() })) {
+    files.push(file);
+  }
+  return files;
+}
+
+/**
+ * Writes a new numbered migration file for `name` under `database/migrations/`,
+ * returning its path and whether it was created (`false` if one already exists).
+ */
+export async function createMigrationFile(name: string): Promise<MigrationFileResult> {
+  const files = await listMigrationFiles();
+  const nextNumber = files.length + 1;
+  const prefix = String(nextNumber).padStart(3, "0");
+  const fileName = `${prefix}_${name}.ts`;
+  const path = `database/migrations/${fileName}`;
+
+  if (await Bun.file(path).exists()) {
+    return { path, created: false };
+  }
+
+  // Bun.write() creates any missing parent directories, so no mkdir is needed.
+  await Bun.write(path, migrationStub(toMigrationClassName(name)));
+  return { path, created: true };
+}
+
+/**
+ * Scaffolds a new migration file (`bun zt make:migration`).
+ *
+ * Writes a blank migration with `up()`/`down()` stubs to
+ * `database/migrations/`, prefixed with the next zero-padded sequence number.
+ *
+ * @example
+ * ```bash
+ * bun zt make:migration create_posts_table
+ * ```
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeMigrationCommand extends Command {
+  static commandName = "make:migration";
+  static description = "Create a new migration file";
+  static needsApp = false;
+  static args = [
+    {
+      name: "name",
+      required: true,
+      description: "Migration name (e.g. create_posts_table)",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const result = await createMigrationFile(name);
+
+    if (!result.created) {
+      this.error(`File already exists: ${result.path}`);
+      return;
+    }
+
+    this.info(`Created: ${result.path}`);
+  }
+}

package/src/commands/MakeModelCommand.ts

@@ -0,0 +1,83 @@
+import { Command, Str } from "@zerotal/core";
+import { createMigrationFile } from "./MakeMigrationCommand.ts";
+
+/**
+ * Returns the source text of a model class named `name` bound to `tableName`.
+ */
+export function modelStub(name: string, tableName: string): string {
+  return `import { BaseModel, column, table } from '@zerotal/orm';
+
+@table('${tableName}').withTimestamps()
+export class ${name} extends BaseModel {
+  // Models guard every attribute by default. List the columns that may be
+  // mass-assigned from user input via create() / fill().
+  static override fillable: string[] = ['name'];
+
+  @column() name!: string;
+}
+`;
+}
+
+/**
+ * Scaffolds a new model class (`bun zt make:model`).
+ *
+ * Writes an `app/models/<Name>.ts` file containing a `BaseModel` subclass whose
+ * table name is the snake-cased model name. Passing `--migration` (`-m`) also
+ * generates a matching `create_<name>_table` migration.
+ *
+ * @example
+ * ```bash
+ * bun zt make:model Post
+ * bun zt make:model Post --migration
+ * ```
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeModelCommand extends Command {
+  static commandName = "make:model";
+  static description = "Create a new model class";
+  static needsApp = false;
+  static args = [
+    {
+      name: "name",
+      required: true,
+      description: "Model name (e.g. User)",
+    },
+  ];
+  static flags = [
+    {
+      name: "migration",
+      short: "m",
+      type: "boolean" as const,
+      description: "Also create a migration file",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = `app/models/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    const tableName = Str.snakeCase(name);
+
+    // Bun.write() creates any missing parent directories, so no mkdir is needed.
+    await Bun.write(path, modelStub(name, tableName));
+    this.info(`Created: ${path}`);
+
+    const withMigration = this.flags["migration"] as boolean;
+    if (withMigration) {
+      const migrationName = `create_${Str.snakeCase(name)}_table`;
+      const result = await createMigrationFile(migrationName);
+      if (!result.created) {
+        this.error(`File already exists: ${result.path}`);
+        return;
+      }
+      this.info(`Created: ${result.path}`);
+    }
+  }
+}

package/src/commands/MakeSeederCommand.ts

@@ -0,0 +1,50 @@
+import { Command } from "@zerotal/core";
+
+/**
+ * Scaffolds a new database seeder class (`bun zt make:seeder`).
+ *
+ * Writes `database/seeders/<Name>.ts` containing a `Seeder` subclass with an
+ * empty `run()` method to be filled in with seeding logic.
+ *
+ * @example
+ * ```bash
+ * bun zt make:seeder UserSeeder
+ * ```
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeSeederCommand extends Command {
+  static commandName = "make:seeder";
+  static description = "Create a new database seeder class";
+  static needsApp = false;
+  static args = [
+    { name: "name", required: true, description: "Seeder class name (e.g. UserSeeder)" },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = `database/seeders/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, seederStub(name));
+    this.info(`Created: ${path}`);
+  }
+}
+
+/**
+ * Returns the source text of a seeder class file named `name`.
+ */
+export function seederStub(name: string): string {
+  return `import { Seeder } from '@zerotal/orm';
+
+export class ${name} extends Seeder {
+  async run(): Promise<void> {
+    // Seed your database here
+  }
+}
+`;
+}

package/src/commands/MigrateCommand.ts

@@ -0,0 +1,60 @@
+import { Command } from "@zerotal/core";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+import { loadMigrations } from "./_loadMigrations.ts";
+
+/**
+ * Runs all pending database migrations (`bun zt migrate`).
+ *
+ * Loads every migration under `database/migrations/`, then applies those not
+ * yet run. Passing `--fresh` first drops all tables and re-runs every
+ * migration from scratch.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate
+ * bun zt migrate --fresh
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateCommand extends Command {
+  static commandName = "migrate";
+  static aliases = ["db:migrate"];
+  static description = "Run all pending database migrations";
+  static needsApp = true;
+  static flags = [
+    {
+      name: "fresh",
+      type: "boolean" as const,
+      description: "Drop all tables and re-run all migrations",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const fresh = this.flags["fresh"] as boolean;
+    const records = await loadMigrations();
+    const entries: MigrationEntry[] = records.map((r) => ({
+      name: r.name,
+      migration: r.instance,
+    }));
+
+    const runner = new MigrationRunner({ connection: _getConnection() });
+
+    if (fresh) {
+      await runner.reset(entries);
+    }
+
+    const ran = await runner.run(entries);
+
+    if (ran.length === 0) {
+      this.info("Nothing to migrate.");
+      return;
+    }
+
+    this.info(`Migrated ${ran.length} migration(s).`);
+    this.table(ran.map((name) => [name, "ran"]));
+  }
+}

package/src/commands/MigrateFreshCommand.ts

@@ -0,0 +1,41 @@
+import { Command } from "@zerotal/core";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+import { loadMigrations } from "./_loadMigrations.ts";
+
+/**
+ * Rolls back every migration, then re-runs them from scratch (`bun zt migrate:fresh`).
+ *
+ * Resets the database by reversing all applied migrations and then re-applying
+ * the full set, giving a clean, fully-migrated schema in one step.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate:fresh
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateFreshCommand extends Command {
+  static commandName = "migrate:fresh";
+  static description = "Roll back every migration, then re-run them from scratch";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const records = await loadMigrations();
+    const entries: MigrationEntry[] = records.map((r) => ({
+      name: r.name,
+      migration: r.instance,
+    }));
+
+    const runner = new MigrationRunner({ connection: _getConnection() });
+    await runner.reset(entries);
+    const ran = await runner.run(entries);
+
+    this.info(`Database refreshed — ran ${ran.length} migration(s).`);
+    if (ran.length > 0) {
+      this.table(ran.map((name) => [name, "migrated"]));
+    }
+  }
+}

package/src/commands/MigrateGenerateCommand.ts

@@ -0,0 +1,110 @@
+import path from "node:path";
+import { Command } from "@zerotal/core";
+import { ModelInspector } from "../schema/ModelInspector.ts";
+import { SchemaDiffer } from "../schema/SchemaDiffer.ts";
+import { generateMigrationContent } from "../schema/MigrationCodegen.ts";
+import { toMigrationClassName } from "./MakeMigrationCommand.ts";
+
+/**
+ * Lists the existing `database/migrations/*.ts` file paths, used to derive the
+ * next zero-padded numeric prefix for the generated migration.
+ *
+ * @internal
+ */
+async function listMigrationFiles(): Promise<string[]> {
+  const glob = new Bun.Glob("database/migrations/*.ts");
+  const files: string[] = [];
+  for await (const file of glob.scan({ cwd: process.cwd() })) {
+    files.push(file);
+  }
+  return files;
+}
+
+/**
+ * Auto-generates a migration from model schema changes (`bun zt migrate:generate`).
+ *
+ * Loads the model files matching the `--models` glob, diffs their `@column()`
+ * schemas against the live database, and writes a numbered migration under
+ * `database/migrations/` describing the new tables and columns. Reports "No
+ * schema changes detected" when the models and database already agree.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate:generate create_posts_table
+ * bun zt migrate:generate add_slug_to_posts --models "app/models/**\/*.ts"
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateGenerateCommand extends Command {
+  static override commandName = "migrate:generate";
+  static override description = "Auto-generate a migration from model schema changes";
+  static override needsApp = false;
+
+  static override args = [
+    {
+      name: "name",
+      required: true,
+      description: "Migration name (e.g. create_posts_table)",
+    },
+  ];
+
+  static override flags = [
+    {
+      name: "models",
+      type: "string" as const,
+      description: "Glob pattern for model files to inspect",
+      default: "app/models/**/*.ts",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const modelsPattern = (this.flags["models"] as string | undefined) ?? "app/models/**/*.ts";
+
+    // ── 1. Import model files ────────────────────────────────────────────────
+    this.dim(`Scanning models: ${modelsPattern}`);
+    await ModelInspector.load(modelsPattern);
+
+    const schemas = ModelInspector.all();
+    if (schemas.length === 0) {
+      this.warn(`No models found matching: ${modelsPattern}`);
+      this.dim("Ensure models use @column() decorators and set static table.");
+      return;
+    }
+    this.dim(`Found ${schemas.length} model(s)`);
+
+    // ── 2. Diff against live DB ──────────────────────────────────────────────
+    const diff = await SchemaDiffer.diff(schemas);
+
+    if (SchemaDiffer.isEmpty(diff)) {
+      this.info("No schema changes detected — nothing to generate.");
+      return;
+    }
+
+    // ── 3. Generate migration content ────────────────────────────────────────
+    const className = toMigrationClassName(name);
+    const content = generateMigrationContent(className, diff);
+
+    // ── 4. Write the migration file ──────────────────────────────────────────
+    const existing = await listMigrationFiles();
+    const nextNumber = existing.length + 1;
+    const prefix = String(nextNumber).padStart(3, "0");
+    const filePath = path.join("database", "migrations", `${prefix}_${name}.ts`);
+    const absPath = path.resolve(process.cwd(), filePath);
+
+    // Bun.write() creates any missing parent directories, so no mkdir is needed.
+    await Bun.write(absPath, content);
+
+    // ── 5. Report ────────────────────────────────────────────────────────────
+    this.info(`Generated: ${filePath}`);
+
+    if (diff.newTables.length > 0) {
+      this.line(`  + New tables:  ${diff.newTables.map((t) => t.schema.table).join(", ")}`);
+    }
+    if (diff.newColumns.length > 0) {
+      const cols = diff.newColumns.map((c) => `${c.table}.${c.column.name}`);
+      this.line(`  + New columns: ${cols.join(", ")}`);
+    }
+  }
+}

package/src/commands/MigrateRollbackCommand.ts

@@ -0,0 +1,43 @@
+import { Command } from "@zerotal/core";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+import { loadMigrations } from "./_loadMigrations.ts";
+
+/**
+ * Rolls back the most recent migration batch (`bun zt migrate:rollback`).
+ *
+ * Reverses the migrations applied in the last batch by calling their `down()`
+ * methods; reports "Nothing to roll back." when no batch remains.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate:rollback
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateRollbackCommand extends Command {
+  static commandName = "migrate:rollback";
+  static description = "Roll back the most recent migration batch";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const records = await loadMigrations();
+    const entries: MigrationEntry[] = records.map((r) => ({
+      name: r.name,
+      migration: r.instance,
+    }));
+
+    const runner = new MigrationRunner({ connection: _getConnection() });
+    const rolledBack = await runner.rollback(entries);
+
+    if (rolledBack.length === 0) {
+      this.info("Nothing to roll back.");
+      return;
+    }
+
+    this.info(`Rolled back ${rolledBack.length} migration(s).`);
+    this.table(rolledBack.map((name) => [name, "rolled back"]));
+  }
+}

package/src/commands/MigrateStatusCommand.ts

@@ -0,0 +1,49 @@
+import { Command } from "@zerotal/core";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+import { loadMigrations } from "./_loadMigrations.ts";
+
+/**
+ * Shows the status of each migration (`bun zt migrate:status`).
+ *
+ * Prints a table listing every known migration and whether it has run, along
+ * with its batch number and the timestamp it was applied.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate:status
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateStatusCommand extends Command {
+  static commandName = "migrate:status";
+  static description = "Show the status of each migration";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const records = await loadMigrations();
+    const entries: MigrationEntry[] = records.map((r) => ({
+      name: r.name,
+      migration: r.instance,
+    }));
+
+    const runner = new MigrationRunner({ connection: _getConnection() });
+    const statuses = await runner.status(entries);
+
+    const rows: [string, string][] = [
+      ["name", "ran | batch | ranAt"],
+      ...statuses.map((status): [string, string] => {
+        if (!status.ran) {
+          return [status.name, "no | - | -"];
+        }
+        const batch = status.batch ?? "-";
+        const ranAt = status.ranAt ? status.ranAt.toISOString() : "-";
+        return [status.name, `yes | ${batch} | ${ranAt}`];
+      }),
+    ];
+
+    this.table(rows);
+  }
+}

package/src/commands/_loadMigrations.ts

@@ -0,0 +1,34 @@
+import type { MigrationRecord } from "../schema/MigrationRunner.ts";
+
+/**
+ * Globs `database/migrations/*.ts`, imports each file, and returns a
+ * {@link MigrationRecord} array of instantiated migrations. Files are sorted by
+ * filename so `001_` runs before `002_`; files without a default export are
+ * skipped.
+ *
+ * Shared by the `migrate`, `migrate:fresh`, `migrate:rollback`, and
+ * `migrate:status` commands.
+ *
+ * @internal
+ */
+export async function loadMigrations(): Promise<MigrationRecord[]> {
+  const glob = new Bun.Glob("database/migrations/*.ts");
+  const files: string[] = [];
+
+  for await (const file of glob.scan({ cwd: process.cwd() })) {
+    files.push(file);
+  }
+
+  files.sort();
+
+  const records: MigrationRecord[] = [];
+  for (const file of files) {
+    const mod = await import(`${process.cwd()}/${file}`);
+    const Ctor = mod.default as (new () => MigrationRecord["instance"]) | undefined;
+    if (!Ctor) continue;
+    const name = file.replace(/^database\/migrations\//, "").replace(/\.ts$/, "");
+    records.push({ name, instance: new Ctor() });
+  }
+
+  return records;
+}

package/src/commands/index.ts

@@ -0,0 +1,30 @@
+/**
+ * CLI commands for the Zerotal ORM: database migrations and code scaffolding.
+ *
+ * This entry point bundles the `Command`-derived classes that back the
+ * ORM's `bun zt` sub-commands — running, refreshing, rolling back, and
+ * inspecting migrations, seeding the database, and generating models,
+ * migrations, factories, and seeders. Register these with the CLI runner to
+ * expose the `migrate:*`, `db:*`, and `make:*` commands in an application.
+ *
+ * @example
+ * ```bash
+ * # Run all pending migrations
+ * bun zt migrate
+ *
+ * # Scaffold a new model class
+ * bun zt make:model Post
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { MigrateCommand } from "./MigrateCommand.ts";
+export { MigrateRollbackCommand } from "./MigrateRollbackCommand.ts";
+export { MigrateStatusCommand } from "./MigrateStatusCommand.ts";
+export { MigrateFreshCommand } from "./MigrateFreshCommand.ts";
+export { MakeMigrationCommand } from "./MakeMigrationCommand.ts";
+export { MigrateGenerateCommand } from "./MigrateGenerateCommand.ts";
+export { MakeModelCommand } from "./MakeModelCommand.ts";
+export { DbSeedCommand } from "./DbSeedCommand.ts";
+export { MakeSeederCommand } from "./MakeSeederCommand.ts";
+export { MakeFactoryCommand } from "./MakeFactoryCommand.ts";