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

package/src/build/esbuild-build-adapter.js

@@ -0,0 +1,422 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { fileSystem } from "@ecopages/file-system";
+const esbuildRequire = createRequire(import.meta.url);
+function transpileProfileToOptions(profile) {
+  switch (profile) {
+    case "browser-script":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+    case "hmr-runtime":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+    case "hmr-entrypoint":
+      return {
+        target: "browser",
+        format: "esm",
+        sourcemap: "none"
+      };
+  }
+}
+class EsbuildBuildAdapter {
+  escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  getPluginsForBuild(additionalPlugins) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const plugin of additionalPlugins ?? []) {
+      if (!byName.has(plugin.name)) {
+        byName.set(plugin.name, plugin);
+      }
+    }
+    return Array.from(byName.values());
+  }
+  normalizeEsbuildLoader(loader) {
+    switch (loader) {
+      case "base64":
+      case "binary":
+      case "copy":
+      case "css":
+      case "dataurl":
+      case "empty":
+      case "file":
+      case "global-css":
+      case "js":
+      case "json":
+      case "jsx":
+      case "local-css":
+      case "text":
+      case "ts":
+      case "tsx":
+        return loader;
+      default:
+        return void 0;
+    }
+  }
+  inferEsbuildLoaderFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+      case ".ts":
+        return "ts";
+      case ".tsx":
+        return "tsx";
+      case ".jsx":
+        return "jsx";
+      case ".json":
+        return "json";
+      case ".css":
+        return "css";
+      default:
+        return "js";
+    }
+  }
+  convertLoadResultToModuleSource(result) {
+    if (!result || typeof result !== "object") {
+      return void 0;
+    }
+    const candidate = result;
+    if (typeof candidate.contents === "string") {
+      return candidate.contents;
+    }
+    if (candidate.loader === "object" && candidate.exports && typeof candidate.exports === "object") {
+      const entries = Object.entries(candidate.exports).map(
+        ([key, value]) => key === "default" ? `export default ${JSON.stringify(value)};` : `export const ${key} = ${JSON.stringify(value)};`
+      ).join("\n");
+      return entries;
+    }
+    return void 0;
+  }
+  convertPluginOnLoadResult(args, result) {
+    if (!result || typeof result !== "object") {
+      return void 0;
+    }
+    const candidate = result;
+    const sourceFromExports = candidate.loader === "object" && candidate.exports && typeof candidate.exports === "object" ? this.convertLoadResultToModuleSource(candidate) : void 0;
+    if (sourceFromExports) {
+      return {
+        contents: sourceFromExports,
+        loader: "js",
+        resolveDir: path.dirname(args.path)
+      };
+    }
+    if (typeof candidate.contents === "string" || candidate.contents instanceof Uint8Array) {
+      return {
+        contents: candidate.contents,
+        loader: this.normalizeEsbuildLoader(candidate.loader) ?? this.inferEsbuildLoaderFromPath(args.path),
+        resolveDir: typeof candidate.resolveDir === "string" ? candidate.resolveDir : path.dirname(args.path)
+      };
+    }
+    return void 0;
+  }
+  resolvePluginPath(value, args, contextRoot) {
+    if (path.isAbsolute(value)) {
+      return value;
+    }
+    if (value.startsWith(".") || value.startsWith("..")) {
+      const baseDir = args.importer ? path.dirname(args.importer) : contextRoot;
+      return path.resolve(baseDir, value);
+    }
+    return value;
+  }
+  /**
+   * Creates an esbuild plugin bridge compatible with the existing Ecopages
+   * plugin API shape.
+   *
+   * **Plugin ordering is semantically significant.**
+   *
+   * Esbuild applies `onResolve` and `onLoad` hooks in the order they are
+   * registered: the first handler whose filter matches wins for `onResolve`,
+   * and the first handler that returns a non-`undefined` result wins for
+   * `onLoad`. Because we call `plugin.setup(bridge)` sequentially here, the
+   * position of each plugin in the `plugins` array determines its priority:
+   *
+   * - **Index 0** has the highest priority (its hooks run first).
+   * - **Last index** has the lowest priority (its hooks only run if no earlier
+   *   plugin claimed the path).
+   *
+   * When adding new integrations or processors, ensure security-critical plugins
+   * (e.g. `ecopages-client-graph-boundary`) are placed **before** general-purpose
+   * loaders in the array so they always get first refusal on every source file.
+   *
+   * There is currently no priority system or validation — correct ordering is
+   * the caller's responsibility.
+   */
+  createEcoPluginBridge(plugins, contextRoot) {
+    return {
+      name: "ecopages-plugin-bridge",
+      setup: async (build) => {
+        let moduleCounter = 0;
+        const bridge = {
+          onResolve: (options, callback) => {
+            build.onResolve(options, async (args) => {
+              const result = await callback({
+                path: args.path,
+                importer: args.importer,
+                namespace: args.namespace
+              });
+              if (!result || typeof result !== "object") {
+                return void 0;
+              }
+              const candidate = result;
+              const resolveResult = {};
+              if (typeof candidate.path === "string") {
+                resolveResult.path = this.resolvePluginPath(candidate.path, args, contextRoot);
+              }
+              if (typeof candidate.namespace === "string") {
+                resolveResult.namespace = candidate.namespace;
+              }
+              if (typeof candidate.external === "boolean") {
+                resolveResult.external = candidate.external;
+              }
+              return Object.keys(resolveResult).length > 0 ? resolveResult : void 0;
+            });
+          },
+          onLoad: (options, callback) => {
+            build.onLoad(options, async (args) => {
+              const result = await callback({
+                path: args.path,
+                namespace: args.namespace
+              });
+              return this.convertPluginOnLoadResult(args, result);
+            });
+          },
+          module: (specifier, callback) => {
+            const namespace = `ecopages-module-${moduleCounter}`;
+            moduleCounter += 1;
+            const filter = new RegExp(`^${this.escapeRegExp(specifier)}$`);
+            build.onResolve({ filter }, () => ({
+              path: specifier,
+              namespace
+            }));
+            build.onLoad({ filter, namespace }, async (args) => {
+              const result = await callback();
+              return this.convertPluginOnLoadResult(args, result);
+            });
+          }
+        };
+        for (const plugin of plugins) {
+          await plugin.setup(bridge);
+        }
+      }
+    };
+  }
+  async loadEsbuildModule(moduleGeneration = 0) {
+    const importedModule = await import("esbuild");
+    const esbuildModule = typeof importedModule.build === "function" ? importedModule : importedModule.default ?? importedModule;
+    if (moduleGeneration > 0 && !this.isMockedEsbuildModule(esbuildModule)) {
+      const freshModule = await import(`${pathToFileURL(esbuildRequire.resolve("esbuild")).href}?ecopages_esbuild=${moduleGeneration}`);
+      const normalizedFreshModule = typeof freshModule.build === "function" ? freshModule : freshModule.default ?? freshModule;
+      if (typeof normalizedFreshModule.build === "function") {
+        return normalizedFreshModule;
+      }
+    }
+    if (typeof esbuildModule.build !== "function") {
+      throw new Error("esbuild is not available. Install esbuild to use Node bundling.");
+    }
+    return esbuildModule;
+  }
+  isMockedEsbuildModule(esbuildModule) {
+    const build = esbuildModule.build;
+    const stop = esbuildModule.stop;
+    return typeof build?.mock === "object" || typeof stop?.mock === "object";
+  }
+  /**
+   * Detects the subset of runtime faults that indicate esbuild's worker
+   * protocol is corrupted rather than a normal build error.
+   */
+  isEsbuildProtocolError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    return ["Unexpected end of JSON input", "Unexpected EOF", "parseJSON", "buildResponseToResult"].some(
+      (fragment) => error.message.includes(fragment) || error.stack?.includes(fragment)
+    );
+  }
+  async stopEsbuildService(moduleGeneration = 0) {
+    const esbuild = await this.loadEsbuildModule(moduleGeneration);
+    if (typeof esbuild.stop === "function") {
+      esbuild.stop();
+    }
+  }
+  async buildOrThrow(options, moduleGeneration = 0) {
+    const esbuild = await this.loadEsbuildModule(moduleGeneration);
+    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+    const outdir = path.resolve(options.outdir ?? "dist/assets");
+    const tsconfigPath = path.join(contextRoot, "tsconfig.json");
+    const tsconfigExists = fileSystem.exists(tsconfigPath);
+    const plugins = this.getPluginsForBuild(options.plugins);
+    const esbuildPlugins = [
+      ...plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []
+    ];
+    const transpileTarget = "es2022";
+    const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
+    const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : void 0;
+    if (outfile) {
+      fileSystem.ensureDir(path.dirname(outfile));
+    }
+    const outputOptions = outfile ? { outfile } : {
+      outdir,
+      ...options.outbase ? { outbase: path.resolve(options.outbase) } : {},
+      entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
+      chunkNames: "[name]-[hash]",
+      assetNames: "[name]-[hash]"
+    };
+    const result = await esbuild.build({
+      absWorkingDir: contextRoot,
+      entryPoints: options.entrypoints,
+      bundle: options.bundle ?? true,
+      ...outputOptions,
+      ...options.conditions ? { conditions: options.conditions } : {},
+      ...options.define ? { define: options.define } : {},
+      format: this.mapEsbuildFormat(options.format),
+      platform: options.target === "browser" ? "browser" : "node",
+      sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
+      splitting: outfile ? false : !!options.splitting,
+      minify: !!options.minify,
+      ...typeof options.treeshaking === "boolean" ? { treeShaking: options.treeshaking } : {},
+      external: options.external,
+      ...options.target !== "browser" && options.externalPackages !== false ? { packages: "external" } : {},
+      target: transpileTarget,
+      metafile: true,
+      write: true,
+      plugins: esbuildPlugins,
+      jsx: "automatic",
+      tsconfig: tsconfigExists ? tsconfigPath : void 0,
+      logLevel: "silent"
+    });
+    const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
+      path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath)
+    }));
+    const logs = result.warnings.map((warning) => ({ message: warning.text }));
+    const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
+    return {
+      success: true,
+      logs,
+      outputs,
+      dependencyGraph
+    };
+  }
+  mapEsbuildSourcemap(value) {
+    switch (value) {
+      case "none":
+        return false;
+      case "inline":
+        return "inline";
+      case "both":
+        return "both";
+      case "external":
+        return "external";
+      default:
+        return "linked";
+    }
+  }
+  mapEsbuildFormat(value) {
+    switch (value) {
+      case "cjs":
+        return "cjs";
+      case "iife":
+        return "iife";
+      default:
+        return "esm";
+    }
+  }
+  hasTemplateTokens(value) {
+    return typeof value === "string" && /\[[^\]]+\]/.test(value);
+  }
+  toEntryNamePattern(value) {
+    if (!value) {
+      return "[name]";
+    }
+    const pattern = value.replaceAll(/\.?\[ext\]/g, "");
+    return pattern.length > 0 ? pattern : "[name]";
+  }
+  normalizeMetafilePath(value, contextRoot) {
+    if (path.isAbsolute(value)) {
+      return path.normalize(value);
+    }
+    return path.normalize(path.resolve(contextRoot, value));
+  }
+  extractDependencyGraph(metafile, contextRoot) {
+    const entrypoints = /* @__PURE__ */ new Map();
+    for (const outputMeta of Object.values(metafile.outputs)) {
+      if (!outputMeta.entryPoint) {
+        continue;
+      }
+      const entrypointPath = this.normalizeMetafilePath(outputMeta.entryPoint, contextRoot);
+      const dependencies = entrypoints.get(entrypointPath) ?? /* @__PURE__ */ new Set();
+      dependencies.add(entrypointPath);
+      for (const inputPath of Object.keys(outputMeta.inputs ?? {})) {
+        dependencies.add(this.normalizeMetafilePath(inputPath, contextRoot));
+      }
+      entrypoints.set(entrypointPath, dependencies);
+    }
+    return {
+      entrypoints: Object.fromEntries(
+        Array.from(entrypoints.entries(), ([entrypointPath, dependencies]) => [
+          entrypointPath,
+          Array.from(dependencies)
+        ])
+      )
+    };
+  }
+  /**
+   * Normalizes esbuild errors into Ecopages `BuildLog` entries.
+   */
+  toBuildLogs(error) {
+    if (error && typeof error === "object") {
+      const candidate = error;
+      if (Array.isArray(candidate.errors) && candidate.errors.length > 0) {
+        return candidate.errors.map((entry) => {
+          const locationPrefix = entry.location?.file ? `${entry.location.file}:${entry.location.line ?? 0}:${entry.location.column ?? 0} ` : "";
+          return {
+            message: `${locationPrefix}${entry.text ?? "Unknown esbuild error"}`
+          };
+        });
+      }
+      if (typeof candidate.message === "string") {
+        return [{ message: candidate.message }];
+      }
+    }
+    return [{ message: "Unknown esbuild error" }];
+  }
+  createFailureResult(error) {
+    return {
+      success: false,
+      logs: this.toBuildLogs(error),
+      outputs: []
+    };
+  }
+  /**
+   * Bundles entrypoints using esbuild for Node runtime builds.
+   */
+  async build(options) {
+    try {
+      return await this.buildOrThrow(options);
+    } catch (error) {
+      return this.createFailureResult(error);
+    }
+  }
+  /**
+   * Resolves module specifiers from a project root.
+   */
+  resolve(importPath, rootDir) {
+    const localRequire = createRequire(path.join(rootDir, "package.json"));
+    return localRequire.resolve(importPath);
+  }
+  /**
+   * Returns transpile defaults for a known transpile profile.
+   */
+  getTranspileOptions(profile) {
+    return transpileProfileToOptions(profile);
+  }
+}
+export {
+  EsbuildBuildAdapter
+};

