@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/adapters/shared/server-route-handler.ts

@@ -1,153 +0,0 @@
-import type { IHmrManager } from '../../types/public-types.ts';
-import type { RouteRegistry } from '../../router/server/route-registry.ts';
-import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.ts';
-import type { FileSystemResponseMatcher } from './fs-server-response-matcher.ts';
-import { appLogger } from '../../global/app-logger.ts';
-import { HttpError } from '../../errors/http-error.ts';
-import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from './hmr-html-response.ts';
-
-/**
- * Configuration parameters for ServerRouteHandler.
- */
-export interface ServerRouteHandlerParams {
-	/** File system router for matching request URLs to route handlers. */
-	router: RouteRegistry;
-	/** Matcher for handling file system route responses. */
-	fileSystemResponseMatcher: FileSystemResponseMatcher;
-	/** Optional matcher for explicit static routes like processed images or sitemaps. */
-	explicitStaticRouteMatcher?: ExplicitStaticRouteMatcher;
-	/** Enable watch mode for development. */
-	watch?: boolean;
-	/** HMR manager for broadcasting hot module reload events in development. */
-	hmrManager?: IHmrManager;
-}
-
-/**
- * Handles HTTP requests and routing for the server.
- *
- * This class manages the request routing flow with a priority-based approach:
- * 1. Explicit static routes (highest priority - intentional mappings like /sitemap.xml)
- * 2. File-based routes without extensions (application routes)
- * 3. Static file fallback (lowest priority - disk serving)
- *
- * In development mode, it also injects HMR scripts into HTML responses.
- */
-export class ServerRouteHandler {
-	private readonly router: RouteRegistry;
-	private readonly fileSystemResponseMatcher: FileSystemResponseMatcher;
-	private readonly explicitStaticRouteMatcher?: ExplicitStaticRouteMatcher;
-	private readonly watch: boolean;
-	private readonly hmrManager?: IHmrManager;
-
-	/**
-	 * Creates a new ServerRouteHandler instance.
-	 *
-	 * @param params - Configuration parameters
-	 */
-	constructor({
-		router,
-		fileSystemResponseMatcher,
-		explicitStaticRouteMatcher,
-		watch = false,
-		hmrManager,
-	}: ServerRouteHandlerParams) {
-		this.router = router;
-		this.fileSystemResponseMatcher = fileSystemResponseMatcher;
-		this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
-		this.watch = watch;
-		this.hmrManager = hmrManager;
-	}
-
-	/**
-	 * Determines if HMR script should be injected.
-	 *
-	 * @returns true if in watch mode and HMR manager is enabled
-	 */
-	shouldInjectHmrScript(): boolean {
-		return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
-	}
-
-	/**
-	 * Checks if a response contains HTML content.
-	 *
-	 * @param response - The HTTP response to check
-	 * @returns true if Content-Type header starts with 'text/html'
-	 */
-	isHtmlResponse(response: Response): boolean {
-		return isHtmlResponse(response);
-	}
-
-	/**
-	 * Handles HTTP requests from the router adapter.
-	 *
-	 * Priority-based routing flow:
-	 * 1. Check explicit static routes first (e.g., /sitemap.xml, /image.webp from plugins)
-	 * 2. Match file-based routes without extensions (application routes)
-	 * 3. Fall back to static file serving from disk
-	 *
-	 * @param request - The incoming HTTP request
-	 * @returns HTTP response, potentially with injected HMR script in dev mode
-	 */
-	async handleResponse(request: Request): Promise<Response> {
-		const pathname = new URL(request.url).pathname;
-
-		const explicitMatch = this.explicitStaticRouteMatcher?.match(request.url);
-
-		if (explicitMatch) {
-			const response = await this.explicitStaticRouteMatcher!.handleMatch(explicitMatch);
-			return this.maybeInjectHmrScript(response);
-		}
-
-		const fsMatch = !pathname.includes('.') && this.router.matchRequest(request.url);
-
-		const response = await (fsMatch
-			? this.fileSystemResponseMatcher.handleMatch(fsMatch, request)
-			: this.handleNoMatch(request));
-
-		return this.maybeInjectHmrScript(response);
-	}
-
-	/**
-	 * Injects HMR script into HTML responses in development mode.
-	 *
-	 * The script is inserted before the closing </html> tag to enable
-	 * hot module reloading without full page refreshes.
-	 *
-	 * @param response - The HTTP response to potentially modify
-	 * @returns Original response or modified response with HMR script
-	 */
-	private async maybeInjectHmrScript(response: Response): Promise<Response> {
-		if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-			return injectHmrRuntimeIntoHtmlResponse(response);
-		}
-
-		return response;
-	}
-
-	/**
-	 * Handles requests that do not match any routes.
-	 *
-	 * This is the final fallback that attempts to serve static files from disk.
-	 * If the requested path corresponds to an HTML file or no file is found,
-	 * a custom 404 response is returned.
-	 *
-	 * @param request - The HTTP request to handle
-	 * @returns Response from file system or error response
-	 * @throws HttpError for standard HTTP errors
-	 */
-	async handleNoMatch(request: Request): Promise<Response> {
-		try {
-			const pathname = new URL(request.url).pathname;
-			return await this.fileSystemResponseMatcher.handleNoMatch(pathname);
-		} catch (error) {
-			if (error instanceof HttpError) {
-				return error.toResponse();
-			}
-			if (error instanceof Error) {
-				this.hmrManager?.broadcast({ type: 'error', message: error.message });
-				appLogger.error('Error handling no match:', error);
-			}
-			return new Response('Internal Server Error', { status: 500 });
-		}
-	}
-}

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

