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

package/src/adapters/shared/server-static-builder.test.ts

@@ -0,0 +1,316 @@
+import assert from 'node:assert/strict';
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import {
+	ServerStaticBuilder,
+	type ServeOptions,
+	type ServerStaticBuilderLogger,
+	type ServerStaticPreviewServerFactory,
+} from './server-static-builder';
+import type { EcoPagesAppConfig } from '../../internal-types';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import type { FSRouter } from '../../router/server/fs-router';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const TMP_DIR = path.join(os.tmpdir(), 'server-static-builder-test');
+
+function createMockDependencies() {
+	const calls = {
+		staticSiteGeneratorRun: [] as Array<unknown>,
+		integrationSetup: 0,
+		processorSetup: 0,
+		warn: [] as Array<[string, string | undefined]>,
+		info: [] as string[],
+		error: [] as string[],
+		createServer: [] as Array<{
+			appConfig: EcoPagesAppConfig;
+			options: { port: number };
+		}>,
+	};
+
+	const StaticSiteGenerator = {
+		run: async (options: unknown) => {
+			calls.staticSiteGeneratorRun.push(options);
+		},
+	} as unknown as StaticSiteGenerator;
+
+	const mockIntegration = {
+		setup: async () => {
+			calls.integrationSetup += 1;
+		},
+	} as any;
+
+	const mockProcessor = {
+		setup: async () => {
+			calls.processorSetup += 1;
+			fs.mkdirSync(path.join(TMP_DIR, 'dist', 'images'), { recursive: true });
+			fs.writeFileSync(path.join(TMP_DIR, 'dist', 'images', 'processor.webp'), 'processor-output');
+		},
+	} as any;
+
+	const AppConfig = {
+		rootDir: TMP_DIR,
+		srcDir: 'src',
+		publicDir: 'public',
+		distDir: 'dist',
+		integrations: [mockIntegration],
+		processors: new Map([['image-processor', mockProcessor]]),
+		absolutePaths: {
+			distDir: path.join(TMP_DIR, 'dist'),
+			workDir: path.join(TMP_DIR, '.eco'),
+		} as EcoPagesAppConfig['absolutePaths'],
+	} as unknown as EcoPagesAppConfig;
+
+	const ServeOptions: ServeOptions = {
+		hostname: 'localhost',
+		port: 3000,
+	};
+
+	const Router = {} as FSRouter;
+	const RouteRendererFactory = {} as RouteRendererFactory;
+	const logger: ServerStaticBuilderLogger = {
+		warn: (message: string, detail?: string) => {
+			calls.warn.push([message, detail]);
+		},
+		info: (message: string) => {
+			calls.info.push(message);
+		},
+		error: (message: string) => {
+			calls.error.push(message);
+		},
+	};
+	const previewServerFactory: ServerStaticPreviewServerFactory = {
+		createServer: ({ appConfig, options }) => {
+			calls.createServer.push({ appConfig, options });
+			return {
+				server: { port: 3000 },
+			};
+		},
+	};
+
+	return {
+		calls,
+		StaticSiteGenerator,
+		AppConfig,
+		mockIntegration,
+		mockProcessor,
+		logger,
+		previewServerFactory,
+		ServeOptions,
+		Router,
+		RouteRendererFactory,
+		ApiHandlers: [],
+	};
+}
+
+describe('ServerStaticBuilder', () => {
+	beforeAll(() => {
+		fs.mkdirSync(TMP_DIR, { recursive: true });
+	});
+
+	afterAll(() => {
+		fs.rmSync(TMP_DIR, { recursive: true, force: true });
+	});
+
+	it('should warn when API handlers are registered for static build modes', async () => {
+		const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+			createMockDependencies();
+
+		const builder = new ServerStaticBuilder({
+			appConfig: AppConfig,
+			staticSiteGenerator: StaticSiteGenerator,
+			serveOptions: ServeOptions,
+			logger,
+			apiHandlers: [
+				{ method: 'GET', path: '/api/auth/*', handler: () => undefined } as any,
+				{ method: 'POST', path: '/api/auth/*', handler: () => undefined } as any,
+			],
+		});
+
+		await builder.build(undefined, {
+			router: Router,
+			routeRendererFactory: RouteRendererFactory,
+		});
+
+		assert.deepEqual(calls.warn, [
+			[
+				'Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n',
+				'➤ GET /api/auth/*, POST /api/auth/*',
+			],
+		]);
+	});
+
+	describe('constructor', () => {
+		it('should create instance with provided options', () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, logger, previewServerFactory } =
+				createMockDependencies();
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+				previewServerFactory,
+			});
+			expect(builder).toBeDefined();
+		});
+	});
+
+	describe('build', () => {
+		it('should run static site generator with correct options', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.deepEqual(calls.staticSiteGeneratorRun, [
+				{
+					router: Router,
+					baseUrl: 'http://localhost:3000',
+					routeRendererFactory: RouteRendererFactory,
+					staticRoutes: undefined,
+				},
+			]);
+		});
+
+		it('should handle custom serve options for base URL', async () => {
+			const { AppConfig, StaticSiteGenerator, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const customServeOptions: ServeOptions = {
+				hostname: '0.0.0.0',
+				port: 8080,
+			};
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: customServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal((calls.staticSiteGeneratorRun[0] as { baseUrl: string }).baseUrl, 'http://0.0.0.0:8080');
+		});
+
+		it('should start preview server when preview option is true', async () => {
+			const {
+				AppConfig,
+				StaticSiteGenerator,
+				ServeOptions,
+				Router,
+				RouteRendererFactory,
+				logger,
+				previewServerFactory,
+				calls,
+			} = createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+				previewServerFactory,
+			});
+
+			await builder.build(
+				{ preview: true },
+				{
+					router: Router,
+					routeRendererFactory: RouteRendererFactory,
+				},
+			);
+
+			assert.deepEqual(calls.createServer, [
+				{
+					appConfig: AppConfig,
+					options: { port: 3000 },
+				},
+			]);
+		});
+
+		it('should rebuild integration runtime assets after resetting the export directory', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal(calls.integrationSetup, 1);
+		});
+
+		it('should rebuild processor-owned assets after resetting the export directory', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal(calls.processorSetup, 1);
+			assert.equal(
+				fs.readFileSync(path.join(TMP_DIR, 'dist', 'images', 'processor.webp'), 'utf8'),
+				'processor-output',
+			);
+		});
+
+		it('should reset stale export contents before regenerating the public output', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger } =
+				createMockDependencies();
+
+			const publicDir = path.join(TMP_DIR, 'src', 'public');
+			const distDir = AppConfig.absolutePaths.distDir;
+			fs.mkdirSync(publicDir, { recursive: true });
+			fs.mkdirSync(path.join(distDir, '.server-modules-meta'), { recursive: true });
+			fs.writeFileSync(path.join(publicDir, 'site.css'), 'body { color: red; }');
+			fs.writeFileSync(path.join(distDir, '.server-modules-meta', 'stale.js'), 'stale');
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			expect(fs.existsSync(path.join(distDir, '.server-modules-meta'))).toBe(false);
+			expect(fs.readFileSync(path.join(distDir, 'site.css'), 'utf8')).toBe('body { color: red; }');
+		});
+	});
+});

