@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/adapters/create-app.js

@@ -1,10 +1,10 @@
 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 adapter = options.adapter ?? "auto";
   const bun = globalThis.Bun;
-  if (bun) {
+  if (adapter === "bun" || adapter === "auto" && bun) {
     return await createBunApp(options);
   }
   return await createNodeApp(options);
@@ -12,55 +12,6 @@ async function createRuntimeApp(options) {
 async function createApp(options) {
   return createRuntimeApp(options);
 }
-class EcopagesApp extends SharedApplicationAdapter {
-  appOptions;
-  runtimeApp = null;
-  runtimeAppPromise = null;
-  constructor(options) {
-    super(options);
-    this.appOptions = options;
-  }
-  async getRuntimeApp() {
-    if (this.runtimeApp) {
-      return this.runtimeApp;
-    }
-    if (!this.runtimeAppPromise) {
-      this.runtimeAppPromise = createRuntimeApp({
-        ...this.appOptions,
-        clearOutput: false
-      }).then((app) => {
-        for (const handler of this.apiHandlers) {
-          app.add(handler);
-        }
-        for (const route of this.staticRoutes) {
-          app.static(route.path, route.loader);
-        }
-        if (this.errorHandler) {
-          app.onError(this.errorHandler);
-        }
-        this.runtimeApp = app;
-        return app;
-      });
-    }
-    return this.runtimeAppPromise;
-  }
-  async initializeServerAdapter() {
-    return this.getRuntimeApp();
-  }
-  async start() {
-    const runtimeApp = await this.getRuntimeApp();
-    return runtimeApp.start();
-  }
-  async fetch(request) {
-    const runtimeApp = await this.getRuntimeApp();
-    const candidate = runtimeApp;
-    if (!candidate.fetch) {
-      throw new Error("The selected runtime adapter does not expose fetch()");
-    }
-    return candidate.fetch(request);
-  }
-}
 export {
-  EcopagesApp,
   createApp
 };

package/src/adapters/index.d.ts

@@ -1,2 +1,2 @@
-export { EcopagesApp, createApp } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.js';
+export { createApp } from './create-app.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/index.js

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

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

@@ -1,5 +1,5 @@
-import { SharedApplicationAdapter } from '../shared/application-adapter.js';
-import type { RuntimeHost } from '../shared/runtime-host.js';
+import { SharedApplicationAdapter } from '../shared/runtime/application-adapter.js';
+import type { RuntimeHost } from '../shared/runtime/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';
@@ -7,6 +7,7 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     serverAdapter: NodeServerAdapterResult | undefined;
     private server;
     private runtimeOrigin;
+    private stopped;
     private readonly runtimeHost;
     constructor(options: EcopagesAppOptions, dependencies: {
         runtimeHost: RuntimeHost<NodeServerInstance, {
@@ -16,9 +17,13 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     });
     protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
+    protected resolveAppRoutes(): Promise<import("../../index.browser.js").EcopagesRouteInfo[]>;
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
-    start(): Promise<NodeServerInstance | void>;
+    protected bootServer(): Promise<NodeServerInstance | void>;
     fetch(request: Request): Promise<Response>;
+    attachWebSocketUpgrades(httpServer: import('node:http').Server, options?: {
+        passthroughUnmatched?: boolean;
+    }): Promise<void>;
 }
 export declare function createNodeApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;
 export declare function createApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;

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

@@ -1,28 +1,44 @@
 import { appLogger } from "../../global/app-logger.js";
-import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { resolveRuntimeBinding } from "../shared/runtime-app-bootstrap.js";
+import { SharedApplicationAdapter } from "../shared/runtime/application-adapter.js";
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime/runtime-app-bootstrap.js";
 import { createNodeServerAdapter } from "./server-adapter.js";
 import { NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeRuntimeHost } from "./runtime-host.js";
+import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
+import { resolveAppStartRoutes } from "../../utils/ecopages-route-info.js";
 class NodeEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
   runtimeOrigin = "";
+  stopped = false;
   runtimeHost;
   constructor(options, dependencies) {
-    super(options);
+    super(options, "Node");
     this.runtimeHost = dependencies.runtimeHost;
   }
   createServerAdapter(params) {
     return createNodeServerAdapter(params);
   }
   async stop(force = true) {
-    if (!this.server) {
+    if (this.stopped) {
       return;
     }
-    const activeServer = this.server;
-    this.server = null;
-    await this.runtimeHost.stop(activeServer, { force });
+    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
+    });
   }
   async initializeServerAdapter() {
     const binding = resolveRuntimeBinding({
@@ -36,29 +52,50 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       apiHandlers: this.apiHandlers,
       staticRoutes: this.staticRoutes,
       errorHandler: this.errorHandler,
+      websocketHandlers: this.websocketHandlers.size > 0 ? this.websocketHandlers : void 0,
       options: { watch: binding.watch },
-      serveOptions: binding.serveOptions
+      serveOptions: binding.serveOptions,
+      hostOwnsDevClient: hostOwnsDevClient(this.runtimeOptions),
+      deferRuntimeAssetSetup: resolveStaticRuntimeMode({
+        appConfig: this.appConfig,
+        cliArgs: this.cliArgs
+      }).canBuildWithoutRuntimeServer,
+      allowPortFallback: binding.allowPortFallback
     });
   }
-  async start() {
+  async bootServer() {
+    if (this.stopped) {
+      this.serverAdapter = void 0;
+      this.stopped = false;
+    }
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
     }
     if (this.server) {
       return this.server;
     }
-    const { build, preview } = this.cliArgs;
+    const { build, preview, force, serveOnly } = this.cliArgs;
+    if (preview && serveOnly) {
+      const previewOrigin = await this.serverAdapter.servePreviewOnly();
+      if (previewOrigin) {
+        await this.notifyListening(previewOrigin);
+      }
+      return;
+    }
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
-      await this.stop(true);
+      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;
     }
     const serveOptions = this.serverAdapter.getServerOptions();
+    startupTrace.beginServerListen();
     this.server = await this.runtimeHost.start({
       serveOptions,
       handleRequest: async (request) => await this.serverAdapter.handleRequest(request),
@@ -67,7 +104,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     });
     this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
     await this.serverAdapter.completeInitialization(this.server);
-    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    await this.notifyListening(this.runtimeOrigin);
     return this.server;
   }
   async fetch(request) {
@@ -76,6 +113,17 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     }
     return this.serverAdapter.handleRequest(request);
   }
