@ecopages/core 0.2.0-alpha.8 → 0.2.1

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

@@ -1,101 +0,0 @@
-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,
-	};
-}

package/src/services/runtime-state/dev-graph.service.ts

@@ -1,217 +0,0 @@
-import type { EcoPagesAppConfig } from '../../internal-types.ts';
-import {
-	CounterServerInvalidationState,
-	getAppServerInvalidationState,
-	setAppServerInvalidationState,
-	type ServerInvalidationState,
-} from './server-invalidation-state.service.ts';
-import {
-	getAppEntrypointDependencyGraph,
-	InMemoryEntrypointDependencyGraph,
-	NoopEntrypointDependencyGraph,
-	setAppEntrypointDependencyGraph,
-	type EntrypointDependencyGraph,
-} from './entrypoint-dependency-graph.service.ts';
-
-/**
- * Tracks development-time dependency relationships and invalidation state for
- * one Ecopages app instance.
- *
- * @remarks
- * The current contract stays intentionally small. It supports today's needs for
- * server-module cache invalidation and entrypoint-to-dependency lookups without
- * forcing the rest of the runtime to know about one specific graph
- * implementation.
- */
-export interface DevGraphService extends ServerInvalidationState, EntrypointDependencyGraph {}
-
-/**
- * Minimal dev-graph implementation used when an app has no selective graph
- * metadata available.
- *
- * @remarks
- * This preserves correct behavior by using coarse invalidation version bumps.
- * Callers still pass changed-file information through the interface now so a
- * richer graph can become more selective later without changing call sites.
- */
-export class NoopDevGraphService implements DevGraphService {
-	private readonly invalidationState = new CounterServerInvalidationState();
-	private readonly dependencyGraph = new NoopEntrypointDependencyGraph();
-
-	/**
-	 * Returns the current coarse invalidation version.
-	 */
-	getServerInvalidationVersion(): number {
-		return this.invalidationState.getServerInvalidationVersion();
-	}
-
-	/**
-	 * Invalidates all server-side module state by incrementing the shared version.
-	 */
-	invalidateServerModules(_changedFiles?: string[]): void {
-		this.invalidationState.invalidateServerModules(_changedFiles);
-	}
-
-	/**
-	 * Indicates that this graph cannot target invalidation to one entrypoint set.
-	 */
-	supportsSelectiveInvalidation(): boolean {
-		return this.dependencyGraph.supportsSelectiveInvalidation();
-	}
-
-	/**
-	 * Returns an empty entrypoint set because this implementation stores no
-	 * dependency graph metadata.
-	 */
-	getDependencyEntrypoints(_filePath: string): Set<string> {
-		return this.dependencyGraph.getDependencyEntrypoints(_filePath);
-	}
-
-	/**
-	 * Accepts dependency updates to preserve interface compatibility, but stores no
-	 * graph state in the noop implementation.
-	 */
-	setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void {
-		this.dependencyGraph.setEntrypointDependencies(_entrypointPath, _dependencies);
-	}
-
-	/**
-	 * Clears one entrypoint from the graph.
-	 *
-	 * @remarks
-	 * There is no stored graph state in this implementation, so this is a no-op.
-	 */
-	clearEntrypointDependencies(_entrypointPath: string): void {
-		this.dependencyGraph.clearEntrypointDependencies(_entrypointPath);
-	}
-
-	/**
-	 * Resets graph-owned state for a fresh runtime cycle.
-	 */
-	reset(): void {
-		this.invalidationState.reset();
-		this.dependencyGraph.reset();
-	}
-}
-
-/**
- * In-memory development graph with entrypoint-to-dependency reverse lookups.
- *
- * @remarks
- * This is the current selective graph implementation used by development flows
- * that need to answer which entrypoints depend on a changed file while still
- * keeping invalidation state app-local.
- */
-export class InMemoryDevGraphService implements DevGraphService {
-	private readonly invalidationState = new CounterServerInvalidationState();
-	private readonly dependencyGraph = new InMemoryEntrypointDependencyGraph();
-
-	/**
-	 * Returns the current app-local server invalidation version.
-	 */
-	getServerInvalidationVersion(): number {
-		return this.invalidationState.getServerInvalidationVersion();
-	}
-
-	/**
-	 * Invalidates the current server-module cache generation.
-	 *
-	 * @remarks
-	 * The current implementation still uses a coarse generation bump for server
-	 * modules. Selective dependency lookups are used by callers that need to limit
-	 * browser rebuild work.
-	 */
-	invalidateServerModules(_changedFiles?: string[]): void {
-		this.invalidationState.invalidateServerModules(_changedFiles);
-	}
-
-	/**
-	 * Indicates that this graph can answer dependency-to-entrypoint lookups.
-	 */
-	supportsSelectiveInvalidation(): boolean {
-		return this.dependencyGraph.supportsSelectiveInvalidation();
-	}
-
-	/**
-	 * Returns all known entrypoints that currently depend on the given file.
-	 */
-	getDependencyEntrypoints(filePath: string): Set<string> {
-		return this.dependencyGraph.getDependencyEntrypoints(filePath);
-	}
-
-	/**
-	 * Replaces the stored dependency set for one entrypoint.
-	 *
-	 * @remarks
-	 * The entrypoint itself is always included in its own dependency set so reverse
-	 * lookups can map a changed entry file back to that same entrypoint.
-	 */
-	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void {
-		this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
-	}
-
-	/**
-	 * Removes one entrypoint and all of its reverse dependency edges.
-	 */
-	clearEntrypointDependencies(entrypointPath: string): void {
-		this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
-	}
-
-	/**
-	 * Clears all graph state and starts a fresh invalidation generation.
-	 */
-	reset(): void {
-		this.invalidationState.reset();
-		this.dependencyGraph.reset();
-	}
-}
-
-/**
- * Returns the dev-graph service owned by one app instance.
- */
-export function getAppDevGraphService(appConfig: EcoPagesAppConfig): DevGraphService {
-	if (appConfig.runtime?.devGraphService) {
-		return appConfig.runtime.devGraphService;
-	}
-
-	const serverInvalidationState = getAppServerInvalidationState(appConfig);
-	const entrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
-
-	return {
-		getServerInvalidationVersion: () => serverInvalidationState.getServerInvalidationVersion(),
-		invalidateServerModules: (changedFiles) => serverInvalidationState.invalidateServerModules(changedFiles),
-		supportsSelectiveInvalidation: () => entrypointDependencyGraph.supportsSelectiveInvalidation(),
-		getDependencyEntrypoints: (filePath) => entrypointDependencyGraph.getDependencyEntrypoints(filePath),
-		setEntrypointDependencies: (entrypointPath, dependencies) =>
-			entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, dependencies),
-		clearEntrypointDependencies: (entrypointPath) =>
-			entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath),
-		reset: () => {
-			serverInvalidationState.reset();
-			entrypointDependencyGraph.reset();
-		},
-	};
-}
-
-/**
- * Installs the dev-graph service that should back one app/runtime instance.
- */
-export function setAppDevGraphService(appConfig: EcoPagesAppConfig, devGraphService: DevGraphService): void {
-	setAppServerInvalidationState(appConfig, {
-		getServerInvalidationVersion: () => devGraphService.getServerInvalidationVersion(),
-		invalidateServerModules: (changedFiles) => devGraphService.invalidateServerModules(changedFiles),
-		reset: () => devGraphService.reset(),
-	});
-	setAppEntrypointDependencyGraph(appConfig, {
-		supportsSelectiveInvalidation: () => devGraphService.supportsSelectiveInvalidation(),
-		getDependencyEntrypoints: (filePath) => devGraphService.getDependencyEntrypoints(filePath),
-		setEntrypointDependencies: (entrypointPath, dependencies) =>
-			devGraphService.setEntrypointDependencies(entrypointPath, dependencies),
-		clearEntrypointDependencies: (entrypointPath) => devGraphService.clearEntrypointDependencies(entrypointPath),
-		reset: () => devGraphService.reset(),
-	});
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		devGraphService,
-	};
-}