package/src/build/runtime-build-executor.d.ts

@@ -0,0 +1,13 @@
+import type { EcoPagesAppConfig } from '../internal-types.js';
+import { type BuildExecutor } from './build-adapter.js';
+/**
+ * Installs the app-owned runtime build executor for one app instance.
+ *
+ * @remarks
+ * This is the single coordinator boundary for runtime executor ownership across
+ * adapters. It preserves an existing development coordinator when available and
+ * always applies app server build plugins through one shared path.
+ */
+export declare function installAppRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
+    development: boolean;
+}): BuildExecutor;

package/src/build/runtime-build-executor.js

@@ -0,0 +1,20 @@
+import {
+  getAppBuildAdapter,
+  getAppBuildExecutor,
+  getAppServerBuildPlugins,
+  setAppBuildExecutor
+} from "./build-adapter.js";
+import { createOrReuseAppBuildExecutor } from "./dev-build-coordinator.js";
+function installAppRuntimeBuildExecutor(appConfig, options) {
+  const buildExecutor = createOrReuseAppBuildExecutor({
+    development: options.development,
+    adapter: getAppBuildAdapter(appConfig),
+    currentExecutor: getAppBuildExecutor(appConfig),
+    getPlugins: () => getAppServerBuildPlugins(appConfig)
+  });
+  setAppBuildExecutor(appConfig, buildExecutor);
+  return buildExecutor;
+}
+export {
+  installAppRuntimeBuildExecutor
+};

