@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

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

@@ -0,0 +1,312 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RESOLVED_ASSETS_DIR } from "../../constants.js";
+import { getAppBuildExecutor } from "../../build/build-adapter.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 { appLogger } from "../../global/app-logger.js";
+import { HmrEntrypointRegistrar } from "../shared/hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  InMemoryEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { getAppRuntimeSpecifierRegistry } from "../../services/runtime-state/runtime-specifier-registry.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+class NodeHmrManager {
+  static entrypointRegistrationTimeoutMs = 4e3;
+  appConfig;
+  bridge;
+  watchers = /* @__PURE__ */ new Map();
+  watchedFiles = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
+  distDir;
+  plugins = [];
+  enabled = true;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  runtimeSpecifierRegistry;
+  serverModuleTranspiler;
+  constructor({ appConfig, bridge }) {
+    this.appConfig = appConfig;
+    this.bridge = bridge;
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs: NodeHmrManager.entrypointRegistrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+    this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new InMemoryEntrypointDependencyGraph();
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.cleanDistDir();
+    this.initializeStrategies();
+  }
+  /**
+   * Ensures the HMR output directory exists.
+   *
+   * This must not remove the directory because multiple app processes
+   * can share the same dist path during e2e runs.
+   */
+  cleanDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  /**
+   * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+   *
+   * @remarks
+   * Higher-priority integration strategies own framework page entrypoints. When
+   * one of them matches, the generic JS strategy must stay out of the way so a
+   * shared dependency invalidation does not overwrite framework-specific output.
+   */
+  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;
+      }
+    });
+  }
+  initializeStrategies() {
+    const jsContext = {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
+    };
+    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  }
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setPlugins(plugins) {
+    this.plugins = [...plugins];
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Registers runtime bare-specifier mappings exposed by integrations.
+   *
+   * @remarks
+   * These mappings are consumed by framework-owned HMR strategies such as the
+   * React integration strategy when they rewrite browser bundles. The registry
+   * stays generic so the same mappings can support broader import-map-style
+   * runtime features later without moving integration semantics into core.
+   */
+  registerSpecifierMap(map) {
+    this.runtimeSpecifierRegistry.register(map);
+  }
+  async buildRuntime() {
+    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!result.success) {
+        this.enabled = false;
+        appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", result.logs);
+      }
+    } catch (error) {
+      this.enabled = false;
+      appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", error);
+    }
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  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 sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+    const strategy = sorted.find((s) => {
+      try {
+        return s.matches(filePath);
+      } catch (err) {
+        appLogger.error(err);
+        return false;
+      }
+    });
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[NodeHmrManager] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast") {
+      if (action.events) {
+        for (const event of action.events) {
+          this.broadcast(event);
+        }
+      }
+    }
+  }
+  getOutputUrl(entrypointPath) {
+    return this.watchedFiles.get(entrypointPath);
+  }
+  getWatchedFiles() {
+    return this.watchedFiles;
+  }
+  getSpecifierMap() {
+    return this.runtimeSpecifierRegistry.getAll();
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getPlugins() {
+    return this.plugins;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  /**
+   * Registers one integration-owned page entrypoint.
+   *
+   * @remarks
+   * Concurrent callers share one in-flight registration. The registration is
+   * removed from the dedupe map once it resolves or fails so later requests do
+   * not inherit stale state.
+   */
+  async registerEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitStrictEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  /**
+   * Registers one generic script entrypoint.
+   *
+   * @remarks
+   * This path is intentionally separate from page entrypoints so non-framework
+   * scripts can still use the generic build fallback without weakening the page
+   * ownership contract.
+   */
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  /**
+   * Performs strict integration-owned entrypoint registration for one normalized source path.
+   *
+   * @remarks
+   * The flow is:
+   * 1. Reserve the output URL in the watched map.
+   * 2. Remove any stale emitted file from an earlier process or failed build.
+   * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+   * 4. Fail if the owning integration did not emit the expected output.
+   */
+  async emitStrictEntrypoint(entrypointPath, _outputPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  /**
+   * Performs registration for a generic script asset.
+   *
+   * @remarks
+   * The manager first gives registered strategies a chance to emit the file so
+   * processor-owned or integration-owned behavior can still participate. Only
+   * when no output exists does it issue the generic build.
+   */
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+    if (!fileSystem.exists(outputPath)) {
+      const buildResult = await this.browserBundleService.bundle({
+        profile: "hmr-entrypoint",
+        entrypoints: [entrypointPath],
+        outdir: this.distDir,
+        naming,
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!buildResult.success) {
+        appLogger.error(
+          `[HMR] Generic script entrypoint build failed for ${entrypointPath}:`,
+          buildResult.logs
+        );
+      }
+    }
+  }
+  /**
+   * Stops active watchers and releases retained registration state.
+   *
+   * @remarks
+   * The manager intentionally does not remove emitted `_hmr` files from disk
+   * because multiple app processes may share the same dist directory during test
+   * runs. It does clear in-memory indexes so old entrypoints, dependencies, and
+   * specifier maps cannot leak across a reused manager instance.
+   */
+  stop() {
+    this.entrypointRegistrations.clear();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.runtimeSpecifierRegistry.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
+  }
+}
+export {
+  NodeHmrManager
+};

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

@@ -0,0 +1,46 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import { type NodeRuntimeManifest } from '../../services/runtime-manifest/node-runtime-manifest.service.js';
+/**
+ * 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>;
+}
+/**
+ * Validates and narrows the persisted Node runtime manifest used by the thin
+ * host handoff.
+ */
+export declare function assertNodeRuntimeManifest(manifest: unknown): NodeRuntimeManifest;
+export declare function createNodeRuntimeAdapter(): NodeRuntimeAdapter;

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

@@ -0,0 +1,306 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createBuildAdapter,
+  getAppBuildExecutor
+} from "../../build/build-adapter.js";
+import { createAppBuildExecutor } from "../../build/dev-build-coordinator.js";
+import { createNodeBootstrapPlugin, getNodeRuntimeNodeModulesDir } from "./bootstrap-dependency-resolver.js";
+import {
+  setAppNodeRuntimeManifest
+} from "../../services/runtime-manifest/node-runtime-manifest.service.js";
+import { DevelopmentInvalidationService } from "../../services/invalidation/development-invalidation.service.js";
+import { getAppEntrypointDependencyGraph } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { createAliasResolverPlugin } from "../../plugins/alias-resolver-plugin.js";
+import {
+  TranspilerServerLoader
+} from "../../services/module-loading/server-loader.service.js";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+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.js", import.meta.url));
+function resolveConfigImportPath(importPath, importer) {
+  if (!importPath) {
+    return void 0;
+  }
+  if (path.isAbsolute(importPath)) {
+    return importPath;
+  }
+  if (!importPath.startsWith(".")) {
+    return void 0;
+  }
+  if (!importer) {
+    return void 0;
+  }
+  return path.resolve(path.dirname(importer), importPath);
+}
+function doesImportReferenceConfig(args, configModulePath) {
+  if (args.path === configModulePath) {
+    return true;
+  }
+  if (args.path === "./eco.config" || args.path === "./eco.config.js") {
+    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;
+}
+function createRuntimeConfigBridgePlugin(configModulePath) {
+  return {
+    name: "node-runtime-config-bridge",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (!doesImportReferenceConfig(args, configModulePath)) {
+          return void 0;
+        }
+        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")
+        };
+      });
+    }
+  };
+}
+function assertNodeRuntimeManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error("Invalid Node runtime manifest: expected an object.");
+  }
+  const candidate = manifest;
+  const modulePaths = candidate.modulePaths;
+  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;
+}
+function getRuntimeOutdir(manifest, kind) {
+  return path.join(
+    resolveInternalExecutionDir({
+      rootDir: manifest.appRootDir,
+      workDir: manifest.workDir,
+      absolutePaths: {
+        workDir: manifest.workDir,
+        distDir: manifest.distDir
+      }
+    }),
+    kind
+  );
+}
+class NodeRuntimeAdapterSession {
+  options;
+  serverLoader;
+  bootstrapBundlePlugin;
+  bootstrapBuildAdapter;
+  bootstrapBuildExecutor;
+  invalidationService = null;
+  appConfig = null;
+  loadedAppRuntime = null;
+  constructor(options) {
+    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
+    });
+  }
+  isDevelopmentMode() {
+    return this.options.cliArgs.includes("--dev") || process.env.NODE_ENV === "development";
+  }
+  get manifest() {
+    return this.options.manifest;
+  }
+  getEntryModulePath() {
+    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;
+  }
+  createAppLoaderContext(appConfig, buildExecutor, invalidationService) {
+    return {
+      rootDir: appConfig.rootDir,
+      getBuildExecutor: () => buildExecutor,
+      getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion(),
+      invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles)
+    };
+  }
+  /**
+   * Installs and returns the app-owned runtime build executor.
+   */
+  installAppBuildExecutor(appConfig) {
+    const appBuildExecutor = installAppRuntimeBuildExecutor(appConfig, {
+      development: this.isDevelopmentMode()
+    });
+    return appBuildExecutor;
+  }
+  /**
+   * Rebinds app-phase server loading to the installed app-owned executor.
+   */
+  bindAppServerLoader(appConfig, buildExecutor) {
+    if (!this.invalidationService) {
+      throw new Error("Node runtime invalidation service is not initialized.");
+    }
+    this.serverLoader.rebindAppContext(
+      this.createAppLoaderContext(appConfig, buildExecutor, this.invalidationService)
+    );
+  }
+  initializeAppRuntime(appConfig) {
+    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.
+   */
+  async loadAppConfig() {
+    if (this.appConfig) {
+      return this.appConfig;
+    }
+    let importedConfigModule;
+    try {
+      importedConfigModule = await this.serverLoader.loadConfig({
+        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() {
+    if (this.loadedAppRuntime) {
+      return this.loadedAppRuntime;
+    }
+    const appConfig = await this.loadAppConfig();
+    const entryModulePath = this.getEntryModulePath();
+    let loadedEntryModule;
+    const runtimeGlobal = globalThis;
+    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) {
+    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() {
+    await this.serverLoader.dispose();
+    if (this.appConfig) {
+      getAppEntrypointDependencyGraph(this.appConfig).reset();
+    }
+    this.invalidationService = null;
+  }
+}
+class DefaultNodeRuntimeAdapter {
+  async start(options) {
+    return new NodeRuntimeAdapterSession(options);
+  }
+}
+function createNodeRuntimeAdapter() {
+  return new DefaultNodeRuntimeAdapter();
+}
+export {
+  assertNodeRuntimeManifest,
+  createNodeRuntimeAdapter
+};