@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/hmr/strategies/js-hmr-strategy.ts

@@ -1,308 +0,0 @@
-/**
- * JavaScript HMR Strategy
- *
- * Handles hot module replacement for JavaScript and TypeScript entrypoints.
- * Bundles files, replaces bare specifiers, and injects HMR boilerplate.
- *
- * @module
- */
-
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
-import { appLogger } from '../../global/app-logger';
-import { defaultBuildAdapter } from '../../build/build-adapter.ts';
-import type { EcoBuildPlugin } from '../../build/build-types.ts';
-
-/**
- * Context interface providing access to HmrManager state.
- * Required for JsHmrStrategy to access registered entrypoints and configuration.
- */
-export interface JsHmrContext {
-	/**
-	 * Map of registered entrypoints to their output URLs.
-	 */
-	getWatchedFiles(): Map<string, string>;
-
-	/**
-	 * Map of bare specifiers to vendor URLs for import resolution.
-	 */
-	getSpecifierMap(): Map<string, string>;
-
-	/**
-	 * Returns entrypoints impacted by a changed dependency path.
-	 *
-	 * @remarks
-	 * This hook is currently provided by the Node HMR manager where dependency
-	 * graph metadata is extracted from the Node/esbuild build adapter.
-	 */
-	getDependencyEntrypoints?(filePath: string): Set<string>;
-
-	/**
-	 * Stores latest dependency set for an entrypoint.
-	 *
-	 * @remarks
-	 * This hook is currently used only by the Node HMR manager to maintain a
-	 * reverse invalidation index. Runtimes that do not provide it keep rebuild-all
-	 * fallback semantics.
-	 */
-	setEntrypointDependencies?(entrypointPath: string, dependencies: string[]): void;
-
-	/**
-	 * Directory where HMR bundles are written.
-	 */
-	getDistDir(): string;
-
-	/**
-	 * Build plugins to use during bundling.
-	 */
-	getPlugins(): EcoBuildPlugin[];
-
-	/**
-	 * Absolute path to the source directory.
-	 */
-	getSrcDir(): string;
-}
-
-/**
- * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
- *
- * This strategy rebuilds all registered entrypoints when any file changes,
- * as we don't currently track dependencies. This is safe but inefficient.
- *
- * The processing steps are:
- * 1. Check if any entrypoints are registered
- * 2. Rebuild all entrypoints (the changed file could be a dependency)
- * 3. Replace bare specifiers with vendor URLs
- * 4. Inject generic HMR boilerplate
- * 5. Broadcast update events for each rebuilt entrypoint
- *
- * @remarks
- * Future enhancement: Track dependencies using Bun's transpiler API to only
- * rebuild affected entrypoints instead of all of them.
- *
- * @see https://bun.sh/docs/runtime/transpiler
- *
- * @example
- * ```typescript
- * const context = {
- *   getWatchedFiles: () => watchedFilesMap,
- *   getSpecifierMap: () => specifierMap,
- *   getDistDir: () => '/path/to/dist/_hmr',
- *   getPlugins: () => [],
- *   getSrcDir: () => '/path/to/src'
- * };
- * const strategy = new JsHmrStrategy(context);
- * ```
- */
-export class JsHmrStrategy extends HmrStrategy {
-	readonly type = HmrStrategyType.SCRIPT;
-
-	constructor(private context: JsHmrContext) {
-		super();
-	}
-
-	/**
-	 * Determines if the file is a JS/TS file that could affect registered entrypoints.
-	 *
-	 * Matches if:
-	 * 1. There are registered entrypoints to rebuild
-	 * 2. The changed file is a JS/TS file in the src directory
-	 *
-	 * @param filePath - Absolute path to the changed file
-	 * @returns True if this file should trigger entrypoint rebuilds
-	 */
-	matches(filePath: string): boolean {
-		const watchedFiles = this.context.getWatchedFiles();
-		const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
-		const isInSrc = filePath.startsWith(this.context.getSrcDir());
-
-		if (watchedFiles.size === 0) {
-			return false;
-		}
-
-		return isJsTs && isInSrc;
-	}
-
-	/**
-	 * Processes a file change by rebuilding affected entrypoints.
-	 *
-	 * @param filePath - Absolute path to the changed file
-	 *
-	 * @remarks
-	 * If runtime-specific dependency graph hooks are unavailable, this strategy
-	 * falls back to rebuilding all watched entrypoints.
-	 * @returns Action to broadcast update events
-	 */
-	async process(filePath: string): Promise<HmrAction> {
-		appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
-		const watchedFiles = this.context.getWatchedFiles();
-
-		if (watchedFiles.size === 0) {
-			appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
-			return { type: 'none' };
-		}
-
-		const updates: string[] = [];
-		let reloadRequired = false;
-		const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? new Set<string>();
-		const hasDependencyHit = dependencyHits.size > 0;
-		const impactedEntrypoints = hasDependencyHit
-			? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint))
-			: Array.from(watchedFiles.keys());
-
-		if (!hasDependencyHit) {
-			appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
-		}
-
-		for (const entrypoint of impactedEntrypoints) {
-			const outputUrl = watchedFiles.get(entrypoint);
-			if (!outputUrl) {
-				continue;
-			}
-
-			const result = await this.bundleEntrypoint(entrypoint, outputUrl);
-			if (result.success) {
-				if (result.dependencies && this.context.setEntrypointDependencies) {
-					this.context.setEntrypointDependencies(entrypoint, result.dependencies);
-				}
-
-				updates.push(outputUrl);
-				if (result.requiresReload) {
-					reloadRequired = true;
-				}
-			}
-		}
-
-		if (updates.length > 0) {
-			if (reloadRequired) {
-				appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
-				return {
-					type: 'broadcast',
-					events: [
-						{
-							type: 'reload',
-						},
-					],
-				};
-			}
-
-			return {
-				type: 'broadcast',
-				events: updates.map((path) => ({
-					type: 'update',
-					path,
-					timestamp: Date.now(),
-				})),
-			};
-		}
-
-		return { type: 'none' };
-	}
-
-	/**
-	 * Bundles a single entrypoint and processes the output.
-	 *
-	 * @param entrypointPath - Absolute path to the source file
-	 * @param outputUrl - URL path for the bundled file
-	 * @returns True if bundling was successful
-	 */
-	private async bundleEntrypoint(
-		entrypointPath: string,
-		outputUrl: string,
-	): Promise<{ success: boolean; requiresReload: boolean; dependencies?: string[] }> {
-		try {
-			const srcDir = this.context.getSrcDir();
-			const relativePath = path.relative(srcDir, entrypointPath);
-			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, '.js');
-			const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-
-			const result = await defaultBuildAdapter.build({
-				entrypoints: [entrypointPath],
-				outdir: this.context.getDistDir(),
-				naming: relativePathJs,
-				...defaultBuildAdapter.getTranspileOptions('hmr-entrypoint'),
-				plugins: this.context.getPlugins(),
-				minify: false,
-				external: ['react', 'react-dom'],
-			});
-
-			if (!result.success) {
-				appLogger.error(`[JsHmrStrategy] Failed to build ${entrypointPath}:`, result.logs);
-				return { success: false, requiresReload: false, dependencies: undefined };
-			}
-
-			const dependencyGraph = result.dependencyGraph?.entrypoints?.[path.resolve(entrypointPath)] ?? [];
-			const output = await this.processOutput(outputPath, outputUrl);
-
-			return {
-				...output,
-				dependencies: dependencyGraph,
-			};
-		} catch (error) {
-			appLogger.error(`[JsHmrStrategy] Error bundling ${entrypointPath}:`, error as Error);
-			return { success: false, requiresReload: false, dependencies: undefined };
-		}
-	}
-
-	/**
-	 * Processes bundled output by replacing specifiers and injecting HMR code.
-	 *
-	 * @param filepath - Path to the bundled output file
-	 * @param url - URL path for the bundled file
-	 * @returns True if processing was successful and update should be broadcast
-	 */
-	private async processOutput(filepath: string, url: string): Promise<{ success: boolean; requiresReload: boolean }> {
-		try {
-			let code = await fileSystem.readFile(filepath);
-
-			if (code.includes('/* [ecopages] hmr */')) {
-				/**
-				 * Already processed, assume it supports HMR if it has the header (legacy safety)
-				 * or check specifically for accept
-				 */
-				return { success: true, requiresReload: !code.includes('import.meta.hot.accept') };
-			}
-
-			code = this.replaceBareSpecifiers(code);
-			await fileSystem.writeAsync(filepath, code);
-
-			appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
-
-			/**
-			 * Implicit HMR check: if the code explicitly accepts HMR, we broadcast update.
-			 * Otherwise, we must reload the page to ensure fresh execution (e.g. for Custom Elements or side effects).
-			 */
-			const hasHmrAccept = code.includes('import.meta.hot.accept');
-			return { success: true, requiresReload: !hasHmrAccept };
-		} catch (error) {
-			appLogger.error(`[JsHmrStrategy] Error processing output for ${url}:`, error as Error);
-			return { success: false, requiresReload: false };
-		}
-	}
-
-	/**
-	 * Replaces bare specifiers with vendor URLs.
-	 *
-	 * Handles both static imports and dynamic imports.
-	 *
-	 * @param code - The bundled code to transform
-	 * @returns The transformed code with vendor URLs
-	 */
-	private replaceBareSpecifiers(code: string): string {
-		const specifierMap = this.context.getSpecifierMap();
-
-		if (specifierMap.size === 0) {
-			return code;
-		}
-
-		let result = code;
-		for (const [bareSpec, vendorUrl] of specifierMap.entries()) {
-			const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-			result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, 'g'), `from "${vendorUrl}"`);
-			result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, 'g'), `import("${vendorUrl}")`);
-		}
-
-		return result;
-	}
-}

