@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/adapters/node/bootstrap-dependency-resolver.js

@@ -0,0 +1,172 @@
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+function getNodeRuntimeNodeModulesDir(manifest) {
+  return path.join(
+    resolveInternalExecutionDir({
+      rootDir: manifest.appRootDir,
+      workDir: manifest.workDir,
+      absolutePaths: {
+        workDir: manifest.workDir,
+        distDir: manifest.distDir
+      }
+    }),
+    "node_modules"
+  );
+}
+function getAppRuntimeNodeModulesDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), "node_modules");
+}
+function getPackageNameFromSpecifier(specifier) {
+  if (specifier.startsWith("@")) {
+    const [scope, name] = specifier.split("/");
+    return `${scope}/${name}`;
+  }
+  return specifier.split("/")[0] ?? specifier;
+}
+function findPackageRoot(resolvedPath) {
+  let currentPath = path.dirname(resolvedPath);
+  while (true) {
+    const packageJsonPath = path.join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return currentPath;
+    }
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`Could not find package root for resolved dependency path: ${resolvedPath}`);
+    }
+    currentPath = parentPath;
+  }
+}
+function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  const packageRoot = findPackageRoot(resolvedPath);
+  const linkPath = path.join(nodeModulesDir, packageName);
+  if (existsSync(linkPath)) {
+    return;
+  }
+  mkdirSync(path.dirname(linkPath), { recursive: true });
+  symlinkSync(packageRoot, linkPath, "dir");
+}
+function getNodeUnsupportedBuiltinError(specifier, importer) {
+  return `Node thin-host bootstrap does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
+}
+function shouldResolveFromImporter(importer) {
+  return Boolean(importer && importer.includes(`${path.sep}node_modules${path.sep}`));
+}
+function getBootstrapBuildLoaderForPath(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    case ".json":
+      return "json";
+    default:
+      return "js";
+  }
+}
+const REEXPORT_FROM_STATEMENT_PATTERN = /^\s*export\s+(?!type\b)(?:\*|\{[\s\S]*?\})\s+from\s+(['"][^'"]+['"])\s*;?\s*$/gm;
+function injectBootstrapReexportImports(source) {
+  const sideEffectImports = [];
+  const importedSpecifiers = /* @__PURE__ */ new Set();
+  let importIndex = 0;
+  const rewrittenSource = source.replace(REEXPORT_FROM_STATEMENT_PATTERN, (statement, specifierLiteral) => {
+    if (!importedSpecifiers.has(specifierLiteral)) {
+      importedSpecifiers.add(specifierLiteral);
+      const importBinding = `__eco_bootstrap_reexport_${importIndex++}`;
+      sideEffectImports.push(`import * as ${importBinding} from ${specifierLiteral};`);
+      sideEffectImports.push(`void ${importBinding};`);
+    }
+    return statement;
+  });
+  if (sideEffectImports.length === 0) {
+    return source;
+  }
+  return `${sideEffectImports.join("\n")}
+${rewrittenSource}`;
+}
+function shouldRewriteBootstrapSource(filePath, projectDir) {
+  const normalizedPath = path.resolve(filePath);
+  const normalizedProjectDir = path.resolve(projectDir);
+  return normalizedPath.startsWith(`${normalizedProjectDir}${path.sep}`) && !normalizedPath.includes(`${path.sep}node_modules${path.sep}`);
+}
+function resolveNodeBootstrapDependency(args, options) {
+  if (args.path.startsWith("./") || args.path.startsWith("../") || args.path.startsWith("@/") || args.path.startsWith("/") || args.path.startsWith("node:")) {
+    return void 0;
+  }
+  const projectRequire = createRequire(path.join(options.projectDir, "package.json"));
+  const requireFromImporter = args.importer && path.isAbsolute(args.importer) && shouldResolveFromImporter(args.importer) ? createRequire(args.importer) : projectRequire;
+  if (args.path.startsWith("@ecopages/")) {
+    return {
+      path: requireFromImporter.resolve(args.path)
+    };
+  }
+  const resolvedPath = requireFromImporter.resolve(args.path);
+  ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath);
+  return {
+    path: args.path,
+    external: true
+  };
+}
+function createNodeBootstrapPlugin(options) {
+  const projectDir = path.resolve(options.projectDir);
+  const importMetaRewritePaths = new Set(
+    (options.preserveImportMetaPaths ?? []).map((filePath) => path.resolve(filePath))
+  );
+  return {
+    name: "node-thin-host-bundle-workspace-packages",
+    setup(build) {
+      build.onResolve({ filter: /^bun:/ }, (args) => {
+        throw new Error(getNodeUnsupportedBuiltinError(args.path, args.importer));
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        const absolutePath = path.resolve(args.path);
+        const shouldPreserveImportMeta = importMetaRewritePaths.has(absolutePath);
+        const shouldRewriteReexports = shouldRewriteBootstrapSource(absolutePath, projectDir);
+        if (!shouldPreserveImportMeta && !shouldRewriteReexports) {
+          return void 0;
+        }
+        const originalContents = readFileSync(args.path, "utf8");
+        let contents = originalContents;
+        if (shouldPreserveImportMeta) {
+          contents = contents.replaceAll("import.meta.dirname", JSON.stringify(path.dirname(args.path))).replaceAll("import.meta.filename", JSON.stringify(args.path));
+        }
+        if (shouldRewriteReexports) {
+          contents = injectBootstrapReexportImports(contents);
+        }
+        if (contents === originalContents) {
+          return void 0;
+        }
+        return {
+          contents,
+          loader: getBootstrapBuildLoaderForPath(args.path),
+          resolveDir: path.dirname(args.path)
+        };
+      });
+      build.onResolve({ filter: /^[@A-Za-z0-9][^:]*$/ }, (args) => {
+        return resolveNodeBootstrapDependency(args, options);
+      });
+    }
+  };
+}
+function createAppNodeBootstrapPlugin(appConfig, options) {
+  return createNodeBootstrapPlugin({
+    projectDir: appConfig.rootDir,
+    runtimeNodeModulesDir: getAppRuntimeNodeModulesDir(appConfig),
+    preserveImportMetaPaths: options?.preserveImportMetaPaths
+  });
+}
+export {
+  createAppNodeBootstrapPlugin,
+  createNodeBootstrapPlugin,
+  getAppRuntimeNodeModulesDir,
+  getNodeRuntimeNodeModulesDir,
+  getNodeUnsupportedBuiltinError,
+  resolveNodeBootstrapDependency
+};

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

@@ -0,0 +1,21 @@
+import { type Server as NodeServerInstance } from 'node:http';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import { type ApplicationAdapterOptions } from '../abstract/application-adapter.js';
+import { SharedApplicationAdapter } from '../shared/application-adapter.js';
+import { type NodeServerAdapterResult } from './server-adapter.js';
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+    appConfig: EcoPagesAppConfig;
+    serverOptions?: Record<string, any>;
+}
+export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+    serverAdapter: NodeServerAdapterResult | undefined;
+    private server;
+    private runtimeOrigin;
+    stop(force?: boolean): Promise<void>;
+    protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
+    start(): Promise<NodeServerInstance | void>;
+    private createWebRequest;
+    private sendNodeResponse;
+    fetch(request: Request): Promise<Response>;
+}
+export declare function createNodeApp(options: EcopagesAppOptions): Promise<EcopagesApp>;

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

@@ -0,0 +1,143 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../constants.js";
+import { appLogger } from "../../global/app-logger.js";
+import {} from "../abstract/application-adapter.js";
+import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { createNodeServerAdapter } from "./server-adapter.js";
+class EcopagesApp extends SharedApplicationAdapter {
+  serverAdapter;
+  server = null;
+  runtimeOrigin = "";
+  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();
+      }
+    });
+  }
+  async initializeServerAdapter() {
+    const { dev } = this.cliArgs;
+    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+    const envPort = process.env.ECOPAGES_PORT;
+    const envHostname = process.env.ECOPAGES_HOSTNAME;
+    const preferredPort = cliPort ?? (envPort ? Number(envPort) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    this.runtimeOrigin = `http://${preferredHostname}:${preferredPort}`;
+    return createNodeServerAdapter({
+      runtimeOrigin: this.runtimeOrigin,
+      appConfig: this.appConfig,
+      apiHandlers: this.apiHandlers,
+      staticRoutes: this.staticRoutes,
+      errorHandler: this.errorHandler,
+      options: { watch: dev },
+      serveOptions: {
+        port: preferredPort,
+        hostname: preferredHostname,
+        ...this.serverOptions
+      }
+    });
+  }
+  async start() {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    if (this.server) {
+      return this.server;
+    }
+    const { build, preview } = this.cliArgs;
+    if (build || preview) {
+      appLogger.debugTime("Building static pages");
+      await this.serverAdapter.buildStatic({ preview });
+      await this.stop(true);
+      appLogger.debugTimeEnd("Building static pages");
+      if (build) {
+        process.exit(0);
+      }
+      return;
+    }
+    const serveOptions = this.serverAdapter.getServerOptions();
+    const hostname = String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    this.runtimeOrigin = `http://${hostname}:${port}`;
+    this.server = createServer(async (req, res) => {
+      try {
+        const webRequest = this.createWebRequest(req);
+        const response = await this.serverAdapter.handleRequest(webRequest);
+        await this.sendNodeResponse(res, response);
+      } catch (error) {
+        appLogger.error("Node server adapter request failed", error);
+        res.statusCode = 500;
+        res.end("Internal Server Error");
+      }
+    });
+    await new Promise((resolve) => {
+      this.server.listen(port, hostname, () => resolve());
+    });
+    await this.serverAdapter.completeInitialization(this.server);
+    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    return this.server;
+  }
+  createWebRequest(req) {
+    const url = new URL(req.url ?? "/", this.runtimeOrigin);
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          headers.append(key, item);
+        }
+        continue;
+      }
+      if (value !== void 0) {
+        headers.set(key, value);
+      }
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    const requestInit = {
+      method,
+      headers
+    };
+    if (method !== "GET" && method !== "HEAD") {
+      requestInit.body = Readable.toWeb(req);
+      requestInit.duplex = "half";
+    }
+    return new Request(url, requestInit);
+  }
+  async sendNodeResponse(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+      res.setHeader(key, value);
+    });
+    if (!response.body) {
+      res.end();
+      return;
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    res.end(body);
+  }
+  async fetch(request) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    return this.serverAdapter.handleRequest(request);
+  }
+}
+async function createNodeApp(options) {
+  return new EcopagesApp(options);
+}
+export {
+  EcopagesApp,
+  createNodeApp
+};

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

