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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.2",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.0",
+    "@ecopages/file-system": "0.2.0-beta.2",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -152,6 +152,11 @@
       "default": "./src/utils/hash.js",
       "types": "./src/utils/hash.d.ts"
     },
+    "./utils/resolve-entry-file": {
+      "import": "./src/utils/resolve-entry-file.js",
+      "types": "./src/utils/resolve-entry-file.d.ts",
+      "default": "./src/utils/resolve-entry-file.js"
+    },
     "./errors": {
       "types": "./src/errors/index.d.ts",
       "default": "./src/errors/index.js"
@@ -276,6 +281,11 @@
       "default": "./src/utils/hash.js",
       "types": "./src/utils/hash.d.ts"
     },
+    "./utils/resolve-entry-file.ts": {
+      "import": "./src/utils/resolve-entry-file.js",
+      "types": "./src/utils/resolve-entry-file.d.ts",
+      "default": "./src/utils/resolve-entry-file.js"
+    },
     "./errors.ts": {
       "types": "./src/errors/index.d.ts",
       "default": "./src/errors/index.js"

package/src/adapters/shared/server-static-builder.d.ts

@@ -18,6 +18,7 @@ export interface ServerStaticBuilderParams {
     apiHandlers?: ApiHandler[];
     logger?: ServerStaticBuilderLogger;
     previewServerFactory?: ServerStaticPreviewServerFactory;
+    entryFile?: string;
 }
 /**
  * Minimal logger dependency used by the static builder.
@@ -52,10 +53,32 @@ export declare class ServerStaticBuilder {
     private readonly apiHandlers;
     private readonly logger;
     private readonly previewServerFactory;
-    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
+    private readonly entryFile;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, entryFile, }: ServerStaticBuilderParams);
     private warnApiHandlersUnavailableInStaticMode;
     private prepareExportDirectory;
     private 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.
+     *
+     * 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.
+     */
+    private bundleServerEntry;
     /**
      * Generates a static build of the site for deployment.
      * @param options.preview - If true, starts a preview server after build

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

@@ -3,6 +3,8 @@ 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";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
@@ -10,13 +12,15 @@ class ServerStaticBuilder {
   apiHandlers;
   logger;
   previewServerFactory;
+  entryFile;
   constructor({
     appConfig,
     staticSiteGenerator,
     serveOptions,
     apiHandlers,
     logger,
-    previewServerFactory
+    previewServerFactory,
+    entryFile
   }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
@@ -24,6 +28,7 @@ class ServerStaticBuilder {
     this.apiHandlers = apiHandlers ?? [];
     this.logger = logger ?? appLogger;
     this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+    this.entryFile = resolveEntryFile({ entryFile });
   }
   warnApiHandlersUnavailableInStaticMode() {
     if (this.apiHandlers.length === 0) {
@@ -60,6 +65,62 @@ class ServerStaticBuilder {
       await integration.setup();
     }
   }
+  /**
+   * 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.
+   *
+   * 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;
+    }
+    const buildAdapter = getAppBuildAdapter(this.appConfig);
+    if (buildAdapter.ownership === "vite-host") {
+      throw new Error(
+        'Cannot bundle the server entry file: build ownership is "vite-host". The host runtime is expected to produce its own server bundle.'
+      );
+    }
+    const entryPath = path.isAbsolute(this.entryFile) ? this.entryFile : path.join(this.appConfig.rootDir, this.entryFile);
+    if (!fileSystem.exists(entryPath)) {
+      throw new Error(
+        `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
+    });
+    if (!result.success) {
+      const errorMessages = result.logs.map((log) => log.message).join("\n");
+      throw new Error(`Failed to bundle server entry file:
+${errorMessages}`);
+    }
+    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
@@ -73,6 +134,7 @@ class ServerStaticBuilder {
     this.warnApiHandlersUnavailableInStaticMode();
     this.prepareExportDirectory();
     await this.refreshRuntimeAssets();
+    await this.bundleServerEntry();
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,

package/src/utils/resolve-entry-file.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The default entry file name when no other source provides a value.
+ */
+export declare const DEFAULT_ENTRY_FILE = "app.ts";
+/**
+ * The environment variable used to override the entry file path.
+ */
+export declare const ENTRY_FILE_ENV = "ECOPAGES_ENTRY_FILE";
+/**
+ * Centralized definition of the entry-file CLI argument.
+ *
+ * Exported so callers (CLI, tests, docs) reference a single source of truth
+ * for the flag name, short alias, and type. Keep this in sync with
+ * `resolveEntryFile` below.
+ */
+export declare const entryFileOptions: {
+    readonly 'entry-file': {
+        readonly type: "string";
+        readonly short: "e";
+    };
+};
+/**
+ * The long flag name for the entry file option. Re-exported as a
+ * constant so consumers don't hardcode the string.
+ */
+export declare const ENTRY_FILE_FLAG = "entry-file";
+/**
+ * Resolved sources for the entry file, in precedence order (highest first):
+ *
+ * 1. `entryFile` argument — explicit caller override (e.g. constructor)
+ * 2. `ECOPAGES_ENTRY_FILE` env var — set by the CLI when spawning
+ * 3. `--entry-file` / `-e` CLI flag — read from `process.argv` via `parseArgs`
+ * 4. `app.ts` — the framework default
+ */
+export interface ResolveEntryFileOptions {
+    /** Explicit override (e.g. constructor param or test fixture). */
+    entryFile?: string;
+    /** Environment to read `ECOPAGES_ENTRY_FILE` from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Argv to parse. Defaults to `process.argv`. */
+    argv?: string[];
+}
+/**
+ * Resolves the entry file path using standard precedence.
+ *
+ * This is the single source of truth for entry-file resolution across
+ * the CLI, build pipeline, and runtime. Both the CLI layer and the
+ * runtime builders call into this function instead of reimplementing
+ * the precedence chain.
+ *
+ * @example
+ *   resolveEntryFile();                                     // 'app.ts' (or env/argv)
+ *   resolveEntryFile({ entryFile: 'src/server.ts' });       // 'src/server.ts'
+ *   resolveEntryFile({ env: { ECOPAGES_ENTRY_FILE: 'x' }}); // 'x'
+ *   resolveEntryFile({ argv: ['node', '-e', 'flag.ts'] });  // 'flag.ts'
+ */
+export declare function resolveEntryFile({ entryFile, env, argv, }?: ResolveEntryFileOptions): string;
+/**
+ * Parses argv for the entry-file flag using the shared `parseArgs` config.
+ *
+ * Exposed for callers that need the raw flag value without the full
+ * precedence chain (e.g. CLI help text, validation).
+ */
+export declare function readEntryFileFlag(argv?: string[]): string | undefined;
+/**
+ * The subdirectory inside `dist/` where the bundled server entry is placed.
+ */
+export declare const SERVER_BUNDLE_DIR = ".server";
+/**
+ * The filename of the bundled server entry.
+ */
+export declare const SERVER_BUNDLE_FILENAME = "app.mjs";

package/src/utils/resolve-entry-file.js

@@ -0,0 +1,41 @@
+import { parseArgs } from "node:util";
+import { getRuntimeArgv } from "./runtime.js";
+const DEFAULT_ENTRY_FILE = "app.ts";
+const ENTRY_FILE_ENV = "ECOPAGES_ENTRY_FILE";
+const entryFileOptions = {
+  "entry-file": { type: "string", short: "e" }
+};
+const ENTRY_FILE_FLAG = "entry-file";
+function resolveEntryFile({
+  entryFile,
+  env = process.env,
+  argv = getRuntimeArgv()
+} = {}) {
+  if (entryFile && entryFile.length > 0) return entryFile;
+  const fromEnv = env[ENTRY_FILE_ENV];
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+  const fromFlag = readEntryFileFlag(argv);
+  if (fromFlag) return fromFlag;
+  return DEFAULT_ENTRY_FILE;
+}
+function readEntryFileFlag(argv = getRuntimeArgv()) {
+  const { values } = parseArgs({
+    args: argv.slice(1),
+    options: { ...entryFileOptions },
+    strict: false
+  });
+  const raw = values[ENTRY_FILE_FLAG];
+  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+const SERVER_BUNDLE_DIR = ".server";
+const SERVER_BUNDLE_FILENAME = "app.mjs";
+export {
+  DEFAULT_ENTRY_FILE,
+  ENTRY_FILE_ENV,
+  ENTRY_FILE_FLAG,
+  SERVER_BUNDLE_DIR,
+  SERVER_BUNDLE_FILENAME,
+  entryFileOptions,
+  readEntryFileFlag,
+  resolveEntryFile
+};