package/src/index.browser.ts

@@ -1,3 +0,0 @@
-export type * from './public-types.ts';
-export type * from './eco/eco.types.ts';
-export { eco } from './eco/eco.ts';

package/src/index.ts

@@ -1,5 +0,0 @@
-export type * from './public-types.ts';
-export type * from './eco/eco.types.ts';
-export { eco } from './eco/eco.ts';
-export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.ts';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './define-api-handler.ts';

package/src/integrations/ghtml/ghtml-renderer.ts

@@ -1,93 +0,0 @@
-/**
- * This module contains the ghtml renderer
- * @module
- */
-
-import type {
-	EcoComponent,
-	EcoPagesElement,
-	IntegrationRendererRenderOptions,
-	PageMetadataProps,
-	RouteRendererBody,
-} from '../../public-types.ts';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/integration-renderer.ts';
-import { GHTML_PLUGIN_NAME } from './ghtml.plugin.ts';
-
-/**
- * A renderer for the ghtml integration.
- * It renders a page using the HtmlTemplate and Page components.
- */
-export class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
-	name = GHTML_PLUGIN_NAME;
-
-	async render({
-		params,
-		query,
-		props,
-		locals,
-		pageLocals,
-		metadata,
-		Page,
-		Layout,
-		HtmlTemplate,
-	}: IntegrationRendererRenderOptions): Promise<RouteRendererBody> {
-		try {
-			const pageContent = await Page({ params, query, ...props, locals: pageLocals });
-			const children =
-				Layout && typeof Layout === 'function' ? await Layout({ children: pageContent, locals }) : pageContent;
-			const body = await HtmlTemplate({
-				metadata,
-				children,
-				pageProps: props || {},
-			});
-
-			return this.DOC_TYPE + body;
-		} catch (error) {
-			throw this.createRenderError('Error rendering page', error);
-		}
-	}
-
-	async renderToResponse<P = Record<string, unknown>>(
-		view: EcoComponent<P>,
-		props: P,
-		ctx: RenderToResponseContext,
-	): Promise<Response> {
-		try {
-			const Layout = view.config?.layout as
-				| ((props: { children: EcoPagesElement } & Record<string, unknown>) => Promise<EcoPagesElement>)
-				| undefined;
-
-			const viewFn = view as (props: P) => Promise<EcoPagesElement>;
-			const pageContent = await viewFn(props);
-
-			let body: string;
-			if (ctx.partial) {
-				body = pageContent as string;
-			} else {
-				const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-
-				const HtmlTemplate = await this.getHtmlTemplate();
-				const metadata: PageMetadataProps = view.metadata
-					? await view.metadata({
-							params: {},
-							query: {},
-							props: props as Record<string, unknown>,
-							appConfig: this.appConfig,
-						})
-					: this.appConfig.defaultMetadata;
-
-				body =
-					this.DOC_TYPE +
-					(await HtmlTemplate({
-						metadata,
-						children: children as EcoPagesElement,
-						pageProps: props as Record<string, unknown>,
-					}));
-			}
-
-			return this.createHtmlResponse(body, ctx);
-		} catch (error) {
-			throw this.createRenderError('Error rendering view', error);
-		}
-	}
-}

