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

package/src/build/esbuild-build-adapter.ts

@@ -6,6 +6,7 @@ import type {
 } from 'esbuild';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { fileSystem } from '@ecopages/file-system';
 import type {
 	EcoBuildOnLoadResult,
@@ -23,6 +24,8 @@ import type {
 	BuildTranspileProfile,
 } from './build-adapter.ts';
 
+const esbuildRequire = createRequire(import.meta.url);
+
 /**
  * Provides common transpile output defaults shared across build profiles.
  */
@@ -56,17 +59,14 @@ function transpileProfileToOptions(profile: BuildTranspileProfile): BuildTranspi
  * and `module`) while delegating bundling and TypeScript/decorator transforms to esbuild.
  */
 export class EsbuildBuildAdapter implements BuildAdapter {
-	private registeredPlugins: EcoBuildPlugin[] = [];
-
 	private escapeRegExp(value: string): string {
 		return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 	}
 
 	private getPluginsForBuild(additionalPlugins?: EcoBuildPlugin[]): EcoBuildPlugin[] {
-		const merged = [...(additionalPlugins ?? []), ...this.registeredPlugins];
 		const byName = new Map<string, EcoBuildPlugin>();
 
-		for (const plugin of merged) {
+		for (const plugin of additionalPlugins ?? []) {
 			if (!byName.has(plugin.name)) {
 				byName.set(plugin.name, plugin);
 			}
@@ -286,8 +286,28 @@ export class EsbuildBuildAdapter implements BuildAdapter {
 		};
 	}
 
-	private async loadEsbuildModule(): Promise<typeof import('esbuild')> {
-		const esbuildModule = (await import('esbuild')) as typeof import('esbuild');
+	private async loadEsbuildModule(moduleGeneration = 0): Promise<typeof import('esbuild')> {
+		const importedModule = await import('esbuild');
+		const esbuildModule = (
+			typeof (importedModule as typeof import('esbuild')).build === 'function'
+				? importedModule
+				: ((importedModule as { default?: typeof import('esbuild') }).default ?? importedModule)
+		) as typeof import('esbuild');
+
+		if (moduleGeneration > 0 && !this.isMockedEsbuildModule(esbuildModule)) {
+			const freshModule = await import(
+				`${pathToFileURL(esbuildRequire.resolve('esbuild')).href}?ecopages_esbuild=${moduleGeneration}`
+			);
+			const normalizedFreshModule = (
+				typeof (freshModule as typeof import('esbuild')).build === 'function'
+					? freshModule
+					: ((freshModule as { default?: typeof import('esbuild') }).default ?? freshModule)
+			) as typeof import('esbuild');
+
+			if (typeof normalizedFreshModule.build === 'function') {
+				return normalizedFreshModule;
+			}
+		}
 
 		if (typeof esbuildModule.build !== 'function') {
 			throw new Error('esbuild is not available. Install esbuild to use Node bundling.');
@@ -296,6 +316,102 @@ export class EsbuildBuildAdapter implements BuildAdapter {
 		return esbuildModule;
 	}
 
+	private isMockedEsbuildModule(esbuildModule: typeof import('esbuild')): boolean {
+		const build = esbuildModule.build as { mock?: unknown } | undefined;
+		const stop = esbuildModule.stop as { mock?: unknown } | undefined;
+		return typeof build?.mock === 'object' || typeof stop?.mock === 'object';
+	}
+
+	/**
+	 * Detects the subset of runtime faults that indicate esbuild's worker
+	 * protocol is corrupted rather than a normal build error.
+	 */
+	isEsbuildProtocolError(error: unknown): boolean {
+		if (!(error instanceof Error)) {
+			return false;
+		}
+
+		return ['Unexpected end of JSON input', 'Unexpected EOF', 'parseJSON', 'buildResponseToResult'].some(
+			(fragment) => error.message.includes(fragment) || error.stack?.includes(fragment),
+		);
+	}
+
+	async stopEsbuildService(moduleGeneration = 0): Promise<void> {
+		const esbuild = await this.loadEsbuildModule(moduleGeneration);
+		if (typeof esbuild.stop === 'function') {
+			esbuild.stop();
+		}
+	}
+
+	async buildOrThrow(options: BuildOptions, moduleGeneration = 0): Promise<BuildResult> {
+		const esbuild = await this.loadEsbuildModule(moduleGeneration);
+		const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+		const outdir = path.resolve(options.outdir ?? 'dist/assets');
+		const tsconfigPath = path.join(contextRoot, 'tsconfig.json');
+		const tsconfigExists = fileSystem.exists(tsconfigPath);
+
+		const plugins = this.getPluginsForBuild(options.plugins);
+		const esbuildPlugins: EsbuildPlugin[] = [
+			...(plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []),
+		];
+		const transpileTarget = 'es2022';
+
+		const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
+		const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : undefined;
+		if (outfile) {
+			fileSystem.ensureDir(path.dirname(outfile));
+		}
+
+		const outputOptions = outfile
+			? { outfile }
+			: {
+					outdir,
+					...(options.outbase ? { outbase: path.resolve(options.outbase) } : {}),
+					entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : '[name]',
+					chunkNames: '[name]-[hash]',
+					assetNames: '[name]-[hash]',
+				};
+
+		const result = await esbuild.build({
+			absWorkingDir: contextRoot,
+			entryPoints: options.entrypoints,
+			bundle: options.bundle ?? true,
+			...outputOptions,
+			...(options.conditions ? { conditions: options.conditions } : {}),
+			...(options.define ? { define: options.define } : {}),
+			format: this.mapEsbuildFormat(options.format),
+			platform: (options.target === 'browser' ? 'browser' : 'node') as 'browser' | 'node',
+			sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
+			splitting: outfile ? false : !!options.splitting,
+			minify: !!options.minify,
+			...(typeof options.treeshaking === 'boolean' ? { treeShaking: options.treeshaking } : {}),
+			external: options.external,
+			...(options.target !== 'browser' && options.externalPackages !== false
+				? { packages: 'external' as const }
+				: {}),
+			target: transpileTarget,
+			metafile: true,
+			write: true,
+			plugins: esbuildPlugins,
+			jsx: 'automatic',
+			tsconfig: tsconfigExists ? tsconfigPath : undefined,
+			logLevel: 'silent',
+		});
+
+		const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
+			path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath),
+		}));
+		const logs = result.warnings.map((warning) => ({ message: warning.text }));
+		const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
+
+		return {
+			success: true,
+			logs,
+			outputs,
+			dependencyGraph,
+		};
+	}
+
 	private mapEsbuildSourcemap(value: string | undefined): false | 'linked' | 'inline' | 'external' | 'both' {
 		switch (value) {
 			case 'none':
@@ -407,80 +523,22 @@ export class EsbuildBuildAdapter implements BuildAdapter {
 		return [{ message: 'Unknown esbuild error' }];
 	}
 
+	createFailureResult(error: unknown): BuildResult {
+		return {
+			success: false,
+			logs: this.toBuildLogs(error),
+			outputs: [],
+		};
+	}
+
 	/**
 	 * Bundles entrypoints using esbuild for Node runtime builds.
 	 */
 	async build(options: BuildOptions): Promise<BuildResult> {
-		const esbuild = await this.loadEsbuildModule();
-		const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
-		const outdir = path.resolve(options.outdir ?? '.eco/assets');
-		const tsconfigPath = path.join(contextRoot, 'tsconfig.json');
-		const tsconfigExists = fileSystem.exists(tsconfigPath);
-
-		const plugins = this.getPluginsForBuild(options.plugins);
-		const esbuildPlugins: EsbuildPlugin[] = [
-			...(plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []),
-		];
-		const transpileTarget = 'es2022';
-
-		const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
-		const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : undefined;
-		if (outfile) {
-			fileSystem.ensureDir(path.dirname(outfile));
-		}
-
-		const outputOptions = outfile
-			? { outfile }
-			: {
-					outdir,
-					entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : '[name]',
-					chunkNames: '[name]-[hash]',
-					assetNames: '[name]-[hash]',
-				};
-
 		try {
-			const result = await esbuild.build({
-				absWorkingDir: contextRoot,
-				entryPoints: options.entrypoints,
-				bundle: options.bundle ?? true,
-				...outputOptions,
-				format: this.mapEsbuildFormat(options.format),
-				platform: (options.target === 'browser' ? 'browser' : 'node') as 'browser' | 'node',
-				sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
-				splitting: outfile ? false : !!options.splitting,
-				minify: !!options.minify,
-				...(typeof options.treeshaking === 'boolean' ? { treeShaking: options.treeshaking } : {}),
-				external: options.external,
-				...(options.target !== 'browser' && options.externalPackages !== false
-					? { packages: 'external' as const }
-					: {}),
-				target: transpileTarget,
-				metafile: true,
-				write: true,
-				plugins: esbuildPlugins,
-				jsx: 'automatic',
-				tsconfig: tsconfigExists ? tsconfigPath : undefined,
-				logLevel: 'silent',
-			});
-
-			const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
-				path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath),
-			}));
-			const logs = result.warnings.map((warning) => ({ message: warning.text }));
-			const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
-
-			return {
-				success: true,
-				logs,
-				outputs,
-				dependencyGraph,
-			};
+			return await this.buildOrThrow(options);
 		} catch (error) {
-			return {
-				success: false,
-				logs: this.toBuildLogs(error),
-				outputs: [],
-			};
+			return this.createFailureResult(error);
 		}
 	}
 
