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

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

@@ -0,0 +1,130 @@
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import {
+	ServerModuleTranspiler,
+	type ServerModuleTranspilerBootstrapArgs,
+	type ServerModuleTranspilerOptions,
+} from './server-module-transpiler.service.ts';
+
+/**
+ * High-level module-loading options owned by the framework loader boundary.
+ *
+ * @remarks
+ * These are the same shape the lower-level transpiler needs, minus the
+ * root/build-executor ownership that the loader keeps internally.
+ */
+export interface ServerLoaderModuleOptions extends ServerModuleTranspilerOptions {
+	plugins?: EcoBuildPlugin[];
+}
+
+/**
+ * Mutable app-phase server-loading context.
+ *
+ * @remarks
+ * The loader starts with bootstrap config-loading context. Once a real built
+ * app config is available, the runtime adapter rebinds the loader so app-entry
+ * and downstream server modules load through the app-owned executor.
+ */
+export interface ServerLoaderAppContext extends ServerModuleTranspilerBootstrapArgs {}
+
+/**
+ * Minimal transpiler dependency required by the server loader.
+ *
+ * @remarks
+ * The loader owns orchestration between bootstrap and app phases, so tests only
+ * need this narrow import/invalidate/dispose surface rather than the concrete
+ * transpiler class.
+ */
+export interface ServerLoaderTranspilerDependency {
+	importModule<T = unknown>(options: ServerLoaderModuleOptions): Promise<T>;
+	invalidate(changedFiles?: string[]): void;
+	dispose(): Promise<void>;
+}
+
+/**
+ * Factory dependency used by the loader to create phase-specific transpilers.
+ */
+export interface ServerLoaderDependencyFactory {
+	createTranspiler(context: ServerModuleTranspilerBootstrapArgs): ServerLoaderTranspilerDependency;
+}
+
+/**
+ * Framework-owned server loading boundary.
+ *
+ * @remarks
+ * This abstraction owns config loading, app-entry loading, and cache lifecycle
+ * for the Node thin-host runtime path. Hosts and runtime adapters should depend
+ * on this boundary rather than coordinating raw transpiler instances directly.
+ */
+export interface ServerLoader {
+	/**
+	 * Loads the bootstrap config module through the bootstrap server-loading
+	 * context.
+	 */
+	loadConfig<T = unknown>(options: ServerLoaderModuleOptions): Promise<T>;
+
+	/**
+	 * Loads the app entry module through the currently active app context.
+	 *
+	 * @remarks
+	 * Until app context is rebound, this falls back to the bootstrap context so a
+	 * caller can still load through one boundary during early bootstrap.
+	 */
+	loadApp<T = unknown>(options: ServerLoaderModuleOptions): Promise<T>;
+
+	/**
+	 * Rebinds the app-phase loading context after a real app config has been
+	 * loaded and app-owned build services are available.
+	 */
+	rebindAppContext(context: ServerLoaderAppContext): void;
+
+	/**
+	 * Invalidates cached server module state for development reloads.
+	 */
+	invalidate(changedFiles?: string[]): void;
+
+	/**
+	 * Releases loader-owned resources.
+	 */
+	dispose(): Promise<void>;
+}
+
+/**
+ * `ServerLoader` implementation backed by `ServerModuleTranspiler` instances.
+ *
+ * @remarks
+ * This is the first named loader abstraction for Workstream 3. It keeps the
+ * lower-level transpiler as the implementation detail while moving ownership of
+ * config/app entry orchestration into one service boundary.
+ */
+export class TranspilerServerLoader implements ServerLoader {
+	private readonly createTranspiler: ServerLoaderDependencyFactory['createTranspiler'];
+	private readonly configTranspiler: ServerLoaderTranspilerDependency;
+	private appTranspiler: ServerLoaderTranspilerDependency | null = null;
+
+	constructor(configContext: ServerModuleTranspilerBootstrapArgs, dependencies?: ServerLoaderDependencyFactory) {
+		this.createTranspiler = dependencies?.createTranspiler ?? ((context) => new ServerModuleTranspiler(context));
+		this.configTranspiler = this.createTranspiler(configContext);
+	}
+
+	async loadConfig<T = unknown>(options: ServerLoaderModuleOptions): Promise<T> {
+		return await this.configTranspiler.importModule<T>(options);
+	}
+
+	async loadApp<T = unknown>(options: ServerLoaderModuleOptions): Promise<T> {
+		return await (this.appTranspiler ?? this.configTranspiler).importModule<T>(options);
+	}
+
+	rebindAppContext(context: ServerLoaderAppContext): void {
+		this.appTranspiler = this.createTranspiler(context);
+	}
+
+	invalidate(changedFiles?: string[]): void {
+		this.configTranspiler.invalidate(changedFiles);
+		this.appTranspiler?.invalidate(changedFiles);
+	}
+
+	async dispose(): Promise<void> {
+		await this.appTranspiler?.dispose();
+		await this.configTranspiler.dispose();
+	}
+}

