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

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

@@ -1,90 +1,47 @@
-import fs from "node:fs";
-import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../constants";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
-import { fileSystem } from "@ecopages/file-system";
-import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy";
-import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy";
-import { appLogger } from "../../global/app-logger";
-class HmrManager {
-  appConfig;
-  bridge;
-  /** Keep track of watchers */
-  watchers = /* @__PURE__ */ new Map();
-  /** entrypoint -> output path */
-  watchedFiles = /* @__PURE__ */ new Map();
-  /** bare specifier -> runtime URL (e.g., 'react' -> '/assets/vendors/react.js') */
-  specifierMap = /* @__PURE__ */ new Map();
-  distDir;
-  plugins = [];
-  enabled = true;
-  strategies = [];
+import { appLogger } from "../../global/app-logger.js";
+import {
+  InMemoryEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { SharedHmrManager } from "../shared/shared-hmr-manager.js";
+class HmrManager extends SharedHmrManager {
   wsHandler;
-  constructor({ appConfig, bridge }) {
-    this.appConfig = appConfig;
-    this.bridge = bridge;
-    this.distDir = path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR, "_hmr");
-    this.cleanDistDir();
-    this.initializeStrategies();
-  }
   /**
-   * 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.
-   */
-  cleanDistDir() {
-    fileSystem.ensureDir(this.distDir);
-  }
-  /**
-   * 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.
    */
-  initializeStrategies() {
-    const jsContext = {
-      getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.specifierMap,
-      getDistDir: () => this.distDir,
-      getPlugins: () => this.plugins,
-      getSrcDir: () => this.appConfig.absolutePaths.srcDir
-    };
-    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  constructor({ appConfig, bridge }) {
+    super({ appConfig, bridge });
   }
   /**
-   * 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) {
-    this.strategies.push(strategy);
-  }
-  setPlugins(plugins) {
-    this.plugins = [...plugins];
-  }
-  setEnabled(enabled) {
-    this.enabled = enabled;
-  }
-  isEnabled() {
-    return this.enabled;
+  createEntrypointDependencyGraph(existingEntrypointDependencyGraph) {
+    return existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new 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) {
-    for (const [specifier, url] of Object.entries(map)) {
-      this.specifierMap.set(specifier, url);
-    }
-  }
   getWebSocketHandler() {
+    const bridge = this.bridge;
     const open = (ws) => {
-      this.bridge.subscribe(ws);
-      appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${this.bridge.subscriberCount}`);
+      bridge.subscribe(ws);
+      appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${bridge.subscriberCount}`);
     };
     const close = (ws) => {
-      this.bridge.unsubscribe(ws);
-      appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${this.bridge.subscriberCount}`);
+      bridge.unsubscribe(ws);
+      appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${bridge.subscriberCount}`);
     };
     this.wsHandler = { open, close };
     return {
@@ -95,127 +52,6 @@ class HmrManager {
       }
     };
   }
-  /**
-   * Builds the client-side HMR runtime script.
-   */
-  async buildRuntime() {
-    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
-    const result = await defaultBuildAdapter.build({
-      entrypoints: [runtimeSource],
-      outdir: this.distDir,
-      naming: "_hmr_runtime.js",
-      minify: false,
-      ...defaultBuildAdapter.getTranspileOptions("hmr-runtime"),
-      plugins: this.plugins
-    });
-    if (!result.success) {
-      appLogger.error("[HMR] Failed to build runtime script:", result.logs);
-    }
-  }
-  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) {
-    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(`[HmrManager] Selected strategy: ${strategy.constructor.name}`);
-    const action = await strategy.process(filePath);
-    if (action.type === "broadcast") {
-      if (action.events) {
-        for (const event of action.events) {
-          this.broadcast(event);
-        }
-      }
-    }
-  }
-  /**
-   * Registers a client entrypoint to be built and watched by Bun.
-   */
-  getOutputUrl(entrypointPath) {
-    return this.watchedFiles.get(entrypointPath);
-  }
-  getWatchedFiles() {
-    return this.watchedFiles;
-  }
-  getSpecifierMap() {
-    return this.specifierMap;
-  }
-  getDistDir() {
-    return this.distDir;
-  }
-  getPlugins() {
-    return this.plugins;
-  }
-  getDefaultContext() {
-    return {
-      getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.specifierMap,
-      getDistDir: () => this.distDir,
-      getPlugins: () => this.plugins,
-      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
-      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
-      getPagesDir: () => this.appConfig.absolutePaths.pagesDir
-    };
-  }
-  async registerEntrypoint(entrypointPath) {
-    if (this.watchedFiles.has(entrypointPath)) {
-      return this.watchedFiles.get(entrypointPath);
-    }
-    const srcDir = this.appConfig.absolutePaths.srcDir;
-    const relativePath = path.relative(srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-    const urlPath = encodedPathJs.split(path.sep).join("/");
-    const outputUrl = `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`;
-    const outputPath = path.join(this.distDir, urlPath);
-    this.watchedFiles.set(entrypointPath, outputUrl);
-    await this.handleFileChange(entrypointPath);
-    if (!fileSystem.exists(outputPath)) {
-      const fallback = await defaultBuildAdapter.build({
-        entrypoints: [entrypointPath],
-        outdir: this.distDir,
-        naming: encodedPathJs,
-        minify: false,
-        external: Array.from(this.specifierMap.keys()),
-        ...defaultBuildAdapter.getTranspileOptions("hmr-entrypoint"),
-        plugins: this.plugins
-      });
-      if (!fallback.success) {
-        appLogger.error(`[HMR] Fallback build failed for ${entrypointPath}:`, fallback.logs);
-      }
-    }
-    return outputUrl;
-  }
-  /**
-   * Encodes dynamic route segments (brackets) in file paths.
-   * Converts `[slug]` to `_slug_` to avoid filesystem/URL issues.
-   */
-  encodeDynamicSegments(filepath) {
-    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
-  }
-  stop() {
-    for (const watcher of this.watchers.values()) {
-      watcher.close();
-    }
-    this.watchers.clear();
-  }
 }
 export {
   HmrManager

package/src/adapters/bun/index.d.ts

@@ -1,3 +1,2 @@
-export { EcopagesApp, createApp } from './create-app.js';
-export { defineApiHandler, defineGroupHandler } from './define-api-handler.js';
-export type { GroupHandler } from './define-api-handler.js';
+export { BunEcopagesApp, createApp } from './create-app.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.js';

package/src/adapters/bun/index.js

@@ -1,7 +1,7 @@
-import { EcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "./define-api-handler.js";
+import { BunEcopagesApp, createApp } from "./create-app.js";
+import { defineApiHandler, defineGroupHandler } from "../shared/define-api-handler.js";
 export {
-  EcopagesApp,
+  BunEcopagesApp,
   createApp,
   defineApiHandler,
   defineGroupHandler

package/src/adapters/bun/runtime-host.d.ts

@@ -0,0 +1,52 @@
+import type { Server } from 'bun';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+type BunRuntimeProvider = {
+    serve(options: Bun.Serve.Options<unknown>): Server<unknown>;
+};
+/**
+ * Bun runtime host that adapts the shared runtime lifecycle contract onto
+ * `Bun.serve()`.
+ *
+ * @remarks
+ * The injected runtime provider exists so tests and non-Bun call sites can
+ * construct the host without assuming `globalThis.Bun` is present. The provider
+ * returns `null` instead of `undefined` to keep that absence explicit at the
+ * host boundary.
+ */
+export declare class BunRuntimeHost<WebSocketData = undefined> implements RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>> {
+    private readonly runtimeProvider;
+    /**
+     * Creates a Bun runtime host with an injectable runtime lookup.
+     *
+     * @remarks
+     * Production code uses the default `getBunRuntime()` lookup. Tests may inject a
+     * fake provider that either supplies a `serve()` implementation or returns
+     * `null` to verify the runtime-required failure path.
+     */
+    constructor(runtimeProvider?: () => BunRuntimeProvider | null);
+    /**
+     * Starts the Bun server using the already-composed serve options from the
+     * shared application bootstrap.
+     */
+    start(options: RuntimeHostStartOptions<Bun.Serve.Options<WebSocketData>>): Promise<Server<WebSocketData>>;
+    /**
+     * Stops the active Bun server immediately.
+     *
+     * @remarks
+     * The shared runtime-host contract accepts optional stop options, but Bun's
+     * server API already models the shutdown behavior directly. This host always
+     * uses Bun's forceful stop path so preview and embedded runtime shutdowns do
+     * not linger on open connections.
+     */
+    stop(server: Server<WebSocketData>): Promise<void>;
+    /**
+     * Resolves the externally reported runtime origin from the active server.
+     *
+     * @remarks
+     * Bun may finalize the hostname or port differently from the requested serve
+     * options. This method prefers the live server binding and only falls back to
+     * the requested options when Bun leaves a field unset.
+     */
+    getOrigin(server: Server<WebSocketData>, fallbackServeOptions: Bun.Serve.Options<WebSocketData>): string;
+}
+export {};

package/src/adapters/bun/runtime-host.js

@@ -0,0 +1,56 @@
+import { getBunRuntime } from "../../utils/runtime.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+class BunRuntimeHost {
+  /**
+   * Creates a Bun runtime host with an injectable runtime lookup.
+   *
+   * @remarks
+   * Production code uses the default `getBunRuntime()` lookup. Tests may inject a
+   * fake provider that either supplies a `serve()` implementation or returns
+   * `null` to verify the runtime-required failure path.
+   */
+  constructor(runtimeProvider = () => getBunRuntime() ?? null) {
+    this.runtimeProvider = runtimeProvider;
+  }
+  runtimeProvider;
+  /**
+   * Starts the Bun server using the already-composed serve options from the
+   * shared application bootstrap.
+   */
+  async start(options) {
+    const bun = this.runtimeProvider();
+    if (!bun) {
+      throw new Error("Bun runtime is required for the Bun adapter");
+    }
+    return bun.serve(options.serveOptions);
+  }
+  /**
+   * Stops the active Bun server immediately.
+   *
+   * @remarks
+   * The shared runtime-host contract accepts optional stop options, but Bun's
+   * server API already models the shutdown behavior directly. This host always
+   * uses Bun's forceful stop path so preview and embedded runtime shutdowns do
+   * not linger on open connections.
+   */
+  async stop(server) {
+    server.stop(true);
+  }
+  /**
+   * Resolves the externally reported runtime origin from the active server.
+   *
+   * @remarks
+   * Bun may finalize the hostname or port differently from the requested serve
+   * options. This method prefers the live server binding and only falls back to
+   * the requested options when Bun leaves a field unset.
+   */
+  getOrigin(server, fallbackServeOptions) {
+    return resolveServeRuntimeOrigin({
+      hostname: server.hostname ?? fallbackServeOptions.hostname,
+      port: server.port ?? fallbackServeOptions.port
+    });
+  }
+}
+export {
+  BunRuntimeHost
+};

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

@@ -1,13 +1,11 @@
 import type { Server, WebSocketHandler } from 'bun';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
-import { ServerRouteHandler, type ServerRouteHandlerParams } from '../shared/server-route-handler.js';
-import { ServerStaticBuilder, type ServerStaticBuilderParams } from '../shared/server-static-builder';
-import { ClientBridge } from './client-bridge';
-import { HmrManager } from './hmr-manager';
-import { ServerLifecycle } from './server-lifecycle.js';
+import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import { ClientBridge } from './client-bridge.js';
+import { HmrManager } from './hmr-manager.js';
 type BunServerInstance = Server<unknown>;
 type BunNativeServeOptions = Bun.Serve.Options<unknown>;
 export type BunServerRoutes = Bun.Serve.Routes<unknown, string>;
@@ -18,6 +16,15 @@ export type BunServeOptions = Omit<BunNativeServeOptions, 'fetch'> & {
     fetch?: (this: BunServerInstance, request: Request, server: BunServerInstance) => Promise<void | Response>;
     websocket?: WebSocketHandler<unknown>;
 };
+/**
+ * Construction parameters for the Bun server adapter.
+ *
+ * @remarks
+ * Callers normally provide only the app-facing fields such as routes, handlers,
+ * and `serveOptions`. The transport collaborators remain optional here because
+ * `createBunServerAdapter()` fills in Bun-specific defaults before the concrete
+ * adapter instance is created.
+ */
 export interface BunServerAdapterParams {
     appConfig: EcoPagesAppConfig;
     runtimeOrigin: string;
@@ -28,11 +35,9 @@ export interface BunServerAdapterParams {
     options?: {
         watch?: boolean;
     };
-    lifecycle?: ServerLifecycle;
-    staticBuilderFactory?: (params: ServerStaticBuilderParams) => ServerStaticBuilder;
-    routeHandlerFactory?: (params: ServerRouteHandlerParams) => ServerRouteHandler;
     hmrManager?: HmrManager;
     bridge?: ClientBridge;
+    previewHost?: StaticPreviewHost;
 }
 export interface BunServerAdapterResult extends ServerAdapterResult {
     getServerOptions: (options?: {
@@ -44,6 +49,16 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
 }
+/**
+ * Bun transport adapter that wires shared Ecopages request handling onto a live
+ * `Bun.serve()` runtime.
+ *
+ * @remarks
+ * The adapter owns Bun-specific concerns that do not exist in the shared server
+ * abstraction: websocket-backed HMR transport, runtime plugin registration, and
+ * preview-host startup for static builds. Routing, rendering, and response
+ * composition still delegate to the shared server adapter base.
+ */
 export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapterParams, BunServerAdapterResult> {
     appConfig: EcoPagesAppConfig;
     options: BunServerAdapterParams['options'];
@@ -52,24 +67,37 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;
     private bridge;
-    private lifecycle;
     hmrManager: HmrManager;
     private initializationPromise;
     private fullyInitialized;
     serverInstance: BunServerInstance | null;
-    private readonly lifecycleFactory?;
-    private readonly staticBuilderFactory?;
-    private readonly routeHandlerFactory?;
-    private readonly hmrManagerFactory?;
-    private readonly bridgeFactory?;
-    constructor({ appConfig, runtimeOrigin, serveOptions, apiHandlers, staticRoutes, errorHandler, options, lifecycle, staticBuilderFactory, routeHandlerFactory, hmrManager, bridge, }: BunServerAdapterParams);
-    /**
-     * Determines if HMR script should be injected.
-     * Only injects in watch mode when HMR manager is enabled.
+    private readonly 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, serveOptions, apiHandlers, staticRoutes, errorHandler, options, hmrManager, bridge, previewHost, }: BunServerAdapterParams & {
+        hmrManager: HmrManager;
+        bridge: ClientBridge;
+        previewHost: StaticPreviewHost;
+    });
+    /**
+     * 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.
      */
     private shouldInjectHmrScript;
     /**
-     * Checks if a response contains HTML content.
+     * Delegates the HTML-response test to the shared response helper used by both
+     * adapters.
      */
     private isHtmlResponse;
     /**
@@ -78,20 +106,37 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     private maybeInjectHmrScript;
     /**
-     * Initializes the server adapter's core components.
-     * Delegates to ServerLifecycle for setup.
+     * Initializes the server adapter's core runtime components.
      */
     initialize(): Promise<void>;
     /**
-     * Refreshes the router routes during watch mode.
+     * Copies the source `public` directory into the runtime output and ensures the
+     * HMR assets directory exists before any runtime bundles are emitted.
+     */
+    private prepareRuntimePublicDir;
+    /**
+     * 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.
+     */
+    private initializeRuntimePlugins;
+    /**
+     * Rebuilds the shared routing state and hot-reloads the live Bun server when a
+     * watched route file changes.
      */
     private refreshRouterRoutes;
     private watch;
     /**
-     * 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 }?: {
         enableHmr?: boolean | undefined;
@@ -104,8 +149,12 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     private retrieveBodyFromRequest;
     /**
-     * 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.
      */
     private buildServerSettings;
     /**
@@ -122,7 +171,12 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     completeInitialization(server?: BunServerInstance | null): Promise<void>;
     /**
-     * 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.
      */
     private _performInitialization;
     /**
@@ -149,7 +203,14 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private handleNoMatch;
 }
 /**
- * Factory function to create a Bun server adapter
+ * Creates the Bun server adapter and fills in the runtime-specific collaborators
+ * that Bun callers usually leave implicit.
+ *
+ * @remarks
+ * This is the canonical entry point for Bun server-adapter construction. It
+ * guarantees that the concrete adapter receives a Bun websocket bridge, HMR
+ * manager, and preview host even though those dependencies are optional on the
+ * public params type.
  */
 export declare function createBunServerAdapter(params: BunServerAdapterParams): Promise<BunServerAdapterResult>;
 export {};