peta-migrate 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,132 @@
+# peta-migrate
+
+[![npm version](https://img.shields.io/npm/v/peta-migrate?style=flat-square)](https://www.npmjs.com/package/peta-migrate)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+Standalone migration runner and generator for [peta-orm](https://www.npmjs.com/package/peta-orm). Run, roll back, and generate database migrations with a clean programmatic API and CLI.
+
+```bash
+bun add peta-migrate kysely @libsql/kysely-libsql @libsql/client
+```
+
+Requires `kysely` as a peer dependency. SQLite via `@libsql/kysely-libsql`, PostgreSQL via `pg`, MySQL via `mysql2`.
+
+---
+
+## Quick Start
+
+### Programmatic
+
+```ts
+import { createClient } from "@libsql/client"
+import { LibsqlDialect } from "@libsql/kysely-libsql"
+import { Kysely } from "kysely"
+import { createMigrationRunner, createMigrationGenerator } from "peta-migrate"
+
+const db = new Kysely({ dialect: new LibsqlDialect({ url: "file:my-app.db" }) })
+const runner = createMigrationRunner(db)
+
+await runner.ensureTable()  // create tracking table
+
+await runner.up([
+  {
+    name: "001_create_users",
+    up: async (k) => {
+      await k.schema
+        .createTable("users")
+        .addColumn("id", "integer", (c) => c.autoIncrement().primaryKey())
+        .addColumn("name", "varchar(255)", (c) => c.notNull())
+        .execute()
+    },
+    down: async (k) => {
+      await k.schema.dropTable("users").execute()
+    },
+  },
+])
+
+// Check status
+const completed = await runner.getCompleted()  // MigrationRecord[]
+const status = await runner.status()           // { completed: [...], pending: [...] }
+```
+
+### CLI
+
+```bash
+bun x peta migrate:init        # Create migrations directory and tracking table
+bun x peta migrate:generate    # Generate initial migration from models
+bun x peta migrate:up          # Run pending migrations
+bun x peta migrate:status      # Show migration status
+```
+
+---
+
+## API
+
+### `createMigrationRunner(kysely)`
+
+Creates a runner that manages migration execution.
+
+| Method | Description |
+|--------|-------------|
+| `ensureTable()` | Create the migrations tracking table |
+| `up(migrations)` | Apply pending migrations in order |
+| `down()` | Roll back the last batch of migrations |
+| `getCompleted()` | Return list of completed migration records |
+| `status()` | Return `{ completed, pending }` with both lists |
+
+### `createMigrationGenerator()`
+
+Creates a generator that produces migration code from model definitions.
+
+| Method | Description |
+|--------|-------------|
+| `generateInitialMigration(models)` | Generate a create-table migration from registered models |
+
+### Configuration
+
+```ts
+import { defineConfig } from "peta-migrate"
+
+const config = defineConfig({
+  migrationsDir: "./migrations",
+  models: ["./src/models/*.ts"],
+  getKysely: () => db,
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `migrationsDir` | `string` | Directory to store migration files |
+| `models` | `string[]` \| `string` | Glob patterns for model files |
+| `getKysely` | `() => Kysely` | Function returning a Kysely instance |
+
+---
+
+## Types
+
+```ts
+interface MigrationFile {
+  name: string
+  up: (db: Kysely<unknown>) => Promise<void>
+  down: (db: Kysely<unknown>) => Promise<void>
+}
+
+interface MigrationRecord {
+  name: string
+  appliedAt: string
+}
+
+interface MigrationStatus {
+  completed: MigrationRecord[]
+  pending: MigrationFile[]
+}
+```
+
+---
+
+## Related packages
+
+- [peta-orm](../orm) — ORM with models, relations, hooks, soft deletes
+- [peta-auth](../auth) — Encrypted cookie sessions, JWT, OAuth
+- [peta-docs](../docs) — OpenAPI 3.1 spec generation + Scalar UI

package/bin/peta

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import { run } from "../dist/cli.mjs"
+await run()

package/dist/cli.mjs

@@ -1,6 +1,6 @@
-import { a as loadMigrationFiles, i as loadConfig, n as createMigrationGenerator, t as createMigrationRunner } from "./runner-DOQsuaSQ.mjs";
-import { resolve } from "node:path";
+import { a as createMigrationGenerator, c as loadConfig, d as computeChecksum, f as loadChecksums, i as createMigrationRunner, l as loadMigrationFiles, m as verifyChecksum, n as loadSnapshot, o as diffSnapshots, p as saveChecksums, r as saveSnapshot, t as createSnapshot, u as loadModels } from "./snapshot-DopEB8mx.mjs";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 import cac from "cac";
 import ora from "ora";
 //#region src/cli.ts
@@ -13,17 +13,71 @@ async function run() {
 		await createMigrationRunner(config.getKysely()).ensureTable();
 		spinner.succeed(`Migrations directory created at ${config.migrationsDir}`);
 	});
-	cli.command("migrate:generate [name]", "Generate initial migration from models").action(async (name) => {
+	cli.command("migrate:generate [name]", "Generate migration from models (initial or incremental)").action(async (name) => {
 		const config = await loadConfig();
-		const spinner = ora("Generating migration...").start();
-		const code = createMigrationGenerator().generateInitialMigration(/* @__PURE__ */ new Map(), { name: name ?? "Initial" });
+		const spinner = ora("Loading models...").start();
+		const models = await loadModels(config.models);
+		if (models.size === 0) {
+			spinner.warn("No models found matching the configured patterns.");
+			return;
+		}
+		spinner.text = "Generating migration...";
+		const gen = createMigrationGenerator();
+		const snapshotPath = resolve(config.migrationsDir, "snapshot.json");
+		const prevSnapshot = await loadSnapshot(snapshotPath);
+		let code;
+		if (prevSnapshot) {
+			const currentSnapshot = createSnapshot(models);
+			const diffs = diffSnapshots(prevSnapshot, currentSnapshot);
+			if (diffs.length === 0) {
+				spinner.succeed("No schema changes detected since last snapshot.");
+				return;
+			}
+			code = gen.generateMigrationFromDiff(diffs, { name: name ?? "changes" });
+			await saveSnapshot(snapshotPath, currentSnapshot);
+			spinner.text = `Generated incremental migration (${diffs.length} change(s))`;
+		} else {
+			code = gen.generateInitialMigration(models);
+			await saveSnapshot(snapshotPath, createSnapshot(models));
+			spinner.text = `Generated initial migration (${models.size} model(s))`;
+		}
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
 		const safeName = (name ?? "initial").replace(/[^a-zA-Z0-9_]/g, "_");
 		const filename = resolve(config.migrationsDir, `${timestamp}_${safeName}.ts`);
 		mkdirSync(config.migrationsDir, { recursive: true });
 		writeFileSync(filename, code);
+		const checksums = loadChecksums(config.migrationsDir);
+		const fileName = `${timestamp}_${safeName}.ts`;
+		checksums[fileName.replace(/\.(ts|js)$/, "")] = computeChecksum(filename);
+		saveChecksums(config.migrationsDir, checksums);
 		spinner.succeed(`Created ${filename}`);
 	});
+	cli.command("migrate:diff", "Preview schema changes without writing a migration").action(async () => {
+		const config = await loadConfig();
+		const prevSnapshot = await loadSnapshot(resolve(config.migrationsDir, "snapshot.json"));
+		if (!prevSnapshot) {
+			console.log("No snapshot found. Run `migrate:generate` first to create one.");
+			return;
+		}
+		const spinner = ora("Loading models...").start();
+		const models = await loadModels(config.models);
+		spinner.stop();
+		if (models.size === 0) {
+			console.log("No models found.");
+			return;
+		}
+		const diffs = diffSnapshots(prevSnapshot, createSnapshot(models));
+		if (diffs.length === 0) {
+			console.log("✅ No schema changes detected.");
+			return;
+		}
+		console.log(`\n  📋 Schema changes: ${diffs.length}\n`);
+		for (const d of diffs) {
+			const icon = d.type.startsWith("drop") ? "🗑️" : d.type.startsWith("create") || d.type.startsWith("add") ? "➕" : "✏️";
+			console.log(`  ${icon} [${d.type}] ${d.table}${d.column ? `.${d.column}` : ""}`);
+		}
+		console.log();
+	});
 	cli.command("migrate:up", "Apply pending migrations").action(async () => {
 		const config = await loadConfig();
 		const migrations = await loadMigrationFiles(config.migrationsDir);
@@ -31,6 +85,13 @@ async function run() {
 			console.log("No migration files found.");
 			return;
 		}
+		for (const m of migrations) {
+			const filePath = resolve(config.migrationsDir, `${m.name}.ts`);
+			if (!verifyChecksum(config.migrationsDir, m.name, filePath)) {
+				console.error(`❌ Checksum mismatch for migration "${m.name}". File has been modified since creation.`);
+				process.exit(1);
+			}
+		}
 		const runner = createMigrationRunner(config.getKysely());
 		const status = await runner.status(migrations);
 		if (status.pending.length === 0) {
@@ -41,7 +102,7 @@ async function run() {
 		await runner.up(migrations);
 		spinner.succeed(`Applied ${(await runner.getCompleted()).length} migration(s)`);
 	});
-	cli.command("migrate:down", "Rollback last batch").action(async () => {
+	cli.command("migrate:down [steps]", "Rollback migrations (default: 1)").action(async (steps) => {
 		const config = await loadConfig();
 		const migrations = await loadMigrationFiles(config.migrationsDir);
 		if (migrations.length === 0) {
@@ -53,9 +114,17 @@ async function run() {
 			console.log("Nothing to rollback.");
 			return;
 		}
-		const spinner = ora("Rolling back...").start();
-		await runner.down(migrations);
-		spinner.succeed("Rolled back");
+		const numSteps = steps ? Number.parseInt(steps, 10) : 1;
+		if (Number.isNaN(numSteps) || numSteps < 1) {
+			console.error("Steps must be a positive integer.");
+			process.exit(1);
+		}
+		const spinner = ora(`Rolling back ${numSteps} migration(s)...`).start();
+		for (let i = 0; i < numSteps; i++) {
+			if ((await runner.getCompleted()).length === 0) break;
+			await runner.down(migrations);
+		}
+		spinner.succeed(`Rolled back ${numSteps} migration(s)`);
 	});
 	cli.command("migrate:status", "Show migration status").action(async () => {
 		const config = await loadConfig();
@@ -67,6 +136,45 @@ async function run() {
 		for (const m of pending) console.log(`    · ${m.name}`);
 		console.log();
 	});
+	cli.command("migrate:push", "Push schema directly to database (prototyping)").action(async () => {
+		const config = await loadConfig();
+		const spinner = ora("Loading models...").start();
+		const models = await loadModels(config.models);
+		if (models.size === 0) {
+			spinner.warn("No models found.");
+			return;
+		}
+		spinner.text = "Pushing schema to database...";
+		const { pushSchema } = await import("./pusher-DJvKHlOT.mjs").then((n) => n.n);
+		const created = await pushSchema(config.getKysely(), models);
+		await saveSnapshot(resolve(config.migrationsDir, "snapshot.json"), createSnapshot(models));
+		if (created.length === 0) spinner.succeed("Schema is up to date (no new tables).");
+		else spinner.succeed(`Created tables: ${created.join(", ")}`);
+	});
+	cli.command("migrate:seed [name]", "Generate or run seed files").action(async (name) => {
+		const config = await loadConfig();
+		if (name) {
+			const spinner = ora("Generating seed...").start();
+			const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
+			const safeName = name.replace(/[^a-zA-Z0-9_]/g, "_");
+			const filename = resolve(config.migrationsDir, `${timestamp}_seed_${safeName}.ts`);
+			writeFileSync(filename, `import type { Kysely } from "kysely"\n\nexport async function seed(db: Kysely<any>): Promise<void> {\n  // TODO: add seed data\n}\n`);
+			spinner.succeed(`Created ${filename}`);
+		} else {
+			const { readdirSync } = await import("node:fs");
+			const spinner = ora("Running seeds...").start();
+			const seedFiles = readdirSync(config.migrationsDir).filter((f) => f.includes("_seed_") && (f.endsWith(".ts") || f.endsWith(".js"))).sort();
+			if (seedFiles.length === 0) {
+				spinner.warn("No seed files found.");
+				return;
+			}
+			for (const file of seedFiles) {
+				const mod = await import(resolve(config.migrationsDir, file));
+				if (mod.seed) await mod.seed(config.getKysely());
+			}
+			spinner.succeed(`Executed ${seedFiles.length} seed(s)`);
+		}
+	});
 	cli.help();
 	cli.parse();
 }