package/src/services/module-loading/server-module-transpiler.service.test.ts

@@ -0,0 +1,115 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import type { BuildResult } from '../../build/build-adapter.js';
+import { ServerModuleTranspiler, type ServerModuleImportDependency } from './server-module-transpiler.service.ts';
+
+function createBuildResult(): BuildResult {
+	return {
+		success: true,
+		logs: [],
+		outputs: [],
+	};
+}
+
+function createFakeImportService(): {
+	dependency: ServerModuleImportDependency;
+	calls: {
+		importModule: Array<unknown>;
+		invalidateDevelopmentGraph: number;
+	};
+	setResult(result: unknown): void;
+} {
+	const calls = {
+		importModule: [] as Array<unknown>,
+		invalidateDevelopmentGraph: 0,
+	};
+	let nextResult: unknown = undefined;
+
+	return {
+		dependency: {
+			async importModule<T = unknown>(
+				options: Parameters<ServerModuleImportDependency['importModule']>[0],
+			): Promise<T> {
+				calls.importModule.push(options);
+				return nextResult as T;
+			},
+			invalidateDevelopmentGraph(): void {
+				calls.invalidateDevelopmentGraph += 1;
+			},
+		},
+		calls,
+		setResult(result: unknown): void {
+			nextResult = result;
+		},
+	};
+}
+
+describe('ServerModuleTranspiler', () => {
+	it('injects app root dir and build executor into page module imports', async () => {
+		const buildExecutor = { build: async () => createBuildResult() };
+		const fakeImportService = createFakeImportService();
+		fakeImportService.setResult({ default: { ok: true } });
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/app',
+			getBuildExecutor: () => buildExecutor,
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		await service.importModule({
+			filePath: '/app/src/pages/index.tsx',
+			outdir: '/app/.eco/.server-modules',
+		});
+
+		assert.deepEqual(fakeImportService.calls.importModule, [
+			{
+				filePath: '/app/src/pages/index.tsx',
+				outdir: '/app/.eco/.server-modules',
+				rootDir: '/app',
+				buildExecutor,
+				invalidationVersion: undefined,
+			},
+		]);
+	});
+
+	it('supports explicit bootstrap root and executor without a full app config', async () => {
+		const buildExecutor = { build: async () => createBuildResult() };
+		const fakeImportService = createFakeImportService();
+		fakeImportService.setResult({ default: { ok: true } });
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/bootstrap-app',
+			getBuildExecutor: () => buildExecutor,
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		await service.importModule({
+			filePath: '/bootstrap-app/eco.config.ts',
+			outdir: '/bootstrap-app/.eco/.server-modules',
+		});
+
+		assert.deepEqual(fakeImportService.calls.importModule, [
+			{
+				filePath: '/bootstrap-app/eco.config.ts',
+				outdir: '/bootstrap-app/.eco/.server-modules',
+				rootDir: '/bootstrap-app',
+				buildExecutor,
+				invalidationVersion: undefined,
+			},
+		]);
+	});
+
+	it('invalidates the owned import graph when no app invalidation callback is provided', () => {
+		const fakeImportService = createFakeImportService();
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/bootstrap-app',
+			getBuildExecutor: () => ({ build: async () => createBuildResult() }),
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		service.invalidate(['/bootstrap-app/src/pages/index.tsx']);
+
+		assert.equal(fakeImportService.calls.invalidateDevelopmentGraph, 1);
+	});
+});

package/src/services/module-loading/server-module-transpiler.service.ts