@@ -492,15 +550,6 @@ export class EsbuildBuildAdapter implements BuildAdapter {
 		return localRequire.resolve(importPath);
 	}
 
-	/**
-	 * Registers a build plugin once by plugin name.
-	 */
-	registerPlugin(plugin: EcoBuildPlugin): void {
-		if (!this.registeredPlugins.find((registered) => registered.name === plugin.name)) {
-			this.registeredPlugins.push(plugin);
-		}
-	}
-
 	/**
 	 * Returns transpile defaults for a known transpile profile.
 	 */

package/src/build/runtime-build-executor.ts

@@ -0,0 +1,34 @@
+import type { EcoPagesAppConfig } from '../internal-types.ts';
+import {
+	getAppBuildAdapter,
+	getAppBuildExecutor,
+	getAppServerBuildPlugins,
+	setAppBuildExecutor,
+	type BuildExecutor,
+} from './build-adapter.ts';
+import { createOrReuseAppBuildExecutor } from './dev-build-coordinator.ts';
+
+/**
+ * Installs the app-owned runtime build executor for one app instance.
+ *
+ * @remarks
+ * This is the single coordinator boundary for runtime executor ownership across
+ * adapters. It preserves an existing development coordinator when available and
+ * always applies app server build plugins through one shared path.
+ */
+export function installAppRuntimeBuildExecutor(
+	appConfig: EcoPagesAppConfig,
+	options: {
+		development: boolean;
+	},
+): BuildExecutor {
+	const buildExecutor = createOrReuseAppBuildExecutor({
+		development: options.development,
+		adapter: getAppBuildAdapter(appConfig),
+		currentExecutor: getAppBuildExecutor(appConfig),
+		getPlugins: () => getAppServerBuildPlugins(appConfig),
+	});
+
+	setAppBuildExecutor(appConfig, buildExecutor);
+	return buildExecutor;
+}

