@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

package/src/services/assets/asset-processing-service/processors/stylesheet/content-stylesheet.processor.ts

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import type { ContentStylesheetAsset, ProcessedAsset } from '../../assets.types.ts';
+import { BaseProcessor } from '../base/base-processor.ts';
+
+export class ContentStylesheetProcessor extends BaseProcessor<ContentStylesheetAsset> {
+	private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+
+	private isProcessableStylesheet(filepath: string): boolean {
+		return ContentStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+	}
+
+	private async applyStylesheetProcessors(content: string, filepath: string): Promise<string> {
+		if (!this.isProcessableStylesheet(filepath)) {
+			return content;
+		}
+
+		let transformedContent = content;
+		const processors = this.appConfig.processors ? Array.from(this.appConfig.processors.values()) : [];
+
+		for (const processor of processors) {
+			const hasCapabilities = processor.getAssetCapabilities().length > 0;
+			const canProcessStylesheet = processor.canProcessAsset('stylesheet', filepath);
+
+			if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes('postcss'))) {
+				continue;
+			}
+
+			if (!processor.matchesFileFilter(filepath)) {
+				continue;
+			}
+
+			const result = await processor.process(transformedContent, filepath);
+
+			if (typeof result === 'string') {
+				transformedContent = result;
+				continue;
+			}
+
+			if (result instanceof Buffer) {
+				transformedContent = result.toString();
+			}
+		}
+
+		return transformedContent;
+	}
+
+	async process(dep: ContentStylesheetAsset): Promise<ProcessedAsset> {
+		const virtualFilepath = path.join(this.appConfig.absolutePaths.distDir, 'styles', 'page-bundle.css');
+		const processedContent = await this.applyStylesheetProcessors(dep.content, virtualFilepath);
+		const hash = this.generateHash(processedContent);
+		const filename = `style-${hash}.css`;
+		const cachekey = this.buildCacheKey(filename, hash, dep);
+
+		return this.getOrProcess(cachekey, () => {
+			const filepath = path.join(this.getAssetsDir(), 'styles', filename);
+
+			if (!dep.inline) fileSystem.write(filepath, processedContent);
+
+			return {
+				filepath: dep.inline ? undefined : filepath,
+				content: dep.inline ? processedContent : undefined,
+				kind: 'stylesheet',
+				position: dep.position,
+				attributes: dep.attributes,
+				inline: dep.inline,
+				packageRole: dep.packageRole,
+				bundledSourceFilepaths: dep.bundledSourceFilepaths,
+			};
+		});
+	}
+}

package/src/services/assets/asset-processing-service/processors/stylesheet/file-stylesheet.processor.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import type { FileStylesheetAsset, ProcessedAsset } from '../../assets.types.ts';
+import { BaseProcessor } from '../base/base-processor.ts';
+
+export class FileStylesheetProcessor extends BaseProcessor<FileStylesheetAsset> {
+	private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+
+	getStyleContent = (srcUrl: string): Buffer => {
+		return fileSystem.readFileAsBuffer(srcUrl);
+	};
+
+	private isProcessableStylesheet(filepath: string): boolean {
+		return FileStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+	}
+
+	private async applyStylesheetProcessors(content: string, filepath: string): Promise<string> {
+		if (!this.isProcessableStylesheet(filepath)) {
+			return content;
+		}
+
+		let transformedContent = content;
+
+		for (const processor of this.appConfig.processors.values()) {
+			const hasCapabilities = processor.getAssetCapabilities().length > 0;
+			const canProcessStylesheet = processor.canProcessAsset('stylesheet', filepath);
+
+			if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes('postcss'))) {
+				continue;
+			}
+
+			if (!processor.matchesFileFilter(filepath)) {
+				continue;
+			}
+
+			const result = await processor.process(transformedContent, filepath);
+
+			if (typeof result === 'string') {
+				transformedContent = result;
+				continue;
+			}
+
+			if (result instanceof Buffer) {
+				transformedContent = result.toString();
+			}
+		}
+
+		return transformedContent;
+	}
+
+	async process(dep: FileStylesheetAsset): Promise<ProcessedAsset> {
+		const buffer = this.getStyleContent(dep.filepath);
+		const rawContent = buffer.toString();
+		const processedContent = await this.applyStylesheetProcessors(rawContent, dep.filepath);
+		const hash = this.generateHash(processedContent);
+		const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
+
+		return this.getOrProcess(cachekey, () => {
+			const filepath = path.join(
+				this.getAssetsDir(),
+				path.relative(this.appConfig.absolutePaths.srcDir, dep.filepath),
+			);
+			const outputBuffer = Buffer.from(processedContent);
+
+			if (!dep.inline) {
+				fileSystem.ensureDir(path.dirname(filepath));
+				fileSystem.write(filepath, outputBuffer);
+			}
+
+			return {
+				filepath: filepath,
+				sourceFilepath: dep.filepath,
+				content: dep.inline ? processedContent : undefined,
+				kind: 'stylesheet',
+				position: dep.position,
+				attributes: dep.attributes,
+				inline: dep.inline,
+				packageRole: dep.packageRole,
+				bundledSourceFilepaths: dep.bundledSourceFilepaths,
+			};
+		});
+	}
+}