@@ -0,0 +1,105 @@
+import type { BuildExecutor } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { PageModuleImportService, type PageModuleImportOptions } from './page-module-import.service.ts';
+
+export type ServerModuleTranspilerOptions = Omit<PageModuleImportOptions, 'rootDir' | 'buildExecutor'>;
+
+/**
+ * Minimal import-service dependency required by the server module transpiler.
+ *
+ * @remarks
+ * This keeps the transpiler boundary testable without module-level mocking and
+ * lets callers provide an app-owned import implementation when needed.
+ */
+export interface ServerModuleImportDependency {
+	importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+	invalidateDevelopmentGraph(): void;
+}
+
+/**
+ * Immutable execution context for one server-transpiler instance.
+ *
+ * @remarks
+ * Callers own when and why a new transpiler is created. This service only owns
+ * applying the supplied root/build-executor pair consistently to every module
+ * load that passes through it.
+ */
+export type ServerModuleTranspilerBootstrapArgs = {
+	rootDir: string;
+	getBuildExecutor: () => BuildExecutor | undefined;
+	getInvalidationVersion?: () => number;
+	invalidateModules?: (changedFiles?: string[]) => void;
+	pageModuleImportService?: ServerModuleImportDependency;
+	/** Factory evaluated on each importModule call to produce plugins applied to every load. */
+	getDefaultPlugins?: () => EcoBuildPlugin[];
+};
+
+/**
+ * App-owned boundary for server-side source module loading.
+ *
+ * @remarks
+ * This service centralizes server-side module transpilation and import behind
+ * an explicit caller-owned root and build executor.
+ */
+export class ServerModuleTranspiler {
+	private readonly pageModuleImportService: ServerModuleImportDependency;
+	private readonly getRootDir: () => string;
+	private readonly getBuildExecutor: () => BuildExecutor | undefined;
+	private readonly getInvalidationVersion: () => number | undefined;
+	private readonly invalidateModules: (changedFiles?: string[]) => void;
+	private readonly getDefaultPlugins: () => EcoBuildPlugin[];
+
+	/**
+	 * Creates one explicit server-transpiler boundary for a given execution
+	 * context.
+	 */
+	constructor(args: ServerModuleTranspilerBootstrapArgs) {
+		this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService();
+		this.getRootDir = () => args.rootDir;
+		this.getBuildExecutor = args.getBuildExecutor;
+		this.getInvalidationVersion = () => args.getInvalidationVersion?.();
+		this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
+		this.invalidateModules = (changedFiles) => {
+			if (args.invalidateModules) {
+				args.invalidateModules(changedFiles);
+				return;
+			}
+
+			this.pageModuleImportService.invalidateDevelopmentGraph();
+		};
+	}
+
+	/**
+	 * Loads a server-side source module through the caller-owned transpile
+	 * context.
+	 */
+	async importModule<T = unknown>(options: ServerModuleTranspilerOptions): Promise<T> {
+		const mergedPlugins = [...this.getDefaultPlugins(), ...(options.plugins ?? [])];
+		const { plugins: _plugins, ...baseOptions } = options;
+		return await this.pageModuleImportService.importModule<T>({
+			...baseOptions,
+			...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
+			rootDir: this.getRootDir(),
+			buildExecutor: this.getBuildExecutor(),
+			invalidationVersion: this.getInvalidationVersion(),
+		});
+	}
+
+	/**
+	 * Invalidates cached module state for development reloads.
+	 */
+	invalidate(changedFiles?: string[]): void {
+		this.invalidateModules(changedFiles);
+	}
+
+	/**
+	 * Releases transpiler-owned resources.
+	 *
+	 * @remarks
+	 * The current implementation delegates cache ownership to lower-level module
+	 * loading services, so disposal is intentionally a no-op for now.
+	 */
+	async dispose(): Promise<void> {
+		return;
+	}
+}

