@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/build/build-adapter.ts

@@ -1,7 +1,15 @@
 import type { BunPlugin } from 'bun';
 import type { EcoBuildPlugin } from './build-types.ts';
+import {
+	createAppBuildManifest,
+	getBrowserBuildPlugins,
+	getServerBuildPlugins,
+	type AppBuildManifest,
+} from './build-manifest.ts';
 import { EsbuildBuildAdapter } from './esbuild-build-adapter.ts';
 import { getRequiredBunRuntime } from '../utils/runtime.ts';
+import type { EcoPagesAppConfig } from '../internal-types.ts';
+import type { IHmrManager } from '../public-types.ts';
 
 export { EsbuildBuildAdapter } from './esbuild-build-adapter.ts';
 
@@ -45,7 +53,10 @@ export interface BuildResult {
 export interface BuildOptions {
 	entrypoints: string[];
 	outdir?: string;
+	outbase?: string;
 	naming?: string;
+	conditions?: string[];
+	define?: Record<string, string>;
 	minify?: boolean;
 	treeshaking?: boolean;
 	target?: string;
@@ -69,12 +80,38 @@ export interface BuildTranspileOptions {
 }
 
 export interface BuildAdapter {
+	/**
+	 * Executes one concrete backend build.
+	 *
+	 * @remarks
+	 * `BuildAdapter` is the low-level backend contract. The default adapter is
+	 * `EsbuildBuildAdapter`, but alternate adapters may satisfy the same shape.
+	 */
 	build(options: BuildOptions): Promise<BuildResult>;
 	resolve(importPath: string, rootDir: string): string;
-	registerPlugin(plugin: EcoBuildPlugin): void;
 	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
 
+/**
+ * Runtime-owned facade for issuing builds.
+ *
+ * @remarks
+ * This is intentionally narrower than `BuildAdapter`. A build executor answers
+ * only the question "how should this app execute a build right now?".
+ *
+ * In production and non-watch flows the executor is usually the adapter itself,
+ * which today means `EsbuildBuildAdapter`. In development watch flows the
+ * executor is typically `DevBuildCoordinator`, which wraps the shared esbuild
+ * adapter to serialize callers and recover from known worker faults.
+ */
+export interface BuildExecutor {
+	build(options: BuildOptions): Promise<BuildResult>;
+}
+
+export function createBuildAdapter(): BuildAdapter {
+	return new EsbuildBuildAdapter();
+}
+
 function transpileProfileToOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
 	switch (profile) {
 		case 'browser-script':
@@ -120,13 +157,205 @@ export class BunBuildAdapter implements BuildAdapter {
 		return getRequiredBunRuntime().resolveSync(importPath, rootDir);
 	}
 
-	registerPlugin(plugin: EcoBuildPlugin): void {
-		getRequiredBunRuntime().plugin(plugin as BunPlugin);
-	}
-
 	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
 		return transpileProfileToOptions(profile);
 	}
 }
 
-export const defaultBuildAdapter: BuildAdapter = new EsbuildBuildAdapter();
+export const defaultBuildAdapter: BuildAdapter = createBuildAdapter();
+
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder installs a dedicated adapter per app. The shared default
+ * adapter remains only as a compatibility fallback for older tests and helpers
+ * that do not yet thread app runtime state explicitly.
+ */
+export function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter {
+	return appConfig.runtime?.buildAdapter ?? defaultBuildAdapter;
+}
+
+/**
+ * Installs the adapter that should serve future builds for one app instance.
+ */
+export function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		buildAdapter,
+	};
+}
+
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ */
+export function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest {
+	return (
+		appConfig.runtime?.buildManifest ??
+		createAppBuildManifest({
+			loaderPlugins: Array.from(appConfig.loaders.values()),
+		})
+	);
+}
+
+/**
+ * Installs the build manifest that should be visible to one app instance.
+ */
+export function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		buildManifest,
+	};
+}
+
+/**
+ * Rebuilds an app-owned manifest from config-owned loaders plus explicit
+ * runtime/browser contribution input.
+ *
+ * @remarks
+ * This keeps loader ownership with config finalization while still letting a
+ * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ */
+export function createConfiguredAppBuildManifest(
+	appConfig: EcoPagesAppConfig,
+	input?: Partial<AppBuildManifest>,
+): AppBuildManifest {
+	return createAppBuildManifest({
+		loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
+		runtimePlugins: input?.runtimePlugins,
+		browserBundlePlugins: input?.browserBundlePlugins,
+	});
+}
+
+/**
+ * Replaces the app-owned manifest using config-owned loaders and explicit
+ * contribution input.
+ */
+export function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void {
+	setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
+}
+
+/**
+ * Collects the build-facing processor and integration contributions that should
+ * be sealed into the app manifest during config finalization.
+ *
+ * @remarks
+ * This runs `prepareBuildContributions()` only. Runtime-only side effects such
+ * as HMR registration, cache prewarming, and runtime-origin wiring belong to
+ * the startup path and must not be triggered here.
+ */
+export async function collectConfiguredAppBuildManifestContributions(
+	appConfig: EcoPagesAppConfig,
+): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>> {
+	const runtimePlugins: EcoBuildPlugin[] = [];
+	const browserBundlePlugins: EcoBuildPlugin[] = [];
+
+	for (const processor of appConfig.processors.values()) {
+		await processor.prepareBuildContributions();
+
+		if (processor.plugins) {
+			runtimePlugins.push(...processor.plugins);
+		}
+
+		if (processor.buildPlugins) {
+			browserBundlePlugins.push(...processor.buildPlugins);
+		}
+	}
+
+	for (const integration of appConfig.integrations) {
+		integration.setConfig(appConfig);
+		await integration.prepareBuildContributions();
+		runtimePlugins.push(...integration.plugins);
+	}
+
+	return {
+		runtimePlugins,
+		browserBundlePlugins,
+	};
+}
+
+/**
+ * Runs runtime-only processor and integration setup against an already sealed
+ * app manifest.
+ *
+ * @remarks
+ * Startup paths call this after config build has finalized manifest
+ * contributions. The manifest is reused as-is; this helper only performs the
+ * runtime side effects that still need live startup context.
+ */
+export async function setupAppRuntimePlugins(options: {
+	appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	hmrManager?: IHmrManager;
+	onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void> {
+	for (const processor of options.appConfig.processors.values()) {
+		await processor.setup();
+
+		if (processor.plugins) {
+			for (const plugin of processor.plugins) {
+				options.onRuntimePlugin?.(plugin);
+			}
+		}
+	}
+
+	for (const integration of options.appConfig.integrations) {
+		integration.setConfig(options.appConfig);
+		integration.setRuntimeOrigin(options.runtimeOrigin);
+		if (options.hmrManager) {
+			integration.setHmrManager(options.hmrManager);
+		}
+
+		await integration.setup();
+
+		for (const plugin of integration.plugins) {
+			options.onRuntimePlugin?.(plugin);
+		}
+	}
+}
+
+export function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[] {
+	return getServerBuildPlugins(getAppBuildManifest(appConfig));
+}
+
+export function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[] {
+	return getBrowserBuildPlugins(getAppBuildManifest(appConfig));
+}
+
+/**
+ * Returns the executor owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder seeds this with the shared default adapter. Runtime
+ * adapters may replace it with a coordinator that still delegates to the same
+ * backend while adding development policy.
+ */
+export function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor {
+	return appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
+}
+
+/**
+ * Installs the executor that should serve future builds for one app instance.
+ */
+export function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		buildExecutor,
+	};
+}
+
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * Callers can pass an explicit executor when builds should be routed through an
+ * app-owned development coordinator. Without one, the shared default adapter is
+ * used directly.
+ */
+export function build(options: BuildOptions, executor: BuildExecutor = defaultBuildAdapter): Promise<BuildResult> {
+	return executor.build(options);
+}
+
+export function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
+	return defaultBuildAdapter.getTranspileOptions(profile);
+}

