@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,166 @@
+import type { IHmrManager } from '../../public-types';
+import type { FSRouter } from '../../router/fs-router';
+import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher';
+import type { FileSystemResponseMatcher } from './fs-server-response-matcher';
+import { appLogger } from '../../global/app-logger';
+import { HttpError } from '../../errors/http-error';
+
+/**
+ * Configuration parameters for ServerRouteHandler.
+ */
+export interface ServerRouteHandlerParams {
+	/** File system router for matching request URLs to route handlers. */
+	router: FSRouter;
+	/** 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: FSRouter;
+	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 this.watch && this.hmrManager?.isEnabled() === true;
+	}
+
+	/**
+	 * 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 {
+		const contentType = response.headers.get('Content-Type');
+		return contentType !== null && contentType.startsWith('text/html');
+	}
+
+	/**
+	 * 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.match(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)) {
+			const html = await response.text();
+
+			const hmrScript = `<script type="module">import '/_hmr_runtime.js';</script>`;
+
+			const updatedHtml = html.replace(/<\/html>/i, `${hmrScript}</html>`);
+
+			const headers = new Headers(response.headers);
+			headers.delete('Content-Length');
+
+			return new Response(updatedHtml, {
+				status: response.status,
+				statusText: response.statusText,
+				headers,
+			});
+		}
+
+		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.d.ts

@@ -0,0 +1,38 @@
+import type { EcoPagesAppConfig } from '../../internal-types';
+import type { StaticRoute } from '../../public-types';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
+import type { FSRouter } from '../../router/fs-router';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+export interface StaticBuildOptions {
+    preview?: boolean;
+}
+export interface ServeOptions {
+    hostname?: string;
+    port?: number | string;
+}
+export interface ServerStaticBuilderParams {
+    appConfig: EcoPagesAppConfig;
+    staticSiteGenerator: StaticSiteGenerator;
+    serveOptions: ServeOptions;
+}
+/**
+ * Handles static site generation and previews.
+ */
+export declare class ServerStaticBuilder {
+    private readonly appConfig;
+    private readonly staticSiteGenerator;
+    private readonly serveOptions;
+    constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams);
+    /**
+     * 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()
+     */
+    build(options: StaticBuildOptions | undefined, dependencies: {
+        router: FSRouter;
+        routeRendererFactory: RouteRendererFactory;
+        staticRoutes?: StaticRoute[];
+    }): Promise<void>;
+}

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