package/src/services/runtime-manifest/node-runtime-manifest.service.test.ts

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import {
+	createNodeRuntimeManifest,
+	getNodeRuntimeManifestPath,
+	getAppNodeRuntimeManifest,
+	setAppNodeRuntimeManifest,
+	writeAppNodeRuntimeManifest,
+} from './node-runtime-manifest.service.ts';
+
+test('createNodeRuntimeManifest summarizes app-owned runtime bootstrap state', () => {
+	const appConfig = {
+		rootDir: '/repo',
+		absolutePaths: {
+			config: '/repo/eco.config.ts',
+			srcDir: '/repo/src',
+			distDir: '/repo/dist',
+			workDir: '/repo/.eco',
+		},
+		loaders: new Map(),
+		runtime: {},
+	} as any;
+
+	const manifest = createNodeRuntimeManifest(appConfig, {
+		entryModulePath: '/repo/app.ts',
+	});
+
+	assert.deepEqual(manifest, {
+		runtime: 'node',
+		appRootDir: '/repo',
+		sourceRootDir: '/repo/src',
+		distDir: '/repo/dist',
+		workDir: '/repo/.eco',
+		modulePaths: {
+			config: '/repo/eco.config.ts',
+			entry: '/repo/app.ts',
+		},
+	});
+});
+
+test('getAppNodeRuntimeManifest falls back to a derived manifest and can be overridden', () => {
+	const appConfig = {
+		rootDir: '/repo',
+		absolutePaths: {
+			config: '/repo/eco.config.ts',
+			srcDir: '/repo/src',
+			distDir: '/repo/dist',
+			workDir: '/repo/.eco',
+		},
+		loaders: new Map(),
+		runtime: {},
+	} as any;
+
+	const derivedManifest = getAppNodeRuntimeManifest(appConfig);
+	assert.equal(derivedManifest.modulePaths.config, '/repo/eco.config.ts');
+	assert.equal(derivedManifest.modulePaths.entry, undefined);
+
+	const overriddenManifest = createNodeRuntimeManifest(appConfig, {
+		entryModulePath: '/repo/custom-entry.ts',
+	});
+	setAppNodeRuntimeManifest(appConfig, overriddenManifest);
+
+	assert.deepEqual(getAppNodeRuntimeManifest(appConfig), overriddenManifest);
+});
+
+test('writeAppNodeRuntimeManifest persists the app-owned manifest to the runtime file boundary', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-runtime-manifest-'));
+	const appConfig = {
+		rootDir,
+		absolutePaths: {
+			config: path.join(rootDir, 'eco.config.ts'),
+			srcDir: path.join(rootDir, 'src'),
+			distDir: path.join(rootDir, 'dist'),
+			workDir: path.join(rootDir, '.eco'),
+		},
+		loaders: new Map(),
+		runtime: {},
+	} as any;
+
+	try {
+		const result = writeAppNodeRuntimeManifest(appConfig, {
+			entryModulePath: path.join(rootDir, 'app.ts'),
+		});
+
+		assert.equal(result.manifestFilePath, getNodeRuntimeManifestPath(appConfig));
+		assert.equal(fs.existsSync(result.manifestFilePath), true);
+		assert.deepEqual(JSON.parse(fs.readFileSync(result.manifestFilePath, 'utf8')), result.manifest);
+		assert.equal(result.manifest.modulePaths.entry, path.join(rootDir, 'app.ts'));
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

package/src/services/runtime-manifest/node-runtime-manifest.service.ts

@@ -0,0 +1,101 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../../constants.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+
+const NODE_RUNTIME_MANIFEST_DIRNAME = 'runtime';
+const NODE_RUNTIME_MANIFEST_FILENAME = 'node-runtime-manifest.json';
+
+export interface NodeRuntimeManifest {
+	runtime: 'node';
+	appRootDir: string;
+	sourceRootDir: string;
+	distDir: string;
+	workDir?: string;
+	modulePaths: {
+		config: string;
+		entry?: string;
+	};
+}
+
+/**
+ * Returns the default file handoff location for the Node runtime manifest.
+ */
+export function getNodeRuntimeManifestPath(appConfig: EcoPagesAppConfig): string {
+	return path.join(resolveWorkDir(appConfig), NODE_RUNTIME_MANIFEST_DIRNAME, NODE_RUNTIME_MANIFEST_FILENAME);
+}
+
+function resolveWorkDir(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): string {
+	return (
+		appConfig.absolutePaths?.workDir ?? path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR)
+	);
+}
+
+export function createNodeRuntimeManifest(
+	appConfig: EcoPagesAppConfig,
+	options?: {
+		entryModulePath?: string;
+	},
+): NodeRuntimeManifest {
+	return {
+		runtime: 'node',
+		appRootDir: appConfig.rootDir,
+		sourceRootDir: appConfig.absolutePaths.srcDir,
+		distDir: appConfig.absolutePaths.distDir,
+		workDir: resolveWorkDir(appConfig),
+		modulePaths: {
+			config: appConfig.absolutePaths.config,
+			...(options?.entryModulePath ? { entry: options.entryModulePath } : {}),
+		},
+	};
+}
+
+/**
+ * Serializes a Node runtime manifest to the file boundary used by the thin host.
+ */
+export function writeNodeRuntimeManifestFile(manifest: NodeRuntimeManifest, manifestFilePath: string): string {
+	mkdirSync(path.dirname(manifestFilePath), { recursive: true });
+	writeFileSync(manifestFilePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+	return manifestFilePath;
+}
+
+/**
+ * Derives the app-owned Node manifest and writes it to the runtime handoff path.
+ */
+export function writeAppNodeRuntimeManifest(
+	appConfig: EcoPagesAppConfig,
+	options?: {
+		entryModulePath?: string;
+		manifestFilePath?: string;
+	},
+): {
+	manifest: NodeRuntimeManifest;
+	manifestFilePath: string;
+} {
+	const manifest = createNodeRuntimeManifest(appConfig, {
+		entryModulePath: options?.entryModulePath,
+	});
+	const manifestFilePath = writeNodeRuntimeManifestFile(
+		manifest,
+		options?.manifestFilePath ?? getNodeRuntimeManifestPath(appConfig),
+	);
+
+	return {
+		manifest,
+		manifestFilePath,
+	};
+}
+
+export function getAppNodeRuntimeManifest(appConfig: EcoPagesAppConfig): NodeRuntimeManifest {
+	return appConfig.runtime?.nodeRuntimeManifest ?? createNodeRuntimeManifest(appConfig);
+}
+
+export function setAppNodeRuntimeManifest(
+	appConfig: EcoPagesAppConfig,
+	nodeRuntimeManifest: NodeRuntimeManifest,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		nodeRuntimeManifest,
+	};
+}