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

package/src/adapters/shared/hmr-entrypoint-registrar.ts

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../../global/app-logger.ts';
+import { RESOLVED_ASSETS_DIR } from '../../constants.ts';
+
+/**
+ * Shared runtime state used while registering HMR-owned entrypoints.
+ */
+export interface HmrEntrypointRegistrarOptions {
+	/** Absolute source directory used to derive the emitted HMR path. */
+	srcDir: string;
+	/** Absolute distribution directory where HMR outputs are written. */
+	distDir: string;
+	/** In-flight registrations keyed by normalized absolute entrypoint path. */
+	entrypointRegistrations: Map<string, Promise<string>>;
+	/** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
+	watchedFiles: Map<string, string>;
+	/** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+	clearFailedRegistration?: (entrypointPath: string) => void;
+	/** Development-only guardrail for integrations that never finish producing output. */
+	registrationTimeoutMs: number;
+}
+
+/**
+ * Runtime-specific hooks required to materialize a single HMR entrypoint.
+ */
+export interface HmrEntrypointRegistrationOptions {
+	/**
+	 * Emits the browser-consumable HMR artifact for an entrypoint.
+	 */
+	emit(entrypointPath: string, outputPath: string): Promise<void>;
+	/**
+	 * Creates the runtime-specific error raised when the emit hook completes without producing output.
+	 */
+	getMissingOutputError(entrypointPath: string, outputPath: string): Error;
+}
+
+/**
+ * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
+ *
+ * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
+ * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
+ * apply the development timeout that prevents unresolved registrations from hanging navigation.
+ * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
+ * this shared registration flow.
+ */
+export class HmrEntrypointRegistrar {
+	private readonly options: HmrEntrypointRegistrarOptions;
+
+	constructor(options: HmrEntrypointRegistrarOptions) {
+		this.options = options;
+	}
+
+	/**
+	 * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+	 *
+	 * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+	 * integration only builds once per registration cycle.
+	 */
+	async registerEntrypoint(
+		entrypointPath: string,
+		registrationOptions: HmrEntrypointRegistrationOptions,
+	): Promise<string> {
+		const normalizedEntrypoint = path.resolve(entrypointPath);
+		const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+		if (existingRegistration) {
+			return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+		}
+
+		const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+		this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+
+		try {
+			return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+		} catch (error) {
+			this.options.clearFailedRegistration?.(normalizedEntrypoint);
+			throw error;
+		} finally {
+			this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+		}
+	}
+
+	private async registerEntrypointInternal(
+		entrypointPath: string,
+		registrationOptions: HmrEntrypointRegistrationOptions,
+	): Promise<string> {
+		if (this.options.watchedFiles.has(entrypointPath)) {
+			return this.options.watchedFiles.get(entrypointPath)!;
+		}
+
+		const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
+
+		this.options.watchedFiles.set(entrypointPath, outputUrl);
+		this.removeStaleEntrypointOutput(outputPath);
+
+		await registrationOptions.emit(entrypointPath, outputPath);
+
+		if (!fileSystem.exists(outputPath)) {
+			throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+		}
+
+		return outputUrl;
+	}
+
+	private async awaitEntrypointRegistration(registration: Promise<string>, entrypointPath: string): Promise<string> {
+		if (process.env.NODE_ENV !== 'development') {
+			return await registration;
+		}
+
+		return await Promise.race([
+			registration,
+			new Promise<string>((_, reject) => {
+				setTimeout(() => {
+					reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+				}, this.options.registrationTimeoutMs);
+			}),
+		]);
+	}
+
+	private getEntrypointOutput(entrypointPath: string): { outputPath: string; outputUrl: string } {
+		const relativePath = path.relative(this.options.srcDir, entrypointPath);
+		const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+		const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+		const urlPath = encodedPathJs.split(path.sep).join('/');
+
+		return {
+			outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, '_hmr', urlPath)}`,
+			outputPath: path.join(this.options.distDir, urlPath),
+		};
+	}
+
+	private removeStaleEntrypointOutput(outputPath: string): void {
+		if (!fileSystem.exists(outputPath)) {
+			return;
+		}
+
+		try {
+			fileSystem.remove(outputPath);
+		} catch (error) {
+			appLogger.warn(
+				`[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	private encodeDynamicSegments(filepath: string): string {
+		return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
+	}
+}

package/src/adapters/shared/hmr-html-response.ts

@@ -0,0 +1,52 @@
+import type { IHmrManager } from '../../public-types';
+
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};</script>`;
+
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export function isHtmlResponse(response: Response): boolean {
+	const contentType = response.headers.get('Content-Type');
+	return contentType !== null && contentType.startsWith('text/html');
+}
+
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean {
+	return watch && hmrManager?.isEnabled() === true;
+}
+
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export async function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response> {
+	const html = await response.text();
+	if (html.includes(HMR_RUNTIME_IMPORT)) {
+		return new Response(html, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers,
+		});
+	}
+
+	const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+	const headers = new Headers(response.headers);
+	headers.delete('Content-Length');
+
+	return new Response(updatedHtml, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}

package/src/adapters/shared/hmr-manager.contract.test.ts

@@ -0,0 +1,196 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, test, vi } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
+import { NodeHmrManager } from '../node/node-hmr-manager.ts';
+import { HmrManager as BunHmrManager } from '../bun/hmr-manager.ts';
+
+type SharedHmrManager = {
+	handleFileChange(filePath: string, options?: { broadcast?: boolean }): Promise<void>;
+	registerEntrypoint(entrypointPath: string): Promise<string>;
+	registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+	registerSpecifierMap(map: Record<string, string>): void;
+	getWatchedFiles(): Map<string, string>;
+	getSpecifierMap(): Map<string, string>;
+	stop(): void;
+	appConfig: Awaited<ReturnType<ConfigBuilder['build']>>;
+	readonly runtimeName: string;
+};
+
+function withRuntimeName<T extends Omit<SharedHmrManager, 'runtimeName'>>(
+	manager: T,
+	runtimeName: SharedHmrManager['runtimeName'],
+): T & Pick<SharedHmrManager, 'runtimeName'> {
+	return Object.assign(manager, { runtimeName });
+}
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+	vi.restoreAllMocks();
+});
+
+const runtimes = [
+	{
+		name: 'node',
+		async create(rootDir: string): Promise<SharedHmrManager> {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return withRuntimeName(
+				new NodeHmrManager({
+					appConfig: config,
+					bridge: {
+						subscriberCount: 0,
+						broadcast: () => {},
+					} as any,
+				}),
+				'node',
+			);
+		},
+	},
+	{
+		name: 'bun',
+		async create(rootDir: string): Promise<SharedHmrManager> {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return withRuntimeName(
+				new BunHmrManager({
+					appConfig: config,
+					bridge: {
+						subscriberCount: 0,
+						broadcast: () => {},
+						subscribe: () => {},
+						unsubscribe: () => {},
+					} as any,
+				}),
+				'bun',
+			);
+		},
+	},
+] as const;
+
+function getEntrypointOutputPath(manager: SharedHmrManager, entrypointPath: string): string {
+	const relativePathJs = path
+		.relative(manager.appConfig.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+	return path.join(resolveInternalWorkDir(manager.appConfig), 'assets', '_hmr', encodedPathJs);
+}
+
+describe.each(runtimes)('shared HMR manager contract: $name', ({ create }) => {
+	test('shares one in-flight entrypoint registration across concurrent callers', async () => {
+		const rootDir = createTempRoot('ecopages-hmr-contract-register');
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(pagesDir, { recursive: true });
+
+		const entrypointPath = path.join(pagesDir, 'react-lab.tsx');
+		fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+		const manager = await create(rootDir);
+		const outputPath = getEntrypointOutputPath(manager, entrypointPath);
+
+		const handleFileChange = vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 25));
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+		});
+
+		const [firstUrl, secondUrl] = await Promise.all([
+			manager.registerEntrypoint(entrypointPath),
+			manager.registerEntrypoint(entrypointPath),
+		]);
+
+		assert.equal(firstUrl, '/assets/_hmr/pages/react-lab.js');
+		assert.equal(secondUrl, '/assets/_hmr/pages/react-lab.js');
+		assert.equal(handleFileChange.mock.calls.length, 1);
+
+		manager.stop();
+	});
+
+	test('fails strict page registration when no integration emits output', async () => {
+		const rootDir = createTempRoot('ecopages-hmr-contract-strict-fail');
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(pagesDir, { recursive: true });
+
+		const entrypointPath = path.join(pagesDir, 'react-content.mdx');
+		fs.writeFileSync(entrypointPath, '# Hello', 'utf8');
+
+		const manager = await create(rootDir);
+		vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+		await assert.rejects(() => manager.registerEntrypoint(entrypointPath), /Integration failed to emit entrypoint/);
+		assert.equal(manager.getWatchedFiles().has(path.resolve(entrypointPath)), false);
+
+		manager.stop();
+	});
+
+	test('uses the generic build path for explicit script entrypoints', async () => {
+		const rootDir = createTempRoot('ecopages-hmr-contract-script-register');
+		const srcDir = path.join(rootDir, 'src');
+		fs.mkdirSync(srcDir, { recursive: true });
+
+		const entrypointPath = path.join(srcDir, 'script.ts');
+		fs.writeFileSync(entrypointPath, 'console.log("hello");', 'utf8');
+
+		const manager = await create(rootDir);
+		const outputPath = path.join(resolveInternalWorkDir(manager.appConfig), 'assets', '_hmr', 'script.js');
+		const buildCalls: string[] = [];
+		manager.appConfig.runtime!.buildExecutor = {
+			build: vi.fn(async (options) => {
+				buildCalls.push(options.entrypoints[0] as string);
+				fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+				fs.writeFileSync(outputPath, 'fresh-output', 'utf8');
+				return {
+					success: true,
+					logs: [],
+					outputs: [{ path: outputPath }],
+				};
+			}),
+		};
+
+		vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+		const outputUrl = await manager.registerScriptEntrypoint(entrypointPath);
+
+		assert.equal(outputUrl, '/assets/_hmr/script.js');
+		assert.deepEqual(buildCalls, [entrypointPath]);
+		assert.equal(fs.readFileSync(outputPath, 'utf8'), 'fresh-output');
+
+		manager.stop();
+	});
+
+	test('stop clears retained registration state', async () => {
+		const rootDir = createTempRoot('ecopages-hmr-contract-stop');
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(pagesDir, { recursive: true });
+
+		const entrypointPath = path.join(pagesDir, 'react-content.tsx');
+		fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+		const manager = await create(rootDir);
+		const outputPath = getEntrypointOutputPath(manager, entrypointPath);
+
+		vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+		});
+
+		manager.registerSpecifierMap({ react: '/assets/vendors/react.js' });
+		await manager.registerEntrypoint(entrypointPath);
+
+		manager.stop();
+
+		assert.equal(manager.getWatchedFiles().size, 0);
+		assert.equal(manager.getSpecifierMap().size, 0);
+	});
+});

package/src/adapters/shared/hmr-manager.dispatch.test.ts

@@ -0,0 +1,220 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, test } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '../../hmr/hmr-strategy.ts';
+import type { ClientBridgeEvent } from '../../public-types.ts';
+import { HmrManager as BunHmrManager } from '../bun/hmr-manager.ts';
+import { NodeHmrManager } from '../node/node-hmr-manager.ts';
+
+class FakeHmrStrategy extends HmrStrategy {
+	readonly type: HmrStrategyType;
+	private readonly _matches: (filePath: string) => boolean;
+	private readonly _action: HmrAction;
+
+	constructor(type: HmrStrategyType, matchFn: (f: string) => boolean, action: HmrAction) {
+		super();
+		this.type = type;
+		this._matches = matchFn;
+		this._action = action;
+	}
+
+	matches(filePath: string): boolean {
+		return this._matches(filePath);
+	}
+
+	async process(_filePath: string): Promise<HmrAction> {
+		return this._action;
+	}
+}
+
+type BridgeSpy = {
+	broadcasts: ClientBridgeEvent[];
+	bridge: {
+		subscriberCount: number;
+		broadcast(event: ClientBridgeEvent): void;
+		subscribe(): void;
+		unsubscribe(): void;
+	};
+};
+
+function createBridgeSpy(): BridgeSpy {
+	const broadcasts: ClientBridgeEvent[] = [];
+	const bridge = {
+		subscriberCount: 0,
+		broadcast(event: ClientBridgeEvent) {
+			broadcasts.push(event);
+		},
+		subscribe() {},
+		unsubscribe() {},
+	};
+	return { broadcasts, bridge };
+}
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+});
+
+const runtimes = [
+	{
+		name: 'node',
+		async create(rootDir: string, bridgeSpy: BridgeSpy) {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return new NodeHmrManager({ appConfig: config, bridge: bridgeSpy.bridge as any });
+		},
+	},
+	{
+		name: 'bun',
+		async create(rootDir: string, bridgeSpy: BridgeSpy) {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return new BunHmrManager({ appConfig: config, bridge: bridgeSpy.bridge as any });
+		},
+	},
+] as const;
+
+describe.each(runtimes)('handleFileChange dispatch: $name', ({ create }) => {
+	test('CSS file change routes to DefaultHmrStrategy and broadcasts reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-css');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const cssFile = path.join(rootDir, 'src', 'styles', 'main.css');
+		await manager.handleFileChange(cssFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+		assert.equal(spy.broadcasts[0].path, cssFile);
+
+		manager.stop();
+	});
+
+	test('HTML file change routes to DefaultHmrStrategy and broadcasts reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-html');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const htmlFile = path.join(rootDir, 'src', 'pages', 'index.html');
+		await manager.handleFileChange(htmlFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+		assert.equal(spy.broadcasts[0].path, htmlFile);
+
+		manager.stop();
+	});
+
+	test('TS file with no registered entrypoints falls back to DefaultHmrStrategy reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-ts-fallback');
+		const srcDir = path.join(rootDir, 'src');
+		fs.mkdirSync(srcDir, { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const tsFile = path.join(srcDir, 'component.ts');
+		await manager.handleFileChange(tsFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+
+		manager.stop();
+	});
+
+	test('broadcast:false suppresses events even when the strategy returns a broadcast action', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-no-broadcast');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const cssFile = path.join(rootDir, 'src', 'main.css');
+		await manager.handleFileChange(cssFile, { broadcast: false });
+
+		assert.equal(spy.broadcasts.length, 0);
+
+		manager.stop();
+	});
+
+	test('INTEGRATION strategy wins over DefaultHmrStrategy for matched files', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-integration-priority');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'component.jsx');
+		const integrationEvent: ClientBridgeEvent = {
+			type: 'update',
+			path: '/assets/_hmr/component.js',
+			timestamp: 1,
+		};
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, {
+				type: 'broadcast',
+				events: [integrationEvent],
+			}),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.deepEqual(spy.broadcasts[0], integrationEvent);
+
+		manager.stop();
+	});
+
+	test('action.type none suppresses broadcast even when shouldBroadcast is true', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-none-action');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'silent.ts');
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, { type: 'none' }),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 0);
+
+		manager.stop();
+	});
+
+	test('all events returned by a strategy are each broadcast individually', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-multi-event');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'multi.ts');
+		const events: ClientBridgeEvent[] = [
+			{ type: 'update', path: '/assets/_hmr/a.js', timestamp: 1 },
+			{ type: 'update', path: '/assets/_hmr/b.js', timestamp: 2 },
+		];
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, {
+				type: 'broadcast',
+				events,
+			}),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 2);
+		assert.deepEqual(spy.broadcasts, events);
+
+		manager.stop();
+	});
+});