feat(migrations): Move StudioCMS Migration system from kysely package to sdk package

.changeset/brown-pots-rush.md

@@ -0,0 +1,6 @@
+---
+"@studiocms/migrator": patch
+"studiocms": patch
+---
+
+Update imports for Migrator to `@withstudiocms/sdk/migrator`

.changeset/young-rabbits-ask.md

@@ -0,0 +1,6 @@
+---
+"@withstudiocms/kysely": patch
+"@withstudiocms/sdk": patch
+---
+
+Move custom StudioCMS migrations from `@withstudiocms/kysely` package to `@withstudiocms/sdk`

package.json

@@ -31,7 +31,7 @@
     "build:studiocms": "pnpm build:packages",
     "build:packages": "pnpm --filter studiocms --filter @studiocms/* --filter @withstudiocms/* build",
 
-    "create-migration": "pnpm --filter @withstudiocms/kysely create-migration",
+    "create-migration": "pnpm --filter @withstudiocms/sdk create-migration",
 
     "playground:dev": "pnpm dev",
     "playground:preview": "pnpm --filter node-playground preview",

packages/@studiocms/migrator/src/db/client.ts

@@ -1,7 +1,7 @@
 import { runEffect } from '@withstudiocms/effect';
 import { getDBClientLive } from '@withstudiocms/kysely/client';
 import { sql } from '@withstudiocms/kysely/kysely';
-import { getMigratorLive } from '@withstudiocms/kysely/migrator';
+import { getMigratorLive } from '@withstudiocms/sdk/migrator';
 import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
 import { type KyselyTableKeys, kyselyTableKeys } from '../lib/tableMap';
 

packages/@withstudiocms/kysely/package.json

@@ -31,7 +31,6 @@
     "build": "pnpm buildkit build 'src/**/*.{ts,json}'",
     "dev": "pnpm buildkit dev 'src/**/*.{ts,json}'",
     "typecheck": "tspc -p tsconfig.tspc.json",
-    "create-migration": "tsx scripts/create-migration.ts",
     "test": "vitest"
   },
   "exports": {
@@ -47,10 +46,6 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
-    "./migrator": {
-      "types": "./dist/migrator.d.ts",
-      "default": "./dist/migrator.js"
-    },
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "default": "./dist/plugin.js"
@@ -71,8 +66,9 @@
       "types": "./dist/drivers/*.d.ts",
       "default": "./dist/drivers/*.js"
     },
-    "./schemas/*": {
-      "default": "./dist/schemas/*.json"
+    "./utils/*": {
+      "types": "./dist/utils/*.d.ts",
+      "default": "./dist/utils/*.js"
     }
   },
   "type": "module",