package/src/integrations/ghtml/ghtml.plugin.ts

@@ -1,32 +0,0 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
-import { GhtmlRenderer } from './ghtml-renderer';
-
-/**
- * The name of the ghtml plugin
- */
-export const GHTML_PLUGIN_NAME = 'ghtml';
-
-/**
- * The Ghtml plugin class
- * This plugin provides support for ghtml components in Ecopages
- */
-export class GhtmlPlugin extends IntegrationPlugin {
-	renderer = GhtmlRenderer;
-
-	constructor(options?: Omit<IntegrationPluginConfig, 'name'>) {
-		super({
-			name: GHTML_PLUGIN_NAME,
-			extensions: ['.ghtml.ts', '.ghtml.tsx', '.ghtml'],
-			...options,
-		});
-	}
-}
-
-/**
- * Factory function to create a Ghtml plugin instance
- * @param options Configuration options for the Ghtml plugin
- * @returns A new GhtmlPlugin instance
- */
-export function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin {
-	return new GhtmlPlugin(options);
-}

package/src/internal-types.ts

@@ -1,212 +0,0 @@
-import type { EcoBuildPlugin } from './build/build-types.ts';
-import type { IntegrationPlugin } from './plugins/integration-plugin.ts';
-import type { Processor } from './plugins/processor.ts';
-import type { PageMetadataProps } from './public-types.ts';
-import type { FSRouter } from './router/fs-router.ts';
-import type { CacheConfig } from './services/cache/cache.types.ts';
-
-/**
- * The templates used to build the pages and loaded via the includes directory.
- */
-export type IncludesTemplates = {
-	head: string;
-	html: string;
-	seo: string;
-};
-
-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 templates used for the pages
-	 * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
-	 */
-	includesTemplates: IncludesTemplates;
-	/** Error 404 page
-	 * @default "404.kita.tsx"
-	 */
-	error404Template: string;
-	/**
-	 * The directory where the output will be located
-	 * @default "dist"
-	 */
-	distDir: 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: IntegrationPlugin[];
-	/** Integrations dependencies */
-	integrationsDependencies: IntegrationDependencyConfig[];
-	/** Derived Paths */
-	absolutePaths: {
-		config: string;
-		componentsDir: string;
-		distDir: 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>;
-	/**
-	 * Cache configuration for ISR and page caching.
-	 * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
-	 */
-	cache?: CacheConfig;
-	/**
-	 * 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 = {
-	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: FSRouter;
-				server: unknown;
-		  }
-		| Promise<{ router: FSRouter; 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';

package/src/plugins/alias-resolver-plugin.ts

@@ -1,45 +0,0 @@
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import type { EcoBuildPlugin } from '../build/build-types.ts';
-
-const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mdx', '.css', '.scss', '.sass', '.less'];
-
-function findResolvablePath(candidate: string): string | undefined {
-	if (path.extname(candidate)) {
-		return existsSync(candidate) ? candidate : undefined;
-	}
-
-	for (const extension of RESOLVABLE_EXTENSIONS) {
-		const fileCandidate = `${candidate}${extension}`;
-		if (existsSync(fileCandidate)) {
-			return fileCandidate;
-		}
-	}
-
-	for (const extension of RESOLVABLE_EXTENSIONS) {
-		const indexCandidate = path.join(candidate, `index${extension}`);
-		if (existsSync(indexCandidate)) {
-			return indexCandidate;
-		}
-	}
-
-	return undefined;
-}
-
-export function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin {
-	return {
-		name: 'ecopages-alias-resolver',
-		setup(build) {
-			build.onResolve({ filter: /^@\// }, (args) => {
-				const candidate = path.join(srcDir, args.path.slice(2));
-				const resolved = findResolvablePath(candidate);
-
-				if (resolved) {
-					return { path: resolved };
-				}
-
-				return {};
-			});
-		},
-	};
-}