@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/adapters/README.md

@@ -0,0 +1,39 @@
+# Runtime Adapters
+
+This directory contains the runtime-host integration layer for Ecopages.
+
+## Purpose
+
+Adapters translate app-owned core services into concrete runtime behavior at the host boundary. Bun remains the direct core runtime, while Node compatibility is driven by the Ecopages CLI thin-host path and reuses internal adapter pieces here.
+
+They are responsible for:
+
+- starting and stopping runtime-specific servers or thin hosts
+- delegating startup into framework-owned loaders and services
+- bridging runtime-specific request/response or HMR transport details
+- keeping host/runtime transport details out of generic core orchestration
+
+They are not responsible for:
+
+- deciding plugin lifecycle ordering
+- owning server-module semantics
+- owning browser bundling policy
+- owning route rendering semantics
+
+## Main Areas
+
+- `bun/`: Bun server adapter, lifecycle coordination, bridge, and HMR transport
+- `node/`: internal Node compatibility adapter pieces used by the CLI thin-host path
+- `shared/`: runtime-neutral adapter helpers used by both hosts
+
+## Ownership Boundary
+
+The adapter layer is transport-oriented.
+
+Core services still own:
+
+- config finalization
+- build-manifest assembly
+- server loading
+- invalidation classification
+- route rendering orchestration

package/src/adapters/abstract/application-adapter.d.ts

@@ -6,15 +6,40 @@
  *
  * @module ApplicationAdapter
  */
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../public-types.js';
+import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
+/**
+ * Runtime bootstrap options layered on top of the app config.
+ *
+ * These options let a host runtime embed Ecopages without mutating process
+ * globals or app runtime state before calling `createApp()`.
+ */
+export interface ApplicationRuntimeOptions {
+    /**
+     * Forces the app into the embedded-runtime CLI mode used by host
+     * environments.
+     *
+     * When enabled and no explicit `hostModuleLoader` is provided, the
+     * adapter auto-detects a host module loader from the global scope.
+     */
+    embedded?: boolean;
+    /**
+     * Explicit source module loader for request-time imports.
+     *
+     * When omitted in embedded mode, the adapter attempts automatic
+     * detection from globals set by the host environment.
+     */
+    hostModuleLoader?: SourceModuleLoader;
+}
 /**
  * Configuration options for application adapters
  */
 export interface ApplicationAdapterOptions {
     appConfig: EcoPagesAppConfig;
     serverOptions?: Record<string, any>;
+    runtime?: ApplicationRuntimeOptions;
     /**
      * Options for clearing the output directory before starting the server
      * @default false
@@ -43,6 +68,7 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected appConfig: EcoPagesAppConfig;
     protected serverOptions: Record<string, any>;
     protected cliArgs: ReturnParseCliArgs;
+    protected runtimeOptions: ApplicationRuntimeOptions;
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;

package/src/adapters/abstract/application-adapter.js

@@ -1,4 +1,9 @@
 import { appLogger } from "../../global/app-logger.js";
+import {
+  getAppModuleLoader,
+  setAppHostModuleLoader
+} from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
 import { invariant } from "../../utils/invariant.js";
 import { fileSystem } from "@ecopages/file-system";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
@@ -6,20 +11,27 @@ class AbstractApplicationAdapter {
   appConfig;
   serverOptions;
   cliArgs;
+  runtimeOptions;
   apiHandlers = [];
   staticRoutes = [];
   errorHandler;
   constructor(options) {
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
-    this.cliArgs = parseCliArgs();
+    this.runtimeOptions = options.runtime ?? {};
+    this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
+    const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : void 0);
+    if (hostModuleLoader) {
+      setAppHostModuleLoader(this.appConfig, hostModuleLoader);
+    }
+    getAppModuleLoader(this.appConfig);
     if (options.clearOutput) {
       this.clearDistFolder().catch((error) => {
         appLogger.error("Error clearing dist folder", error);
       });
     }
   }
-  async clearDistFolder(_filter = []) {
+  async clearDistFolder() {
     const distPath = this.appConfig.absolutePaths.distDir;
     const distExists = fileSystem.exists(distPath);
     if (!distExists) return;

package/src/adapters/abstract/router-adapter.d.ts

@@ -6,7 +6,7 @@
  *
  * @module RouterAdapter
  */
-import type { Routes } from '../../internal-types.js';
+import type { Routes } from '../../types/internal-types.js';
 /**
  * Abstract base class for router adapters across different runtimes
  */

package/src/adapters/abstract/server-adapter.d.ts

@@ -6,8 +6,8 @@
  *
  * @module ServerAdapter
  */
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler } from '../../public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler } from '../../types/public-types.js';
 /**
  * Configuration options for all server adapters
  */

