@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/adapters/node/runtime-adapter.ts

@@ -0,0 +1,439 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import {
+	createBuildAdapter,
+	getAppBuildExecutor,
+	type BuildAdapter,
+	type BuildExecutor,
+} from '../../build/build-adapter.ts';
+import { createAppBuildExecutor } from '../../build/dev-build-coordinator.ts';
+import { createNodeBootstrapPlugin, getNodeRuntimeNodeModulesDir } from './bootstrap-dependency-resolver.ts';
+import {
+	setAppNodeRuntimeManifest,
+	type NodeRuntimeManifest,
+} from '../../services/runtime-manifest/node-runtime-manifest.service.ts';
+import { DevelopmentInvalidationService } from '../../services/invalidation/development-invalidation.service.ts';
+import { getAppEntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import { createAliasResolverPlugin } from '../../plugins/alias-resolver-plugin.ts';
+import {
+	TranspilerServerLoader,
+	type ServerLoaderAppContext,
+} from '../../services/module-loading/server-loader.service.ts';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.ts';
+import { installAppRuntimeBuildExecutor } from '../../build/runtime-build-executor.ts';
+
+/**
+ * Host-to-adapter handoff contract for the Node thin-host runtime.
+ *
+ * @remarks
+ * The thin host is responsible only for validating the persisted manifest,
+ * capturing process-level launch context, and passing those values into the
+ * adapter. All framework bootstrap work begins after this handoff.
+ */
+export interface NodeRuntimeStartOptions {
+	manifest: NodeRuntimeManifest;
+	workingDirectory: string;
+	cliArgs: string[];
+}
+
+/**
+ * Runtime session state produced after the adapter has loaded the app through
+ * the framework-owned loader path.
+ */
+export interface LoadedAppRuntime {
+	manifest: NodeRuntimeManifest;
+	workingDirectory: string;
+	entryModulePath: string;
+	appConfig: EcoPagesAppConfig;
+	entryModule: unknown;
+}
+
+/**
+ * Live Node thin-host runtime session.
+ */
+export interface NodeRuntimeSession {
+	loadApp(): Promise<LoadedAppRuntime>;
+	invalidate(changedFiles: string[]): Promise<void>;
+	dispose(): Promise<void>;
+}
+
+/**
+ * Adapter boundary created by the thin host after manifest validation.
+ */
+export interface NodeRuntimeAdapter {
+	start(options: NodeRuntimeStartOptions): Promise<NodeRuntimeSession>;
+}
+
+const NODE_RUNTIME_CONFIG_OUTDIR = '.node-runtime-config';
+const NODE_RUNTIME_ENTRY_OUTDIR = '.node-runtime-entry';
+const NODE_RUNTIME_BOOTSTRAP_SPLITTING = false;
+const NODE_RUNTIME_CONFIG_NAMESPACE = 'ecopages-runtime-config';
+const NODE_RUNTIME_CONFIG_GLOBAL_KEY = '__ecopagesNodeRuntimeConfig';
+const NODE_HMR_MANAGER_SOURCE_PATH = fileURLToPath(new URL('./node-hmr-manager.ts', import.meta.url));
+
+/**
+ * Resolves a relative import path to an absolute path given its importer.
+ * Returns undefined for bare specifiers or when resolution is not possible.
+ */
+function resolveConfigImportPath(importPath: string, importer?: string): string | undefined {
+	if (!importPath) {
+		return undefined;
+	}
+
+	if (path.isAbsolute(importPath)) {
+		return importPath;
+	}
+
+	if (!importPath.startsWith('.')) {
+		return undefined;
+	}
+
+	if (!importer) {
+		return undefined;
+	}
+
+	return path.resolve(path.dirname(importer), importPath);
+}
+
+/**
+ * Returns true if the given esbuild resolve args refer to the app's eco.config
+ * module, by matching against the absolute config path (with or without
+ * extension) or the well-known relative form `./eco.config`.
+ */
+function doesImportReferenceConfig(args: { path: string; importer?: string }, configModulePath: string): boolean {
+	if (args.path === configModulePath) {
+		return true;
+	}
+
+	if (args.path === './eco.config' || args.path === './eco.config.ts') {
+		return true;
+	}
+
+	const resolvedImportPath = resolveConfigImportPath(args.path, args.importer);
+	if (!resolvedImportPath) {
+		return false;
+	}
+
+	if (resolvedImportPath === configModulePath) {
+		return true;
+	}
+
+	const configPathWithoutExtension = configModulePath.replace(/\.[cm]?[jt]sx?$/i, '');
+	const resolvedPathWithoutExtension = resolvedImportPath.replace(/\.[cm]?[jt]sx?$/i, '');
+	return resolvedPathWithoutExtension === configPathWithoutExtension;
+}
+
+/**
+ * Creates an esbuild plugin that intercepts any import of the app's eco.config
+ * module during app-entry transpilation and redirects it to a synthetic module
+ * that reads the pre-loaded config from `globalThis`. This prevents eco.config
+ * from being re-executed as a side effect of bundling the app-entry module.
+ */
+function createRuntimeConfigBridgePlugin(configModulePath: string): EcoBuildPlugin {
+	return {
+		name: 'node-runtime-config-bridge',
+		setup(build) {
+			build.onResolve({ filter: /.*/ }, (args) => {
+				if (!doesImportReferenceConfig(args, configModulePath)) {
+					return undefined;
+				}
+
+				return {
+					path: NODE_RUNTIME_CONFIG_GLOBAL_KEY,
+					namespace: NODE_RUNTIME_CONFIG_NAMESPACE,
+				};
+			});
+
+			build.onLoad({ filter: /.*/, namespace: NODE_RUNTIME_CONFIG_NAMESPACE }, () => {
+				return {
+					loader: 'js',
+					contents: [
+						`const key = ${JSON.stringify(NODE_RUNTIME_CONFIG_GLOBAL_KEY)};`,
+						'const appConfig = globalThis[key];',
+						'if (!appConfig) {',
+						"throw new Error('Node runtime config bridge expected a loaded app config before app-entry evaluation.');",
+						'}',
+						'export default appConfig;',
+					].join('\n'),
+				};
+			});
+		},
+	};
+}
+
+/**
+ * Validates and narrows the persisted Node runtime manifest used by the thin
+ * host handoff.
+ */
+export function assertNodeRuntimeManifest(manifest: unknown): NodeRuntimeManifest {
+	if (!manifest || typeof manifest !== 'object') {
+		throw new Error('Invalid Node runtime manifest: expected an object.');
+	}
+
+	const candidate = manifest as Record<string, unknown>;
+	const modulePaths = candidate.modulePaths as Record<string, unknown> | undefined;
+
+	if (candidate.runtime !== 'node') {
+		throw new Error('Invalid Node runtime manifest: runtime must be "node".');
+	}
+
+	if (
+		typeof candidate.appRootDir !== 'string' ||
+		typeof candidate.sourceRootDir !== 'string' ||
+		typeof candidate.distDir !== 'string'
+	) {
+		throw new Error('Invalid Node runtime manifest: root, source, and dist paths must be strings.');
+	}
+
+	if (!modulePaths || typeof modulePaths.config !== 'string') {
+		throw new Error('Invalid Node runtime manifest: modulePaths.config must be present.');
+	}
+
+	return candidate as unknown as NodeRuntimeManifest;
+}
+
+/**
+ * Resolves the runtime-specific output directory used for bootstrap module
+ * transpilation.
+ */
+function getRuntimeOutdir(
+	manifest: NodeRuntimeManifest,
+	kind: typeof NODE_RUNTIME_CONFIG_OUTDIR | typeof NODE_RUNTIME_ENTRY_OUTDIR,
+): string {
+	return path.join(
+		resolveInternalExecutionDir({
+			rootDir: manifest.appRootDir,
+			workDir: manifest.workDir,
+			absolutePaths: {
+				workDir: manifest.workDir,
+				distDir: manifest.distDir,
+			},
+		}),
+		kind,
+	);
+}
+
+class NodeRuntimeAdapterSession implements NodeRuntimeSession {
+	private readonly options: NodeRuntimeStartOptions;
+	private readonly serverLoader: TranspilerServerLoader;
+	private readonly bootstrapBundlePlugin: EcoBuildPlugin;
+	private readonly bootstrapBuildAdapter: BuildAdapter;
+	private readonly bootstrapBuildExecutor: BuildExecutor;
+	private invalidationService: DevelopmentInvalidationService | null = null;
+	private appConfig: EcoPagesAppConfig | null = null;
+	private loadedAppRuntime: LoadedAppRuntime | null = null;
+
+	constructor(options: NodeRuntimeStartOptions) {
+		this.options = options;
+		this.bootstrapBundlePlugin = createNodeBootstrapPlugin({
+			projectDir: options.manifest.appRootDir,
+			runtimeNodeModulesDir: getNodeRuntimeNodeModulesDir(options.manifest),
+			preserveImportMetaPaths: [
+				options.manifest.modulePaths.config,
+				...(options.manifest.modulePaths.entry ? [options.manifest.modulePaths.entry] : []),
+				NODE_HMR_MANAGER_SOURCE_PATH,
+			],
+		});
+		this.bootstrapBuildAdapter = createBuildAdapter();
+		this.bootstrapBuildExecutor = createAppBuildExecutor({
+			development: false,
+			adapter: this.bootstrapBuildAdapter,
+		});
+		this.serverLoader = new TranspilerServerLoader({
+			rootDir: options.manifest.appRootDir,
+			getBuildExecutor: () => this.bootstrapBuildExecutor,
+		});
+	}
+
+	private isDevelopmentMode(): boolean {
+		return this.options.cliArgs.includes('--dev') || process.env.NODE_ENV === 'development';
+	}
+
+	private get manifest(): NodeRuntimeManifest {
+		return this.options.manifest;
+	}
+
+	private getEntryModulePath(): string {
+		const entryModulePath = this.manifest.modulePaths.entry;
+
+		if (!entryModulePath) {
+			throw new Error(
+				'Invalid Node runtime manifest: modulePaths.entry must be present before the Node thin-host adapter can load the app.',
+			);
+		}
+
+		return entryModulePath;
+	}
+
+	private createAppLoaderContext(
+		appConfig: EcoPagesAppConfig,
+		buildExecutor: BuildExecutor,
+		invalidationService: DevelopmentInvalidationService,
+	): ServerLoaderAppContext {
+		return {
+			rootDir: appConfig.rootDir,
+			getBuildExecutor: () => buildExecutor,
+			getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion(),
+			invalidateModules: (changedFiles?: string[]) => invalidationService.invalidateServerModules(changedFiles),
+		};
+	}
+
+	/**
+	 * Installs and returns the app-owned runtime build executor.
+	 */
+	private installAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor {
+		const appBuildExecutor = installAppRuntimeBuildExecutor(appConfig, {
+			development: this.isDevelopmentMode(),
+		});
+		return appBuildExecutor;
+	}
+
+	/**
+	 * Rebinds app-phase server loading to the installed app-owned executor.
+	 */
+	private bindAppServerLoader(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void {
+		if (!this.invalidationService) {
+			throw new Error('Node runtime invalidation service is not initialized.');
+		}
+
+		this.serverLoader.rebindAppContext(
+			this.createAppLoaderContext(appConfig, buildExecutor, this.invalidationService),
+		);
+	}
+
+	private initializeAppRuntime(appConfig: EcoPagesAppConfig): EcoPagesAppConfig {
+		setAppNodeRuntimeManifest(appConfig, this.manifest);
+		this.invalidationService = new DevelopmentInvalidationService(appConfig);
+		const appBuildExecutor = this.installAppBuildExecutor(appConfig);
+		this.bindAppServerLoader(appConfig, appBuildExecutor);
+		this.appConfig = appConfig;
+		return appConfig;
+	}
+
+	/**
+	 * Loads and validates the built app config through the framework-owned server
+	 * loader.
+	 */
+	private async loadAppConfig(): Promise<EcoPagesAppConfig> {
+		if (this.appConfig) {
+			return this.appConfig;
+		}
+
+		let importedConfigModule;
+
+		try {
+			importedConfigModule = await this.serverLoader.loadConfig<
+				| {
+						default: EcoPagesAppConfig;
+				  }
+				| EcoPagesAppConfig
+			>({
+				filePath: this.manifest.modulePaths.config,
+				outdir: getRuntimeOutdir(this.manifest, NODE_RUNTIME_CONFIG_OUTDIR),
+				splitting: NODE_RUNTIME_BOOTSTRAP_SPLITTING,
+				externalPackages: false,
+				plugins: [createAliasResolverPlugin(this.manifest.sourceRootDir), this.bootstrapBundlePlugin],
+				transpileErrorMessage: (details) => `Failed to transpile Ecopages config module: ${details}`,
+				noOutputMessage: (filePath) => `No transpiled output generated for Ecopages config module: ${filePath}`,
+			});
+		} catch (error) {
+			throw new Error(
+				`Node thin-host runtime config bootstrap failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+
+		const exportedConfig = 'default' in importedConfigModule ? importedConfigModule.default : importedConfigModule;
+		return this.initializeAppRuntime(exportedConfig);
+	}
+
+	/**
+	 * Loads the application entry through the framework-owned server loader after
+	 * config bootstrap has established app-owned runtime/build services.
+	 */
+	async loadApp(): Promise<LoadedAppRuntime> {
+		if (this.loadedAppRuntime) {
+			return this.loadedAppRuntime;
+		}
+
+		const appConfig = await this.loadAppConfig();
+		const entryModulePath = this.getEntryModulePath();
+		let loadedEntryModule;
+		const runtimeGlobal = globalThis as typeof globalThis & {
+			[NODE_RUNTIME_CONFIG_GLOBAL_KEY]?: EcoPagesAppConfig;
+		};
+
+		runtimeGlobal[NODE_RUNTIME_CONFIG_GLOBAL_KEY] = appConfig;
+
+		try {
+			loadedEntryModule = await this.serverLoader.loadApp({
+				filePath: entryModulePath,
+				outdir: getRuntimeOutdir(this.manifest, NODE_RUNTIME_ENTRY_OUTDIR),
+				splitting: NODE_RUNTIME_BOOTSTRAP_SPLITTING,
+				externalPackages: false,
+				plugins: [
+					createRuntimeConfigBridgePlugin(this.manifest.modulePaths.config),
+					createAliasResolverPlugin(appConfig.absolutePaths.srcDir),
+					this.bootstrapBundlePlugin,
+				],
+				transpileErrorMessage: (details) => `Failed to transpile Ecopages app entry module: ${details}`,
+				noOutputMessage: (filePath) =>
+					`No transpiled output generated for Ecopages app entry module: ${filePath}`,
+			});
+		} catch (error) {
+			throw new Error(
+				`Node thin-host runtime app-entry bootstrap failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		} finally {
+			delete runtimeGlobal[NODE_RUNTIME_CONFIG_GLOBAL_KEY];
+		}
+
+		this.loadedAppRuntime = {
+			manifest: this.manifest,
+			workingDirectory: this.options.workingDirectory,
+			appConfig,
+			entryModulePath,
+			entryModule: loadedEntryModule,
+		};
+
+		return this.loadedAppRuntime;
+	}
+
+	/**
+	 * Invalidates server-loader and app dev-graph state before the next bootstrap
+	 * cycle.
+	 */
+	async invalidate(_changedFiles: string[]): Promise<void> {
+		this.serverLoader.invalidate(_changedFiles);
+		if (this.invalidationService) {
+			this.invalidationService.resetRuntimeState(_changedFiles);
+		}
+		this.loadedAppRuntime = null;
+		if (this.appConfig) {
+			this.bindAppServerLoader(this.appConfig, getAppBuildExecutor(this.appConfig));
+			return;
+		}
+	}
+
+	/**
+	 * Disposes loader-owned resources for the current runtime session.
+	 */
+	async dispose(): Promise<void> {
+		await this.serverLoader.dispose();
+		if (this.appConfig) {
+			getAppEntrypointDependencyGraph(this.appConfig).reset();
+		}
+		this.invalidationService = null;
+	}
+}
+
+class DefaultNodeRuntimeAdapter implements NodeRuntimeAdapter {
+	async start(options: NodeRuntimeStartOptions): Promise<NodeRuntimeSession> {
+		return new NodeRuntimeAdapterSession(options);
+	}
+}
+
+export function createNodeRuntimeAdapter(): NodeRuntimeAdapter {
+	return new DefaultNodeRuntimeAdapter();
+}

package/src/adapters/node/server-adapter.ts

@@ -1,12 +1,6 @@
 import { createServer, type IncomingMessage, type Server as NodeHttpServer, type ServerResponse } from 'node:http';
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import { RESOLVED_ASSETS_DIR } from '../../constants.ts';
-import { defaultBuildAdapter } from '../../build/build-adapter.ts';
-import type { EcoBuildPlugin } from '../../build/build-types.ts';
 import { appLogger } from '../../global/app-logger.ts';
 import type { EcoPagesAppConfig } from '../../internal-types.ts';
-import { ProjectWatcher } from '../../watchers/project-watcher.ts';
 import { NodeClientBridge } from './node-client-bridge.ts';
 import { NodeHmrManager } from './node-hmr-manager.ts';
 import type { ApiHandler, ErrorHandler, StaticRoute } from '../../public-types.ts';
@@ -15,6 +9,13 @@ import { StaticSiteGenerator } from '../../static-site-generator/static-site-gen
 import { SharedServerAdapter } from '../shared/server-adapter.ts';
 import type { ServerAdapterResult } from '../abstract/server-adapter.ts';
 import { ServerStaticBuilder } from '../shared/server-static-builder.ts';
+import {
+	bindSharedRuntimeHmrManager,
+	initializeSharedRuntimePlugins,
+	installSharedRuntimeBuildExecutor,
+	prepareSharedRuntimePublicDir,
+	startSharedProjectWatching,
+} from '../shared/runtime-bootstrap.ts';
 
 import { NodeStaticContentServer } from './static-content-server.ts';
 
@@ -83,7 +84,6 @@ export class NodeServerAdapter extends SharedServerAdapter<NodeServerAdapterPara
 	private previewServer: NodeStaticContentServer | null = null;
 	private bridge: NodeClientBridge | null = null;
 	private hmrManager: NodeHmrManager | null = null;
-	private processorBuildPlugins: EcoBuildPlugin[] = [];
 
 	constructor(options: NodeServerAdapterParams) {
 		super(options);
@@ -106,96 +106,30 @@ export class NodeServerAdapter extends SharedServerAdapter<NodeServerAdapterPara
 	 *    processors during their `setup()` calls.
 	 */
 	public async initialize(): Promise<void> {
-		this.setupLoaders();
-		this.copyPublicDir();
-		await this.initializePlugins();
-		await this.initSharedRouter();
-		this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager ?? undefined);
+		installSharedRuntimeBuildExecutor(this.appConfig, {
+			development: this.options?.watch === true,
+		});
+
+		prepareSharedRuntimePublicDir(this.appConfig);
+		await initializeSharedRuntimePlugins({
+			appConfig: this.appConfig,
+			runtimeOrigin: this.runtimeOrigin,
+			hmrManager: this.hmrManager ?? undefined,
+		});
+		await this.initializeSharedRouteHandling({
+			staticRoutes: this.staticRoutes,
+			hmrManager: this.hmrManager ?? undefined,
+		});
 		this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
 		this.staticBuilder = new ServerStaticBuilder({
 			appConfig: this.appConfig,
 			staticSiteGenerator: this.staticSiteGenerator,
 			serveOptions: this.serveOptions,
+			apiHandlers: this.apiHandlers,
 		});
 		this.initialized = true;
 	}
 
-	/**
-	 * Registers every configured file loader as a build plugin on the shared
-	 * `defaultBuildAdapter`.
-	 *
-	 * Loaders are registered on the *shared* adapter (not on a per-build instance)
-	 * because they must be available globally to both the SSR build and any dynamic
-	 * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
-	 * incremental rebuilds).
-	 */
-	private setupLoaders(): void {
-		for (const loader of this.appConfig.loaders.values()) {
-			defaultBuildAdapter.registerPlugin(loader);
-		}
-	}
-
-	private copyPublicDir(): void {
-		const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
-
-		if (fileSystem.exists(srcPublicDir)) {
-			fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
-		}
-
-		fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-	}
-
-	/**
-	 * Sets up all configured processors and integrations in two distinct phases.
-	 *
-	 * **Phase 1 — Processors:**
-	 * Each processor's `setup()` is called first. A processor may expose two
-	 * plugin lists:
-	 * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
-	 * - `buildPlugins` — esbuild plugins used during the client bundle step.
-	 * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
-	 *
-	 * **Phase 2 — Integrations:**
-	 * Integrations receive the fully-resolved app config, the runtime origin, and
-	 * (if already initialised) the HMR manager before their own `setup()` is called.
-	 * This ordering ensures integrations can query config values that processors
-	 * may have mutated during phase 1.
-	 */
-	private async initializePlugins(): Promise<void> {
-		const processorBuildPlugins: EcoBuildPlugin[] = [];
-
-		for (const processor of this.appConfig.processors.values()) {
-			await processor.setup();
-
-			if (processor.plugins) {
-				for (const plugin of processor.plugins) {
-					defaultBuildAdapter.registerPlugin(plugin);
-				}
-			}
-			if (processor.buildPlugins) {
-				processorBuildPlugins.push(...processor.buildPlugins);
-				for (const plugin of processor.buildPlugins) {
-					defaultBuildAdapter.registerPlugin(plugin);
-				}
-			}
-		}
-
-		for (const integration of this.appConfig.integrations) {
-			integration.setConfig(this.appConfig);
-			integration.setRuntimeOrigin(this.runtimeOrigin);
-			if (this.hmrManager) {
-				integration.setHmrManager(this.hmrManager);
-			}
-			await integration.setup();
-
-			for (const plugin of integration.plugins) {
-				defaultBuildAdapter.registerPlugin(plugin);
-			}
-		}
-
-		this.processorBuildPlugins = processorBuildPlugins;
-	}
-
 	public getServerOptions(): NodeServeAdapterServerOptions {
 		return {
 			...this.serveOptions,
@@ -478,8 +412,8 @@ export class NodeServerAdapter extends SharedServerAdapter<NodeServerAdapterPara
 	 *   broadcast + heartbeat cleanup.
 	 * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
 	 *   rebuilds, notifying connected clients via the bridge.
-	 * - `ProjectWatcher` listens for route-level file changes and refreshes the
-	 *   router and response handlers when pages are added or removed.
+	 * - Shared watcher bootstrapping listens for route-level file changes and
+	 *   refreshes the router and response handlers when pages are added or removed.
 	 *
 	 * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
 	 * immediate socket destroy to prevent unhandled upgrade leaks.
@@ -509,26 +443,19 @@ export class NodeServerAdapter extends SharedServerAdapter<NodeServerAdapterPara
 				}
 			});
 
-			const loaderPlugins = Array.from(this.appConfig.loaders.values());
-			const hmrBuildPlugins = [...loaderPlugins, ...this.processorBuildPlugins];
-			this.hmrManager.setPlugins(hmrBuildPlugins);
-
-			for (const integration of this.appConfig.integrations) {
-				integration.setHmrManager(this.hmrManager);
-			}
+			bindSharedRuntimeHmrManager(this.appConfig, this.hmrManager);
 
 			this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
 
-			const watcher = new ProjectWatcher({
-				config: this.appConfig,
-				refreshRouterRoutesCallback: async () => {
-					await this.initSharedRouter();
-					this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-				},
+			await startSharedProjectWatching({
+				appConfig: this.appConfig,
+				refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
+					staticRoutes: this.staticRoutes,
+					hmrManager: this.hmrManager,
+				}),
 				hmrManager: this.hmrManager,
 				bridge: this.bridge,
 			});
-			await watcher.createWatcherSubscription();
 		}
 
 		appLogger.debug('Node server adapter initialization completed', {

package/src/adapters/node/static-content-server.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { AddressInfo } from 'node:net';
+import { NodeStaticContentServer } from './static-content-server.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+
+const TMP_DIR = path.join(os.tmpdir(), 'node-static-content-server-test');
+
+const createAppConfig = (): EcoPagesAppConfig =>
+	({
+		rootDir: TMP_DIR,
+		distDir: 'dist',
+		absolutePaths: {
+			distDir: path.join(TMP_DIR, 'dist'),
+			workDir: path.join(TMP_DIR, '.eco'),
+		} as EcoPagesAppConfig['absolutePaths'],
+	}) as EcoPagesAppConfig;
+
+describe('NodeStaticContentServer', () => {
+	beforeEach(() => {
+		fs.rmSync(TMP_DIR, { recursive: true, force: true });
+		fs.mkdirSync(path.join(TMP_DIR, 'dist', 'assets', 'pages'), { recursive: true });
+	});
+
+	afterEach(() => {
+		fs.rmSync(TMP_DIR, { recursive: true, force: true });
+	});
+
+	it('should serve built CSS assets with the correct content type in preview mode', async () => {
+		const distDir = path.join(TMP_DIR, 'dist');
+		fs.writeFileSync(
+			path.join(distDir, 'api-lab.html'),
+			'<html><head><link rel="stylesheet" href="/assets/pages/api-lab.css"></head><body>API Lab</body></html>',
+		);
+		fs.writeFileSync(path.join(distDir, 'assets', 'pages', 'api-lab.css'), '.api-lab { color: tomato; }');
+
+		const server = new NodeStaticContentServer({
+			appConfig: createAppConfig(),
+			options: { hostname: '127.0.0.1', port: 0 },
+		});
+
+		const httpServer = await server.start();
+		const address = httpServer.address() as AddressInfo;
+
+		try {
+			const htmlResponse = await fetch(`http://127.0.0.1:${address.port}/api-lab`);
+			const cssResponse = await fetch(`http://127.0.0.1:${address.port}/assets/pages/api-lab.css`);
+
+			expect(htmlResponse.status).toBe(200);
+			expect(await htmlResponse.text()).toContain('/assets/pages/api-lab.css');
+			expect(cssResponse.status).toBe(200);
+			expect(cssResponse.headers.get('content-type')).toContain('text/css');
+			expect(await cssResponse.text()).toContain('.api-lab { color: tomato; }');
+		} finally {
+			await server.stop();
+		}
+	});
+});