@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

package/src/services/html/html-transformer.service.ts

@@ -0,0 +1,275 @@
+import type { AssetPosition, ProcessedAsset, ScriptAsset } from '../assets/asset-processing-service/assets.types.ts';
+import type { PagePackageResult } from '../../types/public-types.ts';
+import {
+	DefaultHtmlRewriterProvider,
+	type HtmlRewriterElement,
+	type HtmlRewriterMode,
+	type HtmlRewriterProvider,
+} from './html-rewriter-provider.service.ts';
+import { dedupeProcessedAssets } from '../../route-renderer/orchestration/processed-asset-dedupe.ts';
+
+export interface HtmlTransformerServiceOptions {
+	htmlRewriterMode?: HtmlRewriterMode;
+	htmlRewriterProvider?: HtmlRewriterProvider;
+}
+
+export class HtmlTransformerService {
+	private processedDependencies: ProcessedAsset[] = [];
+	private pagePackage?: PagePackageResult;
+	private htmlRewriterProvider: HtmlRewriterProvider;
+
+	constructor(options: HtmlTransformerServiceOptions = {}) {
+		this.htmlRewriterProvider = options.htmlRewriterProvider ?? new DefaultHtmlRewriterProvider();
+
+		if (options.htmlRewriterMode) {
+			this.htmlRewriterProvider.setMode(options.htmlRewriterMode);
+		}
+	}
+
+	/**
+	 * Overrides the HTML rewriter runtime selection.
+	 *
+	 * This is intended for internal/runtime tests that need deterministic
+	 * selection between native, worker-tools, and string fallback behavior.
+	 *
+	 * @param mode Requested runtime selection strategy.
+	 */
+	setHtmlRewriterMode(mode: HtmlRewriterMode) {
+		this.htmlRewriterProvider.setMode(mode);
+	}
+
+	private formatAttributes(attrs?: Record<string, string>): string {
+		if (!attrs) return '';
+		return ` ${Object.entries(attrs)
+			.map(([key, value]) => `${key}="${value}"`)
+			.join(' ')}`;
+	}
+
+	private generateScriptTag(dep: ProcessedAsset & { kind: 'script' }): string {
+		return dep.inline
+			? `<script${this.formatAttributes(dep.attributes)}>${dep.content}</script>`
+			: `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}></script>`;
+	}
+
+	private generateStylesheetTag(dep: ProcessedAsset): string {
+		return dep.inline
+			? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>`
+			: `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+	}
+
+	private appendDependencies(element: HtmlRewriterElement, dependencies: ProcessedAsset[]) {
+		for (const dep of dependencies) {
+			const tag =
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep);
+			element.append(tag, { html: true });
+		}
+	}
+
+	private buildDependencyTags(dependencies: ProcessedAsset[]): string {
+		return dependencies
+			.map((dep) =>
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep),
+			)
+			.join('');
+	}
+
+	/**
+	 * Injects generated markup immediately before the closing HTML tag when it is
+	 * present, or appends/prepends a fallback insertion otherwise.
+	 */
+	private injectBeforeClosingTag(html: string, tag: 'head' | 'body', content: string): string {
+		if (!content) {
+			return html;
+		}
+
+		const closingTag = `</${tag}>`;
+		const lowerHtml = html.toLowerCase();
+		const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
+
+		if (closingTagIndex !== -1) {
+			return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+		}
+
+		if (tag === 'head') {
+			return `${content}${html}`;
+		}
+
+		return `${html}${content}`;
+	}
+
+	/**
+	 * Replaces the current processed dependency set used during HTML finalization.
+	 */
+	setProcessedDependencies(processedDependencies: ProcessedAsset[]) {
+		this.pagePackage = undefined;
+		this.processedDependencies = processedDependencies;
+	}
+
+	/**
+	 * Replaces the current structured page package used during HTML finalization.
+	 */
+	setPagePackage(pagePackage: PagePackageResult) {
+		this.pagePackage = pagePackage;
+		this.processedDependencies = pagePackage.htmlAssets;
+	}
+
+	/**
+	 * Returns the processed dependencies queued for the next transform pass.
+	 */
+	getProcessedDependencies(): ProcessedAsset[] {
+		return this.processedDependencies;
+	}
+
+	/**
+	 * Returns the structured page package queued for the next transform pass.
+	 */
+	getPagePackage(): PagePackageResult | undefined {
+		return this.pagePackage;
+	}
+
+	/**
+	 * Applies attributes to the opening `<html>` tag when present.
+	 */
+	applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string {
+		const htmlTagMatch = html.match(/<html\b[^>]*>/i);
+		if (!htmlTagMatch || htmlTagMatch.index === undefined) {
+			return html;
+		}
+
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+
+		const injectionOffset = htmlTagMatch.index + htmlTagMatch[0].length - 1;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+
+	/**
+	 * Applies attributes to the first element nested directly under `<body>`.
+	 */
+	applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string {
+		const bodyMatch = html.match(/<body\b[^>]*>/i);
+		if (!bodyMatch || bodyMatch.index === undefined) {
+			return html;
+		}
+
+		const bodyOpenEnd = bodyMatch.index + bodyMatch[0].length;
+		const afterBody = html.slice(bodyOpenEnd);
+		const firstTagMatch = afterBody.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+		if (!firstTagMatch || firstTagMatch.index === undefined) {
+			return html;
+		}
+
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+
+		const injectionOffset = bodyOpenEnd + firstTagMatch[1].length + firstTagMatch[2].length;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+
+	/**
+	 * Applies attributes to the first element in a fragment or full-document HTML
+	 * string.
+	 */
+	applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string {
+		const firstTagMatch = html.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+		if (!firstTagMatch || firstTagMatch.index === undefined) {
+			return html;
+		}
+
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+
+		const injectionOffset = firstTagMatch[1].length + firstTagMatch[2].length;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+
+	/**
+	 * Removes duplicate processed assets while preserving first-seen order.
+	 *
+	 * @remarks
+	 * Dedupe keys include structural asset fields and HTML attributes so repeated
+	 * orchestration passes can merge assets safely without collapsing distinct tag
+	 * variants.
+	 */
+	dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[] {
+		return dedupeProcessedAssets(assets);
+	}
+
+	/**
+	 * Injects the currently processed dependencies into an HTML response.
+	 *
+	 * @remarks
+	 * Native or worker-tools HTML rewriter support is preferred when available. A
+	 * string-based fallback remains in place for runtimes that cannot provide one
+	 * of those rewriter implementations.
+	 */
+	async transform(res: Response): Promise<Response> {
+		const { head, body } = this.groupDependenciesByPosition();
+		const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
+
+		if (htmlRewriter) {
+			htmlRewriter
+				.on('head', {
+					element: (element) => this.appendDependencies(element, head),
+				})
+				.on('body', {
+					element: (element) => this.appendDependencies(element, body),
+				});
+
+			return htmlRewriter.transform(res);
+		}
+
+		const html = await res.text();
+		const headers = new Headers(res.headers);
+
+		const withHeadDependencies = this.injectBeforeClosingTag(html, 'head', this.buildDependencyTags(head));
+		const transformedHtml = this.injectBeforeClosingTag(
+			withHeadDependencies,
+			'body',
+			this.buildDependencyTags(body),
+		);
+
+		return new Response(transformedHtml, {
+			headers,
+			status: res.status,
+			statusText: res.statusText,
+		});
+	}
+
+	/**
+	 * Splits processed assets into head and body injection groups.
+	 */
+	private groupDependenciesByPosition() {
+		const dependencies = this.pagePackage?.htmlAssets ?? this.processedDependencies;
+
+		return dependencies.reduce(
+			(acc, dep) => {
+				if (dep.kind === 'script') {
+					if (dep.excludeFromHtml) return acc;
+					const position = dep.position || 'body';
+					acc[position].push(dep);
+				} else if (dep.kind === 'stylesheet') {
+					acc.head.push(dep);
+				}
+				return acc;
+			},
+			{ head: [], body: [] } as Record<AssetPosition, ProcessedAsset[]>,
+		);
+	}
+
+	/**
+	 * Builds a serialized HTML attribute string from an attribute object.
+	 */
+	private buildAttributeString(attributes: Record<string, string>): string {
+		return Object.entries(attributes)
+			.filter(([key, value]) => key.length > 0 && value.length > 0)
+			.map(([key, value]) => ` ${key}="${value}"`)
+			.join('');
+	}
+}

package/src/services/invalidation/development-invalidation.service.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.js';
+import { Processor } from '../../plugins/processor.js';
+import { DevelopmentInvalidationService } from './development-invalidation.service.ts';
+import { InMemoryDevGraphService, setAppDevGraphService } from '../runtime-state/dev-graph.service.ts';
+
+class StylesheetProcessor extends Processor {
+	buildPlugins = [];
+	plugins = [];
+
+	constructor() {
+		super({
+			name: 'css',
+			watch: {
+				paths: ['/test/project/src'],
+				extensions: ['.css'],
+			},
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.css'] }],
+		});
+	}
+
+	async setup(): Promise<void> {}
+
+	async teardown(): Promise<void> {}
+
+	async process<T>(input: T): Promise<T> {
+		return input;
+	}
+}
+
+describe('DevelopmentInvalidationService', () => {
+	it('classifies route, include, processor-owned, and additional-watch changes explicitly', async () => {
+		const appConfig = await new ConfigBuilder().setRootDir('/test/project').build();
+		appConfig.additionalWatchPaths = ['**/*.config.ts'];
+		appConfig.processors.set('css', new StylesheetProcessor());
+
+		const service = new DevelopmentInvalidationService(appConfig);
+
+		expect(service.planFileChange('/test/project/src/pages/index.tsx')).toMatchObject({
+			category: 'route-source',
+			invalidateServerModules: true,
+			refreshRoutes: true,
+			delegateToHmr: true,
+		});
+		expect(service.planFileChange('/test/project/src/includes/seo.kita.tsx')).toMatchObject({
+			category: 'include-source',
+			invalidateServerModules: true,
+			reloadBrowser: true,
+			delegateToHmr: false,
+		});
+		expect(service.planFileChange('/test/project/src/styles/main.css')).toMatchObject({
+			category: 'processor-owned-asset',
+			invalidateServerModules: false,
+			processorHandledAsset: true,
+		});
+		expect(service.planFileChange('/test/project/tailwind.config.ts')).toMatchObject({
+			category: 'additional-watch',
+			reloadBrowser: true,
+			invalidateServerModules: false,
+		});
+	});
+
+	it('delegates server invalidation versioning to the app-owned dev graph service', async () => {
+		const appConfig = await new ConfigBuilder().setRootDir('/test/project').build();
+		const devGraphService = new InMemoryDevGraphService();
+		setAppDevGraphService(appConfig, devGraphService);
+		const invalidateDevelopmentGraph = vi.fn(() => {});
+		appConfig.runtime = {
+			...(appConfig.runtime ?? {}),
+			appModuleLoader: {
+				owner: 'bun',
+				importModule: async <T = unknown>() => ({}) as T,
+				invalidateDevelopmentGraph,
+			},
+		};
+		const service = new DevelopmentInvalidationService(appConfig);
+
+		expect(service.getServerModuleInvalidationVersion()).toBe(0);
+
+		service.invalidateServerModules(['/test/project/src/components/Button.tsx']);
+		expect(service.getServerModuleInvalidationVersion()).toBe(1);
+		expect(invalidateDevelopmentGraph).toHaveBeenCalledTimes(1);
+
+		service.resetRuntimeState(['/test/project/src/pages/index.tsx']);
+		expect(service.getServerModuleInvalidationVersion()).toBe(3);
+	});
+});

package/src/services/invalidation/development-invalidation.service.ts

@@ -0,0 +1,262 @@
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { getAppServerInvalidationState } from '../runtime-state/server-invalidation-state.service.ts';
+
+export type DevelopmentInvalidationCategory =
+	| 'public-asset'
+	| 'additional-watch'
+	| 'include-source'
+	| 'route-source'
+	| 'processor-owned-asset'
+	| 'server-source'
+	| 'other';
+
+/**
+ * Framework-owned invalidation plan for one changed file.
+ *
+ * @remarks
+ * This is the explicit invalidation matrix Workstream 4 needs. Watchers and
+ * runtime adapters consume this plan instead of encoding file-category rules in
+ * host-specific control flow.
+ */
+export interface DevelopmentInvalidationPlan {
+	category: DevelopmentInvalidationCategory;
+	invalidateServerModules: boolean;
+	refreshRoutes: boolean;
+	reloadBrowser: boolean;
+	delegateToHmr: boolean;
+	processorHandledAsset: boolean;
+}
+
+/**
+ * Framework-owned development invalidation service.
+ *
+ * @remarks
+ * This service centralizes two responsibilities:
+ * - file-change classification for watcher behavior
+ * - app-owned server-module invalidation versioning backed by the dev graph
+ *
+ * Hosts and watchers should ask this service what a file change means instead
+ * of deciding invalidation semantics inline.
+ */
+export class DevelopmentInvalidationService {
+	private readonly appConfig: EcoPagesAppConfig;
+
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	/**
+	 * Returns the current app-owned server-module invalidation version.
+	 */
+	getServerModuleInvalidationVersion(): number {
+		return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
+	}
+
+	/**
+	 * Invalidates the app-owned server-module graph.
+	 */
+	invalidateServerModules(changedFiles?: string[]): void {
+		getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+		this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
+	}
+
+	/**
+	 * Resets runtime-owned graph state and invalidates server modules.
+	 */
+	resetRuntimeState(changedFiles?: string[]): void {
+		const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
+		serverInvalidationState.invalidateServerModules(changedFiles);
+		serverInvalidationState.reset();
+	}
+
+	/**
+	 * Classifies one changed file into an explicit framework invalidation plan.
+	 */
+	planFileChange(filePath: string): DevelopmentInvalidationPlan {
+		if (this.isPublicDirFile(filePath)) {
+			return {
+				category: 'public-asset',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.matchesAdditionalWatchPaths(filePath)) {
+			return {
+				category: 'additional-watch',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isIncludeSourceFile(filePath)) {
+			return {
+				category: 'include-source',
+				invalidateServerModules: true,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isRouteSourceFile(filePath)) {
+			return {
+				category: 'route-source',
+				invalidateServerModules: true,
+				refreshRoutes: true,
+				reloadBrowser: false,
+				delegateToHmr: true,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isProcessorOwnedAsset(filePath)) {
+			return {
+				category: 'processor-owned-asset',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: false,
+				delegateToHmr: false,
+				processorHandledAsset: true,
+			};
+		}
+
+		if (this.isServerModuleSourceFile(filePath)) {
+			return {
+				category: 'server-source',
+				invalidateServerModules: true,
+				refreshRoutes: false,
+				reloadBrowser: false,
+				delegateToHmr: true,
+				processorHandledAsset: false,
+			};
+		}
+
+		return {
+			category: 'other',
+			invalidateServerModules: false,
+			refreshRoutes: false,
+			reloadBrowser: false,
+			delegateToHmr: true,
+			processorHandledAsset: false,
+		};
+	}
+
+	/**
+	 * Returns whether the file lives under the public directory.
+	 */
+	isPublicDirFile(filePath: string): boolean {
+		return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
+	}
+
+	/**
+	 * Returns whether the file matches `additionalWatchPaths`.
+	 */
+	matchesAdditionalWatchPaths(filePath: string): boolean {
+		const normalizedPath = path.resolve(filePath);
+		const patterns = this.appConfig.additionalWatchPaths;
+		if (!patterns.length) return false;
+
+		for (const pattern of patterns) {
+			if (pattern.includes('*')) {
+				const ext = pattern.replace(/\*\*?\/\*/, '');
+				if (normalizedPath.endsWith(ext)) return true;
+			} else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Returns whether the file is a route source file.
+	 */
+	isRouteSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether the file is an include/template source file.
+	 */
+	isIncludeSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether the file is a server-executed source module outside the
+	 * special route/include buckets.
+	 */
+	isServerModuleSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether a processor owns the changed file as an asset input.
+	 */
+	isProcessorOwnedAsset(filePath: string): boolean {
+		for (const processor of this.appConfig.processors.values()) {
+			const capabilities = processor.getAssetCapabilities?.() ?? [];
+			if (capabilities.length > 0) {
+				const matchesConfiguredAsset =
+					typeof processor.matchesFileFilter !== 'function' || processor.matchesFileFilter(filePath);
+
+				if (
+					matchesConfiguredAsset &&
+					capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))
+				) {
+					return true;
+				}
+
+				continue;
+			}
+
+			const watchConfig = processor.getWatchConfig();
+			if (!watchConfig) continue;
+
+			const { extensions = [] } = watchConfig;
+			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}

package/src/services/module-loading/app-module-loader.service.ts

@@ -0,0 +1,9 @@
+import type { PageModuleImportOptions } from './page-module-import.service.ts';
+
+export type AppModuleLoaderOwner = 'bun' | 'host';
+
+export interface AppModuleLoader {
+	readonly owner: AppModuleLoaderOwner;
+	importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+	invalidateDevelopmentGraph(): void;
+}