package/src/services/assets/asset-processing-service/ungrouped-dependency-processing.ts

@@ -0,0 +1,65 @@
+import { fileSystem } from '@ecopages/file-system';
+import type { AssetProcessor } from './processor.interface.ts';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.ts';
+
+type ProcessUngroupedDependencyOptions = {
+	dep: AssetDefinition;
+	key: string;
+	depKey: string;
+	getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
+	getProcessor: (dep: AssetDefinition) => AssetProcessor | undefined;
+	resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined;
+	setCachedAsset: (dep: AssetDefinition, depKey: string, processed: ProcessedAsset) => void;
+	logMissingProcessor: (dep: AssetDefinition) => void;
+	logMissingFile: (dep: AssetDefinition & { filepath: string }) => void;
+	logProcessingError: (dep: AssetDefinition, error: unknown) => void;
+};
+
+export async function processUngroupedDependency(
+	options: ProcessUngroupedDependencyOptions,
+): Promise<ProcessedAsset | null> {
+	const {
+		dep,
+		key,
+		depKey,
+		getCachedAsset,
+		getProcessor,
+		resolveProcessedAssetSrcUrl,
+		setCachedAsset,
+		logMissingProcessor,
+		logMissingFile,
+		logProcessingError,
+	} = options;
+	const cached = getCachedAsset(dep, depKey);
+
+	if (cached) {
+		return { key, ...cached } as ProcessedAsset;
+	}
+
+	const processor = getProcessor(dep);
+	if (!processor) {
+		logMissingProcessor(dep);
+		return null;
+	}
+
+	if (dep.source === 'file' && 'filepath' in dep && !fileSystem.exists(dep.filepath)) {
+		logMissingFile(dep);
+		return null;
+	}
+
+	try {
+		const processed = await processor.process(dep);
+		const srcUrl = resolveProcessedAssetSrcUrl(processed);
+		const processedWithKey = {
+			key,
+			...processed,
+			srcUrl,
+		};
+
+		setCachedAsset(dep, depKey, processedWithKey);
+		return processedWithKey as ProcessedAsset;
+	} catch (error) {
+		logProcessingError(dep, error);
+		return null;
+	}
+}

package/src/services/assets/browser-bundle.service.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ViteHostBuildAdapter } from '../../build/build-adapter.ts';
+import { BrowserBundleService } from './browser-bundle.service.ts';
+
+describe('BrowserBundleService', () => {
+	it('routes browser bundle requests through the app executor with profile defaults', async () => {
+		const build = vi.fn(async () => ({
+			success: true,
+			logs: [],
+			outputs: [{ path: '/tmp/out/entry.js' }],
+		}));
+		const service = new BrowserBundleService({
+			runtime: {
+				buildAdapter: {
+					getTranspileOptions: () => ({
+						target: 'browser',
+						format: 'esm',
+						sourcemap: 'none',
+					}),
+				},
+				buildExecutor: { build },
+			},
+			loaders: new Map(),
+		} as any);
+
+		await service.bundle({
+			profile: 'browser-script',
+			entrypoints: ['/tmp/entry.ts'],
+			outdir: '/tmp/out',
+			minify: false,
+			naming: '[name].js',
+		});
+
+		expect(build).toHaveBeenCalledWith(
+			expect.objectContaining({
+				entrypoints: ['/tmp/entry.ts'],
+				outdir: '/tmp/out',
+				target: 'browser',
+				format: 'esm',
+				sourcemap: 'none',
+			}),
+		);
+	});
+
+	it('fails fast when a Vite-hosted app tries to use the Bun browser bundle seam', async () => {
+		const service = new BrowserBundleService({
+			runtime: {
+				buildAdapter: new ViteHostBuildAdapter(),
+				buildExecutor: {
+					build: vi.fn(),
+				},
+			},
+			loaders: new Map(),
+		} as any);
+
+		await expect(
+			service.bundle({
+				profile: 'browser-script',
+				entrypoints: ['/tmp/entry.ts'],
+				outdir: '/tmp/out',
+				minify: false,
+				naming: '[name].js',
+			}),
+		).rejects.toThrow(/Vite-hosted builds are owned by the host runtime/);
+	});
+});

