@studiocms/migrator 0.0.0-beta.0 → 0.1.0-beta.1

package/src/pages/index.astro

@@ -0,0 +1,259 @@
+---
+import { Button } from 'studiocms:ui/components/button';
+import { Card } from 'studiocms:ui/components/card';
+import { Divider } from 'studiocms:ui/components/divider';
+import { TabItem, Tabs } from 'studiocms:ui/components/tabs';
+import { runEffect } from '@withstudiocms/effect';
+import type { ComponentProps } from 'astro/types';
+import ErrorCard from '../components/ErrorCard.astro';
+import MigrationMeta from '../components/MigrationMeta.astro';
+import MigrationStatus from '../components/MigrationStatus.astro';
+import StatusTables from '../components/StatusTables.astro';
+import { runConnectionTest, searchTables } from '../db/astrodb.js';
+import {
+	getDataMigrationStatus,
+	getDialectFromEnv,
+	runConnectionTest as runStudioCMSDbConnectionTest,
+	studioCMSDbMigrator,
+} from '../db/client.js';
+import Layout from '../layouts/Layout.astro';
+import { getErrorCases } from '../lib/errors.js';
+import { astroDbTableKeys, migrationMeta } from '../lib/tableMap.js';
+
+// Test AstroDB Connection
+const isAstroDBConnected = await runConnectionTest();
+
+// Test StudioCMS DB Connection
+const isStudioCMSDbConnected = await runStudioCMSDbConnectionTest();
+
+// AstroDB Tables
+const astroDBTables = await searchTables('StudioCMS%').catch(() => []);
+
+// StudioCMS Schema Migrations
+const migrator = await studioCMSDbMigrator();
+const migrationStatus = await runEffect(migrator.status).catch(() => []);
+const migrationTotal = migrationStatus.length;
+const appliedMigrations = migrationStatus.filter((m) => m.executedAt).length;
+
+// Data Migration Status
+const dataMigrationStatus = await getDataMigrationStatus();
+
+// Determine Error Cases
+const errorCases = getErrorCases({
+	astroDBTables,
+	astroDbTableKeys,
+	appliedMigrations,
+	migrationTotal,
+	dataMigrationStatus,
+});
+
+const migrationMetaData = await migrationMeta();
+
+// Prepare Database Status Tables
+const dbStatusTables: ComponentProps<typeof StatusTables>['dbStatusTables'] = [
+	{
+		label: 'AstroDB Database',
+		conditions: [
+			{
+				label: 'Connection Status',
+				value: isAstroDBConnected ? 'Connected' : 'Not Connected',
+				color: isAstroDBConnected ? 'success' : 'danger',
+			},
+			{
+				label: 'Required Tables',
+				value:
+					astroDBTables.length >= astroDbTableKeys.length
+						? 'Available'
+						: `Missing ${astroDbTableKeys.length - astroDBTables.length} Tables`,
+				color: astroDBTables.length >= astroDbTableKeys.length ? 'success' : 'danger',
+			},
+		],
+	},
+	{
+		label: 'StudioCMS Database',
+		conditions: [
+			{
+				label: 'Connection Status',
+				value: isStudioCMSDbConnected ? 'Connected' : 'Not Connected',
+				color: isStudioCMSDbConnected ? 'success' : 'danger',
+			},
+			{
+				label: 'Dialect',
+				value: getDialectFromEnv(),
+				color: 'info',
+			},
+			{
+				label: 'Schema Migration Status',
+				value: appliedMigrations === migrationTotal ? 'Latest' : 'Pending Migrations',
+				color: appliedMigrations === migrationTotal ? 'success' : 'danger',
+			},
+			{
+				label: 'Data Migration Status',
+				value: dataMigrationStatus.canMigrate ? 'Available' : 'Not Available',
+				color: dataMigrationStatus.canMigrate ? 'success' : 'danger',
+			},
+		],
+	},
+];
+---
+<Layout title="StudioCMS Migrator">
+
+    {
+        errorCases
+            .filter((error) => error.condition)
+            .map(({ title, description }) => (
+                <ErrorCard {title} {description} />
+            ))
+    }
+
+    <Card fullWidth class="db-status-card" variant='filled'>
+
+        <div slot="header">
+            <h2>Database Status Overview</h2>
+        </div>
+
+        <div class="split-screen">
+
+            <StatusTables {dbStatusTables} />
+
+        </div>
+
+        <span class="divider-holder"><Divider /></span>
+
+        <h2>Migration Actions</h2>
+
+        <Tabs variant='starlight' syncKey='migration-type' storage='persistent'>
+
+            <TabItem label='Schema Migrations'>
+
+                <div class="button-shelf">
+                    <Button 
+                        id='run-schema-migrations-button'
+                        variant='solid' 
+                        color='primary'
+                        size="md"
+                        disabled={appliedMigrations === migrationTotal}
+                        >Run Schema Migrations
+                    </Button>
+                </div>
+
+                <MigrationStatus {migrationStatus} />
+            </TabItem>
+
+            <TabItem label='Migrate Data'>
+                
+                <div class="button-shelf">
+                    <Button 
+                        id='run-data-migrations-button'
+                        variant='solid' 
+                        color='primary'
+                        size="md"
+                        disabled={!dataMigrationStatus.canMigrate}
+                        >Run Data Migrations
+                    </Button>
+                </div>
+
+                <MigrationMeta {migrationMetaData} />
+            </TabItem>
+
+        </Tabs>
+
+    </Card>
+
+    <script>
+        import { toast } from 'studiocms:ui/components/toaster/client';
+
+        // Helpers
+
+        const $ = <E extends Element>(selector: string) => document.querySelector<E>(selector);
+
+        function resetMigrationButton(element: HTMLButtonElement, text: string) {
+            element.disabled = false;
+            element.textContent = text;
+        };
+
+        // Consts
+
+        const schemaMigrations = $<HTMLButtonElement>('#run-schema-migrations-button');
+        const dataMigrations = $<HTMLButtonElement>('#run-data-migrations-button');
+
+        // Event Listeners
+
+        schemaMigrations?.addEventListener('click', async () => {
+            schemaMigrations.disabled = true;
+            schemaMigrations.textContent = 'Running Migrations...';
+
+            try {
+                const response = await fetch('/schema-migrations', {
+                    method: 'POST',
+                });
+
+                if (response.ok) {
+                    toast({
+                        title: 'Schema Migrations Applied',
+                        description: 'All pending schema migrations have been successfully applied.',
+                        type: 'success',
+                    })
+
+                    setTimeout(() => {
+                        window.location.reload();
+                    }, 3000);
+                } else {
+                    const errorData = await response.json();
+                    toast({
+                        title: 'Error Applying Migrations',
+                        description: errorData.error,
+                        type: 'danger',
+                    });
+                    resetMigrationButton(schemaMigrations, 'Run Schema Migrations');
+                }
+            } catch (error) {
+                toast({
+                    title: 'Network Error',
+                    description: String(error),
+                    type: 'danger',
+                });
+                resetMigrationButton(schemaMigrations, 'Run Schema Migrations');
+            }
+        });
+
+        dataMigrations?.addEventListener('click', async () => {
+            dataMigrations.disabled = true;
+            dataMigrations.textContent = 'Migrating Data...';
+
+            try {
+                const response = await fetch('/data-migrations', {
+                    method: 'POST',
+                });
+
+                if (response.ok) {
+                    toast({
+                        title: 'Data Migration Completed',
+                        description: 'Data migration has been successfully completed.',
+                        type: 'success',
+                    })
+
+                    setTimeout(() => {
+                        window.location.reload();
+                    }, 3000);
+                } else {
+                    const errorData = await response.json();
+                    toast({
+                        title: 'Error During Data Migration',
+                        description: errorData.error,
+                        type: 'danger',
+                    });
+                    resetMigrationButton(dataMigrations, 'Run Data Migrations');
+                }
+            } catch (error) {
+                toast({
+                    title: 'Network Error',
+                    description: String(error),
+                    type: 'danger',
+                });
+                resetMigrationButton(dataMigrations, 'Run Data Migrations');
+            }
+        });
+    </script>
+
+</Layout>