+  async attachWebSocketUpgrades(httpServer, options) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    if (!this.server) {
+      this.server = httpServer;
+      await this.serverAdapter.completeInitialization(httpServer);
+      return;
+    }
+    this.serverAdapter.attachUserWebSocketUpgrades(httpServer, options);
+  }
 }
 async function createNodeApp(options) {
   return new NodeEcopagesApp(options, {

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

@@ -23,4 +23,5 @@ export declare class NodeClientBridge implements IClientBridge {
      * Call this when the dev server is shutting down.
      */
     destroy(): void;
+    [Symbol.dispose](): void;
 }

package/src/adapters/node/node-client-bridge.js

@@ -60,6 +60,9 @@ class NodeClientBridge {
     }
     this.subscribers.clear();
   }
+  [Symbol.dispose]() {
+    this.destroy();
+  }
 }
 export {
   NodeClientBridge

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

@@ -1,6 +1,6 @@
 import type { EcoPagesAppConfig, IClientBridge } from '../../types/internal-types.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';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;

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

@@ -2,7 +2,7 @@ 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";
+import { SharedHmrManager } from "../shared/hmr/shared-hmr-manager.js";
 class NodeHmrManager extends SharedHmrManager {
   /**
    * Creates the Node HMR manager over the shared coordination pipeline.

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

@@ -1,5 +1,5 @@
 import { createServer, type Server as NodeServerInstance } from 'node:http';
-import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime/runtime-host.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
 type NodeServerFactory = typeof createServer;
 /**

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

@@ -1,7 +1,7 @@
 import { createServer } from "node:http";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime/runtime-app-bootstrap.js";
 import { isNodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
 class NodeRuntimeHost {
   /**

package/src/adapters/node/server-adapter-dependencies.js

@@ -1,4 +1,6 @@
 import { WebSocketServer } from "ws";
+import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { setAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 class DefaultNodeServerDevRuntimeFactory {
@@ -6,6 +8,8 @@ class DefaultNodeServerDevRuntimeFactory {
     const websocketServer = new WebSocketServer({ noServer: true });
     const bridge = new NodeClientBridge();
     const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
+    setAppDevClientBridge(options.appConfig, bridge);
+    setAppHmrManager(options.appConfig, hmrManager);
     return {
       websocketServer,
       bridge,

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

@@ -1,10 +1,10 @@
 import { type Server as NodeHttpServer } from 'node:http';
 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 { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { SharedServerAdapter } from '../shared/runtime/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost } from '../shared/runtime/static-preview-host.js';
 import { type NodeServerDevRuntimeFactory } from './server-adapter-dependencies.js';
 export type NodeServerInstance = NodeHttpServer;
 export type NodeServeAdapterServerOptions = {
@@ -19,9 +19,14 @@ export interface NodeServerAdapterParams {
     apiHandlers?: ApiHandler[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
+    delegateBrowserReloadToHost?: boolean;
+    hostOwnsDevClient?: boolean;
     options?: {
         watch?: boolean;
     };
+    deferRuntimeAssetSetup?: boolean;
+    allowPortFallback?: boolean;
     previewHost?: StaticPreviewHost;
     requestBridge?: NodeHttpRequestBridge;
     devRuntimeFactory?: NodeServerDevRuntimeFactory;
@@ -29,6 +34,10 @@ export interface NodeServerAdapterParams {
 export interface NodeServerAdapterResult extends ServerAdapterResult {
     completeInitialization: (server: NodeServerInstance) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Node.js HTTP server adapter for the Ecopages runtime.
@@ -58,13 +67,46 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private errorHandler?;
     private bridge;
     private hmrManager;
+    private projectWatcher;
+    private adapterDisposed;
+    private readonly deferRuntimeAssetSetup;
+    private readonly allowPortFallback;
     private readonly previewHost;
     private readonly requestBridge;
     private readonly devRuntimeFactory;
-    private shouldInjectHmrScript;
-    private isHtmlResponse;
-    private maybeInjectHmrScript;
-    constructor(options: NodeServerAdapterParams);
+    /**
+     * Reference to the application-level WebSocket handlers map.
+     *
+     * @remarks
+     * This is a reference to the map owned by `AbstractApplicationAdapter`,
+     * passed in via the constructor. The Node adapter reads from it to wire
+     * WebSocket upgrades for user-registered patterns.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * Wires user WebSocket routes onto a foreign Node HTTP server.
+     *
+     * Host integrations such as the Vite plugin call this so `app.websocket()`
+     * handlers work while HTTP is still served by the host dev server.
+     */
+    attachUserWebSocketUpgrades(server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
+    private wireUserWebSocketUpgrades;
+    /**
+     * @remarks
+     * `previewHost`, `requestBridge`, and `devRuntimeFactory` are optional on the
+     * public {@link NodeServerAdapterParams} so factory callers can omit them, but
+     * they are mandatory by the time the concrete adapter is constructed —
+     * {@link createNodeServerAdapter} fills in Node-specific defaults first. The
+     * constructor signature makes that invariant explicit instead of relying on
+     * non-null assertions.
+     */
+    constructor(options: NodeServerAdapterParams & {
+        previewHost: StaticPreviewHost;
+        requestBridge: NodeHttpRequestBridge;
+        devRuntimeFactory: NodeServerDevRuntimeFactory;
+    });
     /**
      * Prepares the adapter for use.
      *
@@ -79,27 +121,26 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *    processors during their `setup()` calls.
      */
     initialize(): Promise<void>;
-    private prepareRuntimePublicDir;
     getServerOptions(): NodeServeAdapterServerOptions;
     buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
-    private startBuildRuntimeServer;
-    private getListeningServerOrigin;
+        force?: boolean;
+    }): Promise<string | undefined>;
     /**
-     * Gracefully shuts down the ephemeral build runtime server.
-     *
-     * `closeAllConnections()` is called *before* `close()` because `server.close()`
-     * only stops accepting new connections — it waits for existing keep-alive
-     * connections to finish naturally, which can stall the build indefinitely.
-     * `closeAllConnections()` force-closes any lingering sockets immediately so
-     * the `close()` callback fires promptly.
-     *
-     * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-     * does not prevent the Node.js process from exiting cleanly after the build.
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
      */
-    private stopBuildRuntimeServer;
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     createAdapter(): Promise<NodeServerAdapterResult>;
+    /**
+     * Releases dev-time resources owned by the adapter.
+     *
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound HTTP server — callers
+     * should shut down transport through the runtime host before disposing.
+     */
+    dispose(): Promise<void>;
     /**
      * Handles a single incoming Web `Request` and returns a Web `Response`.
      *
@@ -123,7 +164,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * - Shared watcher bootstrapping listens for route-level file changes and
      *   refreshes the router and response handlers when pages are added or removed.
      *
-     * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
+     * WebSocket upgrade requests that do not match a known path are rejected with an
      * immediate socket destroy to prevent unhandled upgrade leaks.
      */
     completeInitialization(server: NodeServerInstance): Promise<void>;