package/src/build/runtime-specifier-alias-plugin.test.ts

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { EcoBuildOnResolveResult } from './build-types.ts';
+import { createRuntimeSpecifierAliasPlugin } from './runtime-specifier-alias-plugin.ts';
+
+test('createRuntimeSpecifierAliasPlugin resolves mapped specifiers as externals', async () => {
+	const registrations: Array<{
+		filter: RegExp;
+		callback: (args: {
+			path: string;
+		}) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>;
+	}> = [];
+	const plugin = createRuntimeSpecifierAliasPlugin(
+		{
+			react: '/assets/vendors/react.js',
+			'react-dom/client': '/assets/vendors/react-dom.js',
+		},
+		{ name: 'test-runtime-alias' },
+	);
+
+	assert.ok(plugin);
+	assert.equal(plugin.name, 'test-runtime-alias');
+
+	plugin.setup({
+		onResolve(options, callback) {
+			registrations.push({ filter: options.filter, callback });
+		},
+		onLoad() {},
+		module() {},
+	});
+
+	assert.equal(registrations.length, 1);
+	assert.equal(registrations[0]?.filter.test('react'), true);
+	assert.deepEqual(await registrations[0]?.callback({ path: 'react' }), {
+		path: '/assets/vendors/react.js',
+		external: true,
+	});
+	assert.equal(await registrations[0]?.callback({ path: 'unknown' }), undefined);
+});
+
+test('createRuntimeSpecifierAliasPlugin returns null for an empty specifier map', () => {
+	assert.equal(createRuntimeSpecifierAliasPlugin(new Map()), null);
+});