package/src/build/build-manifest.ts

@@ -0,0 +1,54 @@
+import type { EcoBuildPlugin } from './build-types.ts';
+
+export interface AppBuildManifest {
+	loaderPlugins: EcoBuildPlugin[];
+	runtimePlugins: EcoBuildPlugin[];
+	browserBundlePlugins: EcoBuildPlugin[];
+}
+
+/**
+ * Merges plugin lists while preserving first-registration precedence by name.
+ *
+ * @remarks
+ * Build manifests treat plugin names as stable identities. The first plugin
+ * with a given name wins so config-time assembly stays deterministic across
+ * loader, runtime, and browser buckets.
+ */
+export function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[] {
+	const byName = new Map<string, EcoBuildPlugin>();
+
+	for (const plugins of pluginLists) {
+		for (const plugin of plugins ?? []) {
+			if (!byName.has(plugin.name)) {
+				byName.set(plugin.name, plugin);
+			}
+		}
+	}
+
+	return Array.from(byName.values());
+}
+
+/**
+ * Creates one app-owned build manifest from the supplied plugin buckets.
+ */
+export function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest {
+	return {
+		loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
+		runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
+		browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins),
+	};
+}
+
+/**
+ * Returns the plugin list used for server-oriented builds.
+ */
+export function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[] {
+	return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
+}
+
+/**
+ * Returns the plugin list used for browser-oriented builds.
+ */
+export function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[] {
+	return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, manifest.browserBundlePlugins);
+}