package/src/pages/schema-migrations.ts

@@ -0,0 +1,31 @@
+import { runEffect } from '@withstudiocms/effect';
+import type { APIRoute } from 'astro';
+import { studioCMSDbMigrator } from '../db/client.js';
+import logger from '../lib/logger.js';
+import { jsonResponse } from '../lib/response-utils.js';
+
+export const POST: APIRoute = async () => {
+	const migrator = await studioCMSDbMigrator();
+
+	const { error, results } = await runEffect(migrator.toLatest).catch((err) => ({
+		error: err,
+		results: undefined,
+	}));
+
+	if (results) {
+		for (const it of results) {
+			if (it.status === 'Success') {
+				logger.info(`Migration ${it.migrationName} applied successfully.`);
+			} else if (it.status === 'Error') {
+				logger.error(`Error applying migration ${it.migrationName}.`);
+			}
+		}
+	}
+
+	if (error) {
+		logger.error(`Migration failed with error: ${String(error)}`);
+		return jsonResponse({ success: false, error: String(error) }, 500);
+	}
+
+	return jsonResponse({ success: true });
+};

package/src/styles/global.css

@@ -0,0 +1,165 @@
+main {
+	margin: 0 auto;
+	padding: 1rem;
+	max-width: 1000px;
+	width: 100%;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 2rem;
+}
+
+.prose {
+	max-width: 100%;
+	min-width: 100%;
+}
+
+.header-content {
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	width: 100%;
+
+	.header-logo {
+		height: 50px;
+		width: 50px;
+	}
+
+	.header-text {
+		display: flex;
+		width: 100%;
+		min-width: 100%;
+		flex-direction: column;
+		justify-content: center;
+
+		* {
+			width: 100%;
+			min-width: 100%;
+		}
+	}
+}
+
+:root {
+	--color-error: var(--danger-base);
+	--color-error-background: color-mix(in srgb, var(--color-error) 10%, var(--background-base) 90%);
+	--color-error-foreground: var(--danger-vibrant);
+}
+
+.db-error-card {
+	border: 1px solid var(--color-error);
+	background-color: var(--color-error-background);
+	color: var(--color-error-foreground);
+	padding: 1rem;
+	border-radius: 8px;
+	width: 100%;
+
+	.error-header {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+	}
+
+	h2 {
+		margin-top: 0;
+		color: var(--color-error-foreground);
+	}
+
+	p {
+		margin-bottom: 0;
+	}
+}
+
+.db-status-card {
+	h2 {
+		margin-top: 0;
+		font-size: x-large;
+	}
+
+	p {
+		margin-bottom: 0;
+	}
+
+	.status-label {
+		display: flex;
+		align-items: center;
+		width: 100%;
+		font-weight: bold;
+		font-size: large;
+		border-bottom: 2px solid var(--border);
+		margin-bottom: 0.5rem;
+		padding-bottom: 0.25rem;
+	}
+
+	table {
+		border-collapse: collapse;
+		width: 100%;
+
+		tr {
+			border-bottom: 1px solid var(--border);
+		}
+
+		tr:last-child {
+			border-bottom: none;
+		}
+
+		/* tr every other row */
+		tr:nth-child(even) {
+			background-color: var(--background-step-3);
+		}
+
+		tr.not-applicable {
+			opacity: 0.5;
+		}
+
+		th,
+		td {
+			padding: 0.5rem;
+			text-align: left;
+		}
+
+		/* td first column */
+		td:first-child {
+			font-weight: bold;
+		}
+
+		thead {
+			border-bottom: 2px solid var(--border);
+		}
+	}
+
+	table.migration {
+		background-color: var(--background-step-2);
+		border: 1px solid var(--border);
+	}
+
+	.status {
+		font-weight: bold;
+	}
+}
+
+.split-screen {
+	display: flex;
+	gap: 2rem;
+	width: 100%;
+
+	.split-screen-item {
+		flex: 1;
+		width: 100%;
+		background-color: var(--background-step-2);
+		padding: 0.5rem 0.5rem;
+		border: 2px solid var(--border);
+		border-radius: 4px;
+	}
+}
+
+.divider-holder {
+	width: 100%;
+	margin: 1rem 0;
+	display: flex;
+}
+
+.button-shelf {
+	width: 100%;
+	display: flex;
+	margin-bottom: 1rem;
+}