@@ -82,8 +78,7 @@
   },
   "devDependencies": {
     "@types/node": "catalog:",
-    "@types/pg": "catalog:kysely",
-    "tsx": "^4.21.0"
+    "@types/pg": "catalog:kysely"
   },
   "peerDependencies": {
     "effect": "catalog:effect",

packages/@withstudiocms/kysely/src/core/migrator.ts

@@ -98,13 +98,13 @@ export class PassthroughMigrationProvider implements MigrationProvider {
  * const migratorInstance = getMigrator(kyselyInstance);
  */
 const kyselyMigrator =
-	(migrationFolder: Record<string, Migration>) =>
+	(migrations: Record<string, Migration>) =>
 	<Schema>(db: Kysely<Schema>) =>
 		useWithError(
 			() =>
 				new Migrator({
 					db,
-					provider: new PassthroughMigrationProvider(migrationFolder),
+					provider: new PassthroughMigrationProvider(migrations),
 				})
 		);
 
@@ -127,11 +127,9 @@ const kyselyMigrator =
  * Note: This function returns an Effect (deferred computation). You must run/interpret the Effect
  * to obtain and invoke the migration helpers.
  */
-const makeMigrator = <Schema>(migrationFolder: Record<string, Migration>) =>
+const makeMigrator = <Schema>(migrations: Record<string, Migration>) =>
 	Effect.gen(function* () {
-		const base = yield* kyselyClient<Schema>().pipe(
-			Effect.flatMap(kyselyMigrator(migrationFolder))
-		);
+		const base = yield* kyselyClient<Schema>().pipe(Effect.flatMap(kyselyMigrator(migrations)));
 
 		const toLatest = useWithErrorPromise(() => base.migrateToLatest());
 		const down = useWithErrorPromise(() => base.migrateDown());
@@ -162,13 +160,10 @@ const makeMigrator = <Schema>(migrationFolder: Record<string, Migration>) =>
  * @example
  * // Run the returned Effect to obtain and use the migrator in your application runtime.
  */
-export const makeMigratorLive = <Schema>(
-	dialect: Dialect,
-	migrationFolder: Record<string, Migration>
-) =>
+export const makeMigratorLive = <Schema>(dialect: Dialect, migrations: Record<string, Migration>) =>
 	Effect.gen(function* () {
 		const { db } = yield* makeDBClientLive<Schema>(dialect);
-		return yield* makeMigrator<Schema>(migrationFolder).pipe(
+		return yield* makeMigrator<Schema>(migrations).pipe(
 			Effect.provideService(kyselyClient<Schema>(), db)
 		);
 	});

packages/@withstudiocms/kysely/src/index.ts

@@ -1,9 +1,3 @@
-/**
- * Migrator is left out of this index to avoid issues with `node:` imports in ESM/CJS
- * environments that do not support them. Users should import migrator-related
- * functions directly from the migrator module. `@withstudiocms/kysely/migrator`.
- */
-
 export * from './client.js';
 
 // TODO: Create a new Astro integration to handle an Astro-DB like setup

packages/@withstudiocms/kysely/src/test-utils.ts

@@ -4,7 +4,6 @@ import { createClient } from '@libsql/client/node';
 import { Effect } from 'effect';
 import { LibSQLDialect } from 'kysely-turso/libsql';
 import { getDBClientLive } from './client.js';
-import { getMigratorLive } from './migrator.js';
 
 type DBFixtureOptions = {
 	suiteName: string;
@@ -15,7 +14,6 @@ type DBFixtureOptions = {
 	 * Should be `import.meta.url` from the calling module.
 	 */
 	cwd: string;
-	migrationsDir?: string;
 };
 
 function normalize(str: string) {
@@ -108,16 +106,6 @@ export class DBFixture<Schema> {
 			const dialect = this.getDialect();
 			return getDBClientLive<Schema>(dialect);
 		},
-
-		/**
-		 * Creates and returns a migrator instance configured for the test database.
-		 *
-		 * @returns A migrator instance for managing database migrations.
-		 */
-		getMigrator: () => {
-			const dialect = this.getDialect();
-			return getMigratorLive<Schema>(dialect);
-		},
 	};
 
 	/** JavaScript-based utilities for managing the test database fixture. */
@@ -139,12 +127,5 @@ export class DBFixture<Schema> {
 		 * @returns A Kysely<Schema> client instance connected to the test database.
 		 */
 		getClient: () => this.run(this.effect.getClient()),
-
-		/**
-		 * Creates and returns a migrator instance configured for the test database.
-		 *
-		 * @returns A migrator instance for managing database migrations.
-		 */
-		getMigrator: () => this.run(this.effect.getMigrator()),
 	};
 }

packages/@withstudiocms/kysely/test/test-utils.ts

@@ -1,19 +1,10 @@
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import * as allure from 'allure-js-commons';
 import { test as baseTest } from 'vitest';
 import { DBFixture } from '../src/test-utils';
 
 export const parentSuiteName = '@withstudiocms/kysely Package Tests';
 export const sharedTags = ['package:@withstudiocms/kysely', 'type:unit', 'scope:withstudiocms'];
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Path to the migrations folder for tests
-// This ensures that the migrator in tests uses the compiled migrations preventing issues with missing files while allowing correct coverage reporting.
-const migrationFolder = path.join(__dirname, '../dist/migrations');
-
 /**
  * Extends the base test fixture with Allure helpers tailored for tests.
  *
@@ -112,6 +103,5 @@ export const DBClientFixture = <Schema>(suite: string) => {
 	return new DBFixture<Schema>({
 		suiteName: suite,
 		cwd: import.meta.url,
-		migrationsDir: migrationFolder,
 	});
 };

packages/@withstudiocms/sdk/package.json

@@ -29,6 +29,7 @@
   "scripts": {
     "build": "pnpm buildkit build 'src/**/*.{ts,json}'",
     "dev": "pnpm buildkit dev 'src/**/*.{ts,json}'",
+    "create-migration": "tsx scripts/create-migration.ts",
     "typecheck": "tspc -p tsconfig.tspc.json"
   },
   "exports": {
@@ -48,6 +49,10 @@
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
     },
+    "./migrator": {
+      "types": "./dist/migrator.d.ts",
+      "default": "./dist/migrator.js"
+    },
     "./*": "./dist/*"
   },
   "type": "module",
@@ -57,7 +62,8 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/node": "catalog:"
+    "@types/node": "catalog:",
+    "tsx": "^4.21.0"
   },
   "peerDependencies": {
     "@withstudiocms/effect": "workspace:*",

packages/@withstudiocms/kysely/src/migrations/20251025T040912_init.ts → packages/@withstudiocms/sdk/src/migrations/20251025T040912_init.ts

@@ -11,8 +11,12 @@
  */
 /** biome-ignore-all lint/suspicious/noExplicitAny: Requirement from Kysely */
 
-import type { Kysely } from 'kysely';
-import { rollbackMigration, syncDatabaseSchema, type TableDefinition } from '../utils/migrator.js';
+import type { Kysely } from '@withstudiocms/kysely/kysely';
+import {
+	rollbackMigration,
+	syncDatabaseSchema,
+	type TableDefinition,
+} from '@withstudiocms/kysely/utils/migrator';
 
 // import { schemaDefinition as previousSchema } from './placeholder-for-previous-migration.js';
 

packages/@withstudiocms/kysely/src/migrations/20251130T150847_drop_deprecated.ts → packages/@withstudiocms/sdk/src/migrations/20251130T150847_drop_deprecated.ts

@@ -7,8 +7,12 @@
  */
 /** biome-ignore-all lint/suspicious/noExplicitAny: Requirement from Kysely */
 
-import type { Kysely } from 'kysely';
-import { rollbackMigration, syncDatabaseSchema, type TableDefinition } from '../utils/migrator.js';
+import type { Kysely } from '@withstudiocms/kysely/kysely';
+import {
+	rollbackMigration,
+	syncDatabaseSchema,
+	type TableDefinition,
+} from '@withstudiocms/kysely/utils/migrator';
 
 import { schemaDefinition as previousSchema } from './20251025T040912_init.js';
 

packages/@withstudiocms/kysely/src/migrations/20251221T002125_url-mapping.ts → packages/@withstudiocms/sdk/src/migrations/20251221T002125_url-mapping.ts

@@ -7,8 +7,12 @@
  */
 /** biome-ignore-all lint/suspicious/noExplicitAny: Requirement from Kysely */
 
-import type { Kysely } from 'kysely';
-import { rollbackMigration, syncDatabaseSchema, type TableDefinition } from '../utils/migrator.js';
+import type { Kysely } from '@withstudiocms/kysely/kysely';
+import {
+	rollbackMigration,
+	syncDatabaseSchema,
+	type TableDefinition,
+} from '@withstudiocms/kysely/utils/migrator';
 
 import { schemaDefinition as previousSchema } from './20251130T150847_drop_deprecated.js';
 

packages/@withstudiocms/kysely/src/migrator.ts → packages/@withstudiocms/sdk/src/migrator.ts

@@ -1,15 +1,16 @@
 /// <reference types="vite/client" />
 /** biome-ignore-all lint/suspicious/noExplicitAny: Kysely Requirement */
-import type { Dialect, Kysely, Migration } from 'kysely';
-import { makeMigratorLive } from './core/migrator.js';
 
-// TODO: Migrate custom migrations to the StudioCMS SDK package
-// These where not meant to be here long term, but are here temporarily
-// to facilitate the migration to Kysely without blocking early development.
-//
-// Note: when moving the migrations to the SDK package, don't forget to also move
-// the migration files, and the utility script for creating new migrations.
-// (i.e, packages/@withstudiocms/kysely/scripts/create-migration.ts)
+import type { Effect } from '@withstudiocms/effect';
+import type { MigratorError } from '@withstudiocms/kysely/core/errors';
+import { makeMigratorLive } from '@withstudiocms/kysely/core/migrator';
+import type {
+	Dialect,
+	Kysely,
+	Migration,
+	MigrationInfo,
+	MigrationResultSet,
+} from '@withstudiocms/kysely/kysely';
 
 /**
  * Dynamically imports a migration module by its name.
@@ -30,8 +31,7 @@ const importMigration = async (name: string): Promise<Migration> => {
 			throw new Error(`Migration not found: ${name}`);
 		}
 
-		const { up, down } = await migrations[migrationPath]();
-		return { up, down };
+		return await migrations[migrationPath]();
 	}
 
 	return await import(`./migrations/${name}.js`).then(({ up, down }) => ({ up, down }));
@@ -60,5 +60,15 @@ const migrationIndex: Record<string, Migration> = {
  * const migrator = getMigratorLive<MySchema>(yourDriver);
  * await migrator.migrateToLatest();
  */
-export const getMigratorLive = <Schema>(dialect: Dialect) =>
-	makeMigratorLive<Schema>(dialect, migrationIndex);
+export const getMigratorLive = <Schema>(
+	dialect: Dialect
+): Effect.Effect<
+	{
+		readonly toLatest: Effect.Effect<MigrationResultSet, MigratorError, never>;
+		readonly down: Effect.Effect<MigrationResultSet, MigratorError, never>;
+		readonly up: Effect.Effect<MigrationResultSet, MigratorError, never>;
+		readonly status: Effect.Effect<readonly MigrationInfo[], MigratorError, never>;
+	},
+	MigratorError,
+	never
+> => makeMigratorLive<Schema>(dialect, migrationIndex);

packages/studiocms/src/cli/migrator/index.ts

@@ -4,7 +4,7 @@ import { label } from '@withstudiocms/cli-kit/messages';
 import { Cli, Effect, runEffect } from '@withstudiocms/effect';
 import { intro, log, outro, select, tasks } from '@withstudiocms/effect/clack';
 import type { MigrationInfo, MigrationResult } from '@withstudiocms/kysely/kysely';
-import { getMigratorLive } from '@withstudiocms/kysely/migrator';
+import { getMigratorLive } from '@withstudiocms/sdk/migrator';
 import { getDbDriver, parseDbDialect } from '../../db/index.js';
 import { genLogger } from '../../effect.js';
 import type { StudioCMSConfig } from '../../schemas/index.js';