package/src/services/runtime-state/entrypoint-dependency-graph.service.ts

@@ -1,136 +0,0 @@
-import path from 'node:path';
-import type { EcoPagesAppConfig } from '../../internal-types.ts';
-import type { DevGraphService } from './dev-graph.service.ts';
-
-/**
- * App-owned dependency graph used to target browser entrypoint rebuilds.
- */
-export interface EntrypointDependencyGraph {
-	supportsSelectiveInvalidation(): boolean;
-	getDependencyEntrypoints(filePath: string): Set<string>;
-	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
-	clearEntrypointDependencies(entrypointPath: string): void;
-	reset(): void;
-}
-
-/**
- * Graph implementation for runtimes that rebuild every watched entrypoint.
- */
-export class NoopEntrypointDependencyGraph implements EntrypointDependencyGraph {
-	supportsSelectiveInvalidation(): boolean {
-		return false;
-	}
-
-	getDependencyEntrypoints(_filePath: string): Set<string> {
-		return new Set();
-	}
-
-	setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void {}
-
-	clearEntrypointDependencies(_entrypointPath: string): void {}
-
-	reset(): void {}
-}
-
-/**
- * In-memory entrypoint-to-dependency graph with reverse dependency lookups.
- */
-export class InMemoryEntrypointDependencyGraph implements EntrypointDependencyGraph {
-	private readonly dependencyEntrypoints = new Map<string, Set<string>>();
-	private readonly entrypointDependencies = new Map<string, Set<string>>();
-
-	supportsSelectiveInvalidation(): boolean {
-		return true;
-	}
-
-	getDependencyEntrypoints(filePath: string): Set<string> {
-		return new Set(this.dependencyEntrypoints.get(path.resolve(filePath)) ?? []);
-	}
-
-	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void {
-		const normalizedEntrypoint = path.resolve(entrypointPath);
-
-		this.clearEntrypointDependencies(normalizedEntrypoint);
-
-		const normalizedDependencies = new Set<string>([
-			normalizedEntrypoint,
-			...dependencies.map((dependencyPath) => path.resolve(dependencyPath)),
-		]);
-
-		this.entrypointDependencies.set(normalizedEntrypoint, normalizedDependencies);
-
-		for (const dependencyPath of normalizedDependencies) {
-			const entrypoints = this.dependencyEntrypoints.get(dependencyPath) ?? new Set<string>();
-			entrypoints.add(normalizedEntrypoint);
-			this.dependencyEntrypoints.set(dependencyPath, entrypoints);
-		}
-	}
-
-	clearEntrypointDependencies(entrypointPath: string): void {
-		const normalizedEntrypoint = path.resolve(entrypointPath);
-		const previousDependencies = this.entrypointDependencies.get(normalizedEntrypoint);
-
-		if (!previousDependencies) {
-			return;
-		}
-
-		for (const dependencyPath of previousDependencies) {
-			const entrypoints = this.dependencyEntrypoints.get(dependencyPath);
-			if (!entrypoints) {
-				continue;
-			}
-
-			entrypoints.delete(normalizedEntrypoint);
-			if (entrypoints.size === 0) {
-				this.dependencyEntrypoints.delete(dependencyPath);
-			}
-		}
-
-		this.entrypointDependencies.delete(normalizedEntrypoint);
-	}
-
-	reset(): void {
-		this.dependencyEntrypoints.clear();
-		this.entrypointDependencies.clear();
-	}
-}
-
-function isLegacyEntrypointDependencyGraph(value: unknown): value is DevGraphService {
-	return (
-		Boolean(value) &&
-		typeof value === 'object' &&
-		typeof (value as EntrypointDependencyGraph).supportsSelectiveInvalidation === 'function' &&
-		typeof (value as EntrypointDependencyGraph).getDependencyEntrypoints === 'function' &&
-		typeof (value as EntrypointDependencyGraph).setEntrypointDependencies === 'function' &&
-		typeof (value as EntrypointDependencyGraph).clearEntrypointDependencies === 'function' &&
-		typeof (value as EntrypointDependencyGraph).reset === 'function'
-	);
-}
-
-/**
- * Returns the app-owned entrypoint dependency graph.
- */
-export function getAppEntrypointDependencyGraph(appConfig: EcoPagesAppConfig): EntrypointDependencyGraph {
-	if (appConfig.runtime?.entrypointDependencyGraph) {
-		return appConfig.runtime.entrypointDependencyGraph;
-	}
-
-	if (isLegacyEntrypointDependencyGraph(appConfig.runtime?.devGraphService)) {
-		return appConfig.runtime.devGraphService;
-	}
-
-	return new NoopEntrypointDependencyGraph();
-}
-
-/**
- * Installs the dependency graph used by one app instance.
- */
-export function setAppEntrypointDependencyGraph(
-	appConfig: EcoPagesAppConfig,
-	entrypointDependencyGraph: EntrypointDependencyGraph,
-): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		entrypointDependencyGraph,
-	};
-}