package/src/build/runtime-specifier-alias-plugin.ts

@@ -0,0 +1,58 @@
+import type { EcoBuildPlugin } from './build-types.ts';
+
+type RuntimeSpecifierMap = ReadonlyMap<string, string> | Record<string, string>;
+
+/**
+ * Normalizes runtime specifier input into a read-only map shape.
+ */
+function toRuntimeSpecifierMap(specifierMap: RuntimeSpecifierMap): ReadonlyMap<string, string> {
+	return specifierMap instanceof Map ? specifierMap : new Map(Object.entries(specifierMap));
+}
+
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ */
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Creates a build plugin that aliases runtime bare specifiers to concrete URLs.
+ *
+ * @remarks
+ * This helper is used when browser-target builds must preserve integration-owned
+ * runtime specifier semantics while letting the bundler treat the mapped URLs as
+ * external runtime assets.
+ */
+export function createRuntimeSpecifierAliasPlugin(
+	specifierMapInput: RuntimeSpecifierMap,
+	options?: {
+		name?: string;
+		external?: boolean;
+	},
+): EcoBuildPlugin | null {
+	const specifierMap = toRuntimeSpecifierMap(specifierMapInput);
+
+	if (specifierMap.size === 0) {
+		return null;
+	}
+
+	const filter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join('|')})$`);
+
+	return {
+		name: options?.name ?? 'runtime-specifier-alias',
+		setup(build) {
+			build.onResolve({ filter }, (args) => {
+				const mappedPath = specifierMap.get(args.path);
+				if (!mappedPath) {
+					return undefined;
+				}
+
+				return {
+					path: mappedPath,
+					external: options?.external ?? true,
+				};
+			});
+		},
+	};
+}

package/src/config/README.md

@@ -0,0 +1,33 @@
+# Config Layer
+
+This directory contains the app-configuration finalization path for Ecopages.
+
+## Purpose
+
+The config layer answers one question:
+
+How does one `eco.config.ts` become one stable, app-owned runtime/build configuration?
+
+It is responsible for:
+
+- validating integration, processor, and loader registration
+- resolving semantic paths such as `html` and `404` templates
+- creating app-owned runtime state such as the build adapter, build executor, build manifest, dev graph service, runtime specifier registry, and Node runtime manifest
+- enforcing runtime capability requirements before startup
+
+## Main Files
+
+- `config-builder.ts`: the primary builder and config finalization boundary
+- `config-builder.test.ts`: coverage for validation, path resolution, and runtime capability checks
+
+## Ownership Rules
+
+- Integrations and processors declare contributions.
+- `ConfigBuilder.build()` decides ordering and validates compatibility.
+- Runtime startup reuses finalized config/build state; it should not recompute manifest ownership.
+
+## Output
+
+The result of this layer is a built `EcoPagesAppConfig` with resolved absolute paths and app-owned runtime services attached under `appConfig.runtime`.
+
+That built config is then consumed by server adapters, static generation, route rendering, and HMR.