@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

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

@@ -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, {
@@ -17,8 +18,11 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
     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,36 @@
 import { appLogger } from "../../global/app-logger.js";
 import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { resolveRuntimeBinding } from "../shared/runtime-app-bootstrap.js";
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/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";
 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 initializeServerAdapter() {
     const binding = resolveRuntimeBinding({
@@ -36,23 +44,43 @@ 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) {
+        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) {
+        this.notifyListening(previewOrigin);
+      }
       if (build) {
         process.exit(0);
       }
@@ -67,7 +95,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}`);
+    this.notifyListening(this.runtimeOrigin);
     return this.server;
   }
   async fetch(request) {
@@ -76,6 +104,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

@@ -4,6 +4,7 @@ import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
+    registrationTimeoutMs?: number;
 }
 /**
  * Node development HMR manager.
@@ -28,7 +29,7 @@ export declare class NodeHmrManager extends SharedHmrManager {
      * actually differs: dependency-graph storage, missing-file tolerance, and how
      * runtime bundle failures disable HMR.
      */
-    constructor({ appConfig, bridge }: NodeHmrManagerParams);
+    constructor({ appConfig, bridge, registrationTimeoutMs }: NodeHmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when the app already has one and
      * otherwise creates the default Node development graph.

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

@@ -13,8 +13,8 @@ class NodeHmrManager extends SharedHmrManager {
    * actually differs: dependency-graph storage, missing-file tolerance, and how
    * runtime bundle failures disable HMR.
    */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
+    super({ appConfig, bridge, registrationTimeoutMs });
   }
   /**
    * Reuses the shared in-memory dependency graph when the app already has one and

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,6 +1,6 @@
 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 type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
@@ -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,47 @@ 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;
+    /**
+     * 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;
     private maybeInjectHmrScript;
-    constructor(options: NodeServerAdapterParams);
+    /**
+     * @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 +122,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 +165,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>;