package/src/services/runtime-state/runtime-specifier-registry.service.ts

@@ -1,96 +0,0 @@
-import type { EcoPagesAppConfig } from '../../internal-types.ts';
-
-/**
- * Stores runtime-visible bare-specifier mappings for one app instance.
- *
- * @remarks
- * Integrations populate this registry during runtime setup when they expose
- * browser runtime modules through stable bare imports. Build and HMR code later
- * consume the collected map to create aliasing and bootstrap behavior without
- * forcing integrations to own global registry state.
- */
-export interface RuntimeSpecifierRegistry {
-	/**
-	 * Merges a new batch of specifier mappings into the registry.
-	 *
-	 * @remarks
-	 * Later registrations replace earlier URLs for the same specifier. This keeps
-	 * runtime setup deterministic while still allowing an integration to refresh
-	 * its own declarations during one app session.
-	 */
-	register(map: Record<string, string>): void;
-
-	/**
-	 * Returns the current registry contents.
-	 *
-	 * @remarks
-	 * The returned map is the live backing map for the registry implementation, so
-	 * callers should treat it as read-only unless they intentionally own registry
-	 * mutation semantics.
-	 */
-	getAll(): Map<string, string>;
-
-	/**
-	 * Removes all registered specifiers for the current app/runtime instance.
-	 */
-	clear(): void;
-}
-
-/**
- * Default in-memory runtime specifier registry used by core.
- *
- * @remarks
- * Runtime specifier maps are app-local bootstrap metadata, not durable build
- * artifacts, so the default implementation stays intentionally small.
- */
-export class InMemoryRuntimeSpecifierRegistry implements RuntimeSpecifierRegistry {
-	private readonly specifierMap = new Map<string, string>();
-
-	/**
-	 * Merges one integration-provided mapping set into the app registry.
-	 */
-	register(map: Record<string, string>): void {
-		for (const [specifier, url] of Object.entries(map)) {
-			this.specifierMap.set(specifier, url);
-		}
-	}
-
-	/**
-	 * Returns the live app-owned mapping table.
-	 */
-	getAll(): Map<string, string> {
-		return this.specifierMap;
-	}
-
-	/**
-	 * Clears all mappings for the current runtime session.
-	 */
-	clear(): void {
-		this.specifierMap.clear();
-	}
-}
-
-/**
- * Returns the runtime specifier registry owned by one app instance.
- *
- * @remarks
- * Older tests and helpers may not seed runtime state explicitly yet, so this
- * helper still provides an in-memory fallback when the app runtime has not been
- * initialized.
- */
-export function getAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig): RuntimeSpecifierRegistry {
-	return appConfig.runtime?.runtimeSpecifierRegistry ?? new InMemoryRuntimeSpecifierRegistry();
-}
-
-/**
- * Installs the runtime specifier registry that should back one app instance.
- */
-export function setAppRuntimeSpecifierRegistry(
-	appConfig: EcoPagesAppConfig,
-	runtimeSpecifierRegistry: RuntimeSpecifierRegistry,
-): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		runtimeSpecifierRegistry,
-	};
-}

