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

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

@@ -1,140 +1,181 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { appLogger } from "../../global/app-logger.js";
-import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime-app-bootstrap.js";
-import { createBunServerAdapter } from "./server-adapter.js";
-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();
+/**
+ * This file contains the implementation of the Bun application adapter for EcoPages.
+ * It extends the AbstractApplicationAdapter class and provides methods for handling
+ * HTTP requests, initializing the server adapter, and starting the Bun application server.
+ * The adapter is designed to work with the Bun runtime and provides a way to create
+ * EcoPages applications using Bun's features.
+ *
+ * @module EcopagesApp
+ */
+import { appLogger } from '../../global/app-logger.js';
+import { SharedApplicationAdapter } from '../shared/runtime/application-adapter.js';
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from '../shared/runtime/runtime-app-bootstrap.js';
+import { startupTrace } from '../../diagnostics/startup-trace.js';
+import { createBunServerAdapter } from './server-adapter.js';
+import { BunRuntimeHost } from './runtime-host.js';
+import { hostOwnsDevClient } from '../../dev/dev-client-ownership.js';
+import { resolveAppStartRoutes } from '../../utils/ecopages-route-info.js';
+/**
+ * Bun-specific application adapter implementation
+ * This class extends the {@link AbstractApplicationAdapter}
+ * and provides methods for handling HTTP requests and managing the server.
+ */
+export class BunEcopagesApp extends SharedApplicationAdapter {
+    serverAdapter;
+    server = null;
+    stopped = false;
+    runtimeHost;
+    constructor(options, dependencies) {
+        super(options, 'Bun');
+        this.runtimeHost = dependencies.runtimeHost;
     }
-    await this.serverAdapter.completeInitialization(this.server);
-    return this.serverAdapter.handleRequest(request);
-  }
-  /**
-   * Complete the initialization of the server adapter by processing dynamic routes
-   * @param server The Bun server instance
-   */
-  async completeInitialization(server) {
-    if (!this.serverAdapter) {
-      throw new Error("Server adapter not initialized. Call start() first.");
+    async fetch(request) {
+        if (!this.serverAdapter) {
+            this.serverAdapter = await this.initializeServerAdapter();
+        }
+        await this.serverAdapter.completeInitialization(this.server);
+        return this.serverAdapter.handleRequest(request);
     }
-    await this.serverAdapter.completeInitialization(server);
-  }
-  /**
-   * Initialize the Bun server adapter
-   */
-  async initializeServerAdapter() {
-    const binding = resolveRuntimeBinding({
-      cliArgs: this.cliArgs,
-      serverOptions: this.serverOptions
-    });
-    appLogger.debug("initializeServerAdapter", {
-      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: binding.runtimeOrigin,
-      appConfig: this.appConfig,
-      apiHandlers: this.apiHandlers,
-      staticRoutes: this.staticRoutes,
-      errorHandler: this.errorHandler,
-      options: { watch: binding.watch },
-      serveOptions: binding.serveOptions
-    });
-  }
-  /**
-   * Start the Bun application server
-   * @param options Optional settings
-   * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
-   */
-  async start() {
-    if (!this.serverAdapter) {
-      this.serverAdapter = await this.initializeServerAdapter();
+    async attachWebSocketUpgrades(httpServer, options) {
+        if (!this.serverAdapter) {
+            this.serverAdapter = await this.initializeServerAdapter();
+        }
+        this.serverAdapter.attachUserWebSocketUpgrades(httpServer, options);
     }
-    const { dev, preview, build } = this.cliArgs;
-    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");
-      if (build) {
-        process.exit(0);
-      }
-      return;
+    /**
+     * Complete the initialization of the server adapter by processing dynamic routes
+     * @param server The Bun server instance
+     */
+    async completeInitialization(server) {
+        if (!this.serverAdapter) {
+            throw new Error('Server adapter not initialized. Call start() first.');
+        }
+        await this.serverAdapter.completeInitialization(server);
     }
-    const enableHmr = dev || !preview && !build;
-    const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
-    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");
+    /**
+     * Initialize the Bun server adapter
+     */
+    async initializeServerAdapter() {
+        const binding = resolveRuntimeBinding({
+            cliArgs: this.cliArgs,
+            serverOptions: this.serverOptions,
+        });
+        return createBunServerAdapter({
+            runtimeOrigin: binding.runtimeOrigin,
+            appConfig: this.appConfig,
+            apiHandlers: this.apiHandlers,
+            staticRoutes: this.staticRoutes,
+            errorHandler: this.errorHandler,
+            websocketHandlers: this.websocketHandlers.size > 0 ? this.websocketHandlers : undefined,
+            options: { watch: binding.watch },
+            serveOptions: binding.serveOptions,
+            hostOwnsDevClient: hostOwnsDevClient(this.runtimeOptions),
+            deferRuntimeAssetSetup: resolveStaticRuntimeMode({
+                appConfig: this.appConfig,
+                cliArgs: this.cliArgs,
+            }).canBuildWithoutRuntimeServer,
+            allowPortFallback: binding.allowPortFallback,
+        });
     }
-    appLogger.info(
-      `Server running at ${this.runtimeHost.getOrigin(this.server, runtimeServerOptions)}`
-    );
-    if (build || preview) {
-      appLogger.debugTime("Building static pages");
-      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
+    /**
+     * Start the Bun application server
+     * @param options Optional settings
+     * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
+     */
+    async bootServer() {
+        if (this.stopped) {
+            this.serverAdapter = undefined;
+            this.stopped = false;
+        }
+        if (!this.serverAdapter) {
+            this.serverAdapter = await this.initializeServerAdapter();
+        }
+        const { dev, preview, build, force, serveOnly } = this.cliArgs;
+        const staticRuntimeMode = resolveStaticRuntimeMode({
+            appConfig: this.appConfig,
+            cliArgs: this.cliArgs,
         });
-        if (previewPort) {
-          appLogger.info(`Preview running at http://${configuredHostname}:${previewPort}`);
+        if (preview && serveOnly) {
+            const previewOrigin = await this.serverAdapter.servePreviewOnly();
+            if (previewOrigin) {
+                await this.notifyListening(previewOrigin);
+            }
+            return;
+        }
+        if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
+            appLogger.debugTime('Building static pages');
+            const previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
+            appLogger.debugTimeEnd('Building static pages');
+            if (preview && previewOrigin) {
+                await this.notifyListening(previewOrigin);
+            }
+            if (build) {
+                process.exit(0);
+            }
+            return;
         }
-      }
-      appLogger.debugTimeEnd("Building static pages");
-      if (build) {
-        process.exit(0);
-      }
+        const enableHmr = dev || (!preview && !build);
+        const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
+        const runtimeServerOptions = serverOptions;
+        startupTrace.beginServerListen();
+        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');
+        }
+        const runtimeOrigin = this.runtimeHost.getOrigin(this.server, runtimeServerOptions);
+        let previewOrigin;
+        if (build || preview) {
+            appLogger.debugTime('Building static pages');
+            previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
+            const buildRuntimeServer = this.server;
+            this.server = null;
+            await this.runtimeHost.stop(buildRuntimeServer, { force: true });
+            appLogger.debugTimeEnd('Building static pages');
+            if (build) {
+                process.exit(0);
+            }
+        }
+        else {
+            await this.notifyListening(runtimeOrigin);
+        }
+        if (preview && previewOrigin) {
+            await this.notifyListening(previewOrigin);
+        }
+        return this.server ?? undefined;
+    }
+    async stop(force = true) {
+        if (this.stopped) {
+            return;
+        }
+        if (this.server) {
+            const activeServer = this.server;
+            this.server = null;
+            await this.runtimeHost.stop(activeServer, { force });
+        }
+        if (this.serverAdapter) {
+            await this.serverAdapter.dispose();
+        }
+        this.stopped = true;
+    }
+    async resolveAppRoutes() {
+        return resolveAppStartRoutes({
+            listStaticGenerationRoutes: this.serverAdapter?.listStaticGenerationRoutes,
+            runtimeOrigin: this.appConfig.baseUrl,
+        });
     }
-    return this.server;
-  }
 }