package/start.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConfigFile, parseAndMerge } from '@withstudiocms/config-utils';
+import dotenv from 'dotenv';
+import { configPaths } from 'studiocms/consts';
+import { StudioCMSOptionsSchema } from 'studiocms/schemas';
+import { Logger } from './utils/logger.mjs';
+import createPathResolver from './utils/resolver.mjs';
+
+const logger = new Logger({ level: 'info' }, '@studiocms/migrator');
+
+/**
+ * Asynchronously loads the StudioCMS configuration for the current project, merges it with
+ * a minimal default configuration, and populates process.env with derived environment variables.
+ *
+ * Behavior:
+ * - Computes the project root URL from process.cwd() using pathToFileURL.
+ * - Attempts to load a user configuration via loadConfigFile(rootPath, configPaths, 'db-migrator-util').
+ * - Logs whether a config file was found or if the default configuration will be used.
+ * - Constructs a minimal default configuration via StudioCMSOptionsSchema.parse({}).
+ * - Merges the loaded user configuration (if any) with the default using parseAndMerge.
+ * - Sets the STUDIOCMS_DIALECT environment variable from the merged user configuration
+ *   and writes it into process.env using dotenv.populate(..., { quiet: true }).
+ *
+ * Notes:
+ * - The function produces side effects: console output and mutation of process.env.
+ * - The implementation depends on surrounding module-scope values/exports such as
+ *   pathToFileURL, configPaths, loadConfigFile, StudioCMSOptionsSchema, parseAndMerge, and dotenv.
+ *
+ * @async
+ * @function loadCMSConfigFile
+ * @returns {Promise<void>} Resolves when the configuration has been loaded, merged, and environment variables populated.
+ * @throws {Error} If loading, parsing, or merging the configuration fails (errors bubbled from loadConfigFile,
+ *                 StudioCMSOptionsSchema.parse, parseAndMerge, or dotenv.populate).
+ * @example
+ * // Usage (top-level await or from an async function):
+ * await loadCMSConfigFile();
+ */
+async function loadCMSConfigFile() {
+	try {
+		// Determine the root path of the project
+		const rootPath = pathToFileURL(join(createPathResolver(process.cwd()).resolve('.'), './'));
+
+		// Load StudioCMS Config file
+		const configFile = await loadConfigFile(rootPath, configPaths, 'db-migrator-util');
+
+		// Log whether the config file was found
+		if (configFile) {
+			logger.info('Loaded StudioCMS config file successfully.');
+		} else {
+			logger.warn('No StudioCMS config file found, using default configuration.');
+		}
+
+		// Merge user config with default config
+		const userConfig = parseAndMerge(StudioCMSOptionsSchema, configFile);
+
+		// Set custom environment variables based on user config
+		const customENV = { STUDIOCMS_DIALECT: userConfig.db.dialect };
+
+		// Populate process.env with custom environment variables
+		dotenv.populate(process.env, customENV, { quiet: true });
+	} catch (error) {
+		logger.error(
+			`Error loading StudioCMS configuration: ${error instanceof Error ? error.message : String(error)}`
+		);
+		throw error;
+	}
+}
+
+/**
+ * Asynchronously serves the Astro-based UI for the migrator tool.
+ *
+ * This function dynamically imports the necessary Astro modules and starts
+ * the development server with the StudioCMS UI integration for styles and components.
+ *
+ * Behavior:
+ * - Dynamically imports 'astro', '@astrojs/node', and '@studiocms/ui'.
+ * - Calls astro.dev() with the appropriate configuration to start the server.
+ * - Catches and logs any errors that occur during the server startup process.
+ *
+ * Notes:
+ * - The function produces side effects: launching server processes/listeners
+ *   and modifying process.env.
+ *
+ * @async
+ * @function serveUI
+ * @returns {Promise<void>} Resolves when the Astro server has been started.
+ * @throws {Error} If starting the Astro server fails (errors bubbled from astro.dev).
+ */
+async function serveUI() {
+	const astro = await import('astro');
+	const { default: node } = await import('@astrojs/node');
+	const { default: ui } = await import('@studiocms/ui');
+
+	const pkgRootPath = createPathResolver(import.meta.url).resolve('.');
+
+	try {
+		await astro.dev({
+			root: pkgRootPath,
+			output: 'server',
+			configFile: false,
+			logLevel: 'error',
+			devToolbar: {
+				enabled: false,
+			},
+			adapter: node({
+				mode: 'standalone',
+			}),
+			integrations: [
+				ui(),
+				{
+					name: 'studiocms-migrator-ui',
+					hooks: {
+						'astro:server:start': ({ address }) => {
+							for (const line of [
+								'🚀 StudioCMS Migrator UI is running!',
+								`You can access it at: http://localhost:${address.port}`,
+							]) {
+								logger.info(line);
+							}
+						},
+					},
+				},
+			],
+		});
+	} catch (error) {
+		logger.error(
+			`Error starting Astro server for StudioCMS Migrator UI: ${error instanceof Error ? error.message : String(error)}`
+		);
+		throw error;
+	}
+}
+
+/**
+ * Initialize the application runtime by loading configuration and starting the Astro server.
+ *
+ * This async function performs two sequential startup tasks:
+ * 1. Loads the configuration file and applies any resulting environment variable settings.
+ * 2. Loads and starts the Astro server.
+ *
+ * Both operations are awaited; the returned promise resolves once configuration has been applied
+ * and the Astro server has been successfully started. Side effects include modification of
+ * process.env and launching server processes/listeners.
+ *
+ * @async
+ * @function start
+ * @returns {Promise<void>} Resolves when configuration is loaded and the Astro server is started.
+ * @throws {Error} If loading the configuration or starting the Astro server fails.
+ */
+export async function start() {
+	logger.info('Starting StudioCMS Migrator...');
+	dotenv.config({ quiet: true });
+	await loadCMSConfigFile();
+	await serveUI();
+}
+
+start().catch((error) => {
+	logger.error(
+		`Failed to start StudioCMS Migrator: ${error instanceof Error ? error.message : String(error)}`
+	);
+	process.exit(1);
+});

