@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

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

@@ -1,166 +0,0 @@
-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 { ApiHandler, StaticRoute } from '../../public-types';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/server/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;
-	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: FSRouter;
-			routeRendererFactory: RouteRendererFactory;
-			staticRoutes?: StaticRoute[];
-		},
-	): Promise<void> {
-		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,
-			baseUrl,
-			routeRendererFactory: dependencies.routeRendererFactory,
-			staticRoutes: dependencies.staticRoutes,
-		});
-
-		if (!preview) {
-			this.logger.info('Build completed');
-			return;
-		}
-
-		const previewPort = this.serveOptions.port || 3000;
-
-		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');
-		}
-	}
-}

package/src/build/build-adapter.ts

@@ -1,361 +0,0 @@
-import type { BunPlugin } from 'bun';
-import type { EcoBuildPlugin } from './build-types.ts';
-import {
-	createAppBuildManifest,
-	getBrowserBuildPlugins,
-	getServerBuildPlugins,
-	type AppBuildManifest,
-} from './build-manifest.ts';
-import { EsbuildBuildAdapter } from './esbuild-build-adapter.ts';
-import { getRequiredBunRuntime } from '../utils/runtime.ts';
-import type { EcoPagesAppConfig } from '../internal-types.ts';
-import type { IHmrManager } from '../public-types.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;
-	outbase?: string;
-	naming?: string;
-	conditions?: string[];
-	define?: Record<string, 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 {
-	/**
-	 * Executes one concrete backend build.
-	 *
-	 * @remarks
-	 * `BuildAdapter` is the low-level backend contract. The default adapter is
-	 * `EsbuildBuildAdapter`, but alternate adapters may satisfy the same shape.
-	 */
-	build(options: BuildOptions): Promise<BuildResult>;
-	resolve(importPath: string, rootDir: string): string;
-	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}
-
-/**
- * Runtime-owned facade for issuing builds.
- *
- * @remarks
- * This is intentionally narrower than `BuildAdapter`. A build executor answers
- * only the question "how should this app execute a build right now?".
- *
- * In production and non-watch flows the executor is usually the adapter itself,
- * which today means `EsbuildBuildAdapter`. In development watch flows the
- * executor is typically `DevBuildCoordinator`, which wraps the shared esbuild
- * adapter to serialize callers and recover from known worker faults.
- */
-export interface BuildExecutor {
-	build(options: BuildOptions): Promise<BuildResult>;
-}
-
-export function createBuildAdapter(): BuildAdapter {
-	return new EsbuildBuildAdapter();
-}
-
-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);
-	}
-
-	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
-		return transpileProfileToOptions(profile);
-	}
-}
-
-export const defaultBuildAdapter: BuildAdapter = createBuildAdapter();
-
-/**
- * Returns the adapter owned by an app/runtime instance.
- *
- * @remarks
- * The config builder installs a dedicated adapter per app. The shared default
- * adapter remains only as a compatibility fallback for older tests and helpers
- * that do not yet thread app runtime state explicitly.
- */
-export function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter {
-	return appConfig.runtime?.buildAdapter ?? defaultBuildAdapter;
-}
-
-/**
- * Installs the adapter that should serve future builds for one app instance.
- */
-export function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		buildAdapter,
-	};
-}
-
-/**
- * Returns the build manifest owned by an app/runtime instance.
- */
-export function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest {
-	return (
-		appConfig.runtime?.buildManifest ??
-		createAppBuildManifest({
-			loaderPlugins: Array.from(appConfig.loaders.values()),
-		})
-	);
-}
-
-/**
- * Installs the build manifest that should be visible to one app instance.
- */
-export function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		buildManifest,
-	};
-}
-
-/**
- * Rebuilds an app-owned manifest from config-owned loaders plus explicit
- * runtime/browser contribution input.
- *
- * @remarks
- * This keeps loader ownership with config finalization while still letting a
- * caller supply the non-loader plugin buckets that were discovered elsewhere.
- */
-export function createConfiguredAppBuildManifest(
-	appConfig: EcoPagesAppConfig,
-	input?: Partial<AppBuildManifest>,
-): AppBuildManifest {
-	return createAppBuildManifest({
-		loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
-		runtimePlugins: input?.runtimePlugins,
-		browserBundlePlugins: input?.browserBundlePlugins,
-	});
-}
-
-/**
- * Replaces the app-owned manifest using config-owned loaders and explicit
- * contribution input.
- */
-export function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void {
-	setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
-}
-
-/**
- * Collects the build-facing processor and integration contributions that should
- * be sealed into the app manifest during config finalization.
- *
- * @remarks
- * This runs `prepareBuildContributions()` only. Runtime-only side effects such
- * as HMR registration, cache prewarming, and runtime-origin wiring belong to
- * the startup path and must not be triggered here.
- */
-export async function collectConfiguredAppBuildManifestContributions(
-	appConfig: EcoPagesAppConfig,
-): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>> {
-	const runtimePlugins: EcoBuildPlugin[] = [];
-	const browserBundlePlugins: EcoBuildPlugin[] = [];
-
-	for (const processor of appConfig.processors.values()) {
-		await processor.prepareBuildContributions();
-
-		if (processor.plugins) {
-			runtimePlugins.push(...processor.plugins);
-		}
-
-		if (processor.buildPlugins) {
-			browserBundlePlugins.push(...processor.buildPlugins);
-		}
-	}
-
-	for (const integration of appConfig.integrations) {
-		integration.setConfig(appConfig);
-		await integration.prepareBuildContributions();
-		runtimePlugins.push(...integration.plugins);
-	}
-
-	return {
-		runtimePlugins,
-		browserBundlePlugins,
-	};
-}
-
-/**
- * Runs runtime-only processor and integration setup against an already sealed
- * app manifest.
- *
- * @remarks
- * Startup paths call this after config build has finalized manifest
- * contributions. The manifest is reused as-is; this helper only performs the
- * runtime side effects that still need live startup context.
- */
-export async function setupAppRuntimePlugins(options: {
-	appConfig: EcoPagesAppConfig;
-	runtimeOrigin: string;
-	hmrManager?: IHmrManager;
-	onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
-}): Promise<void> {
-	for (const processor of options.appConfig.processors.values()) {
-		await processor.setup();
-
-		if (processor.plugins) {
-			for (const plugin of processor.plugins) {
-				options.onRuntimePlugin?.(plugin);
-			}
-		}
-	}
-
-	for (const integration of options.appConfig.integrations) {
-		integration.setConfig(options.appConfig);
-		integration.setRuntimeOrigin(options.runtimeOrigin);
-		if (options.hmrManager) {
-			integration.setHmrManager(options.hmrManager);
-		}
-
-		await integration.setup();
-
-		for (const plugin of integration.plugins) {
-			options.onRuntimePlugin?.(plugin);
-		}
-	}
-}
-
-export function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[] {
-	return getServerBuildPlugins(getAppBuildManifest(appConfig));
-}
-
-export function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[] {
-	return getBrowserBuildPlugins(getAppBuildManifest(appConfig));
-}
-
-/**
- * Returns the executor owned by an app/runtime instance.
- *
- * @remarks
- * The config builder seeds this with the shared default adapter. Runtime
- * adapters may replace it with a coordinator that still delegates to the same
- * backend while adding development policy.
- */
-export function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor {
-	return appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
-}
-
-/**
- * Installs the executor that should serve future builds for one app instance.
- */
-export function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		buildExecutor,
-	};
-}
-
-/**
- * Runs a build through the active pipeline.
- *
- * @remarks
- * Callers can pass an explicit executor when builds should be routed through an
- * app-owned development coordinator. Without one, the shared default adapter is
- * used directly.
- */
-export function build(options: BuildOptions, executor: BuildExecutor = defaultBuildAdapter): Promise<BuildResult> {
-	return executor.build(options);
-}
-
-export function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
-	return defaultBuildAdapter.getTranspileOptions(profile);
-}