-async function createApp(options) {
-  return new BunEcopagesApp(options, {
-    runtimeHost: new BunRuntimeHost(),
-    previewHost: new BunStaticPreviewHost()
-  });
+/**
+ * Factory function to create a Bun application
+ */
+export async function createApp(options) {
+    return new BunEcopagesApp(options, {
+        runtimeHost: new BunRuntimeHost(),
+    });
 }
-export {
-  BunEcopagesApp,
-  createApp
-};

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

@@ -2,7 +2,7 @@ import type { WebSocketHandler } from 'bun';
 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';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
 type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;

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

@@ -1,58 +1,63 @@
-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;
-  /**
-   * Creates the Bun HMR manager around the shared HMR orchestration pipeline.
-   *
-   * @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.
-   */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
-  }
-  /**
-   * Reuses the shared in-memory dependency graph when possible and otherwise
-   * creates the Bun-compatible default graph implementation.
-   */
-  createEntrypointDependencyGraph(existingEntrypointDependencyGraph) {
-    return existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new InMemoryEntrypointDependencyGraph();
-  }
-  /**
-   * 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.
-   */
-  getWebSocketHandler() {
-    const bridge = this.bridge;
-    const open = (ws) => {
-      bridge.subscribe(ws);
-      appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${bridge.subscriberCount}`);
-    };
-    const close = (ws) => {
-      bridge.unsubscribe(ws);
-      appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${bridge.subscriberCount}`);
-    };
-    this.wsHandler = { open, close };
-    return {
-      open: this.wsHandler.open,
-      close: this.wsHandler.close,
-      message: (_ws, message) => {
-        appLogger.debug("[HMR] Received message from client:", message);
-      }
-    };
-  }
+import { appLogger } from '../../global/app-logger.js';
+import { InMemoryEntrypointDependencyGraph, } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
+/**
+ * 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 class HmrManager extends SharedHmrManager {
+    wsHandler;
+    /**
+     * Creates the Bun HMR manager around the shared HMR orchestration pipeline.
+     *
+     * @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.
+     */
+    constructor({ appConfig, bridge }) {
+        super({ appConfig, bridge });
+    }
+    /**
+     * Reuses the shared in-memory dependency graph when possible and otherwise
+     * creates the Bun-compatible default graph implementation.
+     */
+    createEntrypointDependencyGraph(existingEntrypointDependencyGraph) {
+        return existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph
+            ? existingEntrypointDependencyGraph
+            : new InMemoryEntrypointDependencyGraph();
+    }
+    /**
+     * 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.
+     */
+    getWebSocketHandler() {
+        const bridge = this.bridge;
+        const open = (ws) => {
+            bridge.subscribe(ws);
+            appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${bridge.subscriberCount}`);
+        };
+        const close = (ws) => {
+            bridge.unsubscribe(ws);
+            appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${bridge.subscriberCount}`);
+        };
+        this.wsHandler = { open, close };
+        return {
+            open: this.wsHandler.open,
+            close: this.wsHandler.close,
+            message: (_ws, message) => {
+                appLogger.debug('[HMR] Received message from client:', message);
+            },
+        };
+    }
 }
-export {
-  HmrManager
-};

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

@@ -1,2 +1,2 @@
 export { BunEcopagesApp, createApp } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, type GroupHandler, } from '../shared/http/define-api-handler.js';

package/src/adapters/bun/index.js

@@ -1,8 +1,2 @@
-import { BunEcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "../shared/define-api-handler.js";
-export {
-  BunEcopagesApp,
-  createApp,
-  defineApiHandler,
-  defineGroupHandler
-};
+export { BunEcopagesApp, createApp } from './create-app.js';
+export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, } from '../shared/http/define-api-handler.js';

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

@@ -1,5 +1,5 @@
 import type { Server } from 'bun';
-import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime/runtime-host.js';
 type BunRuntimeProvider = {
     serve(options: Bun.Serve.Options<unknown>): Server<unknown>;
 };

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

@@ -1,56 +1,63 @@
-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");
+import { getBunRuntime } from '../../utils/runtime.js';
+import { resolveServeRuntimeOrigin } from '../shared/runtime/runtime-app-bootstrap.js';
+/**
+ * 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 class BunRuntimeHost {
+    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 = () => getBunRuntime() ?? null) {
+        this.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,
+        });
     }
-    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
-};