@@ -1,338 +0,0 @@
-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 '../../types/internal-types';
-import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
-import type { RouteRegistry } from '../../router/server/route-registry';
-import type { StaticGenerationRendererResolver } 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 RouteRegistry;
-	const RouteRendererFactory = {} as StaticGenerationRendererResolver;
-	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 allow build-time base URL overrides', async () => {
-			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
-				createMockDependencies();
-
-			const builder = new ServerStaticBuilder({
-				appConfig: AppConfig,
-				staticSiteGenerator: StaticSiteGenerator,
-				serveOptions: ServeOptions,
-				logger,
-			});
-
-			await builder.build(
-				{ baseUrl: 'http://localhost:41731' },
-				{
-					router: Router,
-					routeRendererFactory: RouteRendererFactory,
-				},
-			);
-
-			assert.equal((calls.staticSiteGeneratorRun[0] as { baseUrl: string }).baseUrl, 'http://localhost:41731');
-		});
-
-		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,170 +0,0 @@
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
-import { StaticContentServer } from '../../dev/sc-server.ts';
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type { ApiHandler, StaticRoute } from '../../types/public-types.ts';
-import type { RouteRegistry } from '../../router/server/route-registry.ts';
-import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.ts';
-import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.ts';
-
-export interface StaticBuildOptions {
-	preview?: boolean;
-	baseUrl?: string;
-}
-
-export interface ServeOptions {
-	hostname?: string;
-	port?: number | string;
-}
-
-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;
-	};
-}
-
-/**
- * Handles static site generation and previews.
- */
-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,
-		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();
-		}
-	}
-
-	/**
-	 * Generates a static build of the site for deployment.
-	 * @param options.preview - If true, starts a preview server after build
-	 * @param dependencies.router - The initialized router
-	 * @param dependencies.routeRendererFactory - The route renderer factory
-	 * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
-	 */
-	async build(
-		options: StaticBuildOptions | undefined,
-		dependencies: {
-			router: RouteRegistry;
-			routeRendererFactory: StaticGenerationRendererResolver;
-			staticRoutes?: StaticRoute[];
-		},
-	): Promise<void> {
-		const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
-
-		const baseUrl =
-			explicitBaseUrl ??
-			`http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
-		this.warnApiHandlersUnavailableInStaticMode();
-		this.prepareExportDirectory();
-		await this.refreshRuntimeAssets();
-
-		await this.staticSiteGenerator.run({
-			router: dependencies.router,
-			baseUrl,
-			routeRendererFactory: dependencies.routeRendererFactory,
-			staticRoutes: dependencies.staticRoutes,
-		});
-
-		if (!preview) {
-			this.logger.info('Build completed');
-			return;
-		}
-
-		const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-
-		const { server } = this.previewServerFactory.createServer({
-			appConfig: this.appConfig,
-			options: { port: Number(previewPort) },
-		});
-
-		if (server?.port) {
-			this.logger.info(`Preview running at http://localhost:${server.port}`);
-		} else {
-			this.logger.error('Failed to start preview server');
-		}
-	}
-}