@@ -0,0 +1,6 @@
+export { NodeServerAdapter, createNodeServerAdapter } from './server-adapter.js';
+export { EcopagesApp, createNodeApp } from './create-app.js';
+export { assertNodeRuntimeManifest, createNodeRuntimeAdapter } from './runtime-adapter.js';
+export type { EcopagesAppOptions } from './create-app.js';
+export type { LoadedAppRuntime, NodeRuntimeAdapter, NodeRuntimeSession, NodeRuntimeStartOptions, } from './runtime-adapter.js';
+export type { NodeServerAdapterParams, NodeServerAdapterResult, NodeServerInstance, NodeServeAdapterServerOptions, } from './server-adapter.js';

package/src/adapters/node/index.js

@@ -0,0 +1,11 @@
+import { NodeServerAdapter, createNodeServerAdapter } from "./server-adapter.js";
+import { EcopagesApp, createNodeApp } from "./create-app.js";
+import { assertNodeRuntimeManifest, createNodeRuntimeAdapter } from "./runtime-adapter.js";
+export {
+  EcopagesApp,
+  NodeServerAdapter,
+  assertNodeRuntimeManifest,
+  createNodeApp,
+  createNodeRuntimeAdapter,
+  createNodeServerAdapter
+};

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

@@ -0,0 +1,26 @@
+import type { WebSocket } from 'ws';
+import type { ClientBridgeEvent, IClientBridge } from '../../public-types.js';
+export declare class NodeClientBridge implements IClientBridge {
+    private subscribers;
+    private heartbeatTimer;
+    constructor();
+    /**
+     * Pings all open subscribers and removes any that are no longer in OPEN state.
+     * This prevents a slow memory leak caused by zombie connections that never
+     * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+     */
+    private sweep;
+    subscribe(ws: WebSocket): void;
+    unsubscribe(ws: WebSocket): void;
+    broadcast(event: ClientBridgeEvent): void;
+    reload(): void;
+    cssUpdate(path: string): void;
+    update(path: string): void;
+    error(message: string): void;
+    get subscriberCount(): number;
+    /**
+     * Stops the heartbeat timer and clears all subscribers.
+     * Call this when the dev server is shutting down.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,66 @@
+const HEARTBEAT_INTERVAL_MS = 3e4;
+class NodeClientBridge {
+  subscribers = /* @__PURE__ */ new Set();
+  heartbeatTimer = null;
+  constructor() {
+    this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
+    this.heartbeatTimer.unref?.();
+  }
+  /**
+   * Pings all open subscribers and removes any that are no longer in OPEN state.
+   * This prevents a slow memory leak caused by zombie connections that never
+   * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+   */
+  sweep() {
+    for (const ws of this.subscribers) {
+      if (ws.readyState !== 1) {
+        this.subscribers.delete(ws);
+        continue;
+      }
+      ws.ping();
+    }
+  }
+  subscribe(ws) {
+    this.subscribers.add(ws);
+  }
+  unsubscribe(ws) {
+    this.subscribers.delete(ws);
+  }
+  broadcast(event) {
+    const payload = JSON.stringify(event);
+    for (const ws of this.subscribers) {
+      if (ws.readyState === 1) {
+        ws.send(payload);
+      }
+    }
+  }
+  reload() {
+    this.broadcast({ type: "reload" });
+  }
+  cssUpdate(path) {
+    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
+  }
+  update(path) {
+    this.broadcast({ type: "update", path, timestamp: Date.now() });
+  }
+  error(message) {
+    this.broadcast({ type: "error", message });
+  }
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+  /**
+   * Stops the heartbeat timer and clears all subscribers.
+   * Call this when the dev server is shutting down.
+   */
+  destroy() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.subscribers.clear();
+  }
+}
+export {
+  NodeClientBridge
+};

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