package/src/services/runtime-state/server-invalidation-state.service.ts

@@ -1,68 +0,0 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { DevGraphService } from './dev-graph.service.ts';
-
-/**
- * App-owned coarse invalidation state for server-executed modules.
- */
-export interface ServerInvalidationState {
-	getServerInvalidationVersion(): number;
-	invalidateServerModules(changedFiles?: string[]): void;
-	reset(): void;
-}
-
-/**
- * Minimal app-local invalidation state backed by a single generation counter.
- */
-export class CounterServerInvalidationState implements ServerInvalidationState {
-	private serverInvalidationVersion = 0;
-
-	getServerInvalidationVersion(): number {
-		return this.serverInvalidationVersion;
-	}
-
-	invalidateServerModules(_changedFiles?: string[]): void {
-		this.serverInvalidationVersion += 1;
-	}
-
-	reset(): void {
-		this.serverInvalidationVersion += 1;
-	}
-}
-
-function isLegacyServerInvalidationState(value: unknown): value is DevGraphService {
-	return (
-		Boolean(value) &&
-		typeof value === 'object' &&
-		typeof (value as ServerInvalidationState).getServerInvalidationVersion === 'function' &&
-		typeof (value as ServerInvalidationState).invalidateServerModules === 'function' &&
-		typeof (value as ServerInvalidationState).reset === 'function'
-	);
-}
-
-/**
- * Returns the app-owned server invalidation state.
- */
-export function getAppServerInvalidationState(appConfig: EcoPagesAppConfig): ServerInvalidationState {
-	if (appConfig.runtime?.serverInvalidationState) {
-		return appConfig.runtime.serverInvalidationState;
-	}
-
-	if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
-		return appConfig.runtime.devGraphService;
-	}
-
-	return new CounterServerInvalidationState();
-}
-
-/**
- * Installs the invalidation state used by one app instance.
- */
-export function setAppServerInvalidationState(
-	appConfig: EcoPagesAppConfig,
-	serverInvalidationState: ServerInvalidationState,
-): void {
-	appConfig.runtime = {
-		...(appConfig.runtime ?? {}),
-		serverInvalidationState,
-	};
-}