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

package/src/static-site-generator/static-site-generator.ts

@@ -1,445 +0,0 @@
-import path from 'node:path';
-import { appLogger } from '../global/app-logger.ts';
-import type { EcoPagesAppConfig } from '../types/internal-types.ts';
-import type { EcoPageComponent, StaticRoute } from '../types/public-types.ts';
-import type {
-	ExplicitViewRenderer,
-	ExplicitViewRendererResolver,
-	PageRendererResolver,
-	StaticGenerationRendererResolver,
-} from '../route-renderer/route-renderer.ts';
-import type { StaticGenerationRoute } from '../router/server/route-registry.ts';
-import { fileSystem } from '@ecopages/file-system';
-import { PathUtils } from '../utils/path-utils.module.ts';
-import { prepareExplicitStaticRender } from '../adapters/shared/explicit-static-render-preparation.ts';
-
-type StaticGenerationRouteSource = {
-	listStaticGenerationRoutes(input: { runtimeOrigin: string }): Promise<readonly StaticGenerationRoute[]>;
-};
-
-type StaticPageRouteRendererFactory = PageRendererResolver;
-
-type ExplicitStaticRouteRendererFactory = ExplicitViewRendererResolver;
-
-type StaticGenerationRendererFactory = StaticGenerationRendererResolver;
-
-type ExplicitStaticRouteEntry = {
-	pathname: string;
-	params: Record<string, string | string[]>;
-};
-
-export const STATIC_SITE_GENERATOR_ERRORS = {
-	ROUTE_RENDERER_FACTORY_REQUIRED: 'RouteRendererFactory is required for render strategy',
-	unsupportedBodyType: (bodyType: string) => `Unsupported body type for static generation: ${bodyType}`,
-	missingIntegration: (routePath: string) =>
-		`View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page().`,
-	noRendererForIntegration: (integrationName: string) => `No renderer found for integration: ${integrationName}`,
-	dynamicRouteRequiresStaticPaths: (routePath: string) =>
-		`Dynamic route ${routePath} requires staticPaths to be defined on the view.`,
-} as const;
-
-/**
- * Generates static output files from the finalized app config and route graph.
- *
- * @remarks
- * This class intentionally reuses the same routing, renderer, and server-module
- * loading seams used by runtime rendering. Static generation should be a build
- * loop over the normal app model, not a parallel rendering stack with different
- * semantics.
- */
-export class StaticSiteGenerator {
-	appConfig: EcoPagesAppConfig;
-
-	/**
-	 * Creates the static-site generator for one app config.
-	 */
-	constructor({ appConfig }: { appConfig: EcoPagesAppConfig }) {
-		this.appConfig = appConfig;
-	}
-
-	private getExportDir(): string {
-		return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-	}
-
-	/**
-	 * Logs the standardized warning emitted when a dynamic-cache page is skipped.
-	 */
-	private warnDynamicPageSkipped(filePath: string): void {
-		appLogger.warn(
-			"Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
-			`➤ ${filePath}`,
-		);
-	}
-
-	/**
-	 * Determines whether one filesystem-discovered page should be excluded from
-	 * static generation.
-	 */
-	private async shouldSkipStaticPageFile(
-		filePath: string,
-		routeRendererFactory: StaticPageRouteRendererFactory,
-	): Promise<boolean> {
-		const module = (await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath, {
-			cacheScope: 'static-page-probe',
-		})) as {
-			default?: EcoPageComponent<any>;
-		};
-
-		if (module.default?.cache !== 'dynamic') {
-			return false;
-		}
-
-		this.warnDynamicPageSkipped(filePath);
-		return true;
-	}
-
-	/**
-	 * Determines whether one explicit static route view should be excluded from
-	 * static generation.
-	 */
-	private shouldSkipStaticView(routePath: string, view: EcoPageComponent<any>): boolean {
-		if (view.cache !== 'dynamic') {
-			return false;
-		}
-
-		this.warnDynamicPageSkipped(routePath);
-		return true;
-	}
-
-	/**
-	 * Writes the robots.txt file declared by the app config.
-	 */
-	generateRobotsTxt(): void {
-		let data = '';
-		const preferences = this.appConfig.robotsTxt.preferences;
-
-		for (const userAgent in preferences) {
-			data += `user-agent: ${userAgent}\n`;
-			for (const path of preferences[userAgent]) {
-				data += `disallow: ${path}\n`;
-			}
-			data += '\n';
-		}
-
-		fileSystem.ensureDir(this.getExportDir());
-		fileSystem.write(path.join(this.getExportDir(), 'robots.txt'), data);
-	}
-
-	/**
-	 * Returns whether the input path points at the root directory.
-	 */
-	isRootDir(path: string) {
-		const slashes = path.match(/\//g);
-		return slashes && slashes.length === 1;
-	}
-
-	/**
-	 * Collects parent directories that must exist for the generated route set.
-	 */
-	getDirectories(routes: string[]) {
-		const directories = new Set<string>();
-
-		for (const route of routes) {
-			const path = route.startsWith('http') ? new URL(route).pathname : route;
-
-			const segments = path.split('/');
-
-			if (segments.length > 2) {
-				directories.add(segments.slice(0, segments.length - 1).join('/'));
-			}
-		}
-
-		return Array.from(directories);
-	}
-
-	private writeStaticOutput(routePath: string, contents: string | Buffer, directories: string[] = []): string {
-		const outputPath = this.getOutputPath(routePath, directories);
-		fileSystem.ensureDir(path.dirname(outputPath));
-		fileSystem.write(outputPath, contents);
-		return outputPath;
-	}
-
-	private getStaticBuildStrategy(filePath: string): 'fetch' | 'render' {
-		const ext = PathUtils.getEcoTemplateExtension(filePath);
-		const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
-		return integration?.staticBuildStep || 'render';
-	}
-
-	private async createFilesystemStaticContents(
-		route: StaticGenerationRoute,
-		baseUrl: string,
-		routeRendererFactory?: StaticPageRouteRendererFactory,
-	): Promise<string | Buffer | null> {
-		const {
-			templateRoute: { filePath },
-			params,
-		} = route;
-
-		if (this.getStaticBuildStrategy(filePath) === 'fetch') {
-			const fetchUrl = this.resolveStaticFetchUrl(route.requestUrl, baseUrl);
-			const response = await fetch(fetchUrl);
-
-			if (!response.ok) {
-				appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
-				return null;
-			}
-
-			return response.text();
-		}
-
-		if (!routeRendererFactory) {
-			throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
-		}
-
-		if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
-			return null;
-		}
-
-		const renderer = routeRendererFactory.getPageRenderer(filePath);
-		const result = await renderer.execute({
-			file: filePath,
-			params: params as Record<string, string>,
-		});
-
-		const body = result.body;
-		if (typeof body === 'string' || Buffer.isBuffer(body)) {
-			return body;
-		}
-
-		if (body instanceof ReadableStream) {
-			return new Response(body).text();
-		}
-
-		throw new Error(STATIC_SITE_GENERATOR_ERRORS.unsupportedBodyType(typeof body));
-	}
-
-	/**
-	 * Generates static output for all filesystem-discovered routes.
-	 *
-	 * @remarks
-	 * Routes whose integrations opt into fetch-based static builds are rendered by
-	 * issuing a request against the running server origin. Render-strategy routes
-	 * go through the normal route renderer directly.
-	 */
-	async generateStaticPages(
-		router: StaticGenerationRouteSource,
-		baseUrl: string,
-		routeRendererFactory?: StaticPageRouteRendererFactory,
-	) {
-		const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
-
-		appLogger.debug(
-			'Static Pages',
-			routes.map((route) => route.requestUrl),
-		);
-
-		const directories = this.getDirectories(routes.map((route) => route.requestUrl));
-
-		for (const route of routes) {
-			try {
-				const contents = await this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory);
-				if (contents === null) {
-					continue;
-				}
-
-				this.writeStaticOutput(route.pathname, contents, directories);
-			} catch (error) {
-				appLogger.error(
-					`Error generating static page for ${route.requestUrl}:`,
-					error instanceof Error ? error : String(error),
-				);
-			}
-		}
-	}
-
-	private resolveStaticFetchUrl(route: string, baseUrl: string): string {
-		if (!route.startsWith('http://') && !route.startsWith('https://')) {
-			return `${baseUrl}${route}`;
-		}
-
-		const targetUrl = new URL(route);
-		const buildUrl = new URL(baseUrl);
-		buildUrl.pathname = targetUrl.pathname;
-		buildUrl.search = targetUrl.search;
-		buildUrl.hash = targetUrl.hash;
-
-		return buildUrl.href;
-	}
-
-	/**
-	 * Executes the full static-generation workflow for one app run.
-	 */
-	async run({
-		router,
-		baseUrl,
-		routeRendererFactory,
-		staticRoutes,
-	}: {
-		router: StaticGenerationRouteSource;
-		baseUrl: string;
-		routeRendererFactory?: StaticGenerationRendererFactory;
-		staticRoutes?: StaticRoute[];
-	}) {
-		this.generateRobotsTxt();
-		await this.generateStaticPages(router, baseUrl, routeRendererFactory);
-
-		if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-			await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
-		}
-	}
-
-	/**
-	 * Generates static pages from explicit static routes registered via app.static().
-	 * These routes use eco.page views via loader functions for HMR support.
-	 */
-	private async generateExplicitStaticPages(
-		staticRoutes: StaticRoute[],
-		routeRendererFactory: ExplicitStaticRouteRendererFactory,
-	): Promise<void> {
-		appLogger.debug(
-			'Generating explicit static routes',
-			staticRoutes.map((r) => r.path),
-		);
-
-		for (const route of staticRoutes) {
-			try {
-				const mod = await route.loader();
-				const view = mod.default;
-				if (this.shouldSkipStaticView(route.path, view)) {
-					continue;
-				}
-
-				await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
-			} catch (error) {
-				appLogger.error(
-					`Error generating explicit static page for ${route.path}:`,
-					error instanceof Error ? error : String(error),
-				);
-			}
-		}
-	}
-
-	private async generateExplicitStaticRoute(
-		routePath: string,
-		view: EcoPageComponent<any>,
-		routeRendererFactory: ExplicitStaticRouteRendererFactory,
-	): Promise<void> {
-		const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
-
-		for (const { pathname, params } of routeEntries) {
-			const contents = await this.createExplicitStaticContents(
-				routePath,
-				view,
-				params,
-				routeRendererFactory,
-				renderer,
-			);
-
-			const outputPath = this.writeStaticOutput(pathname, contents);
-
-			appLogger.debug(`Generated static page: ${pathname} -> ${outputPath}`);
-		}
-	}
-
-	private async planExplicitStaticRoute(
-		routePath: string,
-		view: EcoPageComponent<any>,
-		routeRendererFactory: ExplicitStaticRouteRendererFactory,
-	): Promise<{ renderer: ExplicitViewRenderer; routeEntries: ExplicitStaticRouteEntry[] }> {
-		const { renderer } = await prepareExplicitStaticRender({
-			routePath,
-			view,
-			params: {},
-			appConfig: this.appConfig,
-			runtimeOrigin: this.appConfig.baseUrl,
-			routeRendererFactory,
-			errors: STATIC_SITE_GENERATOR_ERRORS,
-		});
-
-		return {
-			renderer,
-			routeEntries: await this.listExplicitStaticRouteEntries(routePath, view),
-		};
-	}
-
-	private async createExplicitStaticContents(
-		routePath: string,
-		view: EcoPageComponent<any>,
-		params: Record<string, string | string[]>,
-		routeRendererFactory: ExplicitStaticRouteRendererFactory,
-		renderer: ExplicitViewRenderer,
-	): Promise<string> {
-		const { props, view: renderableView } = await prepareExplicitStaticRender({
-			routePath,
-			view,
-			params,
-			appConfig: this.appConfig,
-			runtimeOrigin: this.appConfig.baseUrl,
-			routeRendererFactory,
-			errors: STATIC_SITE_GENERATOR_ERRORS,
-		});
-
-		const response = await renderer.renderToResponse(renderableView, props, {});
-		return response.text();
-	}
-
-	private async listExplicitStaticRouteEntries(
-		routePath: string,
-		view: EcoPageComponent<any>,
-	): Promise<ExplicitStaticRouteEntry[]> {
-		const isDynamic = routePath.includes(':') || routePath.includes('[');
-		if (!isDynamic) {
-			return [{ pathname: routePath, params: {} }];
-		}
-
-		if (!view.staticPaths) {
-			throw new Error(STATIC_SITE_GENERATOR_ERRORS.dynamicRouteRequiresStaticPaths(routePath));
-		}
-
-		const { paths } = await view.staticPaths({
-			appConfig: this.appConfig,
-			runtimeOrigin: this.appConfig.baseUrl,
-		});
-
-		return paths.map(({ params }) => ({
-			pathname: this.resolveRoutePath(routePath, params),
-			params,
-		}));
-	}
-
-	/**
-	 * Resolve a route path template with actual params.
-	 * Supports both :param and [param] syntax.
-	 */
-	private resolveRoutePath(routePath: string, params: Record<string, string | string[]>): string {
-		let resolved = routePath;
-
-		for (const [key, value] of Object.entries(params)) {
-			const paramValue = Array.isArray(value) ? value.join('/') : value;
-			resolved = resolved.replace(`:${key}`, paramValue);
-			resolved = resolved.replace(`[${key}]`, paramValue);
-			resolved = resolved.replace(`[...${key}]`, paramValue);
-		}
-
-		return resolved;
-	}
-
-	/**
-	 * Get the output file path for a given route.
-	 */
-	private getOutputPath(routePath: string, directories: string[] = []): string {
-		let outputName: string;
-
-		if (routePath === '/') {
-			outputName = 'index.html';
-		} else if (directories.includes(routePath)) {
-			outputName = `${routePath}/index.html`;
-		} else if (routePath.endsWith('/')) {
-			outputName = `${routePath}index.html`;
-		} else {
-			outputName = `${routePath}.html`;
-		}
-
-		return path.join(this.getExportDir(), outputName);
-	}
-}

