@ecopages/core 0.2.0-alpha.1

package/src/build/build-types.ts

@@ -0,0 +1,83 @@
+/**
+ * Arguments passed to a build plugin `onResolve` callback.
+ */
+export type EcoBuildOnResolveArgs = {
+	path: string;
+	importer?: string;
+	namespace?: string;
+};
+
+/**
+ * Result returned by a build plugin `onResolve` callback.
+ */
+export type EcoBuildOnResolveResult = {
+	path?: string;
+	namespace?: string;
+	external?: boolean;
+};
+
+/**
+ * Arguments passed to a build plugin `onLoad` callback.
+ */
+export type EcoBuildOnLoadArgs = {
+	path: string;
+	namespace?: string;
+};
+
+/**
+ * Loader kinds supported across Bun/esbuild bridge points.
+ */
+export type EcoBuildLoader =
+	| 'base64'
+	| 'binary'
+	| 'copy'
+	| 'css'
+	| 'dataurl'
+	| 'empty'
+	| 'file'
+	| 'global-css'
+	| 'js'
+	| 'json'
+	| 'jsx'
+	| 'local-css'
+	| 'object'
+	| 'text'
+	| 'ts'
+	| 'tsx';
+
+/**
+ * Result returned by a build plugin `onLoad` callback.
+ */
+export type EcoBuildOnLoadResult = {
+	contents?: string | Uint8Array;
+	loader?: EcoBuildLoader;
+	exports?: Record<string, unknown>;
+	resolveDir?: string;
+};
+
+/**
+ * Shared plugin builder contract used by Ecopages across Bun and esbuild.
+ */
+export interface EcoBuildPluginBuilder {
+	onResolve(
+		options: { filter: RegExp; namespace?: string },
+		callback: (
+			args: EcoBuildOnResolveArgs,
+		) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>,
+	): void;
+	onLoad(
+		options: { filter: RegExp; namespace?: string },
+		callback: (
+			args: EcoBuildOnLoadArgs,
+		) => EcoBuildOnLoadResult | undefined | Promise<EcoBuildOnLoadResult | undefined>,
+	): void;
+	module(specifier: string, callback: () => EcoBuildOnLoadResult | Promise<EcoBuildOnLoadResult>): void;
+}
+
+/**
+ * Runtime-agnostic build plugin contract consumed by Ecopages processors/loaders.
+ */
+export type EcoBuildPlugin = {
+	name: string;
+	setup: (build: EcoBuildPluginBuilder) => void | Promise<void>;
+};

package/src/build/esbuild-build-adapter.d.ts

@@ -0,0 +1,69 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
+/**
+ * Node build adapter backed by esbuild.
+ *
+ * This adapter keeps Ecopages build plugin compatibility (`onResolve`, `onLoad`,
+ * and `module`) while delegating bundling and TypeScript/decorator transforms to esbuild.
+ */
+export declare class EsbuildBuildAdapter implements BuildAdapter {
+    private registeredPlugins;
+    private escapeRegExp;
+    private getPluginsForBuild;
+    private normalizeEsbuildLoader;
+    private inferEsbuildLoaderFromPath;
+    private convertLoadResultToModuleSource;
+    private convertPluginOnLoadResult;
+    private resolvePluginPath;
+    /**
+     * 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.
+     */
+    private createEcoPluginBridge;
+    private loadEsbuildModule;
+    private mapEsbuildSourcemap;
+    private mapEsbuildFormat;
+    private hasTemplateTokens;
+    private toEntryNamePattern;
+    private normalizeMetafilePath;
+    private extractDependencyGraph;
+    /**
+     * Normalizes esbuild errors into Ecopages `BuildLog` entries.
+     */
+    private toBuildLogs;
+    /**
+     * Bundles entrypoints using esbuild for Node runtime builds.
+     */
+    build(options: BuildOptions): Promise<BuildResult>;
+    /**
+     * Resolves module specifiers from a project root.
+     */
+    resolve(importPath: string, rootDir: string): string;
+    /**
+     * Registers a build plugin once by plugin name.
+     */
+    registerPlugin(plugin: EcoBuildPlugin): void;
+    /**
+     * Returns transpile defaults for a known transpile profile.
+     */
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}

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

@@ -0,0 +1,390 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileSystem } from "@ecopages/file-system";
+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 {
+  registeredPlugins = [];
+  escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  getPluginsForBuild(additionalPlugins) {
+    const merged = [...additionalPlugins ?? [], ...this.registeredPlugins];
+    const byName = /* @__PURE__ */ new Map();
+    for (const plugin of merged) {
+      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() {
+    const esbuildModule = await import("esbuild");
+    if (typeof esbuildModule.build !== "function") {
+      throw new Error("esbuild is not available. Install esbuild to use Node bundling.");
+    }
+    return esbuildModule;
+  }
+  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" }];
+  }
+  /**
+   * Bundles entrypoints using esbuild for Node runtime builds.
+   */
+  async build(options) {
+    const esbuild = await this.loadEsbuildModule();
+    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+    const outdir = path.resolve(options.outdir ?? ".eco/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,
+      entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
+      chunkNames: "[name]-[hash]",
+      assetNames: "[name]-[hash]"
+    };
+    try {
+      const result = await esbuild.build({
+        absWorkingDir: contextRoot,
+        entryPoints: options.entrypoints,
+        bundle: options.bundle ?? true,
+        ...outputOptions,
+        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
+      };
+    } catch (error) {
+      return {
+        success: false,
+        logs: this.toBuildLogs(error),
+        outputs: []
+      };
+    }
+  }
+  /**
+   * Resolves module specifiers from a project root.
+   */
+  resolve(importPath, rootDir) {
+    const localRequire = createRequire(path.join(rootDir, "package.json"));
+    return localRequire.resolve(importPath);
+  }
+  /**
+   * Registers a build plugin once by plugin name.
+   */
+  registerPlugin(plugin) {
+    if (!this.registeredPlugins.find((registered) => registered.name === plugin.name)) {
+      this.registeredPlugins.push(plugin);
+    }
+  }
+  /**
+   * Returns transpile defaults for a known transpile profile.
+   */
+  getTranspileOptions(profile) {
+    return transpileProfileToOptions(profile);
+  }
+}
+export {
+  EsbuildBuildAdapter
+};