@@ -0,0 +1,46 @@
+import { StaticContentServer } from "../../dev/sc-server";
+import { appLogger } from "../../global/app-logger";
+class ServerStaticBuilder {
+  appConfig;
+  staticSiteGenerator;
+  serveOptions;
+  constructor({ appConfig, staticSiteGenerator, serveOptions }) {
+    this.appConfig = appConfig;
+    this.staticSiteGenerator = staticSiteGenerator;
+    this.serveOptions = serveOptions;
+  }
+  /**
+   * 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, dependencies) {
+    const { preview = false } = options ?? {};
+    const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    await this.staticSiteGenerator.run({
+      router: dependencies.router,
+      baseUrl,
+      routeRendererFactory: dependencies.routeRendererFactory,
+      staticRoutes: dependencies.staticRoutes
+    });
+    if (!preview) {
+      appLogger.info("Build completed");
+      return;
+    }
+    const previewPort = this.serveOptions.port || 3e3;
+    const { server } = StaticContentServer.createServer({
+      appConfig: this.appConfig,
+      options: { port: Number(previewPort) }
+    });
+    if (server) {
+      appLogger.info(`Preview running at http://localhost:${server.port}`);
+    } else {
+      appLogger.error("Failed to start preview server");
+    }
+  }
+}
+export {
+  ServerStaticBuilder
+};

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

@@ -0,0 +1,82 @@
+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 { RouteRendererFactory } from '../../route-renderer/route-renderer';
+import type { FSRouter } from '../../router/fs-router';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+
+export interface StaticBuildOptions {
+	preview?: boolean;
+}
+
+export interface ServeOptions {
+	hostname?: string;
+	port?: number | string;
+}
+
+export interface ServerStaticBuilderParams {
+	appConfig: EcoPagesAppConfig;
+	staticSiteGenerator: StaticSiteGenerator;
+	serveOptions: ServeOptions;
+}
+
+/**
+ * Handles static site generation and previews.
+ */
+export class ServerStaticBuilder {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly staticSiteGenerator: StaticSiteGenerator;
+	private readonly serveOptions: ServeOptions;
+
+	constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams) {
+		this.appConfig = appConfig;
+		this.staticSiteGenerator = staticSiteGenerator;
+		this.serveOptions = serveOptions;
+	}
+
+	/**
+	 * 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: FSRouter;
+			routeRendererFactory: RouteRendererFactory;
+			staticRoutes?: StaticRoute[];
+		},
+	): Promise<void> {
+		const { preview = false } = options ?? {};
+
+		const baseUrl = `http://${this.serveOptions.hostname || 'localhost'}:${this.serveOptions.port || 3000}`;
+
+		await this.staticSiteGenerator.run({
+			router: dependencies.router,
+			baseUrl,
+			routeRendererFactory: dependencies.routeRendererFactory,
+			staticRoutes: dependencies.staticRoutes,
+		});
+
+		if (!preview) {
+			appLogger.info('Build completed');
+			return;
+		}
+
+		const previewPort = this.serveOptions.port || 3000;
+
+		const { server } = StaticContentServer.createServer({
+			appConfig: this.appConfig,
+			options: { port: Number(previewPort) },
+		});
+
+		if (server) {
+			appLogger.info(`Preview running at http://localhost:${server.port}`);
+		} else {
+			appLogger.error('Failed to start preview server');
+		}
+	}
+}

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

@@ -0,0 +1,74 @@
+import type { EcoBuildPlugin } from './build-types.js';
+export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+export interface BuildLog {
+    message: string;
+}
+export interface BuildOutput {
+    path: string;
+}
+/**
+ * Dependency graph metadata produced by a build backend.
+ *
+ * @remarks
+ * This structure is runtime-neutral at the type level, but current population
+ * is Node/esbuild-only. Bun-backed builds may omit this metadata.
+ */
+export interface BuildDependencyGraph {
+    /**
+     * Normalized absolute entrypoint path mapped to all normalized absolute
+     * source inputs that contributed to that entrypoint output.
+     */
+    entrypoints: Record<string, string[]>;
+}
+export interface BuildResult {
+    success: boolean;
+    logs: BuildLog[];
+    outputs: BuildOutput[];
+    /**
+     * Optional build dependency metadata for selective invalidation.
+     *
+     * @remarks
+     * This is currently filled by the Node/esbuild adapter. Other runtimes should
+     * treat missing graph data as a valid state and fall back deterministically.
+     */
+    dependencyGraph?: BuildDependencyGraph;
+}
+export interface BuildOptions {
+    entrypoints: string[];
+    outdir?: string;
+    naming?: string;
+    minify?: boolean;
+    treeshaking?: boolean;
+    target?: string;
+    format?: string;
+    sourcemap?: string;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
+}
+export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+export interface BuildTranspileOptions {
+    target: string;
+    format: string;
+    sourcemap: string;
+}
+export interface BuildAdapter {
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    registerPlugin(plugin: EcoBuildPlugin): void;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+/**
+ * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
+ */
+export declare class BunBuildAdapter implements BuildAdapter {
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    registerPlugin(plugin: EcoBuildPlugin): void;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+export declare const defaultBuildAdapter: BuildAdapter;

package/src/build/build-adapter.js

@@ -0,0 +1,54 @@
+import { EsbuildBuildAdapter } from "./esbuild-build-adapter.js";
+import { getRequiredBunRuntime } from "../utils/runtime.js";
+import { EsbuildBuildAdapter as EsbuildBuildAdapter2 } from "./esbuild-build-adapter.js";
+function transpileProfileToOptions(profile) {
+  switch (profile) {
+    case "browser-script":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+    case "hmr-runtime":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+    case "hmr-entrypoint":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+  }
+}
+class BunBuildAdapter {
+  async build(options) {
+    const bun = getRequiredBunRuntime();
+    const result = await bun.build({
+      ...options,
+      plugins: options.plugins
+    });
+    return {
+      success: result.success,
+      logs: result.logs.map((log) => ({ message: log.message })),
+      outputs: result.outputs.map((output) => ({ path: output.path }))
+    };
+  }
+  resolve(importPath, rootDir) {
+    return getRequiredBunRuntime().resolveSync(importPath, rootDir);
+  }
+  registerPlugin(plugin) {
+    getRequiredBunRuntime().plugin(plugin);
+  }
+  getTranspileOptions(profile) {
+    return transpileProfileToOptions(profile);
+  }
+}
+const defaultBuildAdapter = new EsbuildBuildAdapter();
+export {
+  BunBuildAdapter,
+  EsbuildBuildAdapter2 as EsbuildBuildAdapter,
+  defaultBuildAdapter
+};

package/src/build/build-adapter.ts

@@ -0,0 +1,132 @@
+import type { BunPlugin } from 'bun';
+import type { EcoBuildPlugin } from './build-types.ts';
+import { EsbuildBuildAdapter } from './esbuild-build-adapter.ts';
+import { getRequiredBunRuntime } from '../utils/runtime.ts';
+
+export { EsbuildBuildAdapter } from './esbuild-build-adapter.ts';
+
+export interface BuildLog {
+	message: string;
+}
+
+export interface BuildOutput {
+	path: string;
+}
+
+/**
+ * Dependency graph metadata produced by a build backend.
+ *
+ * @remarks
+ * This structure is runtime-neutral at the type level, but current population
+ * is Node/esbuild-only. Bun-backed builds may omit this metadata.
+ */
+export interface BuildDependencyGraph {
+	/**
+	 * Normalized absolute entrypoint path mapped to all normalized absolute
+	 * source inputs that contributed to that entrypoint output.
+	 */
+	entrypoints: Record<string, string[]>;
+}
+
+export interface BuildResult {
+	success: boolean;
+	logs: BuildLog[];
+	outputs: BuildOutput[];
+	/**
+	 * Optional build dependency metadata for selective invalidation.
+	 *
+	 * @remarks
+	 * This is currently filled by the Node/esbuild adapter. Other runtimes should
+	 * treat missing graph data as a valid state and fall back deterministically.
+	 */
+	dependencyGraph?: BuildDependencyGraph;
+}
+
+export interface BuildOptions {
+	entrypoints: string[];
+	outdir?: string;
+	naming?: string;
+	minify?: boolean;
+	treeshaking?: boolean;
+	target?: string;
+	format?: string;
+	sourcemap?: string;
+	splitting?: boolean;
+	root?: string;
+	bundle?: boolean;
+	externalPackages?: boolean;
+	external?: string[];
+	plugins?: EcoBuildPlugin[];
+	[key: string]: unknown;
+}
+
+export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+
+export interface BuildTranspileOptions {
+	target: string;
+	format: string;
+	sourcemap: string;
+}
+
+export interface BuildAdapter {
+	build(options: BuildOptions): Promise<BuildResult>;
+	resolve(importPath: string, rootDir: string): string;
+	registerPlugin(plugin: EcoBuildPlugin): void;
+	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+
+function transpileProfileToOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
+	switch (profile) {
+		case 'browser-script':
+			return {
+				target: 'browser',
+				format: 'esm',
+				sourcemap: 'none',
+			};
+		case 'hmr-runtime':
+			return {
+				target: 'browser',
+				format: 'esm',
+				sourcemap: 'none',
+			};
+		case 'hmr-entrypoint':
+			return {
+				target: 'browser',
+				format: 'esm',
+				sourcemap: 'none',
+			};
+	}
+}
+
+/**
+ * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
+ */
+export class BunBuildAdapter implements BuildAdapter {
+	async build(options: BuildOptions): Promise<BuildResult> {
+		const bun = getRequiredBunRuntime();
+		const result = await bun.build({
+			...options,
+			plugins: options.plugins as BunPlugin[] | undefined,
+		} as Bun.BuildConfig);
+
+		return {
+			success: result.success,
+			logs: result.logs.map((log) => ({ message: log.message })),
+			outputs: result.outputs.map((output) => ({ path: output.path })),
+		};
+	}
+
+	resolve(importPath: string, rootDir: string): string {
+		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();

package/src/build/build-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Arguments passed to a build plugin `onResolve` callback.
+ */
+export type EcoBuildOnResolveArgs = {
+    path: string;
+    importer?: string;
+    namespace?: string;
+};
+/**
+ * Result returned by a build plugin `onResolve` callback.
+ */
+export type EcoBuildOnResolveResult = {
+    path?: string;
+    namespace?: string;
+    external?: boolean;
+};
+/**
+ * Arguments passed to a build plugin `onLoad` callback.
+ */
+export type EcoBuildOnLoadArgs = {
+    path: string;
+    namespace?: string;
+};
+/**
+ * Loader kinds supported across Bun/esbuild bridge points.
+ */
+export type EcoBuildLoader = 'base64' | 'binary' | 'copy' | 'css' | 'dataurl' | 'empty' | 'file' | 'global-css' | 'js' | 'json' | 'jsx' | 'local-css' | 'object' | 'text' | 'ts' | 'tsx';
+/**
+ * Result returned by a build plugin `onLoad` callback.
+ */
+export type EcoBuildOnLoadResult = {
+    contents?: string | Uint8Array;
+    loader?: EcoBuildLoader;
+    exports?: Record<string, unknown>;
+    resolveDir?: string;
+};
+/**
+ * Shared plugin builder contract used by Ecopages across Bun and esbuild.
+ */
+export interface EcoBuildPluginBuilder {
+    onResolve(options: {
+        filter: RegExp;
+        namespace?: string;
+    }, callback: (args: EcoBuildOnResolveArgs) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>): void;
+    onLoad(options: {
+        filter: RegExp;
+        namespace?: string;
+    }, callback: (args: EcoBuildOnLoadArgs) => EcoBuildOnLoadResult | undefined | Promise<EcoBuildOnLoadResult | undefined>): void;
+    module(specifier: string, callback: () => EcoBuildOnLoadResult | Promise<EcoBuildOnLoadResult>): void;
+}
+/**
+ * Runtime-agnostic build plugin contract consumed by Ecopages processors/loaders.
+ */
+export type EcoBuildPlugin = {
+    name: string;
+    setup: (build: EcoBuildPluginBuilder) => void | Promise<void>;
+};