package/src/build/build-manifest.ts

@@ -1,54 +0,0 @@
-import type { EcoBuildPlugin } from './build-types.ts';
-
-export interface AppBuildManifest {
-	loaderPlugins: EcoBuildPlugin[];
-	runtimePlugins: EcoBuildPlugin[];
-	browserBundlePlugins: EcoBuildPlugin[];
-}
-
-/**
- * Merges plugin lists while preserving first-registration precedence by name.
- *
- * @remarks
- * Build manifests treat plugin names as stable identities. The first plugin
- * with a given name wins so config-time assembly stays deterministic across
- * loader, runtime, and browser buckets.
- */
-export function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[] {
-	const byName = new Map<string, EcoBuildPlugin>();
-
-	for (const plugins of pluginLists) {
-		for (const plugin of plugins ?? []) {
-			if (!byName.has(plugin.name)) {
-				byName.set(plugin.name, plugin);
-			}
-		}
-	}
-
-	return Array.from(byName.values());
-}
-
-/**
- * Creates one app-owned build manifest from the supplied plugin buckets.
- */
-export function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest {
-	return {
-		loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
-		runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
-		browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins),
-	};
-}
-
-/**
- * Returns the plugin list used for server-oriented builds.
- */
-export function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[] {
-	return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
-}
-
-/**
- * Returns the plugin list used for browser-oriented builds.
- */
-export function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[] {
-	return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, manifest.browserBundlePlugins);
-}

package/src/build/build-types.ts

@@ -1,83 +0,0 @@
-/**
- * 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>;
-};