package/src/build/dev-build-coordinator.ts

@@ -0,0 +1,221 @@
+import { appLogger } from '../global/app-logger.ts';
+import {
+	defaultBuildAdapter,
+	type BuildAdapter,
+	type BuildExecutor,
+	type BuildOptions,
+	type BuildResult,
+	EsbuildBuildAdapter,
+} from './build-adapter.ts';
+import { mergeEcoBuildPlugins } from './build-manifest.ts';
+import type { EcoBuildPlugin } from './build-types.ts';
+
+function mergeBuildPlugins(options: BuildOptions, appPlugins: EcoBuildPlugin[]): BuildOptions {
+	if (appPlugins.length === 0) {
+		return options;
+	}
+
+	return {
+		...options,
+		plugins: mergeEcoBuildPlugins(options.plugins, appPlugins),
+	};
+}
+
+class BuildExecutorWithPlugins implements BuildExecutor {
+	private readonly executor: BuildExecutor;
+	private readonly getPlugins: () => EcoBuildPlugin[];
+
+	constructor(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]) {
+		this.executor = executor;
+		this.getPlugins = getPlugins;
+	}
+
+	async build(options: BuildOptions): Promise<BuildResult> {
+		return await this.executor.build(mergeBuildPlugins(options, this.getPlugins()));
+	}
+
+	unwrap(): BuildExecutor {
+		return this.executor;
+	}
+}
+
+function unwrapBuildExecutor(executor: BuildExecutor): BuildExecutor {
+	if (executor instanceof BuildExecutorWithPlugins) {
+		return unwrapBuildExecutor(executor.unwrap());
+	}
+
+	return executor;
+}
+
+export function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor {
+	return new BuildExecutorWithPlugins(executor, getPlugins);
+}
+
+/**
+ * Serialized development build coordinator for the shared esbuild adapter.
+ *
+ * The underlying adapter remains responsible for plain build execution. This
+ * coordinator owns the policy that must be shared across callers in dev mode:
+ *
+ * - serialized access to the shared esbuild service
+ * - warm-service recycling for Node-target builds
+ * - recovery from known esbuild worker protocol faults
+ *
+ * Unlike the previous design, the coordinator does not monkey-patch the adapter
+ * or install process-level fault handlers. The owning app/runtime passes this
+ * executor explicitly to build consumers that need coordinated development
+ * builds.
+ */
+export class DevBuildCoordinator implements BuildExecutor {
+	private buildQueue: Promise<void> = Promise.resolve();
+	private esbuildSessionWarm = false;
+	private esbuildModuleGeneration = 0;
+	private readonly adapter: EsbuildBuildAdapter;
+
+	constructor(adapter: EsbuildBuildAdapter) {
+		this.adapter = adapter;
+	}
+
+	/**
+	 * Executes a build through the serialized development queue.
+	 *
+	 * Node-target builds recycle the warmed esbuild service between requests to
+	 * avoid stale worker state accumulating across long-lived dev sessions.
+	 *
+	 * If an esbuild protocol fault is detected, the coordinator resets the queue,
+	 * stops the corrupted service, increments the module generation, and retries
+	 * the build once.
+	 */
+	async build(options: BuildOptions): Promise<BuildResult> {
+		return this.runSerialized(async () => {
+			try {
+				if (this.shouldRecycleEsbuildService(options)) {
+					await this.adapter.stopEsbuildService(this.esbuildModuleGeneration);
+					this.esbuildSessionWarm = false;
+				}
+
+				const result = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+				this.esbuildSessionWarm = true;
+				return result;
+			} catch (error) {
+				if (await this.recoverFromProtocolFault(error)) {
+					appLogger.warn('Recovered from esbuild protocol fault. Retrying build.');
+					try {
+						const retry = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+						this.esbuildSessionWarm = true;
+						return retry;
+					} catch (retryError) {
+						return this.adapter.createFailureResult(retryError);
+					}
+				}
+				return this.adapter.createFailureResult(error);
+			}
+		});
+	}
+
+	/**
+	 * Attempts recovery from a known esbuild worker protocol fault.
+	 *
+	 * Returns `true` only when the error matches the protocol-fault signature and
+	 * the coordinator successfully reset its shared state.
+	 */
+	async recoverFromProtocolFault(error: unknown): Promise<boolean> {
+		if (!this.adapter.isEsbuildProtocolError(error)) {
+			return false;
+		}
+		this.buildQueue = Promise.resolve();
+		this.esbuildSessionWarm = false;
+		await this.adapter.stopEsbuildService(this.esbuildModuleGeneration);
+		this.esbuildModuleGeneration += 1;
+		return true;
+	}
+
+	/**
+	 * Clears internal coordinator state for isolated tests.
+	 */
+	resetForTests(): void {
+		this.buildQueue = Promise.resolve();
+		this.esbuildSessionWarm = false;
+		this.esbuildModuleGeneration = 0;
+	}
+
+	/**
+	 * Overrides the internal queue promise for fault-recovery tests.
+	 */
+	setBuildQueueForTests(queue: Promise<void>): void {
+		this.buildQueue = queue;
+	}
+
+	/**
+	 * Returns the current internal queue promise for fault-recovery tests.
+	 */
+	getBuildQueueForTests(): Promise<void> {
+		return this.buildQueue;
+	}
+
+	private shouldRecycleEsbuildService(options: BuildOptions): boolean {
+		return process.env.NODE_ENV === 'development' && options.target !== 'browser' && this.esbuildSessionWarm;
+	}
+
+	private async runSerialized<T>(operation: () => Promise<T>): Promise<T> {
+		let releaseBuild: (() => void) | undefined;
+		const currentBuild = new Promise<void>((resolve) => {
+			releaseBuild = resolve;
+		});
+		const previousBuild = this.buildQueue;
+
+		this.buildQueue = previousBuild.catch(() => undefined).then(async () => await currentBuild);
+		await previousBuild.catch(() => undefined);
+
+		try {
+			return await operation();
+		} finally {
+			releaseBuild?.();
+		}
+	}
+}
+
+/**
+ * Creates the appropriate build executor for one app/runtime instance.
+ *
+ * Development runtimes get a dedicated coordinator around the shared esbuild
+ * adapter. Non-development runtimes use the adapter directly.
+ */
+export function createAppBuildExecutor(options: {
+	development: boolean;
+	adapter?: BuildAdapter;
+	getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor {
+	const adapter = options.adapter ?? defaultBuildAdapter;
+	const baseExecutor =
+		!options.development || !(adapter instanceof EsbuildBuildAdapter) ? adapter : new DevBuildCoordinator(adapter);
+
+	if (!options.getPlugins) {
+		return baseExecutor;
+	}
+
+	return new BuildExecutorWithPlugins(baseExecutor, options.getPlugins);
+}
+
+export function createOrReuseAppBuildExecutor(options: {
+	development: boolean;
+	adapter?: BuildAdapter;
+	currentExecutor?: BuildExecutor;
+	getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor {
+	const adapter = options.adapter ?? defaultBuildAdapter;
+	const currentBaseExecutor = options.currentExecutor ? unwrapBuildExecutor(options.currentExecutor) : undefined;
+	const baseExecutor =
+		options.development && currentBaseExecutor instanceof DevBuildCoordinator
+			? currentBaseExecutor
+			: createAppBuildExecutor({
+					development: options.development,
+					adapter,
+				});
+
+	if (!options.getPlugins) {
+		return baseExecutor;
+	}
+
+	return withBuildExecutorPlugins(baseExecutor, options.getPlugins);
+}