package/src/services/assets/browser-bundle.service.ts

@@ -0,0 +1,109 @@
+import type { BuildOptions, BuildResult, BuildTranspileProfile } from '../../build/build-adapter.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { getAppBrowserBuildPlugins, getAppBuildExecutor, getAppTranspileOptions } from '../../build/build-adapter.ts';
+import { mergeEcoBuildPlugins } from '../../build/build-manifest.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+
+export type BrowserBundleOptions = {
+	entrypoints: string[] | Record<string, string>;
+	outdir?: string;
+	outbase?: string;
+	naming?: string;
+	conditions?: string[];
+	define?: Record<string, string>;
+	minify?: boolean;
+	treeshaking?: boolean;
+	splitting?: boolean;
+	root?: string;
+	bundle?: boolean;
+	externalPackages?: boolean;
+	external?: string[];
+	plugins?: EcoBuildPlugin[];
+	[key: string]: unknown;
+	profile: BuildTranspileProfile;
+	excludeAppBuildPlugins?: string[];
+};
+
+type BrowserBundleGroupedOptions = {
+	outdir?: string;
+	outbase?: string;
+	naming?: string;
+	conditions?: string[];
+	define?: Record<string, string>;
+	minify?: boolean;
+	treeshaking?: boolean;
+	splitting?: boolean;
+	root?: string;
+	bundle?: boolean;
+	externalPackages?: boolean;
+	external?: string[];
+	plugins?: EcoBuildPlugin[];
+	[key: string]: unknown;
+	profile: BuildTranspileProfile;
+	excludeAppBuildPlugins?: string[];
+};
+
+export interface BrowserBundleExecutor {
+	bundle(options: BrowserBundleOptions): Promise<BuildResult>;
+}
+
+export type BrowserBundleGroupedEntry = {
+	entrypoint: string;
+	entryName: string;
+};
+
+/**
+ * App-owned boundary for browser-oriented bundle work.
+ *
+ * @remarks
+ * This service owns the shared browser transpile defaults and ensures browser
+ * builds always run through the app-owned executor rather than direct backend
+ * calls scattered across HMR and asset processing paths.
+ */
+export class BrowserBundleService implements BrowserBundleExecutor {
+	private readonly appConfig: EcoPagesAppConfig;
+
+	/**
+	 * Creates the browser bundle boundary for one finalized app instance.
+	 */
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	/**
+	 * Runs one browser-targeted build through the app-owned executor.
+	 *
+	 * @remarks
+	 * Browser defaults and app-owned browser build plugins are applied here so HMR
+	 * and runtime asset generation do not have to recreate that policy at each call
+	 * site.
+	 */
+	async bundle(options: BrowserBundleOptions): Promise<BuildResult> {
+		const { profile, excludeAppBuildPlugins, plugins, ...rawBuildOptions } = options;
+		const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
+		const filteredAppBrowserPlugins =
+			excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0
+				? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name))
+				: appBrowserPlugins;
+		const request: BuildOptions = {
+			...rawBuildOptions,
+			entrypoints: options.entrypoints,
+			...getAppTranspileOptions(this.appConfig, profile),
+			plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins),
+		};
+
+		return await getAppBuildExecutor(this.appConfig).build(request);
+	}
+
+	async bundleGroupedEntries(
+		entries: BrowserBundleGroupedEntry[],
+		options: BrowserBundleGroupedOptions,
+	): Promise<BuildResult> {
+		const request: BrowserBundleOptions = {
+			...options,
+			entrypoints: entries.map((entry) => entry.entrypoint),
+		};
+
+		return this.bundle(request);
+	}
+}