package/src/adapters/bun/client-bridge.d.ts

@@ -1,5 +1,5 @@
 import type { ServerWebSocket } from 'bun';
-import type { ClientBridgeEvent, IClientBridge } from '../../public-types';
+import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.js';
 type BunSocket = ServerWebSocket<unknown>;
 /**
  * Manages WebSocket subscribers and broadcasts development events.

package/src/adapters/bun/create-app.d.ts

@@ -8,18 +8,12 @@
  * @module EcopagesApp
  */
 import type { Server } from 'bun';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandlerContext, RouteGroupBuilder } from '../../public-types.js';
-import { type ApplicationAdapterOptions } from '../abstract/application-adapter.js';
+import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.js';
 import { SharedApplicationAdapter } from '../shared/application-adapter.js';
+import type { RuntimeHost } from '../shared/runtime-host.js';
+import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { EcopagesAppOptions } from '../create-app.js';
 import { type BunServerAdapterResult } from './server-adapter.js';
-/**
- * Configuration options for the Bun application adapter
- */
-export interface EcopagesAppOptions extends ApplicationAdapterOptions {
-    appConfig: EcoPagesAppConfig;
-    serverOptions?: Record<string, any>;
-}
 /**
  * Bun-specific route group builder that properly infers route params from path patterns.
  * When you define a route like `/posts/:slug`, the handler context will have
@@ -34,9 +28,15 @@ export type BunRouteGroupBuilder<WebSocketData = undefined, TContext extends Api
  * This class extends the {@link AbstractApplicationAdapter}
  * and provides methods for handling HTTP requests and managing the server.
  */
-export declare class EcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
+export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
     serverAdapter: BunServerAdapterResult | undefined;
     private server;
+    private readonly runtimeHost;
+    private readonly previewHost;
+    constructor(options: EcopagesAppOptions, dependencies: {
+        runtimeHost: RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>>;
+        previewHost: StaticPreviewHost;
+    });
     fetch(request: Request): Promise<Response>;
     /**
      * Complete the initialization of the server adapter by processing dynamic routes
@@ -57,4 +57,4 @@ export declare class EcopagesApp<WebSocketData = undefined> extends SharedApplic
 /**
  * Factory function to create a Bun application
  */
-export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<EcopagesApp<WebSocketData>>;
+export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<BunEcopagesApp<WebSocketData>>;

package/src/adapters/bun/create-app.js

@@ -1,12 +1,20 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
-import { getBunRuntime } from "../../utils/runtime.js";
-import {} from "../abstract/application-adapter.js";
 import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime-app-bootstrap.js";
 import { createBunServerAdapter } from "./server-adapter.js";