package/src/types/internal-types.ts

@@ -1,243 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.ts';
-import type { AppBuildManifest } from '../build/build-manifest.ts';
-import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.ts';
-import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.ts';
-import type { Processor } from '../plugins/processor.ts';
-import type { EcoSourceTransform } from '../plugins/source-transform.ts';
-import type { PageMetadataProps } from './public-types.ts';
-import type { RouteRegistry } from '../router/server/route-registry.ts';
-import type { CacheConfig } from '../services/cache/cache.types.ts';
-import type { DevGraphService } from '../services/runtime-state/dev-graph.service.ts';
-import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.ts';
-import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.ts';
-import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.ts';
-import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.ts';
-import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.ts';
-
-export interface RobotsPreference {
-	/**
-	 * The user agent
-	 * If an empty array is provided, it will enable all paths for the user agent
-	 * If a path is provided, it will disallow the path for the user agent
-	 */
-	[key: string]: string[];
-}
-
-/**
- * Represents the complete configuration object for EcoPages.
- */
-export type EcoPagesAppConfig = {
-	/**
-	 * The base URL of the website, localhost or the domain
-	 */
-	baseUrl: string;
-	/**
-	 * The root directory of the project
-	 * @default "."
-	 */
-	rootDir: string;
-	/**
-	 * The root directory of the project
-	 * @default "src"
-	 */
-	srcDir: string;
-	/**
-	 * The directory where the public files are located
-	 * @default "public"
-	 */
-	publicDir: string;
-	/**
-	 * The directory where the pages are located
-	 * @default "pages"
-	 */
-	pagesDir: string;
-	/**
-	 * The directory where the includes templates are located
-	 * @default "includes"
-	 */
-	includesDir: string;
-	/**
-	 * The directory where the layouts are located
-	 * @default "layouts"
-	 */
-	layoutsDir: string;
-	/**
-	 * The directory where the output will be located
-	 * @default "dist"
-	 */
-	distDir: string;
-	/**
-	 * The directory where internal runtime and build artifacts are stored.
-	 *
-	 * @remarks
-	 * This directory is not intended for deployment. It owns transpiled server
-	 * modules, runtime manifests, and processor caches so `distDir` can remain a
-	 * clean export tree.
-	 *
-	 * @default ".eco"
-	 */
-	workDir: string;
-	/**
-	 * The templates extensions based on the integrations
-	 */
-	templatesExt: string[];
-	/**
-	 * The directory where the components are located
-	 * @default "components"
-	 */
-	componentsDir: string;
-	/**
-	 * The robots.txt configuration
-	 */
-	robotsTxt: {
-		/**
-		 * The robots preferences. The key is the user agent and the value is the disallowed paths.
-		 * @default { "*": [] }
-		 */
-		preferences: RobotsPreference;
-	};
-	/** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
-	additionalWatchPaths: string[];
-	/**
-	 * @default { title: 'Ecopages', description: 'Ecopages' }
-	 */
-	defaultMetadata: PageMetadataProps;
-	/** Integrations plugins */
-	integrations: AnyIntegrationPlugin[];
-	/** Integrations dependencies */
-	integrationsDependencies: IntegrationDependencyConfig[];
-	/** Derived Paths */
-	absolutePaths: {
-		config: string;
-		componentsDir: string;
-		distDir: string;
-		workDir: string;
-		includesDir: string;
-		layoutsDir: string;
-		pagesDir: string;
-		projectDir: string;
-		publicDir: string;
-		srcDir: string;
-		htmlTemplatePath: string;
-		error404TemplatePath: string;
-	};
-	/**
-	 * The processors to be used in the app
-	 */
-	processors: Map<string, Processor>;
-	/**
-	 * Loaders to be used in the app, these are used to process the files when importing them
-	 */
-	loaders: Map<string, EcoBuildPlugin>;
-	/**
-	 * App-owned source transforms that can be adapted into Vite or other
-	 * transform-first bundlers without going through the legacy loader bridge.
-	 */
-	sourceTransforms: Map<string, EcoSourceTransform>;
-	/**
-	 * Cache configuration for ISR and page caching.
-	 * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
-	 */
-	cache?: CacheConfig;
-	/**
-	 * Runtime-owned services attached after config construction.
-	 *
-	 * These values are internal implementation details used to thread per-app
-	 * executors and similar runtime state through the system without relying on
-	 * process-global registries.
-	 */
-	runtime?: {
-		appModuleLoader?: AppModuleLoader;
-		buildOwnership?: BuildOwnership;
-		buildAdapter?: BuildAdapter;
-		buildManifest?: AppBuildManifest;
-		buildExecutor?: BuildExecutor;
-		devGraphService?: DevGraphService;
-		entrypointDependencyGraph?: EntrypointDependencyGraph;
-		hostModuleLoader?: SourceModuleLoader;
-		rendererModuleContext?: unknown;
-		serverInvalidationState?: ServerInvalidationState;
-		serverModuleTranspiler?: ServerModuleTranspiler;
-	};
-	/**
-	 * Experimental features.
-	 */
-	experimental?: {
-		/** Escape hatch for short-lived private toggles. No validation or IntelliSense. */
-		unsafe?: Record<string, unknown>;
-	};
-};
-
-export type IntegrationDependencyConfig = {
-	integration: string;
-	kind: 'script' | 'stylesheet';
-	position?: 'head' | 'body';
-	srcUrl: string;
-	filePath: string;
-	/** @todo inline dependencies not implemented yet */
-	inline?: boolean;
-};
-
-/**
- * The possible kinds of a route.
- */
-export type RouteKind = 'exact' | 'catch-all' | 'dynamic';
-
-/**
- * Represents the result of a route match.
- */
-export type MatchResult = {
-	requestedPathname: string;
-	templateRoute: {
-		filePath: string;
-		kind: RouteKind;
-		pathname: string;
-	};
-	query: Record<string, string>;
-	params: Record<string, string | string[]>;
-};
-
-/**
- * Represents a route in EcoPages.
- */
-export type Route = {
-	kind: RouteKind;
-	filePath: string;
-	pathname: string;
-};
-
-/**
- * Represents the routes in EcoPages.
- */
-export type Routes = Record<string, Route>;
-
-/**
- * Represents the options for the file system server.
- */
-export type FileSystemServerOptions = {
-	watchMode: boolean;
-	port?: number | string;
-};
-
-/**
- * Represents the file system server adapter.
- */
-export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown> {
-	startServer(serverOptions: ServerInstanceOptions):
-		| {
-				router: RouteRegistry;
-				server: unknown;
-		  }
-		| Promise<{ router: RouteRegistry; server: unknown }>;
-}
-
-export interface ProcessorPlugin {
-	name: string;
-	description?: string;
-	setup(): Promise<void>;
-	process<T = unknown>(input: T): Promise<T>;
-	teardown?(): Promise<void>;
-}
-
-// Re-export HMR types from public-types for internal use
-export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.ts';