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

package/src/adapters/bun/server-adapter.js

@@ -1,28 +1,44 @@
+import path from "node:path";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HttpError } from "../../errors/http-error.js";
 import { createRequire } from "../../utils/locals-utils.js";
 import { fileSystem } from "@ecopages/file-system";
+import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ApiResponseBuilder } from "../shared/api-response.js";
-import { ServerRouteHandler } from "../shared/server-route-handler.js";
-import { ServerStaticBuilder } from "../shared/server-static-builder";
-import { ClientBridge } from "./client-bridge";
-import { HmrManager } from "./hmr-manager";
-import { ServerLifecycle } from "./server-lifecycle.js";
+import { ServerStaticBuilder } from "../shared/server-static-builder.js";
+import {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+} from "../shared/hmr-html-response.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { ClientBridge } from "./client-bridge.js";
+import { HmrManager } from "./hmr-manager.js";
+import { BunStaticPreviewHost } from "./static-preview-host.js";
 class BunServerAdapter extends SharedServerAdapter {
   apiHandlers;
   staticRoutes;
   errorHandler;
   bridge;
-  lifecycle;
   hmrManager;
   initializationPromise = null;
   fullyInitialized = false;
-  lifecycleFactory;
-  staticBuilderFactory;
-  routeHandlerFactory;
-  hmrManagerFactory;
-  bridgeFactory;
+  previewHost;
+  /**
+   * Creates a Bun server adapter with already-resolved runtime collaborators.
+   *
+   * @remarks
+   * The public params interface keeps `hmrManager`, `bridge`, and `previewHost`
+   * optional so factory callers can omit them. By the time the concrete adapter
+   * is constructed, those collaborators are mandatory because the adapter cannot
+   * initialize Bun HMR or preview flows without them.
+   */
   constructor({
     appConfig,
     runtimeOrigin,
@@ -31,35 +47,35 @@ class BunServerAdapter extends SharedServerAdapter {
     staticRoutes,
     errorHandler,
     options,
-    lifecycle,
-    staticBuilderFactory,
-    routeHandlerFactory,
     hmrManager,
-    bridge
+    bridge,
+    previewHost
   }) {
     super({ appConfig, runtimeOrigin, serveOptions, options });
     this.apiHandlers = apiHandlers || [];
     this.staticRoutes = staticRoutes || [];
     this.errorHandler = errorHandler;
-    this.lifecycleFactory = lifecycle;
-    this.staticBuilderFactory = staticBuilderFactory;
-    this.routeHandlerFactory = routeHandlerFactory;
-    this.hmrManagerFactory = hmrManager;
-    this.bridgeFactory = bridge;
+    this.bridge = bridge;
+    this.hmrManager = hmrManager;
+    this.previewHost = previewHost;
   }
   /**
-   * Determines if HMR script should be injected.
-   * Only injects in watch mode when HMR manager is enabled.
+   * Returns whether adapter-level HTML responses still need HMR runtime injection.
+   *
+   * @remarks
+   * Filesystem-routed pages are wrapped later in the shared route layer. This
+   * adapter-level check exists for explicit API handlers that return HTML and
+   * would otherwise bypass the route wrapper entirely.
    */
   shouldInjectHmrScript() {
-    return this.options?.watch === true && this.hmrManager?.isEnabled() === true;
+    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager);
   }
   /**
-   * Checks if a response contains HTML content.
+   * Delegates the HTML-response test to the shared response helper used by both
+   * adapters.
    */
   isHtmlResponse(response) {
-    const contentType = response.headers.get("Content-Type");
-    return contentType !== null && contentType.startsWith("text/html");
+    return isHtmlResponse(response);
   }
   /**
    * Injects HMR script into HTML responses in development mode.
@@ -67,72 +83,109 @@ class BunServerAdapter extends SharedServerAdapter {
    */
   async maybeInjectHmrScript(response) {
     if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      const html = await response.text();
-      const hmrScript = `<script type="module">import '/_hmr_runtime.js';<\/script>`;
-      const updatedHtml = html.replace(/<\/html>/i, `${hmrScript}</html>`);
-      const headers = new Headers(response.headers);
-      headers.delete("Content-Length");
-      return new Response(updatedHtml, {
-        status: response.status,
-        statusText: response.statusText,
-        headers
-      });
+      return injectHmrRuntimeIntoHtmlResponse(response);
     }
     return response;
   }
   /**
-   * Initializes the server adapter's core components.
-   * Delegates to ServerLifecycle for setup.
+   * Initializes the server adapter's core runtime components.
    */
   async initialize() {
-    this.bridge = this.bridgeFactory ?? new ClientBridge();
-    this.hmrManager = this.hmrManagerFactory ?? new HmrManager({ appConfig: this.appConfig, bridge: this.bridge });
-    this.lifecycle = this.lifecycleFactory ?? new ServerLifecycle({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager,
-      bridge: this.bridge
+    installAppRuntimeBuildExecutor(this.appConfig, {
+      development: this.options?.watch === true
     });
-    this.staticSiteGenerator = await this.lifecycle.initialize();
+    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+    await this.hmrManager.buildRuntime();
+    this.prepareRuntimePublicDir();
     const staticBuilderOptions = {
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions
+      serveOptions: this.serveOptions,
+      apiHandlers: this.apiHandlers
     };
-    this.staticBuilder = this.staticBuilderFactory ? this.staticBuilderFactory(staticBuilderOptions) : new ServerStaticBuilder(staticBuilderOptions);
-    await this.lifecycle.initializePlugins({ watch: this.options?.watch });
+    this.staticBuilder = new ServerStaticBuilder(staticBuilderOptions);
+    await this.initializeRuntimePlugins({ watch: this.options?.watch });
+  }
+  /**
+   * Copies the source `public` directory into the runtime output and ensures the
+   * HMR assets directory exists before any runtime bundles are emitted.
+   */
+  prepareRuntimePublicDir() {
+    const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+    }
+    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+  }
+  /**
+   * Registers runtime plugins and propagates the final HMR manager into each
+   * integration.
+   *
+   * @remarks
+   * This is where Bun's runtime-plugin registration path meets the integration
+   * lifecycle. A failure here leaves the runtime partially bootstrapped, so the
+   * method logs the underlying error and rethrows instead of trying to limp on.
+   */
+  async initializeRuntimePlugins(options) {
+    try {
+      this.hmrManager.setEnabled(Boolean(options?.watch));
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager,
+        onRuntimePlugin: (plugin) => {
+          Bun.plugin(plugin);
+        }
+      });
+      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
+      this.hmrManager.setPlugins(browserBuildPlugins);
+      for (const integration of this.appConfig.integrations) {
+        integration.setHmrManager(this.hmrManager);
+      }
+    } catch (error) {
+      appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
   }
   /**
-   * Refreshes the router routes during watch mode.
+   * Rebuilds the shared routing state and hot-reloads the live Bun server when a
+   * watched route file changes.
    */
   async refreshRouterRoutes() {
-    if (this.serverInstance && typeof this.serverInstance.reload === "function") {
-      try {
-        await this.initSharedRouter();
-        this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+    if (!this.serverInstance || typeof this.serverInstance.reload !== "function") {
+      appLogger.error("Server instance is not available for reloading");
+      return;
+    }
+    await this.createSharedWatchRefreshCallback({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager,
+      onRoutesReady: () => {
         const options = this.getServerOptions({ enableHmr: true });
         this.serverInstance.reload(options);
         appLogger.debug("Server routes updated with dynamic routes");
-      } catch (error) {
-        if (error instanceof Error) {
-          this.hmrManager.broadcast({ type: "error", message: error.message });
-          appLogger.error("Failed to refresh router routes:", error);
-        }
+      },
+      onError: (error) => {
+        this.hmrManager.broadcast({ type: "error", message: error.message });
+        appLogger.error("Failed to refresh router routes:", error);
       }
-    } else {
-      appLogger.error("Server instance is not available for reloading");
-    }
+    })();
   }
   async watch() {
-    await this.lifecycle.startWatching({
-      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this)
+    const watcher = new ProjectWatcher({
+      config: this.appConfig,
+      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this),
+      hmrManager: this.hmrManager,
+      bridge: this.bridge
     });
+    await watcher.createWatcherSubscription();
   }
   /**
-   * Retrieves the current server options, optionally enabling HMR.
-   * If HMR is enabled, modifies fetch to handle WebSocket upgrades and serve HMR runtime.
-   * Ensures original fetch logic is preserved and called for non-HMR requests.
-   * @param options.enableHmr Whether to enable Hot Module Replacement
+   * Builds the `Bun.serve()` options for the current adapter state.
+   *
+   * @remarks
+   * The HMR-enabled variant wraps the base fetch handler so one Bun server can
+   * serve normal requests, accept HMR websocket upgrades, and expose the HMR
+   * runtime asset without splitting responsibility across separate listeners.
    */
   getServerOptions({ enableHmr = false } = {}) {
     appLogger.debug(`[BunServerAdapter] getServerOptions called with enableHmr: ${enableHmr}`);
@@ -188,8 +241,12 @@ class BunServerAdapter extends SharedServerAdapter {
     return void 0;
   }
   /**
-   * Creates complete server configuration with request handling.
-   * @returns Server options ready for Bun.serve()
+   * Composes the base Bun server settings that all runtime modes build from.
+   *
+   * @remarks
+   * This method centralizes the Bun-specific error boundary. It preserves the
+   * shared route pipeline while still allowing adapter-level custom error-handler
+   * execution and `HttpError` passthrough.
    */
   buildServerSettings() {
     const serverOptions = { ...this.serveOptions };
@@ -246,14 +303,34 @@ class BunServerAdapter extends SharedServerAdapter {
    */
   async buildStatic(options) {
     if (!this.fullyInitialized) {
-      await this.initSharedRouter();
-      this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+      await this.initializeSharedRouteHandling({
+        staticRoutes: this.staticRoutes,
+        hmrManager: this.hmrManager
+      });
+    }
+    const buildRuntimeOrigin = this.serverInstance ? `http://${this.serverInstance.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serverInstance.port || DEFAULT_ECOPAGES_PORT}` : void 0;
+    await this.staticBuilder.build(
+      { ...options, preview: false, baseUrl: buildRuntimeOrigin },
+      {
+        router: this.router,
+        routeRendererFactory: this.routeRendererFactory,
+        staticRoutes: this.staticRoutes
+      }
+    );
+    if (!options?.preview) {
+      return;
     }
-    await this.staticBuilder.build(options, {
-      router: this.router,
-      routeRendererFactory: this.routeRendererFactory,
-      staticRoutes: this.staticRoutes
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    const previewPort = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
+    const activePreviewPort = await this.previewHost.start({
+      appConfig: this.appConfig,
+      hostname: String(previewHostname),
+      port: previewPort
     });
+    if (activePreviewPort) {
+      appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
+      return;
+    }
   }
   /**
    * Initializes the server with dynamic routes after server creation.
@@ -273,13 +350,20 @@ class BunServerAdapter extends SharedServerAdapter {
     return this.initializationPromise;
   }
   /**
-   * Performs complete server setup including routing, watchers, and HMR.
+   * Performs the one-time post-bind initialization path for Bun servers.
+   *
+   * @remarks
+   * This is intentionally split from `initialize()` because shared route handling
+   * and file watching need the live server instance to exist before Bun can
+   * reload updated route handlers in place.
    */
   async _performInitialization(server) {
     this.serverInstance = server;
     appLogger.debug("Completing server initialization with dynamic routes");
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+    await this.initializeSharedRouteHandling({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager
+    });
     this.fullyInitialized = true;
     if (this.options?.watch) await this.watch();
     if (server && typeof server.reload === "function") {
@@ -342,23 +426,16 @@ class BunServerAdapter extends SharedServerAdapter {
   }
 }
 async function createBunServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
   const bridge = params.bridge ?? new ClientBridge();
   const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
-  const lifecycle = params.lifecycle ?? new ServerLifecycle({
-    appConfig: params.appConfig,
-    runtimeOrigin,
-    hmrManager,
-    bridge
-  });
+  const previewHost = params.previewHost ?? new BunStaticPreviewHost();
   const adapter = new BunServerAdapter({
     ...params,
     runtimeOrigin,
     bridge,
     hmrManager,
-    lifecycle,
-    staticBuilderFactory: params.staticBuilderFactory ?? ((opts) => new ServerStaticBuilder(opts)),
-    routeHandlerFactory: params.routeHandlerFactory ?? ((p) => new ServerRouteHandler(p))
+    previewHost
   });
   return adapter.createAdapter();
 }

package/src/adapters/bun/static-preview-host.d.ts

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+type BunStaticPreviewServer = {
+    server: {
+        port?: number;
+    } | null;
+    stop(): void;
+};
+type BunStaticPreviewServerFactory = {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): BunStaticPreviewServer;
+};
+type BunStaticPreviewLogger = {
+    error(message: string): unknown;
+};
+export declare class BunStaticPreviewHost implements StaticPreviewHost {
+    private readonly previewServerFactory;
+    private readonly logger;
+    private previewServer;
+    constructor(previewServerFactory?: BunStaticPreviewServerFactory, logger?: BunStaticPreviewLogger);
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    stop(): Promise<void>;
+}
+export {};

package/src/adapters/bun/static-preview-host.js

@@ -0,0 +1,45 @@
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
+class BunStaticPreviewHost {
+  constructor(previewServerFactory = StaticContentServer, logger = appLogger) {
+    this.previewServerFactory = previewServerFactory;
+    this.logger = logger;
+  }
+  previewServerFactory;
+  logger;
+  previewServer = null;
+  async start(options) {
+    await this.stop();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      try {
+        this.previewServer = this.previewServerFactory.createServer({
+          appConfig: options.appConfig,
+          options: { port: options.port }
+        });
+        const previewPort = this.previewServer.server?.port;
+        if (previewPort) {
+          return previewPort;
+        }
+        break;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorCode = typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+        const isPortReleaseRace = errorCode === "EADDRINUSE" || errorMessage.includes("EADDRINUSE");
+        if (!isPortReleaseRace || attempt === 19) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+    this.logger.error("Failed to start preview server");
+    return null;
+  }
+  async stop() {
+    this.previewServer?.stop();
+    this.previewServer = null;
+  }
+}
+export {
+  BunStaticPreviewHost
+};

package/src/{create-app.d.ts → adapters/create-app.d.ts}

@@ -1,9 +1,12 @@
-import type { EcopagesAppOptions as BunOptions } from './adapters/bun/create-app.js';
-import type { EcopagesAppOptions as NodeOptions } from './adapters/node/create-app.js';
-import { AbstractApplicationAdapter } from './adapters/abstract/application-adapter.js';
-import { SharedApplicationAdapter } from './adapters/shared/application-adapter.js';
-export type EcopagesAppOptions = BunOptions | NodeOptions;
-export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, any, Request>;
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { AbstractApplicationAdapter } from './abstract/application-adapter.js';
+import type { ApplicationAdapterOptions } from './abstract/application-adapter.js';
+import { SharedApplicationAdapter } from './shared/application-adapter.js';
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+    appConfig: EcoPagesAppConfig;
+    serverOptions?: Record<string, any>;
+}
+export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
 export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp>;
 export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, unknown, Request> {
     private readonly appOptions;

package/src/{create-app.js → adapters/create-app.js}

@@ -1,12 +1,12 @@
-import { AbstractApplicationAdapter } from "./adapters/abstract/application-adapter.js";
-import { SharedApplicationAdapter } from "./adapters/shared/application-adapter.js";
+import { AbstractApplicationAdapter } from "./abstract/application-adapter.js";
+import { SharedApplicationAdapter } from "./shared/application-adapter.js";
+import { createApp as createBunApp } from "./bun/create-app.js";
+import { createNodeApp } from "./node/create-app.js";
 async function createRuntimeApp(options) {
   const bun = globalThis.Bun;
   if (bun) {
-    const { createApp: createBunApp } = await import("./adapters/bun/create-app.js");
     return await createBunApp(options);
   }
-  const { createNodeApp } = await import("./adapters/node/create-app.js");
   return await createNodeApp(options);
 }
 async function createApp(options) {

package/src/adapters/index.d.ts

@@ -1,6 +1,2 @@
-export { EcopagesApp, createApp } from './bun/create-app.js';
-export { defineApiHandler, defineGroupHandler } from './bun/define-api-handler.js';
-export { NodeServerAdapter, createNodeServerAdapter } from './node/server-adapter.js';
-export { EcopagesApp as NodeAdapterEcopagesApp, createNodeApp } from './node/create-app.js';
-export type { NodeServerAdapterParams, NodeServerAdapterResult } from './node/server-adapter.js';
-export type { EcopagesAppOptions as NodeEcopagesAppOptions } from './node/create-app.js';
+export { EcopagesApp, createApp } from './create-app.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.js';

package/src/adapters/index.js

@@ -1,14 +1,8 @@
-import { EcopagesApp, createApp } from "./bun/create-app.js";
-import { defineApiHandler, defineGroupHandler } from "./bun/define-api-handler.js";
-import { NodeServerAdapter, createNodeServerAdapter } from "./node/server-adapter.js";
-import { EcopagesApp as EcopagesApp2, createNodeApp } from "./node/create-app.js";
+import { EcopagesApp, createApp } from "./create-app.js";
+import { defineApiHandler, defineGroupHandler } from "./shared/define-api-handler.js";
 export {
   EcopagesApp,
-  EcopagesApp2 as NodeAdapterEcopagesApp,
-  NodeServerAdapter,
   createApp,
-  createNodeApp,
-  createNodeServerAdapter,
   defineApiHandler,
   defineGroupHandler
 };

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

@@ -1,21 +1,24 @@
-import { type Server as NodeServerInstance } from 'node:http';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import { type ApplicationAdapterOptions } from '../abstract/application-adapter.js';
 import { SharedApplicationAdapter } from '../shared/application-adapter.js';
-import { type NodeServerAdapterResult } from './server-adapter.js';
-export interface EcopagesAppOptions extends ApplicationAdapterOptions {
-    appConfig: EcoPagesAppConfig;
-    serverOptions?: Record<string, any>;
-}
-export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+import type { RuntimeHost } from '../shared/runtime-host.js';
+import type { EcopagesAppOptions } from '../create-app.js';
+import { type NodeServerAdapterResult, createNodeServerAdapter } from './server-adapter.js';
+import type { NodeServerInstance } from './server-adapter.js';
+export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
     serverAdapter: NodeServerAdapterResult | undefined;
     private server;
     private runtimeOrigin;
+    private readonly runtimeHost;
+    constructor(options: EcopagesAppOptions, dependencies: {
+        runtimeHost: RuntimeHost<NodeServerInstance, {
+            port?: number;
+            hostname?: string;
+        }>;
+    });
+    protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
     start(): Promise<NodeServerInstance | void>;
-    private createWebRequest;
-    private sendNodeResponse;
     fetch(request: Request): Promise<Response>;
 }
-export declare function createNodeApp(options: EcopagesAppOptions): Promise<EcopagesApp>;
+export declare function createNodeApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;
+export declare function createApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;