-class EcopagesApp extends SharedApplicationAdapter {
+import { BunStaticPreviewHost } from "./static-preview-host.js";
+import { BunRuntimeHost } from "./runtime-host.js";
+class BunEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
+  runtimeHost;
+  previewHost;
+  constructor(options, dependencies) {
+    super(options);
+    this.runtimeHost = dependencies.runtimeHost;
+    this.previewHost = dependencies.previewHost;
+  }
   async fetch(request) {
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
@@ -28,34 +36,28 @@ class EcopagesApp extends SharedApplicationAdapter {
    * Initialize the Bun server adapter
    */
   async initializeServerAdapter() {
-    const { dev } = this.cliArgs;
-    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
-    const envPort = process.env.ECOPAGES_PORT ? process.env.ECOPAGES_PORT : void 0;
-    const envHostname = process.env.ECOPAGES_HOSTNAME;
-    const preferredPort = cliPort ?? envPort ?? DEFAULT_ECOPAGES_PORT;
-    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    const binding = resolveRuntimeBinding({
+      cliArgs: this.cliArgs,
+      serverOptions: this.serverOptions
+    });
     appLogger.debug("initializeServerAdapter", {
-      dev,
-      cliPort,
-      cliHostname,
-      envPort,
-      envHostname,
-      preferredPort,
-      preferredHostname,
-      composedUrl: `http://${preferredHostname}:${preferredPort}`
+      dev: this.cliArgs.dev,
+      cliPort: this.cliArgs.port,
+      cliHostname: this.cliArgs.hostname,
+      envPort: process.env.ECOPAGES_PORT,
+      envHostname: process.env.ECOPAGES_HOSTNAME,
+      preferredPort: binding.preferredPort,
+      preferredHostname: binding.preferredHostname,
+      composedUrl: binding.runtimeOrigin
     });
     return await createBunServerAdapter({
-      runtimeOrigin: `http://${preferredHostname}:${preferredPort}`,
+      runtimeOrigin: binding.runtimeOrigin,
       appConfig: this.appConfig,
       apiHandlers: this.apiHandlers,
       staticRoutes: this.staticRoutes,
       errorHandler: this.errorHandler,
-      options: { watch: dev },
-      serveOptions: {
-        port: preferredPort,
-        hostname: preferredHostname,
-        ...this.serverOptions
-      }
+      options: { watch: binding.watch },
+      serveOptions: binding.serveOptions
     });
   }
   /**
@@ -68,11 +70,11 @@ class EcopagesApp extends SharedApplicationAdapter {
       this.serverAdapter = await this.initializeServerAdapter();
     }
     const { dev, preview, build } = this.cliArgs;
-    const requiresFetchRuntime = this.appConfig.integrations.some(
-      (integration) => integration.staticBuildStep === "fetch"
-    );
-    const canBuildWithoutRuntimeServer = (build || preview) && !requiresFetchRuntime;
-    if (canBuildWithoutRuntimeServer) {
+    const staticRuntimeMode = resolveStaticRuntimeMode({
+      appConfig: this.appConfig,
+      cliArgs: this.cliArgs
+    });
+    if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
       appLogger.debugTime("Building static pages");
       await this.serverAdapter.buildStatic({ preview });
       appLogger.debugTimeEnd("Building static pages");
@@ -83,23 +85,41 @@ class EcopagesApp extends SharedApplicationAdapter {
     }
     const enableHmr = dev || !preview && !build;
     const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
-    const bun = getBunRuntime();
-    if (!bun) {
-      throw new Error("Bun runtime is required for the Bun adapter");
-    }
-    const bunServer = bun.serve(serverOptions);
-    this.server = bunServer;
+    const configuredHostname = String(serverOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+    const configuredPort = Number(serverOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    const runtimeServerOptions = (preview || build) && staticRuntimeMode.requiresFetchRuntime ? {
+      ...serverOptions,
+      port: 0
+    } : serverOptions;
+    this.server = await this.runtimeHost.start({
+      serveOptions: runtimeServerOptions,
+      handleRequest: async () => new Response(null, { status: 500 }),
+      onError: async () => {
+      }
+    });
     await this.serverAdapter.completeInitialization(this.server).catch((error) => {
       appLogger.error(`Failed to complete initialization: ${error}`);
     });
     if (!this.server) {
       throw new Error("Server failed to start");
     }
-    appLogger.info(`Server running at http://${this.server.hostname}:${this.server.port}`);
+    appLogger.info(
+      `Server running at ${this.runtimeHost.getOrigin(this.server, runtimeServerOptions)}`
+    );
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
-      this.server.stop(true);
+      await this.serverAdapter.buildStatic({ preview: false });
+      await this.runtimeHost.stop(this.server, { force: true });
+      if (preview) {
+        const previewPort = await this.previewHost.start({
+          appConfig: this.appConfig,
+          hostname: configuredHostname,
+          port: configuredPort
+        });
+        if (previewPort) {
+          appLogger.info(`Preview running at http://${configuredHostname}:${previewPort}`);
+        }
+      }
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);
@@ -109,9 +129,12 @@ class EcopagesApp extends SharedApplicationAdapter {
   }
 }
 async function createApp(options) {
-  return new EcopagesApp(options);
+  return new BunEcopagesApp(options, {
+    runtimeHost: new BunRuntimeHost(),
+    previewHost: new BunStaticPreviewHost()
+  });
 }
 export {
-  EcopagesApp,
+  BunEcopagesApp,
   createApp
 };

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

@@ -1,79 +1,47 @@
 import type { WebSocketHandler } from 'bun';
-import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager } from '../../internal-types';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
-import type { HmrStrategy } from '../../hmr/hmr-strategy';
-import type { ClientBridge } from './client-bridge';
-import type { ClientBridgeEvent } from '../../public-types';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ClientBridge } from './client-bridge.js';
+import { InMemoryEntrypointDependencyGraph, type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
 type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: ClientBridge;
 }
-export declare class HmrManager implements IHmrManager {
-    readonly appConfig: EcoPagesAppConfig;
-    private readonly bridge;
-    /** Keep track of watchers */
-    private watchers;
-    /** entrypoint -> output path */
-    private watchedFiles;
-    /** bare specifier -> runtime URL (e.g., 'react' -> '/assets/vendors/react.js') */
-    private specifierMap;
-    private distDir;
-    private plugins;
-    private enabled;
-    private strategies;
+/**
+ * Bun development HMR manager.
+ *
+ * @remarks
+ * Bun shares the same public contract as the Node manager: page entrypoints are
+ * strict integration-owned registrations, while generic script assets use their
+ * own explicit registration path.
+ */
+export declare class HmrManager extends SharedHmrManager {
     private wsHandler;
-    constructor({ appConfig, bridge }: HmrManagerParams);
     /**
-     * Ensures the HMR output directory exists.
+     * Creates the Bun HMR manager around the shared HMR orchestration pipeline.
      *
-     * This must not remove the directory because multiple app processes
-     * can share the same dist path during e2e runs.
-     */
-    private cleanDistDir;
-    /**
-     * Initializes core HMR strategies.
-     * Strategies are evaluated in priority order (highest first).
+     * @remarks
+     * Bun delegates route watching, rebuild dispatch, and runtime bundle
+     * generation to `SharedHmrManager`. The Bun subclass only supplies the
+     * transport-specific dependency graph policy and websocket hook surface.
      */
-    private initializeStrategies;
+    constructor({ appConfig, bridge }: HmrManagerParams);
     /**
-     * Registers a custom HMR strategy.
-     * Used by integrations to provide framework-specific HMR handling.
-     * @param strategy - The HMR strategy to register
+     * Reuses the shared in-memory dependency graph when possible and otherwise
+     * creates the Bun-compatible default graph implementation.
      */
-    registerStrategy(strategy: HmrStrategy): void;
-    setPlugins(plugins: EcoBuildPlugin[]): void;
-    setEnabled(enabled: boolean): void;
-    isEnabled(): boolean;
+    protected createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): InMemoryEntrypointDependencyGraph;
     /**
-     * Registers a mapping from bare specifiers to vendor URLs.
-     * Used by integrations to provide their module resolution mappings.
-     * @param map - Object mapping bare specifiers to vendor URLs
+     * Returns the Bun websocket hooks that attach and detach live HMR subscribers.
+     *
+     * @remarks
+     * `SharedHmrManager` stores the bridge behind the transport-agnostic
+     * `IClientBridge` contract because most HMR coordination only needs broadcast
+     * behavior. Bun connection lifecycle wiring is the point where that abstraction
+     * intentionally narrows back to the concrete Bun bridge so websocket instances
+     * can be tracked directly.
      */
-    registerSpecifierMap(map: Record<string, string>): void;
     getWebSocketHandler(): BunSocketHandler;
-    /**
-     * Builds the client-side HMR runtime script.
-     */
-    buildRuntime(): Promise<void>;
-    getRuntimePath(): string;
-    broadcast(event: ClientBridgeEvent): void;
-    handleFileChange(filePath: string): Promise<void>;
-    /**
-     * Registers a client entrypoint to be built and watched by Bun.
-     */
-    getOutputUrl(entrypointPath: string): string | undefined;
-    getWatchedFiles(): Map<string, string>;
-    getSpecifierMap(): Map<string, string>;
-    getDistDir(): string;
-    getPlugins(): EcoBuildPlugin[];
-    getDefaultContext(): DefaultHmrContext;
-    registerEntrypoint(entrypointPath: string): Promise<string>;
-    /**
-     * Encodes dynamic route segments (brackets) in file paths.
-     * Converts `[slug]` to `_slug_` to avoid filesystem/URL issues.
-     */
-    private encodeDynamicSegments;
-    stop(): void;
 }
 export {};