package/src/build/runtime-specifier-alias-plugin.d.ts

@@ -0,0 +1,15 @@
+import type { EcoBuildPlugin } from './build-types.js';
+type RuntimeSpecifierMap = ReadonlyMap<string, string> | Record<string, string>;
+/**
+ * Creates a build plugin that aliases runtime bare specifiers to concrete URLs.
+ *
+ * @remarks
+ * This helper is used when browser-target builds must preserve integration-owned
+ * runtime specifier semantics while letting the bundler treat the mapped URLs as
+ * external runtime assets.
+ */
+export declare function createRuntimeSpecifierAliasPlugin(specifierMapInput: RuntimeSpecifierMap, options?: {
+    name?: string;
+    external?: boolean;
+}): EcoBuildPlugin | null;
+export {};

package/src/build/runtime-specifier-alias-plugin.js

@@ -0,0 +1,31 @@
+function toRuntimeSpecifierMap(specifierMap) {
+  return specifierMap instanceof Map ? specifierMap : new Map(Object.entries(specifierMap));
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createRuntimeSpecifierAliasPlugin(specifierMapInput, options) {
+  const specifierMap = toRuntimeSpecifierMap(specifierMapInput);
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const filter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
+  return {
+    name: options?.name ?? "runtime-specifier-alias",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external: options?.external ?? true
+        };
+      });
+    }
+  };
+}
+export {
+  createRuntimeSpecifierAliasPlugin
+};