emdash 0.34.0 → 0.35.0

package/src/migrations/config-loader.ts

@@ -0,0 +1,205 @@
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { AstroI18nInput } from "../i18n/normalize.js";
+import { normalizeAstroI18n } from "../i18n/normalize.js";
+import type { CoreMigrationIdentity } from "./identity.js";
+import {
+	getMigrationIntegrationMetadata,
+	MIGRATION_CONFIG_SYMBOL,
+} from "./integration-metadata.js";
+import { buildMigrationManifest } from "./manifest-builder.js";
+import type { MigrationManifestV1 } from "./manifest.js";
+
+const ASTRO_CONFIG_FILENAMES = [
+	"astro.config.mjs",
+	"astro.config.js",
+	"astro.config.ts",
+	"astro.config.mts",
+] as const;
+
+interface EvaluatedAstroConfig {
+	integrations?: unknown[];
+	i18n?: AstroI18nInput | null;
+}
+
+export interface BuildMigrationManifestFromConfigOptions {
+	projectRoot: string;
+	configFile?: string;
+}
+
+export interface MigrationConfigLoaderDependencies {
+	findConfigFile: (projectRoot: string, configFile?: string) => Promise<string>;
+	loadConfig: (projectRoot: string, configFile: string) => Promise<unknown>;
+	loadIdentity: (projectRoot: string) => Promise<CoreMigrationIdentity>;
+}
+
+export class MigrationConfigLoaderError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "MigrationConfigLoaderError";
+	}
+}
+
+async function isAccessible(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function findAstroConfigFile(
+	projectRoot: string,
+	configFile?: string,
+): Promise<string> {
+	const root = resolve(projectRoot);
+	if (configFile) {
+		const explicitPath = isAbsolute(configFile) ? configFile : resolve(root, configFile);
+		if (await isAccessible(explicitPath)) return explicitPath;
+		throw new MigrationConfigLoaderError(`Astro config file not found: ${explicitPath}`);
+	}
+
+	for (const filename of ASTRO_CONFIG_FILENAMES) {
+		const candidate = resolve(root, filename);
+		if (await isAccessible(candidate)) return candidate;
+	}
+
+	throw new MigrationConfigLoaderError(`No Astro config file found in ${root}`);
+}
+
+function projectRequire(projectRoot: string) {
+	return createRequire(resolve(projectRoot, "package.json"));
+}
+
+async function importModule(path: string): Promise<unknown> {
+	return import(pathToFileURL(path).href);
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function moduleExport(module: unknown, name: string): unknown {
+	if (!isRecord(module)) return undefined;
+	const direct = module[name];
+	if (direct !== undefined) return direct;
+	const defaultExport = module.default;
+	return isRecord(defaultExport) ? defaultExport[name] : undefined;
+}
+
+function isCoreMigrationIdentity(value: unknown): value is CoreMigrationIdentity {
+	return (
+		isRecord(value) &&
+		typeof value.emdashVersion === "string" &&
+		Array.isArray(value.names) &&
+		value.names.every((name) => typeof name === "string") &&
+		typeof value.fingerprint === "string"
+	);
+}
+
+async function loadProjectConfig(projectRoot: string, configFile: string): Promise<unknown> {
+	let viteEntrypoint: string;
+	try {
+		const require = projectRequire(projectRoot);
+		const astroEntrypoint = require.resolve("astro");
+		viteEntrypoint = createRequire(astroEntrypoint).resolve("vite");
+	} catch (error) {
+		throw new MigrationConfigLoaderError(
+			"Could not resolve Vite through the project's Astro installation",
+			{ cause: error },
+		);
+	}
+
+	const vite = await importModule(viteEntrypoint);
+	const loadConfigFromFile = moduleExport(vite, "loadConfigFromFile");
+	if (typeof loadConfigFromFile !== "function") {
+		throw new MigrationConfigLoaderError(
+			"The Vite installation used by project-local Astro does not export loadConfigFromFile",
+		);
+	}
+	const loaded: unknown = await Reflect.apply(loadConfigFromFile, undefined, [
+		{ command: "build", mode: "production" },
+		configFile,
+		projectRoot,
+		"silent",
+	]);
+	if (!isRecord(loaded) || !Object.hasOwn(loaded, "config")) {
+		throw new MigrationConfigLoaderError(`Vite could not load Astro config: ${configFile}`);
+	}
+	return loaded.config;
+}
+
+async function loadProjectIdentity(projectRoot: string): Promise<CoreMigrationIdentity> {
+	let identityEntrypoint: string;
+	try {
+		identityEntrypoint = projectRequire(projectRoot).resolve("emdash/migrations");
+	} catch (error) {
+		throw new MigrationConfigLoaderError("Could not resolve emdash/migrations from the project", {
+			cause: error,
+		});
+	}
+
+	const module = await importModule(identityEntrypoint);
+	const getIdentity = moduleExport(module, "getCoreMigrationIdentity");
+	if (typeof getIdentity !== "function") {
+		throw new MigrationConfigLoaderError(
+			"The project-local emdash/migrations module does not export getCoreMigrationIdentity",
+		);
+	}
+	const identity: unknown = await Reflect.apply(getIdentity, undefined, []);
+	if (!isCoreMigrationIdentity(identity)) {
+		throw new MigrationConfigLoaderError(
+			"The project-local emdash/migrations module returned an invalid migration identity",
+		);
+	}
+	return identity;
+}
+
+const defaultDependencies: MigrationConfigLoaderDependencies = {
+	findConfigFile: findAstroConfigFile,
+	loadConfig: loadProjectConfig,
+	loadIdentity: loadProjectIdentity,
+};
+
+function asAstroConfig(value: unknown): EvaluatedAstroConfig {
+	if (typeof value !== "object" || value === null) {
+		throw new MigrationConfigLoaderError("Astro config must export an object");
+	}
+	return value;
+}
+
+export async function buildMigrationManifestFromConfig(
+	options: BuildMigrationManifestFromConfigOptions,
+	dependencies: MigrationConfigLoaderDependencies = defaultDependencies,
+): Promise<MigrationManifestV1> {
+	const projectRoot = resolve(options.projectRoot);
+	const configFile = await dependencies.findConfigFile(projectRoot, options.configFile);
+	const config = asAstroConfig(await dependencies.loadConfig(projectRoot, configFile));
+	const integrations = Array.isArray(config.integrations) ? config.integrations : [];
+	const matchingIntegrations = integrations.filter(
+		(integration) => getMigrationIntegrationMetadata(integration) !== undefined,
+	);
+	if (matchingIntegrations.length !== 1) {
+		throw new MigrationConfigLoaderError(
+			`Expected exactly one EmDash integration with migration metadata (${String(MIGRATION_CONFIG_SYMBOL)}), found ${matchingIntegrations.length}`,
+		);
+	}
+
+	const metadata = getMigrationIntegrationMetadata(matchingIntegrations[0]);
+	if (!metadata?.database) {
+		throw new MigrationConfigLoaderError(
+			"The EmDash integration does not provide database migration metadata",
+		);
+	}
+	const identity = await dependencies.loadIdentity(projectRoot);
+
+	return buildMigrationManifest({
+		identity,
+		i18n: normalizeAstroI18n(config.i18n),
+		database: metadata.database,
+	});
+}

package/src/migrations/direct-executor.ts

@@ -0,0 +1,141 @@
+import { type Dialect, Kysely } from "kysely";
+
+import {
+	getExactMigrationStatus,
+	runMigrations,
+	type ExactMigrationStatus,
+} from "../database/migrations/runner.js";
+import type { Database } from "../database/types.js";
+import { getI18nConfig, setI18nConfig } from "../i18n/config.js";
+import { getCoreMigrationIdentity } from "./identity.js";
+import type {
+	MigrationExecutor,
+	MigrationReport,
+	MigrationRequest,
+	MigrationTarget,
+} from "./protocol.js";
+
+export interface DirectMigrationExecutorOptions {
+	target: MigrationTarget;
+	createDialect: () => Dialect | Promise<Dialect>;
+}
+
+function createReport(
+	target: MigrationTarget,
+	status: ExactMigrationStatus,
+	executed: readonly string[],
+): MigrationReport {
+	return {
+		target,
+		knownApplied: [...status.knownApplied],
+		pending: [...status.pending],
+		unknownApplied: [...status.unknownApplied],
+		executed: [...executed],
+	};
+}
+
+async function verifyRequest(request: MigrationRequest): Promise<void> {
+	const identity = await getCoreMigrationIdentity();
+	if (
+		request.artifact.emdashVersion !== identity.emdashVersion ||
+		request.artifact.migrationSetFingerprint !== identity.fingerprint
+	) {
+		throw new Error(
+			"Migration artifact does not match the loaded EmDash version and migration registry.",
+		);
+	}
+}
+
+async function executeRequest(
+	db: Kysely<Database>,
+	target: MigrationTarget,
+	request: MigrationRequest,
+): Promise<MigrationReport> {
+	const initialStatus = await getExactMigrationStatus(db);
+	if (request.action === "check") {
+		return createReport(target, initialStatus, []);
+	}
+
+	if (initialStatus.unknownApplied.length > 0) {
+		throw new Error(
+			`Cannot apply migrations with unknown applied migrations: ${initialStatus.unknownApplied.join(", ")}`,
+		);
+	}
+	if (initialStatus.pending.length === 0) {
+		return createReport(target, initialStatus, []);
+	}
+
+	const result = await runMigrations(db);
+	const finalStatus = await getExactMigrationStatus(db);
+	return createReport(target, finalStatus, result.applied);
+}
+
+export function createDirectMigrationExecutor(
+	options: DirectMigrationExecutorOptions,
+): MigrationExecutor {
+	const target = Object.freeze({ ...options.target });
+	let used = false;
+	let disposed = false;
+	let activeDb: Kysely<Database> | undefined;
+	let closePromise: Promise<void> | undefined;
+
+	const closeActiveDb = (): Promise<void> => {
+		if (!activeDb) return Promise.resolve();
+		closePromise ??= activeDb.destroy();
+		return closePromise;
+	};
+
+	return {
+		target,
+		async execute(request) {
+			if (disposed) {
+				throw new Error("Migration executor has been disposed.");
+			}
+			if (used) {
+				throw new Error("Migration executors are single-use.");
+			}
+			used = true;
+
+			if (request.action !== "check" && request.action !== "apply") {
+				throw new Error("Unsupported migration action.");
+			}
+			await verifyRequest(request);
+
+			const dialect = await options.createDialect();
+			const db = new Kysely<Database>({ dialect });
+			activeDb = db;
+			if (disposed) {
+				await closeActiveDb();
+				throw new Error("Migration executor has been disposed.");
+			}
+			const previousI18n = getI18nConfig();
+			let executionFailed = false;
+			let executionError: unknown;
+			let report: MigrationReport | undefined;
+			setI18nConfig(request.i18n);
+
+			try {
+				report = await executeRequest(db, target, request);
+			} catch (error) {
+				executionFailed = true;
+				executionError = error;
+			} finally {
+				setI18nConfig(previousI18n);
+				try {
+					await closeActiveDb();
+				} catch {
+					console.error("[migrations] Database close failed.");
+					closePromise = Promise.resolve();
+				}
+			}
+
+			if (executionFailed) throw executionError;
+			if (!report) throw new Error("Migration execution did not produce a report.");
+			return report;
+		},
+		dispose() {
+			disposed = true;
+			return closeActiveDb();
+		},
+	};
+}

package/src/migrations/identity.ts

@@ -0,0 +1,46 @@
+import { MIGRATION_NAMES } from "../database/migrations/runner.js";
+import { VERSION } from "../version.js";
+
+export interface CoreMigrationIdentity {
+	emdashVersion: string;
+	names: readonly string[];
+	fingerprint: string;
+}
+
+function encodeFingerprintInput(emdashVersion: string, names: readonly string[]): ArrayBuffer {
+	const encoded = new TextEncoder().encode(JSON.stringify({ emdashVersion, names }));
+	const buffer = new ArrayBuffer(encoded.byteLength);
+	new Uint8Array(buffer).set(encoded);
+	return buffer;
+}
+
+function encodeHex(bytes: Uint8Array): string {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function fingerprintMigrationSet(
+	emdashVersion: string,
+	names: readonly string[],
+): Promise<string> {
+	const digest = await crypto.subtle.digest(
+		"SHA-256",
+		encodeFingerprintInput(emdashVersion, names),
+	);
+	return encodeHex(new Uint8Array(digest));
+}
+
+export async function createCoreMigrationIdentity(
+	emdashVersion: string,
+	names: readonly string[],
+): Promise<CoreMigrationIdentity> {
+	const nameSnapshot = Object.freeze([...names]);
+	return Object.freeze({
+		emdashVersion,
+		names: nameSnapshot,
+		fingerprint: await fingerprintMigrationSet(emdashVersion, nameSnapshot),
+	});
+}
+
+export function getCoreMigrationIdentity(): Promise<CoreMigrationIdentity> {
+	return createCoreMigrationIdentity(VERSION, MIGRATION_NAMES);
+}

package/src/migrations/index.ts

@@ -0,0 +1,19 @@
+export { createDirectMigrationExecutor } from "./direct-executor.js";
+export type { DirectMigrationExecutorOptions } from "./direct-executor.js";
+export {
+	createCoreMigrationIdentity,
+	fingerprintMigrationSet,
+	getCoreMigrationIdentity,
+} from "./identity.js";
+export type { CoreMigrationIdentity } from "./identity.js";
+export type {
+	MigrationAction,
+	MigrationExecutor,
+	MigrationExecutorFactory,
+	MigrationExecutorFactoryContext,
+	MigrationExecutorModule,
+	MigrationReport,
+	MigrationRequest,
+	MigrationTarget,
+	MigrationTargetOverrides,
+} from "./protocol.js";

package/src/migrations/integration-metadata.ts

@@ -0,0 +1,67 @@
+import type { DatabaseDescriptor } from "../db/adapters.js";
+import { validateSecretFreeExecutorConfig } from "./manifest.js";
+
+export const MIGRATION_CONFIG_SYMBOL = Symbol.for("emdash:migration-config");
+
+export interface MigrationIntegrationMetadata {
+	database?: Pick<DatabaseDescriptor, "type" | "migrations">;
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isMigrationIntegrationMetadata(value: unknown): value is MigrationIntegrationMetadata {
+	if (!isRecord(value)) return false;
+	const database = value.database;
+	if (database === undefined) return true;
+	if (!isRecord(database) || (database.type !== "sqlite" && database.type !== "postgres")) {
+		return false;
+	}
+
+	const migrations = database.migrations;
+	return (
+		migrations === undefined ||
+		(isRecord(migrations) &&
+			typeof migrations.entrypoint === "string" &&
+			Object.hasOwn(migrations, "manifestConfig"))
+	);
+}
+
+export function createMigrationIntegrationMetadata(
+	database?: DatabaseDescriptor,
+): MigrationIntegrationMetadata {
+	if (!database) return {};
+
+	return {
+		database: {
+			type: database.type,
+			migrations: database.migrations
+				? {
+						entrypoint: database.migrations.entrypoint,
+						manifestConfig: validateSecretFreeExecutorConfig(
+							database.migrations.manifestConfig,
+							"database.migrations.manifestConfig",
+						),
+					}
+				: undefined,
+		},
+	};
+}
+
+export function getMigrationIntegrationMetadata(
+	integration: unknown,
+): MigrationIntegrationMetadata | undefined {
+	if (
+		(typeof integration !== "object" || integration === null) &&
+		typeof integration !== "function"
+	) {
+		return undefined;
+	}
+	if (!Object.hasOwn(integration, MIGRATION_CONFIG_SYMBOL)) {
+		return undefined;
+	}
+
+	const metadata: unknown = Reflect.get(integration, MIGRATION_CONFIG_SYMBOL);
+	return isMigrationIntegrationMetadata(metadata) ? metadata : undefined;
+}

package/src/migrations/manifest-builder.ts

@@ -0,0 +1,55 @@
+import type { DatabaseDescriptor } from "../db/adapters.js";
+import type { I18nConfig } from "../i18n/config.js";
+import type { CoreMigrationIdentity } from "./identity.js";
+import { fingerprintMigrationSet } from "./identity.js";
+import type { MigrationManifestV1 } from "./manifest.js";
+import { MigrationManifestValidationError, validateMigrationManifest } from "./manifest.js";
+
+export type ManifestDatabaseDescriptor = Pick<DatabaseDescriptor, "type" | "migrations">;
+
+export interface BuildMigrationManifestOptions {
+	identity: CoreMigrationIdentity;
+	i18n: I18nConfig | null;
+	database: ManifestDatabaseDescriptor;
+}
+
+export class UnsupportedMigrationAdapterError extends Error {
+	constructor() {
+		super("The configured database adapter does not provide a deployment migration executor");
+		this.name = "UnsupportedMigrationAdapterError";
+	}
+}
+
+export async function buildMigrationManifest({
+	identity,
+	i18n,
+	database,
+}: BuildMigrationManifestOptions): Promise<MigrationManifestV1> {
+	const identityFingerprint = await fingerprintMigrationSet(identity.emdashVersion, identity.names);
+	if (identityFingerprint !== identity.fingerprint) {
+		throw new MigrationManifestValidationError(
+			"loaded identity fingerprint does not match its version and ordered names",
+		);
+	}
+	if (!database.migrations) {
+		throw new UnsupportedMigrationAdapterError();
+	}
+
+	return validateMigrationManifest(
+		{
+			schemaVersion: 1,
+			emdashVersion: identity.emdashVersion,
+			migrationSet: {
+				names: [...identity.names],
+				fingerprint: identity.fingerprint,
+			},
+			i18n,
+			database: {
+				type: database.type,
+				executorEntrypoint: database.migrations.entrypoint,
+				executorConfig: database.migrations.manifestConfig,
+			},
+		},
+		identity,
+	);
+}

package/src/migrations/manifest-writer.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import {
+	mkdir as nodeMkdir,
+	rename as nodeRename,
+	unlink as nodeUnlink,
+	writeFile as nodeWriteFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { MigrationManifestV1 } from "./manifest.js";
+import { serializeMigrationManifest, validateMigrationManifest } from "./manifest.js";
+
+export const MIGRATION_MANIFEST_PATH = ".emdash/migrations.json";
+
+export interface ManifestWriterFileSystem {
+	mkdir(path: string, options: { recursive: true }): Promise<unknown>;
+	writeFile(
+		path: string,
+		data: string,
+		options: { encoding: "utf8"; flag: "wx" },
+	): Promise<unknown>;
+	rename(from: string, to: string): Promise<unknown>;
+	unlink(path: string): Promise<unknown>;
+}
+
+const nodeFileSystem: ManifestWriterFileSystem = {
+	mkdir: (path, options) => nodeMkdir(path, options),
+	writeFile: (path, data, options) => nodeWriteFile(path, data, options),
+	rename: (from, to) => nodeRename(from, to),
+	unlink: (path) => nodeUnlink(path),
+};
+
+export async function writeMigrationManifest(
+	projectRoot: string,
+	manifest: MigrationManifestV1,
+	fileSystem: ManifestWriterFileSystem = nodeFileSystem,
+): Promise<string> {
+	const validated = await validateMigrationManifest(manifest);
+	const outputPath = join(projectRoot, MIGRATION_MANIFEST_PATH);
+	const outputDirectory = dirname(outputPath);
+	await fileSystem.mkdir(outputDirectory, { recursive: true });
+
+	const temporaryPath = join(
+		outputDirectory,
+		`.migrations.json.${process.pid}.${randomUUID()}.tmp`,
+	);
+	let temporaryFileMayExist = false;
+	try {
+		temporaryFileMayExist = true;
+		await fileSystem.writeFile(temporaryPath, serializeMigrationManifest(validated), {
+			encoding: "utf8",
+			flag: "wx",
+		});
+		await fileSystem.rename(temporaryPath, outputPath);
+		temporaryFileMayExist = false;
+		return outputPath;
+	} catch (error) {
+		if (temporaryFileMayExist) {
+			await fileSystem.unlink(temporaryPath).catch(() => undefined);
+		}
+		throw error;
+	}
+}