package/src/adapters/shared/server-static-builder.ts

@@ -1,9 +1,11 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
 import { StaticContentServer } from '../../dev/sc-server';
 import { appLogger } from '../../global/app-logger';
 import type { EcoPagesAppConfig } from '../../internal-types';
-import type { StaticRoute } from '../../public-types';
+import type { ApiHandler, StaticRoute } from '../../public-types';
 import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/fs-router';
+import type { FSRouter } from '../../router/server/fs-router';
 import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
 
 export interface StaticBuildOptions {
@@ -19,6 +21,29 @@ export interface ServerStaticBuilderParams {
 	appConfig: EcoPagesAppConfig;
 	staticSiteGenerator: StaticSiteGenerator;
 	serveOptions: ServeOptions;
+	apiHandlers?: ApiHandler[];
+	logger?: ServerStaticBuilderLogger;
+	previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+	warn(message: string, detail?: string): unknown;
+	info(message: string): unknown;
+	error(message: string): unknown;
+}
+
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+	createServer(args: { appConfig: EcoPagesAppConfig; options: { port: number } }): {
+		server?: {
+			port?: number;
+		} | null;
+	};
 }
 
 /**
@@ -28,11 +53,67 @@ export class ServerStaticBuilder {
 	private readonly appConfig: EcoPagesAppConfig;
 	private readonly staticSiteGenerator: StaticSiteGenerator;
 	private readonly serveOptions: ServeOptions;
+	private readonly apiHandlers: ApiHandler[];
+	private readonly logger: ServerStaticBuilderLogger;
+	private readonly previewServerFactory: ServerStaticPreviewServerFactory;
 
-	constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams) {
+	constructor({
+		appConfig,
+		staticSiteGenerator,
+		serveOptions,
+		apiHandlers,
+		logger,
+		previewServerFactory,
+	}: ServerStaticBuilderParams) {
 		this.appConfig = appConfig;
 		this.staticSiteGenerator = staticSiteGenerator;
 		this.serveOptions = serveOptions;
+		this.apiHandlers = apiHandlers ?? [];
+		this.logger = logger ?? appLogger;
+		this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+	}
+
+	private warnApiHandlersUnavailableInStaticMode(): void {
+		if (this.apiHandlers.length === 0) {
+			return;
+		}
+
+		const uniqueHandlers = Array.from(
+			new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`)),
+		);
+		const visibleHandlers = uniqueHandlers.slice(0, 5).join(', ');
+		const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+		const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+
+		this.logger.warn(
+			'Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n',
+			`➤ ${summary}`,
+		);
+	}
+
+	private prepareExportDirectory(): void {
+		const exportDir =
+			this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+		fileSystem.ensureDir(exportDir, true);
+
+		const srcPublicDir = path.join(
+			this.appConfig.rootDir,
+			this.appConfig.srcDir ?? 'src',
+			this.appConfig.publicDir ?? 'public',
+		);
+		if (fileSystem.exists(srcPublicDir)) {
+			fileSystem.copyDir(srcPublicDir, exportDir);
+		}
+	}
+
+	private async refreshRuntimeAssets(): Promise<void> {
+		for (const processor of this.appConfig.processors.values()) {
+			await processor.setup();
+		}
+
+		for (const integration of this.appConfig.integrations) {
+			await integration.setup();
+		}
 	}
 
 	/**
@@ -53,6 +134,9 @@ export class ServerStaticBuilder {
 		const { preview = false } = options ?? {};
 
 		const baseUrl = `http://${this.serveOptions.hostname || 'localhost'}:${this.serveOptions.port || 3000}`;
+		this.warnApiHandlersUnavailableInStaticMode();
+		this.prepareExportDirectory();
+		await this.refreshRuntimeAssets();
 
 		await this.staticSiteGenerator.run({
 			router: dependencies.router,
@@ -62,21 +146,21 @@ export class ServerStaticBuilder {
 		});
 
 		if (!preview) {
-			appLogger.info('Build completed');
+			this.logger.info('Build completed');
 			return;
 		}
 
 		const previewPort = this.serveOptions.port || 3000;
 
-		const { server } = StaticContentServer.createServer({
+		const { server } = this.previewServerFactory.createServer({
 			appConfig: this.appConfig,
 			options: { port: Number(previewPort) },
 		});
 
-		if (server) {
-			appLogger.info(`Preview running at http://localhost:${server.port}`);
+		if (server?.port) {
+			this.logger.info(`Preview running at http://localhost:${server.port}`);
 		} else {
-			appLogger.error('Failed to start preview server');
+			this.logger.error('Failed to start preview server');
 		}
 	}
 }

package/src/build/README.md

@@ -0,0 +1,101 @@
+# Build Layer
+
+This directory contains the runtime-neutral build contract used across Ecopages and the esbuild-backed implementation that currently powers the default fallback adapter.
+
+## Files
+
+- `build-adapter.ts`: shared build interfaces, result types, app-owned adapter/executor helpers, the exported `defaultBuildAdapter` fallback, and the top-level `build()` / `getTranspileOptions()` pipeline functions.
+- `build-types.ts`: plugin bridge types used by integrations and processors.
+- `esbuild-build-adapter.ts`: the concrete esbuild backend.
+- `dev-build-coordinator.ts`: development-only orchestration around the shared esbuild backend.
+- `*.test.ts`: focused regression coverage for plain builds and development serialization and recovery.
+
+## Responsibilities
+
+The build layer is intentionally split into two parts.
+
+`BuildExecutor` is the runtime-facing contract.
+
+- It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
+- It answers only how a given app instance should execute builds right now.
+- `EsbuildBuildAdapter` satisfies this contract directly in plain flows.
+- `DevBuildCoordinator` also satisfies this contract by wrapping the shared esbuild adapter with development-only serialization and recovery policy.
+
+`EsbuildBuildAdapter` is the backend. It knows how to:
+
+- load the esbuild module
+- translate Ecopages `BuildOptions` into esbuild options
+- bridge Ecopages build plugins into esbuild hooks
+- normalize build output, logs, and dependency graph metadata
+- detect the subset of runtime faults that mean the esbuild worker protocol is corrupted
+
+`DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
+
+- page module imports
+- HMR entrypoint builds
+- script and asset processors
+- React integration build paths
+
+Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns:
+
+- serialized access to the shared adapter in development
+- recycling warm Node-target esbuild sessions between builds
+- recovery from known esbuild worker protocol faults
+
+## Default Flow
+
+Each `EcoPagesAppConfig` owns a build adapter, build manifest, and `buildExecutor` in `appConfig.runtime`. `ConfigBuilder.build()` now creates that app-owned build state up front so later runtime startup can reuse it rather than mutating a shared adapter.
+
+When a Node or Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+
+Plugins are part of app-owned manifest or per-build input now. The source build contract no longer exposes adapter-level plugin registration, which keeps build composition scoped to an app/runtime instance instead of leaking across instances.
+
+HMR callers follow the same ownership model. Integration-specific runtime aliasing stays with the integration that owns those specifiers, rather than in generic core HMR bundling.
+
+## Orchestration Diagram
+
+```mermaid
+flowchart TD
+    Config["ConfigBuilder.build()"] --> DefaultExec["appConfig.runtime.buildExecutor = createAppBuildExecutor(app adapter, manifest)"]
+    Adapter["Server adapter initialize() in watch mode"] --> DevExec["appConfig.runtime.buildExecutor = DevBuildCoordinator"]
+    Caller["Any build caller with app/runtime context"] --> Build["executor.build(options) or build(options, executor)"]
+    Build --> Executor["BuildExecutor"]
+    Executor --> Coordinator["DevBuildCoordinator.build()"]
+    Coordinator --> Backend["EsbuildBuildAdapter.buildOrThrow()"]
+    Executor -->|plain flow| Direct["EsbuildBuildAdapter.build()"]
+    Backend --> Result["BuildResult"]
+    Direct --> Result["BuildResult"]
+    Result --> Browser["Browser consumes emitted bundle directly"]
+```
+
+## Recovery Model
+
+The recovery path is narrow on purpose. The coordinator only treats an error as recoverable when `EsbuildBuildAdapter.isEsbuildProtocolError()` matches one of the known worker-protocol failure signatures.
+
+When that happens, recovery does three things in order:
+
+1. Reset the serialized queue so future builds are not stuck behind a wedged promise.
+2. Stop the current esbuild service instance.
+3. Increment the esbuild module generation so the next import gets a fresh worker instance.
+
+After that reset, the coordinator retries the failed build once.
+
+## Why Explicit App Ownership
+
+There are many build callsites across core and integrations. The coordinator still needs to stay centralized, but process-global installation hid the real dependency and tied behavior to startup order.
+
+The explicit app-owned executor model keeps the design honest:
+
+- each app/runtime owns its own build executor
+- development policy stays in one place (`DevBuildCoordinator`)
+- callers with app context use that executor explicitly instead of consulting global state
+- tests can still instantiate `EsbuildBuildAdapter` or `DevBuildCoordinator` directly when they want the raw backend only
+
+## Testing Strategy
+
+The build tests are split by concern.
+
+- `build-adapter.test.ts` verifies plain backend behavior and plugin bridging.
+- `build-adapter-serialization.test.ts` verifies development orchestration behavior such as serialization, warm-session recycling, and protocol-fault recovery.
+
+If you change the build orchestration rules, update the coordinator tests first. If you change esbuild option mapping or plugin behavior, update the backend tests first.