@@ -0,0 +1,133 @@
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import type { ClientBridgeEvent } from '../../public-types.js';
+export interface NodeHmrManagerParams {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+}
+type HandleFileChangeOptions = {
+    broadcast?: boolean;
+};
+/**
+ * Node development HMR manager.
+ *
+ * @remarks
+ * This manager owns three separate concerns:
+ * - runtime websocket event fanout
+ * - entrypoint registration and dedupe
+ * - strategy coordination for rebuilds and invalidation
+ *
+ * The strict page-entrypoint contract lives here: `registerEntrypoint()` is
+ * reserved for integration-owned page bundles, while generic script assets must
+ * go through `registerScriptEntrypoint()`.
+ */
+export declare class NodeHmrManager implements IHmrManager {
+    private static readonly entrypointRegistrationTimeoutMs;
+    readonly appConfig: EcoPagesAppConfig;
+    private readonly bridge;
+    private watchers;
+    private watchedFiles;
+    private entrypointRegistrations;
+    private distDir;
+    private plugins;
+    private enabled;
+    private strategies;
+    private readonly entrypointRegistrar;
+    private readonly browserBundleService;
+    private readonly entrypointDependencyGraph;
+    private readonly runtimeSpecifierRegistry;
+    private readonly serverModuleTranspiler;
+    constructor({ appConfig, bridge }: NodeHmrManagerParams);
+    /**
+     * Ensures the HMR output directory exists.
+     *
+     * This must not remove the directory because multiple app processes
+     * can share the same dist path during e2e runs.
+     */
+    private cleanDistDir;
+    /**
+     * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+     *
+     * @remarks
+     * Higher-priority integration strategies own framework page entrypoints. When
+     * one of them matches, the generic JS strategy must stay out of the way so a
+     * shared dependency invalidation does not overwrite framework-specific output.
+     */
+    private shouldJsStrategyProcessEntrypoint;
+    private initializeStrategies;
+    registerStrategy(strategy: HmrStrategy): void;
+    setPlugins(plugins: EcoBuildPlugin[]): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * Registers runtime bare-specifier mappings exposed by integrations.
+     *
+     * @remarks
+     * These mappings are consumed by framework-owned HMR strategies such as the
+     * React integration strategy when they rewrite browser bundles. The registry
+     * stays generic so the same mappings can support broader import-map-style
+     * runtime features later without moving integration semantics into core.
+     */
+    registerSpecifierMap(map: Record<string, string>): void;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    getWatchedFiles(): Map<string, string>;
+    getSpecifierMap(): Map<string, string>;
+    getDistDir(): string;
+    getPlugins(): EcoBuildPlugin[];
+    getDefaultContext(): DefaultHmrContext;
+    private clearFailedEntrypointRegistration;
+    /**
+     * Registers one integration-owned page entrypoint.
+     *
+     * @remarks
+     * Concurrent callers share one in-flight registration. The registration is
+     * removed from the dedupe map once it resolves or fails so later requests do
+     * not inherit stale state.
+     */
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    /**
+     * Registers one generic script entrypoint.
+     *
+     * @remarks
+     * This path is intentionally separate from page entrypoints so non-framework
+     * scripts can still use the generic build fallback without weakening the page
+     * ownership contract.
+     */
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    /**
+     * Performs strict integration-owned entrypoint registration for one normalized source path.
+     *
+     * @remarks
+     * The flow is:
+     * 1. Reserve the output URL in the watched map.
+     * 2. Remove any stale emitted file from an earlier process or failed build.
+     * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+     * 4. Fail if the owning integration did not emit the expected output.
+     */
+    private emitStrictEntrypoint;
+    /**
+     * Performs registration for a generic script asset.
+     *
+     * @remarks
+     * The manager first gives registered strategies a chance to emit the file so
+     * processor-owned or integration-owned behavior can still participate. Only
+     * when no output exists does it issue the generic build.
+     */
+    private emitScriptEntrypoint;
+    /**
+     * Stops active watchers and releases retained registration state.
+     *
+     * @remarks
+     * The manager intentionally does not remove emitted `_hmr` files from disk
+     * because multiple app processes may share the same dist directory during test
+     * runs. It does clear in-memory indexes so old entrypoints, dependencies, and
+     * specifier maps cannot leak across a reused manager instance.
+     */
+    stop(): void;
+}
+export {};