package/src/services/cache/cache.types.ts

@@ -0,0 +1,126 @@
+/**
+ * Cache types and interfaces for page caching and ISR
+ * @module
+ */
+
+/**
+ * Result from rendering a page, including HTML and cache strategy.
+ */
+export interface RenderResult {
+	html: string;
+	strategy: CacheStrategy;
+}
+
+/**
+ * Render strategy configuration for pages.
+ * - `'static'`: Render once, cache indefinitely
+ * - `'dynamic'`: No caching, render on every request
+ * - `{ revalidate, tags }`: Cache with time-based revalidation and optional tags
+ */
+export type CacheStrategy =
+	| 'static'
+	| 'dynamic'
+	| {
+			/** Seconds until cache is considered stale */
+			revalidate: number;
+			/** Tags for on-demand invalidation */
+			tags?: string[];
+	  };
+
+/**
+ * Cache entry stored in the cache store.
+ */
+export interface CacheEntry {
+	/** The rendered HTML content */
+	html: string;
+	/** Timestamp when the entry was created */
+	createdAt: number;
+	/** Timestamp when the entry should be revalidated (null = never stale) */
+	revalidateAfter: number | null;
+	/** Tags associated with this entry for invalidation */
+	tags: string[];
+	/** The cache strategy used (for generating headers on HIT) */
+	strategy: CacheStrategy;
+}
+
+/**
+ * Cache statistics for debugging and monitoring.
+ */
+export interface CacheStats {
+	/** Number of entries in the cache */
+	entries: number;
+	/** Memory usage in bytes (if available) */
+	memoryUsage?: number;
+	/** Cache hit rate (if tracked) */
+	hitRate?: number;
+}
+
+/**
+ * Abstract interface for cache storage backends.
+ * Implementations must handle serialization/deserialization internally.
+ */
+export interface CacheStore {
+	/** Retrieve an entry by key */
+	get(key: string): Promise<CacheEntry | null>;
+
+	/** Store an entry */
+	set(key: string, entry: CacheEntry): Promise<void>;
+
+	/** Delete a specific entry */
+	delete(key: string): Promise<boolean>;
+
+	/** Delete all entries matching any of the provided tags */
+	invalidateByTags(tags: string[]): Promise<number>;
+
+	/** Delete entries by exact path */
+	invalidateByPaths(paths: string[]): Promise<number>;
+
+	/** Clear all entries */
+	clear(): Promise<void>;
+
+	/** Get cache statistics (optional, for debugging) */
+	stats?(): Promise<CacheStats>;
+}
+
+/**
+ * Configuration for the cache system.
+ */
+export interface CacheConfig {
+	/**
+	 * Cache store implementation.
+	 * @default 'memory'
+	 */
+	store?: 'memory' | CacheStore;
+
+	/**
+	 * Default cache strategy for pages that don't specify one.
+	 * @default 'static'
+	 */
+	defaultStrategy?: CacheStrategy;
+
+	/**
+	 * Whether caching is enabled.
+	 * Automatically disabled in dev mode unless explicitly set.
+	 * @default true (production), false (development)
+	 */
+	enabled?: boolean;
+
+	/**
+	 * Maximum number of entries in the memory cache before LRU eviction.
+	 * Only applies when using the built-in memory store.
+	 * @default 1000
+	 */
+	maxEntries?: number;
+}
+
+/**
+ * Result of a cache lookup operation.
+ */
+export interface CacheResult {
+	/** The cached HTML content */
+	html: string;
+	/** Cache status for X-Cache header */
+	status: 'hit' | 'miss' | 'stale';
+	/** The cache strategy (for generating Cache-Control headers) */
+	strategy: CacheStrategy;
+}

package/src/services/cache/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Cache services exports
+ * @module
+ */
+
+export type {
+	CacheConfig,
+	CacheEntry,
+	CacheResult,
+	CacheStats,
+	CacheStore,
+	CacheStrategy,
+	RenderResult,
+} from './cache.types.ts';
+
+export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory-cache-store.ts';
+
+export { getCacheControlHeader, PageCacheService, type PageCacheServiceOptions } from './page-cache-service.ts';