@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/adapters/node/static-content-server.js

@@ -1,197 +1,183 @@
-import { createServer } from "node:http";
-import { extname, join, normalize, sep } from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../config/constants.js";
-import { fileSystem } from "@ecopages/file-system";
-import { ServerUtils } from "../../utils/server-utils.module.js";
-class NodeStaticContentServer {
-  appConfig;
-  options;
-  server = null;
-  /**
-   * Creates the Node static-content server for one built app output directory.
-   */
-  constructor({ appConfig, options }) {
-    this.appConfig = appConfig;
-    this.options = {
-      hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
-      port: options?.port ?? DEFAULT_ECOPAGES_PORT
-    };
-  }
-  /**
-   * Returns whether the given content type should be served from a pre-gzipped
-   * companion file when available.
-   */
-  shouldServeGzip(contentType) {
-    return ["text/javascript", "text/css"].includes(contentType);
-  }
-  /**
-   * Normalizes a request pathname and rejects directory traversal attempts.
-   */
-  sanitizePath(pathname) {
-    const withoutLeadingSlash = pathname.replace(/^\/+/, "");
-    const normalizedPath = normalize(withoutLeadingSlash);
-    if (normalizedPath.startsWith("..") || normalizedPath.includes(`..${sep}`)) {
-      return null;
+import { createServer } from 'node:http';
+import { extname, join, normalize, sep } from 'node:path';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from '../../config/constants.js';
+import { fileSystem } from '@ecopages/file-system';
+import { ServerUtils } from '../../utils/server-utils.module.js';
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
+export class NodeStaticContentServer {
+    appConfig;
+    options;
+    server = null;
+    /**
+     * Creates the Node static-content server for one built app output directory.
+     */
+    constructor({ appConfig, options }) {
+        this.appConfig = appConfig;
+        this.options = {
+            hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
+            port: options?.port ?? DEFAULT_ECOPAGES_PORT,
+        };
     }
-    return normalizedPath;
-  }
-  /**
-   * Writes one HTTP response with the provided headers and optional body.
-   */
-  sendResponse(res, status, headers, body) {
-    res.statusCode = status;
-    for (const [key, value] of Object.entries(headers)) {
-      res.setHeader(key, value);
+    /**
+     * Returns whether the given content type should be served from a pre-gzipped
+     * companion file when available.
+     */
+    shouldServeGzip(contentType) {
+        return ['text/javascript', 'text/css'].includes(contentType);
     }
-    if (!body) {
-      res.end();
-      return;
-    }
-    res.end(body);
-  }
-  /**
-   * Serves the generated 404 page when present, or a plain-text fallback.
-   */
-  sendNotFoundPage(req, res) {
-    const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, "404.html");
-    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
-    if (!fileSystem.exists(error404TemplatePath)) {
-      this.sendResponse(
-        res,
-        404,
-        { "Content-Type": "text/plain" },
-        isHead ? void 0 : Buffer.from(STATUS_MESSAGE[404])
-      );
-      return;
-    }
-    const file = fileSystem.readFileAsBuffer(error404TemplatePath);
-    this.sendResponse(res, 404, { "Content-Type": "text/html" }, isHead ? void 0 : file);
-  }
-  /**
-   * Serves one concrete file path, honoring gzip and HEAD semantics.
-   */
-  serveFile(req, res, filePath, status = 200) {
-    const contentType = ServerUtils.getContentType(extname(filePath));
-    const acceptsGzip = req.headers["accept-encoding"]?.includes("gzip");
-    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
-    if (acceptsGzip && this.shouldServeGzip(contentType)) {
-      const gzipPath = `${filePath}.gz`;
-      if (fileSystem.exists(gzipPath)) {
-        const file2 = fileSystem.readFileAsBuffer(gzipPath);
-        this.sendResponse(
-          res,
-          status,
-          {
-            "Content-Type": contentType,
-            "Content-Encoding": "gzip",
-            Vary: "Accept-Encoding"
-          },
-          isHead ? void 0 : file2
-        );
-        return;
-      }
-    }
-    if (!fileSystem.exists(filePath)) {
-      this.sendNotFoundPage(req, res);
-      return;
+    /**
+     * Normalizes a request pathname and rejects directory traversal attempts.
+     */
+    sanitizePath(pathname) {
+        const withoutLeadingSlash = pathname.replace(/^\/+/, '');
+        const normalizedPath = normalize(withoutLeadingSlash);
+        if (normalizedPath.startsWith('..') || normalizedPath.includes(`..${sep}`)) {
+            return null;
+        }
+        return normalizedPath;
     }
-    const file = fileSystem.readFileAsBuffer(filePath);
-    this.sendResponse(res, status, { "Content-Type": contentType }, isHead ? void 0 : file);
-  }
-  /**
-   * Handles one incoming Node HTTP request against the built static output tree.
-   */
-  handleRequest(req, res) {
-    const method = (req.method ?? "GET").toUpperCase();
-    const isHead = method === "HEAD";
-    if (method !== "GET" && method !== "HEAD") {
-      this.sendResponse(
-        res,
-        405,
-        { Allow: "GET, HEAD", "Content-Type": "text/plain" },
-        isHead ? void 0 : Buffer.from("Method Not Allowed")
-      );
-      return;
+    /**
+     * Writes one HTTP response with the provided headers and optional body.
+     */
+    sendResponse(res, status, headers, body) {
+        res.statusCode = status;
+        for (const [key, value] of Object.entries(headers)) {
+            res.setHeader(key, value);
+        }
+        if (!body) {
+            res.end();
+            return;
+        }
+        res.end(body);
     }
-    const url = new URL(req.url ?? "/", "http://localhost");
-    let decodedPathname = "/";
-    try {
-      decodedPathname = decodeURIComponent(url.pathname);
-    } catch {
-      this.sendResponse(
-        res,
-        400,
-        { "Content-Type": "text/plain" },
-        isHead ? void 0 : Buffer.from("Invalid path")
-      );
-      return;
+    /**
+     * Serves the generated 404 page when present, or a plain-text fallback.
+     */
+    sendNotFoundPage(req, res) {
+        const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, '404.html');
+        const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
+        if (!fileSystem.exists(error404TemplatePath)) {
+            this.sendResponse(res, 404, { 'Content-Type': 'text/plain' }, isHead ? undefined : Buffer.from(STATUS_MESSAGE[404]));
+            return;
+        }
+        const file = fileSystem.readFileAsBuffer(error404TemplatePath);
+        this.sendResponse(res, 404, { 'Content-Type': 'text/html' }, isHead ? undefined : file);
     }
-    const pathname = decodedPathname === "/" ? "/index.html" : decodedPathname;
-    const relativePath = this.sanitizePath(pathname);
-    if (!relativePath) {
-      this.sendResponse(
-        res,
-        400,
-        { "Content-Type": "text/plain" },
-        isHead ? void 0 : Buffer.from("Invalid path")
-      );
-      return;
+    /**
+     * Serves one concrete file path, honoring gzip and HEAD semantics.
+     */
+    serveFile(req, res, filePath, status = 200) {
+        const contentType = ServerUtils.getContentType(extname(filePath));
+        const acceptsGzip = req.headers['accept-encoding']?.includes('gzip');
+        const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
+        if (acceptsGzip && this.shouldServeGzip(contentType)) {
+            const gzipPath = `${filePath}.gz`;
+            if (fileSystem.exists(gzipPath)) {
+                const file = fileSystem.readFileAsBuffer(gzipPath);
+                this.sendResponse(res, status, {
+                    'Content-Type': contentType,
+                    'Content-Encoding': 'gzip',
+                    Vary: 'Accept-Encoding',
+                }, isHead ? undefined : file);
+                return;
+            }
+        }
+        if (!fileSystem.exists(filePath)) {
+            this.sendNotFoundPage(req, res);
+            return;
+        }
+        const file = fileSystem.readFileAsBuffer(filePath);
+        this.sendResponse(res, status, { 'Content-Type': contentType }, isHead ? undefined : file);
     }
-    const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
-    if (pathname.includes(".")) {
-      this.serveFile(req, res, basePath);
-      return;
+    /**
+     * Handles one incoming Node HTTP request against the built static output tree.
+     */
+    handleRequest(req, res) {
+        const method = (req.method ?? 'GET').toUpperCase();
+        const isHead = method === 'HEAD';
+        if (method !== 'GET' && method !== 'HEAD') {
+            this.sendResponse(res, 405, { Allow: 'GET, HEAD', 'Content-Type': 'text/plain' }, isHead ? undefined : Buffer.from('Method Not Allowed'));
+            return;
+        }
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        let decodedPathname = '/';
+        try {
+            decodedPathname = decodeURIComponent(url.pathname);
+        }
+        catch {
+            this.sendResponse(res, 400, { 'Content-Type': 'text/plain' }, isHead ? undefined : Buffer.from('Invalid path'));
+            return;
+        }
+        const pathname = decodedPathname === '/' ? '/index.html' : decodedPathname;
+        const relativePath = this.sanitizePath(pathname);
+        if (!relativePath) {
+            this.sendResponse(res, 400, { 'Content-Type': 'text/plain' }, isHead ? undefined : Buffer.from('Invalid path'));
+            return;
+        }
+        const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
+        if (pathname.includes('.')) {
+            this.serveFile(req, res, basePath);
+            return;
+        }
+        const htmlCandidates = [`${basePath}.html`, join(basePath, 'index.html')];
+        for (const candidate of htmlCandidates) {
+            if (fileSystem.exists(candidate)) {
+                this.serveFile(req, res, candidate);
+                return;
+            }
+        }
+        this.sendNotFoundPage(req, res);
     }
-    const htmlCandidates = [`${basePath}.html`, join(basePath, "index.html")];
-    for (const candidate of htmlCandidates) {
-      if (fileSystem.exists(candidate)) {
-        this.serveFile(req, res, candidate);
-        return;
-      }
+    /**
+     * Starts the static preview server.
+     */
+    async start() {
+        if (this.server) {
+            return this.server;
+        }
+        this.server = createServer(this.handleRequest.bind(this));
+        const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+        const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
+        await new Promise((resolve, reject) => {
+            const activeServer = this.server;
+            activeServer.once('error', reject);
+            activeServer.listen(port, hostname, () => {
+                activeServer.off('error', reject);
+                resolve();
+            });
+        });
+        return this.server;
     }
-    this.sendNotFoundPage(req, res);
-  }
-  /**
-   * Starts the static preview server.
-   */
-  async start() {
-    if (this.server) {
-      return this.server;
+    /**
+     * Stops the static preview server and optionally closes active connections.
+     */
+    async stop(force = true) {
+        if (!this.server) {
+            return;
+        }
+        const activeServer = this.server;
+        this.server = null;
+        await new Promise((resolve, reject) => {
+            activeServer.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+            if (force) {
+                activeServer.closeAllConnections();
+            }
+        });
     }
-    this.server = createServer(this.handleRequest.bind(this));
-    const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-    const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
-    await new Promise((resolve) => {
-      this.server.listen(port, hostname, () => resolve());
-    });
-    return this.server;
-  }
-  /**
-   * Stops the static preview server and optionally closes active connections.
-   */
-  async stop(force = true) {
-    if (!this.server) {
-      return;
+    async [Symbol.asyncDispose]() {
+        await this.stop();
     }
-    const activeServer = this.server;
-    this.server = null;
-    await new Promise((resolve, reject) => {
-      activeServer.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      if (force) {
-        activeServer.closeAllConnections();
-      }
-    });
-  }
-  async [Symbol.asyncDispose]() {
-    await this.stop();
-  }
 }
-export {
-  NodeStaticContentServer
-};

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

@@ -1,6 +1,6 @@
 import type { AddressInfo } from 'node:net';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/runtime/static-preview-host.js';
 type NodeStaticPreviewServer = {
     start(): Promise<{
         address(): AddressInfo | string | null;

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

@@ -1,68 +1,92 @@
-import { NodeStaticContentServer } from "./static-content-server.js";
-class NodeStaticPreviewHost {
-  /**
-   * Creates the preview host with an injectable preview-server constructor.
-   */
-  constructor(previewServerFactory = NodeStaticContentServer) {
-    this.previewServerFactory = previewServerFactory;
-  }
-  previewServerFactory;
-  previewServer = null;
-  stopPromise = null;
-  /**
-   * Starts the Node preview host after fully draining any previous preview server
-   * shutdown that may still be in flight.
-   *
-   * @remarks
-   * The host only publishes a new preview server after `start()` succeeds. That
-   * keeps failed startup attempts from replacing the last known-good server with a
-   * half-initialized instance.
-   */
-  async start(options) {
-    await this.stop();
-    const previewServer = new this.previewServerFactory({
-      appConfig: options.appConfig,
-      options: {
-        hostname: options.hostname,
-        port: options.port
-      }
-    });
-    const server = await previewServer.start();
-    this.previewServer = previewServer;
-    const address = server.address();
-    if (address && typeof address === "object") {
-      return address.port;
+import { appLogger } from '../../global/app-logger.js';
+import { PortManager } from '../shared/runtime/port-manager.js';
+import { NodeStaticContentServer } from './static-content-server.js';
+/**
+ * Node preview-host wrapper that manages the lifecycle of the static preview
+ * server used after a build.
+ *
+ * @remarks
+ * The host separates preview-server construction from lifecycle control so the
+ * Node server adapter can restart preview serving safely across repeated build
+ * and preview flows.
+ */
+export class NodeStaticPreviewHost {
+    previewServerFactory;
+    previewServer = null;
+    stopPromise = null;
+    /**
+     * Creates the preview host with an injectable preview-server constructor.
+     */
+    constructor(previewServerFactory = NodeStaticContentServer) {
+        this.previewServerFactory = previewServerFactory;
     }
-    return options.port;
-  }
-  /**
-   * Stops the active preview server and coalesces overlapping stop requests onto
-   * the same shutdown promise.
-   *
-   * @remarks
-   * The host keeps the server reference until shutdown succeeds. If shutdown
-   * fails, callers can still retry `stop()` or inspect the same live instance
-   * instead of losing the handle during a rejected async stop.
-   */
-  async stop(force = true) {
-    if (this.stopPromise) {
-      await this.stopPromise;
-      return;
+    /**
+     * Starts the Node preview host after fully draining any previous preview server
+     * shutdown that may still be in flight.
+     *
+     * @remarks
+     * The host only publishes a new preview server after `start()` succeeds. That
+     * keeps failed startup attempts from replacing the last known-good server with a
+     * half-initialized instance.
+     */
+    async start(options) {
+        await this.stop();
+        const portManager = new PortManager({
+            startOnPort: async (port) => {
+                const previewServer = new this.previewServerFactory({
+                    appConfig: options.appConfig,
+                    options: {
+                        hostname: options.hostname,
+                        port,
+                    },
+                });
+                const server = await previewServer.start();
+                this.previewServer = previewServer;
+                const address = server.address();
+                if (address && typeof address === 'object') {
+                    return address.port;
+                }
+                return port;
+            },
+            warn: (message) => appLogger.warn(message),
+        });
+        const previewPort = await portManager.bind({
+            preferredPort: options.port,
+            allowPortFallback: options.allowPortFallback === true,
+        });
+        if (!previewPort) {
+            this.previewServer = null;
+        }
+        return previewPort;
     }
-    if (!this.previewServer) {
-      return;
+    /**
+     * Stops the active preview server and coalesces overlapping stop requests onto
+     * the same shutdown promise.
+     *
+     * @remarks
+     * The host keeps the server reference until shutdown succeeds. If shutdown
+     * fails, callers can still retry `stop()` or inspect the same live instance
+     * instead of losing the handle during a rejected async stop.
+     */
+    async stop(force = true) {
+        if (this.stopPromise) {
+            await this.stopPromise;
+            return;
+        }
+        if (!this.previewServer) {
+            return;
+        }
+        const activePreviewServer = this.previewServer;
+        this.stopPromise = activePreviewServer
+            .stop(force)
+            .then(() => {
+            if (this.previewServer === activePreviewServer) {
+                this.previewServer = null;
+            }
+        })
+            .finally(() => {
+            this.stopPromise = null;
+        });
+        await this.stopPromise;
     }
-    const activePreviewServer = this.previewServer;
-    this.stopPromise = activePreviewServer.stop(force).then(() => {
-      if (this.previewServer === activePreviewServer) {
-        this.previewServer = null;
-      }
-    }).finally(() => {
-      this.stopPromise = null;
-    });
-    await this.stopPromise;
-  }
 }
-export {
-  NodeStaticPreviewHost
-};

package/src/adapters/shared/hmr/dev-transform-entrypoint-registry.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedHmrEntrypoint } from '../../../hmr/hmr-entrypoint-output.js';
+/**
+ * Tracks dev-transform entrypoints registered for HMR invalidation.
+ */
+export declare class DevTransformEntrypointRegistry {
+    private readonly registered;
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    getWatchedOutputUrls(): Map<string, string>;
+    clearRegistration(entrypointPath: string): void;
+    registerTransformModule(sourcePath: string, outputUrl: string, options: {
+        role: 'page';
+    } | {
+        role: 'script';
+    }): void;
+    clearAll(): void;
+}

package/src/adapters/shared/hmr/dev-transform-entrypoint-registry.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+/**
+ * Tracks dev-transform entrypoints registered for HMR invalidation.
+ */
+export class DevTransformEntrypointRegistry {
+    registered = new Map();
+    getRegisteredEntrypoints() {
+        return this.registered;
+    }
+    getWatchedOutputUrls() {
+        const watchedFiles = new Map();
+        for (const [sourcePath, entrypoint] of this.registered) {
+            watchedFiles.set(sourcePath, entrypoint.outputUrl);
+        }
+        return watchedFiles;
+    }
+    clearRegistration(entrypointPath) {
+        this.registered.delete(path.resolve(entrypointPath));
+    }
+    registerTransformModule(sourcePath, outputUrl, options) {
+        const normalized = path.resolve(sourcePath);
+        this.registered.set(normalized, {
+            sourcePath: normalized,
+            outputPath: normalized,
+            outputUrl,
+            role: options.role,
+        });
+    }
+    clearAll() {
+        this.registered.clear();
+    }
+}

package/src/adapters/shared/{hmr-html-response.d.ts → hmr/hmr-html-response.d.ts}

@@ -1,4 +1,4 @@
-import type { IHmrManager } from '../../types/public-types.js';
+import type { IHmrManager } from '../../../types/public-types.js';
 /**
  * Returns whether a response is HTML and therefore eligible for development HMR
  * runtime injection.
@@ -11,7 +11,7 @@ export declare function isHtmlResponse(response: Response): boolean;
  * responses flow through different layers, but both need identical injection
  * behavior in watch mode.
  */
-export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>, hostOwnsDevClient?: boolean): boolean;
 /**
  * Injects the development HMR runtime script into an HTML response if it is not
  * already present.

package/src/adapters/shared/hmr/hmr-html-response.js

@@ -0,0 +1,50 @@
+import { HMR_RUNTIME_SCRIPT_URL } from '../../../hmr/hmr-runtime-paths.js';
+const HMR_RUNTIME_IMPORT = `import '${HMR_RUNTIME_SCRIPT_URL}'`;
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};</script>`;
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export function isHtmlResponse(response) {
+    const contentType = response.headers.get('Content-Type');
+    return contentType !== null && contentType.startsWith('text/html');
+}
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export function shouldInjectHmrHtmlResponse(watch, hmrManager, hostOwnsDevClient = false) {
+    if (hostOwnsDevClient) {
+        return false;
+    }
+    return watch && hmrManager?.isEnabled() === true;
+}
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export async function injectHmrRuntimeIntoHtmlResponse(response) {
+    const html = await response.text();
+    const headers = new Headers(response.headers);
+    headers.set('Cache-Control', 'no-store, must-revalidate');
+    headers.delete('Content-Length');
+    if (html.includes(HMR_RUNTIME_IMPORT)) {
+        return new Response(html, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+        });
+    }
+    const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+    return new Response(updatedHtml, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}