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

package/src/adapters/shared/server-static-builder.js

@@ -1,53 +1,66 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { StaticContentServer } from "../../dev/sc-server.js";
 import { appLogger } from "../../global/app-logger.js";
-import { getAppBuildAdapter } from "../../build/build-adapter.js";
-import { resolveEntryFile, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.js";
+import { build, getAppBuildAdapter, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { attachHmrToIntegrations } from "./runtime-server-lifecycle.js";
+import { resolveBuildProfileOptions } from "../../build/build-profile-options.js";
+import {
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  recordServerEntryBuildCache,
+  writeServerBundleDeployManifest
+} from "../../build/server-entry-build-cache.js";
+import { getInstalledServerEntryBuildExecutor } from "../../build/runtime-build-executor.js";
+import {
+  clearProductionBuildCaches,
+  shouldResetStaticExportDirectory
+} from "../../static-site-generator/static-build-invalidation.js";
+import { resolveEntryFile, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
   serveOptions;
-  apiHandlers;
+  runtimeOrigin;
+  needsServerBundle;
   logger;
-  previewServerFactory;
   entryFile;
+  hmrManager;
+  onRuntimePlugin;
   constructor({
     appConfig,
     staticSiteGenerator,
     serveOptions,
-    apiHandlers,
+    runtimeOrigin,
+    needsServerBundle,
     logger,
-    previewServerFactory,
-    entryFile
+    entryFile,
+    hmrManager,
+    onRuntimePlugin
   }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
-    this.apiHandlers = apiHandlers ?? [];
+    this.runtimeOrigin = runtimeOrigin;
+    this.needsServerBundle = needsServerBundle ?? false;
     this.logger = logger ?? appLogger;
-    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
     this.entryFile = resolveEntryFile({ entryFile });
+    this.hmrManager = hmrManager;
+    this.onRuntimePlugin = onRuntimePlugin;
   }
-  warnApiHandlersUnavailableInStaticMode() {
-    if (this.apiHandlers.length === 0) {
-      return;
+  prepareExportDirectory(force) {
+    if (force) {
+      clearProductionBuildCaches(this.appConfig);
     }
-    const uniqueHandlers = Array.from(
-      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
-    );
-    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
-    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
-    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
-    this.logger.warn(
-      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
-      `\u27A4 ${summary}`
-    );
-  }
-  prepareExportDirectory() {
     const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-    fileSystem.ensureDir(exportDir, true);
+    const shouldCleanDist = shouldResetStaticExportDirectory(this.appConfig, force);
+    fileSystem.ensureDir(exportDir, shouldCleanDist);
+    if (shouldCleanDist) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        runtimeAssetsPrepared: false
+      };
+    }
     const srcPublicDir = path.join(
       this.appConfig.rootDir,
       this.appConfig.srcDir ?? "src",
@@ -56,39 +69,42 @@ class ServerStaticBuilder {
     if (fileSystem.exists(srcPublicDir)) {
       fileSystem.copyDir(srcPublicDir, exportDir);
     }
+    return !shouldCleanDist;
   }
   async refreshRuntimeAssets() {
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
-    }
-    for (const integration of this.appConfig.integrations) {
-      await integration.setup();
+    appLogger.debugTime("refreshRuntimeAssets");
+    try {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        onRuntimePlugin: this.onRuntimePlugin
+      });
+      if (this.hmrManager?.isEnabled()) {
+        attachHmrToIntegrations(this.appConfig, this.hmrManager);
+      }
+    } finally {
+      appLogger.debugTimeEnd("refreshRuntimeAssets");
     }
   }
   /**
    * Bundles the server entry file for production use.
    *
    * @remarks
-   * When the project has API endpoints, the entry file must be bundled
-   * into a single JS file so the production server can start without
-   * on-the-fly TypeScript transpilation. The bundle is output to
-   * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-   * `ecopages start` in production.
+   * Only invoked when the app requires a runtime server (API handlers,
+   * websocket handlers, etc.). Static-only apps skip this step entirely.
+   * Incremental builds may skip Rolldown when the `.eco/.server-entry`
+   * cache is still valid.
    *
    * Package imports remain external so native addons and runtime-owned
    * dependencies continue to load through the app's installed
    * `node_modules` tree. Only the app entry graph is bundled.
    *
-   * Skips silently when no API endpoints are registered (static-only site).
    * Throws if the build adapter is unavailable, is owned by a host
    * runtime, or bundling fails.
    *
    * @throws If the build adapter is unavailable, is host-owned, or bundling fails.
    */
-  async bundleServerEntry() {
-    if (this.apiHandlers.length === 0) {
-      return;
-    }
+  async bundleServerEntry(options) {
     const buildAdapter = getAppBuildAdapter(this.appConfig);
     if (buildAdapter.ownership === "vite-host") {
       throw new Error(
@@ -101,60 +117,71 @@ class ServerStaticBuilder {
         `Cannot bundle server entry: file "${this.entryFile}" not found in "${this.appConfig.rootDir}".`
       );
     }
-    const distDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-    const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
-    this.logger.info("Bundling server entry file...");
-    const result = await buildAdapter.build({
-      entrypoints: [entryPath],
-      outdir: serverOutdir,
-      naming: SERVER_BUNDLE_FILENAME,
-      target: "node",
-      format: "esm",
-      sourcemap: "hidden",
-      externalPackages: true,
-      root: this.appConfig.rootDir
+    const { serverOutdir, serverEntryPath } = getServerBundleOutputPaths(this.appConfig);
+    const cached = lookupServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      force: options?.force
     });
+    if (cached) {
+      const hasBundle = cached.outputPaths.some(
+        (outputPath) => path.resolve(outputPath) === path.resolve(serverEntryPath) && fileSystem.exists(outputPath)
+      );
+      if (hasBundle) {
+        this.logger.info("Reusing cached server entry bundle");
+        writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+        return;
+      }
+    }
+    this.logger.info("Bundling server entry file...");
+    const buildOptions = {
+      ...resolveBuildProfileOptions("server-entry", this.appConfig, {
+        entrypoints: [entryPath],
+        outdir: serverOutdir,
+        naming: SERVER_BUNDLE_FILENAME,
+        sourcemap: "hidden"
+      }),
+      entrypoints: [entryPath]
+    };
+    const result = await build(buildOptions, getInstalledServerEntryBuildExecutor(this.appConfig));
     if (!result.success) {
       const errorMessages = result.logs.map((log) => log.message).join("\n");
       throw new Error(`Failed to bundle server entry file:
 ${errorMessages}`);
     }
+    const outputPaths = result.outputs.length > 0 ? result.outputs.map((output) => output.path) : fileSystem.exists(serverEntryPath) ? [serverEntryPath] : [];
+    recordServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      buildResult: result,
+      outputPaths
+    });
+    writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
     this.logger.info("Server entry file bundled successfully");
   }
   /**
    * Generates a static build of the site for deployment.
-   * @param options.preview - If true, starts a preview server after build
    * @param dependencies.router - The initialized router
    * @param dependencies.routeRendererFactory - The route renderer factory
    * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
    */
   async build(options, dependencies) {
-    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const { baseUrl: explicitBaseUrl, force = false } = options ?? {};
     const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
-    this.warnApiHandlersUnavailableInStaticMode();
-    this.prepareExportDirectory();
+    const preserveExportDirectory = this.prepareExportDirectory(force);
     await this.refreshRuntimeAssets();
-    await this.bundleServerEntry();
+    if (this.needsServerBundle) {
+      await this.bundleServerEntry({ force });
+    }
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
       routeRendererFactory: dependencies.routeRendererFactory,
-      staticRoutes: dependencies.staticRoutes
+      staticRoutes: dependencies.staticRoutes,
+      force,
+      preserveExportDirectory
     });
-    if (!preview) {
-      this.logger.info("Build completed");
-      return;
-    }
-    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-    const { server } = this.previewServerFactory.createServer({
-      appConfig: this.appConfig,
-      options: { port: Number(previewPort) }
-    });
-    if (server?.port) {
-      this.logger.info(`Preview running at http://localhost:${server.port}`);
-    } else {
-      this.logger.error("Failed to start preview server");
-    }
+    this.logger.info("Build completed");
   }
 }
 export {

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

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
+import { type ResolvedHmrEntrypoint } from '../../hmr/hmr-entrypoint-output.js';
 import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
 import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import { DevelopmentInvalidationService } from '../../services/invalidation/development-invalidation.service.js';
 import type { ClientBridgeEvent } from '../../types/public-types.js';
 import { HmrEntrypointRegistrar } from './hmr-entrypoint-registrar.js';
 import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
@@ -13,23 +14,22 @@ type HandleFileChangeOptions = {
 type SharedHmrManagerParams = {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
-    registrationTimeoutMs?: number;
 };
 export declare abstract class SharedHmrManager implements IHmrManager {
     readonly appConfig: EcoPagesAppConfig;
     protected readonly bridge: IClientBridge;
     protected watchers: Map<string, fs.FSWatcher>;
-    protected watchedFiles: Map<string, string>;
-    protected entrypointRegistrations: Map<string, Promise<string>>;
     protected distDir: string;
-    protected plugins: EcoBuildPlugin[];
     protected enabled: boolean;
     protected strategies: HmrStrategy[];
     protected readonly entrypointRegistrar: HmrEntrypointRegistrar;
     protected readonly browserBundleService: BrowserBundleService;
+    protected readonly invalidationService: DevelopmentInvalidationService;
     protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
     protected readonly serverModuleTranspiler: ServerModuleTranspiler;
-    constructor({ appConfig, bridge, registrationTimeoutMs }: SharedHmrManagerParams);
+    private runtimeBuildPromise;
+    private runtimeReady;
+    constructor({ appConfig, bridge }: SharedHmrManagerParams);
     protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
     protected shouldSkipMissingFileChange(_filePath: string): boolean;
     protected onRuntimeBundleFailure(error: unknown): void;
@@ -37,23 +37,57 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean;
     protected initializeStrategies(): void;
     registerStrategy(strategy: HmrStrategy): void;
-    setPlugins(plugins: EcoBuildPlugin[]): void;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
+    isRuntimeReady(): boolean;
+    /**
+     * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+     */
+    ensureRuntimeReady(): Promise<boolean>;
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
+    private buildRuntimeInternal;
     broadcast(event: ClientBridgeEvent): void;
     handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    private getStrategiesByPriority;
+    private selectChangeStrategy;
+    private selectEntrypointEmitter;
+    protected createUnownedEntrypointError(entrypointPath: string): Error;
+    /**
+     * Materializes one integration-owned page entrypoint during cold registration.
+     *
+     * @remarks
+     * Registration uses {@link HmrStrategy.canEmitEntrypoint} / {@link HmrStrategy.emitEntrypoint},
+     * not {@link HmrStrategy.matches} / {@link HmrStrategy.process}. File-change handling stays
+     * on `handleFileChange()`.
+     */
+    emitIntegrationEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
+    /**
+     * Runs server invalidation and integration hooks before rebuilding a registered script entrypoint.
+     *
+     * @remarks
+     * Browser-only `*.script.ts` entrypoints skip server module invalidation and bypass-cache
+     * import; only integration change handlers and the downstream strategy rebuild run.
+     */
+    private prepareRegisteredScriptChange;
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns the emitted HMR script output when the entrypoint is already registered
+     * and its browser bundle exists on disk.
+     *
+     * @remarks
+     * Disk artifacts alone are not enough: a fresh dev session must still register
+     * the entrypoint so file watchers can rebuild it on change.
+     */
+    getResolvedScriptOutput(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
     getWatchedFiles(): Map<string, string>;
     getDistDir(): string;
-    getPlugins(): EcoBuildPlugin[];
     getDefaultContext(): DefaultHmrContext;
+    stop(): void;
     protected clearFailedEntrypointRegistration(entrypointPath: string): void;
     registerEntrypoint(entrypointPath: string): Promise<string>;
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
-    protected emitStrictEntrypoint(entrypointPath: string): Promise<void>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
     protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
-    stop(): void;
+    [Symbol.dispose](): void;
 }
 export {};