@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/adapters/shared/hmr/shared-hmr-manager.d.ts

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import { type ResolvedHmrEntrypoint } from '../../../hmr/hmr-entrypoint-output.js';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../../types/internal-types.js';
+import { type HmrStrategy } from '../../../hmr/hmr-strategy.js';
+import { DevelopmentInvalidationService } from '../../../services/invalidation/development-invalidation.service.js';
+import type { ClientBridgeEvent, HmrFileChangeOptions } from '../../../types/public-types.js';
+import { DevTransformEntrypointRegistry } from './dev-transform-entrypoint-registry.js';
+import { BrowserBundleService } from '../../../services/assets/browser-bundle.service.js';
+import { type EntrypointDependencyGraph } from '../../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { ServerModuleTranspiler } from '../../../services/module-loading/server-module-transpiler.service.js';
+import { DevTransformServer } from '../../../dev/transform-server/dev-transform-server.js';
+import type { DevTransformBundleContributor } from '../../../dev/transform-server/types.js';
+type HandleFileChangeOptions = HmrFileChangeOptions;
+type SharedHmrManagerParams = {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+};
+export declare abstract class SharedHmrManager implements IHmrManager {
+    readonly appConfig: EcoPagesAppConfig;
+    protected readonly bridge: IClientBridge;
+    protected watchers: Map<string, fs.FSWatcher>;
+    protected runtimeWorkDir: string;
+    protected enabled: boolean;
+    protected strategies: HmrStrategy[];
+    private readonly registeredScriptReloadRequired;
+    protected readonly entrypointRegistry: DevTransformEntrypointRegistry;
+    protected readonly browserBundleService: BrowserBundleService;
+    protected readonly invalidationService: DevelopmentInvalidationService;
+    protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
+    protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+    private runtimeBuildPromise;
+    private runtimeReady;
+    private devToolbarWorkDir;
+    private devToolbarBuildPromise;
+    private devToolbarReady;
+    protected readonly devTransformServer: DevTransformServer;
+    constructor({ appConfig, bridge }: SharedHmrManagerParams);
+    protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
+    protected shouldSkipMissingFileChange(_filePath: string): boolean;
+    protected onRuntimeBundleFailure(error: unknown): void;
+    protected ensureRuntimeWorkDir(): void;
+    protected shouldBuildDevToolbar(): boolean;
+    private getDevToolbarHost;
+    protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean;
+    registerDevTransformContributor(contributor: DevTransformBundleContributor): void;
+    protected initializeStrategies(): void;
+    registerStrategy(strategy: HmrStrategy): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    isRuntimeReady(): boolean;
+    /**
+     * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+     */
+    ensureRuntimeReady(): Promise<boolean>;
+    private ensureHmrRuntimeReady;
+    private ensureDevToolbarRuntimeReady;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    private buildDevToolbarRuntimeInternal;
+    getDevToolbarRuntimePath(): string;
+    private buildRuntimeInternal;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    private broadcastStrategyAction;
+    private invalidateDevTransformDependents;
+    consumeRegisteredScriptReloadRequired(filePath: string): boolean;
+    private getStrategiesByPriority;
+    private selectChangeStrategy;
+    private prepareRegisteredEntrypointChange;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns the registered script output when the entrypoint is already tracked for HMR.
+     *
+     * @remarks
+     * Dev-transform scripts use the source path as `outputPath`. A fresh dev session must
+     * still register the entrypoint so file watchers can invalidate it on change.
+     */
+    getResolvedScriptOutput(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
+    getWatchedFiles(): Map<string, string>;
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    tryHandleDevClientRequest(request: Request): Promise<Response | null>;
+    tryHandleAssetRequest(request: Request): Response | null;
+    getRuntimeWorkDir(): string;
+    getDefaultContext(): DefaultHmrContext;
+    stop(): void;
+    protected clearFailedEntrypointRegistration(entrypointPath: string): void;
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
+    private registerDevTransformEntrypoint;
+    [Symbol.dispose](): void;
+}
+export {};

package/src/adapters/shared/hmr/shared-hmr-manager.js

@@ -0,0 +1,446 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HMR_RUNTIME_SCRIPT_URL, resolveHmrRuntimeWorkDir } from '../../../hmr/hmr-runtime-paths.js';
+import { DEV_TOOLBAR_RUNTIME_SCRIPT_URL, resolveDevToolbarRuntimeWorkDir, } from '../../../dev-toolbar/dev-toolbar-runtime-paths.js';
+import { DevToolbarHost } from '../../../dev-toolbar/dev-toolbar-host.js';
+import { isDevTransformModuleUrl } from '../../../hmr/hmr-asset-paths.js';
+import { removeStaleHmrEntrypointOutput, isRegisteredDevTransformEntrypoint, isRegisteredScriptEntrypoint, } from '../../../hmr/hmr-entrypoint-output.js';
+import { fileSystem } from '@ecopages/file-system';
+import { HmrStrategyType } from '../../../hmr/hmr-strategy.js';
+import { DefaultHmrStrategy } from '../../../hmr/strategies/default-hmr-strategy.js';
+import { JsHmrStrategy } from '../../../hmr/strategies/js-hmr-strategy.js';
+import { ServerRenderedTemplateHmrStrategy } from '../../../hmr/strategies/server-rendered-template-hmr-strategy.js';
+import { DevelopmentInvalidationService } from '../../../services/invalidation/development-invalidation.service.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { DevTransformEntrypointRegistry } from './dev-transform-entrypoint-registry.js';
+import { BrowserBundleService } from '../../../services/assets/browser-bundle.service.js';
+import { getAppServerModuleTranspiler } from '../../../services/module-loading/app-server-module-transpiler.service.js';
+import { getAppEntrypointDependencyGraph, setAppEntrypointDependencyGraph, } from '../../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../../utils/resolve-work-dir.js';
+import { DevTransformServer } from '../../../dev/transform-server/dev-transform-server.js';
+export class SharedHmrManager {
+    appConfig;
+    bridge;
+    watchers = new Map();
+    runtimeWorkDir;
+    enabled = false;
+    strategies = [];
+    registeredScriptReloadRequired = new Set();
+    entrypointRegistry;
+    browserBundleService;
+    invalidationService;
+    entrypointDependencyGraph;
+    serverModuleTranspiler;
+    runtimeBuildPromise = null;
+    runtimeReady = false;
+    devToolbarWorkDir;
+    devToolbarBuildPromise = null;
+    devToolbarReady = false;
+    devTransformServer;
+    constructor({ appConfig, bridge }) {
+        this.appConfig = appConfig;
+        this.bridge = bridge;
+        this.runtimeWorkDir = resolveHmrRuntimeWorkDir(resolveInternalWorkDir(this.appConfig));
+        this.devToolbarWorkDir = resolveDevToolbarRuntimeWorkDir(resolveInternalWorkDir(this.appConfig));
+        this.entrypointRegistry = new DevTransformEntrypointRegistry();
+        this.browserBundleService = new BrowserBundleService(appConfig);
+        this.invalidationService = new DevelopmentInvalidationService(appConfig);
+        this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(getAppEntrypointDependencyGraph(appConfig));
+        setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+        this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+        this.devTransformServer = new DevTransformServer({
+            appConfig: this.appConfig,
+            onModuleDependencies: (modulePath, dependencies) => {
+                this.entrypointDependencyGraph.setEntrypointDependencies(modulePath, dependencies);
+            },
+        });
+        this.ensureRuntimeWorkDir();
+        this.initializeStrategies();
+    }
+    shouldSkipMissingFileChange(_filePath) {
+        return false;
+    }
+    onRuntimeBundleFailure(error) {
+        appLogger.error('[HMR] Failed to build runtime script:', error);
+    }
+    ensureRuntimeWorkDir() {
+        fileSystem.ensureDir(this.runtimeWorkDir);
+        if (this.shouldBuildDevToolbar()) {
+            fileSystem.ensureDir(this.devToolbarWorkDir);
+        }
+    }
+    shouldBuildDevToolbar() {
+        return this.getDevToolbarHost().isEnabled();
+    }
+    getDevToolbarHost() {
+        return DevToolbarHost.forApp(this.appConfig, { watch: this.enabled });
+    }
+    shouldJsStrategyProcessEntrypoint(entrypointPath) {
+        return !this.strategies.some((strategy) => {
+            if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+                return false;
+            }
+            try {
+                return strategy.matches(entrypointPath);
+            }
+            catch (error) {
+                appLogger.error(error);
+                return false;
+            }
+        });
+    }
+    registerDevTransformContributor(contributor) {
+        this.devTransformServer.addContributor(contributor);
+    }
+    initializeStrategies() {
+        const jsContext = {
+            getWatchedFiles: () => this.entrypointRegistry.getWatchedOutputUrls(),
+            getRegisteredEntrypoints: () => this.entrypointRegistry.getRegisteredEntrypoints(),
+            getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+            getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+            getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+            getTemplateExtensions: () => this.appConfig.templatesExt,
+            getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+            shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath),
+            invalidateDevTransformSource: (sourcePath) => this.devTransformServer.invalidateSource(sourcePath),
+            consumeRegisteredScriptReloadRequired: (sourcePath) => this.consumeRegisteredScriptReloadRequired(sourcePath),
+        };
+        this.strategies = [
+            new JsHmrStrategy(jsContext),
+            new ServerRenderedTemplateHmrStrategy(this.invalidationService),
+            new DefaultHmrStrategy(),
+        ];
+    }
+    registerStrategy(strategy) {
+        this.strategies.push(strategy);
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    isRuntimeReady() {
+        return this.runtimeReady && fileSystem.exists(this.getRuntimePath());
+    }
+    /**
+     * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+     */
+    async ensureRuntimeReady() {
+        const [hmrReady, devToolbarReady] = await Promise.all([
+            this.ensureHmrRuntimeReady(),
+            this.ensureDevToolbarRuntimeReady(),
+        ]);
+        return hmrReady && devToolbarReady;
+    }
+    async ensureHmrRuntimeReady() {
+        if (this.runtimeReady) {
+            return true;
+        }
+        if (this.runtimeBuildPromise) {
+            return this.runtimeBuildPromise;
+        }
+        this.runtimeBuildPromise = this.buildRuntimeInternal();
+        try {
+            const ready = await this.runtimeBuildPromise;
+            this.runtimeReady = ready;
+            return ready;
+        }
+        finally {
+            this.runtimeBuildPromise = null;
+        }
+    }
+    async ensureDevToolbarRuntimeReady() {
+        if (!this.shouldBuildDevToolbar()) {
+            return true;
+        }
+        if (this.devToolbarReady) {
+            return true;
+        }
+        if (this.devToolbarBuildPromise) {
+            return this.devToolbarBuildPromise;
+        }
+        this.devToolbarBuildPromise = this.buildDevToolbarRuntimeInternal();
+        try {
+            const ready = await this.devToolbarBuildPromise;
+            this.devToolbarReady = ready;
+            return ready;
+        }
+        finally {
+            this.devToolbarBuildPromise = null;
+        }
+    }
+    async buildRuntime() {
+        await this.ensureRuntimeReady();
+    }
+    getRuntimePath() {
+        return path.join(this.runtimeWorkDir, path.basename(HMR_RUNTIME_SCRIPT_URL));
+    }
+    async buildDevToolbarRuntimeInternal() {
+        return this.getDevToolbarHost().bundleClientRuntime({
+            browserBundleService: this.browserBundleService,
+            workDir: this.devToolbarWorkDir,
+            onFailure: (error) => this.onRuntimeBundleFailure(error),
+        });
+    }
+    getDevToolbarRuntimePath() {
+        return path.join(this.devToolbarWorkDir, path.basename(DEV_TOOLBAR_RUNTIME_SCRIPT_URL));
+    }
+    async buildRuntimeInternal() {
+        const runtimeSource = fileURLToPath(import.meta.resolve('@ecopages/core/hmr/client/hmr-runtime'));
+        const runtimePath = this.getRuntimePath();
+        removeStaleHmrEntrypointOutput(runtimePath, 'HMR');
+        try {
+            const result = await this.browserBundleService.bundle({
+                profile: 'hmr-runtime',
+                entrypoints: [runtimeSource],
+                outdir: this.runtimeWorkDir,
+                naming: path.basename(HMR_RUNTIME_SCRIPT_URL),
+                minify: false,
+            });
+            if (!result.success) {
+                this.onRuntimeBundleFailure(result.logs);
+                return false;
+            }
+            const emittedRuntime = result.outputs.find((output) => path.resolve(output.path) === path.resolve(runtimePath));
+            if (!emittedRuntime || !fileSystem.exists(runtimePath)) {
+                this.onRuntimeBundleFailure(new Error(`[HMR] Runtime bundle missing expected output at ${runtimePath}`));
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            this.onRuntimeBundleFailure(error);
+            return false;
+        }
+    }
+    broadcast(event) {
+        appLogger.debug(`[HMR] Broadcasting ${event.type} event, path=${event.path || 'all'}, subscribers=${this.bridge.subscriberCount}`);
+        this.bridge.broadcast(event);
+    }
+    async handleFileChange(filePath, options = {}) {
+        const resolvedFilePath = path.resolve(filePath);
+        const isRegisteredDevTransformEdit = isRegisteredDevTransformEntrypoint(this.entrypointRegistry.getRegisteredEntrypoints(), resolvedFilePath);
+        if (!isRegisteredDevTransformEdit) {
+            this.invalidateDevTransformDependents(resolvedFilePath);
+        }
+        if (this.shouldSkipMissingFileChange(filePath) && !fileSystem.exists(filePath)) {
+            appLogger.debug(`[${this.constructor.name}] Skipping missing file change: ${filePath}`);
+            this.clearFailedEntrypointRegistration(filePath);
+            return;
+        }
+        if (isRegisteredDevTransformEdit) {
+            await this.prepareRegisteredEntrypointChange(resolvedFilePath);
+            const registered = this.entrypointRegistry.getRegisteredEntrypoints().get(resolvedFilePath);
+            if (registered && isDevTransformModuleUrl(registered.outputUrl)) {
+                this.devTransformServer.invalidateSource(resolvedFilePath);
+            }
+        }
+        const strategy = this.selectChangeStrategy(filePath);
+        if (!strategy) {
+            appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+            this.broadcastStrategyAction(filePath, { type: 'none' }, options, !isRegisteredDevTransformEdit);
+            return;
+        }
+        appLogger.debug(`[${this.constructor.name}] Selected strategy: ${strategy.constructor.name}`);
+        this.broadcastStrategyAction(filePath, await strategy.process(filePath), options, !isRegisteredDevTransformEdit);
+    }
+    broadcastStrategyAction(filePath, action, options, fallbackReload) {
+        const shouldBroadcast = options.broadcast ?? true;
+        if (!shouldBroadcast) {
+            return;
+        }
+        if (action.type === 'broadcast' && action.events) {
+            if (this.bridge.subscriberCount === 0) {
+                appLogger.debug(`[${this.constructor.name}] Deferring HMR client broadcast for ${filePath} until a subscriber connects`);
+                return;
+            }
+            for (const event of action.events) {
+                const graphIdentities = event.graphIdentities ?? options.graphIdentities;
+                this.broadcast(graphIdentities === undefined ? event : { ...event, graphIdentities });
+            }
+            return;
+        }
+        if (fallbackReload && this.bridge.subscriberCount > 0) {
+            this.broadcast({ type: 'reload' });
+        }
+    }
+    invalidateDevTransformDependents(changedFilePath) {
+        const affectedEntrypoints = this.entrypointDependencyGraph.getDependencyEntrypoints(changedFilePath);
+        if (affectedEntrypoints.size > 0) {
+            for (const entrypointPath of affectedEntrypoints) {
+                this.devTransformServer.invalidateSource(entrypointPath);
+            }
+            this.devTransformServer.invalidateSource(changedFilePath);
+            return;
+        }
+        if (!this.entrypointDependencyGraph.supportsSelectiveInvalidation()) {
+            for (const sourcePath of this.entrypointRegistry.getRegisteredEntrypoints().keys()) {
+                this.devTransformServer.invalidateSource(sourcePath);
+            }
+            return;
+        }
+        this.devTransformServer.invalidateSource(changedFilePath);
+    }
+    consumeRegisteredScriptReloadRequired(filePath) {
+        const resolved = path.resolve(filePath);
+        const required = this.registeredScriptReloadRequired.has(resolved);
+        this.registeredScriptReloadRequired.delete(resolved);
+        return required;
+    }
+    getStrategiesByPriority() {
+        return [...this.strategies].sort((left, right) => right.priority - left.priority);
+    }
+    selectChangeStrategy(filePath) {
+        return this.getStrategiesByPriority().find((candidate) => {
+            try {
+                return candidate.matches(filePath);
+            }
+            catch (error) {
+                appLogger.error(error);
+                return false;
+            }
+        });
+    }
+    async prepareRegisteredEntrypointChange(filePath) {
+        const isRegisteredScript = isRegisteredScriptEntrypoint(this.entrypointRegistry.getRegisteredEntrypoints(), filePath);
+        if (!isRegisteredScript) {
+            this.invalidationService.invalidateServerModules([filePath]);
+        }
+        const handlers = this.appConfig.runtime?.registeredScriptEntrypointChangeHandlers ?? [];
+        for (const handler of handlers) {
+            try {
+                const result = await handler(filePath);
+                if (result === true) {
+                    this.registeredScriptReloadRequired.add(path.resolve(filePath));
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error
+                    ? error.message
+                    : `Failed to handle registered script entrypoint change for ${filePath}: ${String(error)}`;
+                this.broadcast({ type: 'error', message });
+                throw error;
+            }
+        }
+        if (isRegisteredScript) {
+            return;
+        }
+        const appModuleLoader = this.appConfig.runtime?.appModuleLoader;
+        if (!appModuleLoader) {
+            return;
+        }
+        await appModuleLoader.importModule({
+            filePath,
+            rootDir: this.appConfig.rootDir,
+            outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules'),
+            externalPackages: true,
+            bypassCache: true,
+        });
+    }
+    getOutputUrl(entrypointPath) {
+        return this.entrypointRegistry.getRegisteredEntrypoints().get(path.resolve(entrypointPath))?.outputUrl;
+    }
+    /**
+     * Returns the registered script output when the entrypoint is already tracked for HMR.
+     *
+     * @remarks
+     * Dev-transform scripts use the source path as `outputPath`. A fresh dev session must
+     * still register the entrypoint so file watchers can invalidate it on change.
+     */
+    getResolvedScriptOutput(entrypointPath) {
+        const normalizedEntrypoint = path.resolve(entrypointPath);
+        const registered = this.entrypointRegistry.getRegisteredEntrypoints().get(normalizedEntrypoint);
+        if (!registered || !fileSystem.exists(registered.outputPath)) {
+            return undefined;
+        }
+        return registered;
+    }
+    getWatchedFiles() {
+        return this.entrypointRegistry.getWatchedOutputUrls();
+    }
+    getRegisteredEntrypoints() {
+        return this.entrypointRegistry.getRegisteredEntrypoints();
+    }
+    async tryHandleDevClientRequest(request) {
+        return this.devTransformServer.tryHandleRequest(request);
+    }
+    tryHandleAssetRequest(request) {
+        const url = new URL(request.url);
+        if (url.pathname === HMR_RUNTIME_SCRIPT_URL) {
+            const runtimePath = this.getRuntimePath();
+            if (fileSystem.exists(runtimePath)) {
+                return new Response(fileSystem.readFileAsBuffer(runtimePath), {
+                    headers: {
+                        'Content-Type': 'application/javascript',
+                        'Cache-Control': 'no-store, must-revalidate',
+                    },
+                });
+            }
+        }
+        if (url.pathname === DEV_TOOLBAR_RUNTIME_SCRIPT_URL && this.shouldBuildDevToolbar()) {
+            const runtimeResponse = this.getDevToolbarHost().readBundledRuntime(this.devToolbarWorkDir);
+            if (runtimeResponse) {
+                return runtimeResponse;
+            }
+        }
+        return null;
+    }
+    getRuntimeWorkDir() {
+        return this.runtimeWorkDir;
+    }
+    getDefaultContext() {
+        return {
+            getWatchedFiles: () => this.entrypointRegistry.getWatchedOutputUrls(),
+            getRegisteredEntrypoints: () => this.entrypointRegistry.getRegisteredEntrypoints(),
+            getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+            getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+            getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+            getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+            importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+                filePath,
+                outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules'),
+                externalPackages: true,
+            }),
+        };
+    }
+    stop() {
+        this.runtimeReady = false;
+        this.entrypointRegistry.clearAll();
+        this.devTransformServer.reset();
+        for (const watcher of this.watchers.values()) {
+            watcher.close();
+        }
+        this.watchers.clear();
+        this.entrypointDependencyGraph.reset();
+    }
+    clearFailedEntrypointRegistration(entrypointPath) {
+        this.entrypointRegistry.clearRegistration(entrypointPath);
+        this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+    }
+    async registerEntrypoint(entrypointPath) {
+        return this.registerDevTransformEntrypoint(entrypointPath, 'page').outputUrl;
+    }
+    async registerScriptEntrypoint(entrypointPath) {
+        const { normalized, outputUrl, role } = this.registerDevTransformEntrypoint(entrypointPath, 'script');
+        return {
+            sourcePath: normalized,
+            outputPath: normalized,
+            outputUrl,
+            role,
+        };
+    }
+    registerDevTransformEntrypoint(entrypointPath, role) {
+        const normalized = path.resolve(entrypointPath);
+        if (!fileSystem.exists(normalized)) {
+            throw new Error(`[HMR] Failed to register ${role} entrypoint: missing source ${normalized}`);
+        }
+        const outputUrl = this.devTransformServer.registerModule(entrypointPath);
+        this.entrypointRegistry.registerTransformModule(entrypointPath, outputUrl, { role });
+        return { normalized, outputUrl, role };
+    }
+    [Symbol.dispose]() {
+        this.stop();
+    }
+}