package/utils/logger.mjs

@@ -0,0 +1,93 @@
+import { styleText } from 'node:util';
+
+/**
+ * Intl.DateTimeFormat instance for formatting timestamps in log messages.
+ */
+const dateTimeFormat = new Intl.DateTimeFormat([], {
+	hour: '2-digit',
+	minute: '2-digit',
+	second: '2-digit',
+	hour12: false,
+});
+
+/**
+ * Returns a formatted level prefix string based on the log level.
+ */
+function getLevelPrefix(level) {
+	const levelLabel = level.toUpperCase();
+	switch (level) {
+		case 'error':
+			return `[${levelLabel}]`;
+		case 'warn':
+			return `[${levelLabel}]`;
+		case 'debug':
+			return `[${levelLabel}]`;
+		default:
+			return '';
+	}
+}
+
+/**
+ * Generates a formatted event prefix string based on the log level and optional label.
+ */
+const getEventPrefix = (level, label) => {
+	const timestamp = `${dateTimeFormat.format(/* @__PURE__ */ new Date())}`;
+	const prefix = [];
+	if (level === 'error' || level === 'warn' || level === 'debug') {
+		prefix.push(styleText('bold', timestamp));
+		prefix.push(getLevelPrefix(level));
+	} else {
+		prefix.push(timestamp);
+	}
+	if (label) {
+		prefix.push(`[${label}]`);
+	}
+	if (level === 'error') {
+		return styleText('red', prefix.join(' '));
+	}
+	if (level === 'warn') {
+		return styleText('yellow', prefix.join(' '));
+	}
+	if (level === 'debug') {
+		return styleText('blue', prefix.join(' '));
+	}
+	if (prefix.length === 1) {
+		/* v8 ignore start */
+		return styleText('dim', prefix[0]);
+		/* v8 ignore stop */
+	}
+	return `${styleText('dim', prefix[0])} ${styleText('blue', prefix.splice(1).join(' '))}`;
+};
+
+/**
+ * A simple logger class for logging messages with different levels and labels.
+ */
+export class Logger {
+	options;
+	label;
+
+	constructor(logging, label) {
+		this.options = logging;
+		this.label = label;
+	}
+
+	/**
+	 * Creates a new logger instance with a new label, but the same log options.
+	 */
+	fork(label) {
+		return new Logger(this.options, label);
+	}
+
+	info(message) {
+		console.log(`${getEventPrefix('info', this.label)} ${message}`);
+	}
+	warn(message) {
+		console.warn(`${getEventPrefix('warn', this.label)} ${message}`);
+	}
+	error(message) {
+		console.error(`${getEventPrefix('error', this.label)} ${message}`);
+	}
+	debug(message) {
+		console.debug(`${getEventPrefix('debug', this.label)} ${message}`);
+	}
+}