package/src/adapters/shared/http/api-request-pipeline.d.ts

@@ -0,0 +1,23 @@
+import type { SchemaValidationService } from '../../../services/validation/schema-validation-service.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext } from '../../../types/public-types.js';
+export type ApiRequestPipelineOptions = {
+    schemaValidator: SchemaValidationService;
+    getRenderContext: () => RenderContext;
+    getCacheService: () => CacheInvalidator | null;
+};
+export declare class ApiRequestPipeline<TRequest extends Request = Request, TServer = unknown> {
+    private readonly schemaValidator;
+    private readonly getRenderContext;
+    private readonly getCacheService;
+    constructor(options: ApiRequestPipelineOptions);
+    match(request: TRequest, apiHandlers: ApiHandler<string, TRequest, TServer>[]): {
+        routeConfig: ApiHandler<string, TRequest, TServer>;
+        params: Record<string, string | string[]>;
+    } | null;
+    tryHandle(request: TRequest, apiHandlers: ApiHandler<string, TRequest, TServer>[], serverInstance: TServer | undefined, errorHandler?: ErrorHandler<TRequest, TServer>): Promise<Response | null>;
+    execute(request: TRequest, params: Record<string, string | string[]>, routeConfig: ApiHandler<string, TRequest, TServer>, serverInstance: TServer | undefined, errorHandler?: ErrorHandler<TRequest, TServer>): Promise<Response>;
+    private createContext;
+    private normalizeParams;
+    private applyRequestSchema;
+    private runMiddlewareChain;
+}