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

package/src/build/build-adapter.js

@@ -0,0 +1,168 @@
+import {
+  createAppBuildManifest,
+  getBrowserBuildPlugins,
+  getServerBuildPlugins
+} from "./build-manifest.js";
+import { EsbuildBuildAdapter } from "./esbuild-build-adapter.js";
+import { getRequiredBunRuntime } from "../utils/runtime.js";
+import { EsbuildBuildAdapter as EsbuildBuildAdapter2 } from "./esbuild-build-adapter.js";
+function createBuildAdapter() {
+  return new EsbuildBuildAdapter();
+}
+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 BunBuildAdapter {
+  async build(options) {
+    const bun = getRequiredBunRuntime();
+    const result = await bun.build({
+      ...options,
+      plugins: options.plugins
+    });
+    return {
+      success: result.success,
+      logs: result.logs.map((log) => ({ message: log.message })),
+      outputs: result.outputs.map((output) => ({ path: output.path }))
+    };
+  }
+  resolve(importPath, rootDir) {
+    return getRequiredBunRuntime().resolveSync(importPath, rootDir);
+  }
+  getTranspileOptions(profile) {
+    return transpileProfileToOptions(profile);
+  }
+}
+const defaultBuildAdapter = createBuildAdapter();
+function getAppBuildAdapter(appConfig) {
+  return appConfig.runtime?.buildAdapter ?? defaultBuildAdapter;
+}
+function setAppBuildAdapter(appConfig, buildAdapter) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildAdapter
+  };
+}
+function getAppBuildManifest(appConfig) {
+  return appConfig.runtime?.buildManifest ?? createAppBuildManifest({
+    loaderPlugins: Array.from(appConfig.loaders.values())
+  });
+}
+function setAppBuildManifest(appConfig, buildManifest) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildManifest
+  };
+}
+function createConfiguredAppBuildManifest(appConfig, input) {
+  return createAppBuildManifest({
+    loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
+    runtimePlugins: input?.runtimePlugins,
+    browserBundlePlugins: input?.browserBundlePlugins
+  });
+}
+function updateAppBuildManifest(appConfig, input) {
+  setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
+}
+async function collectConfiguredAppBuildManifestContributions(appConfig) {
+  const runtimePlugins = [];
+  const browserBundlePlugins = [];
+  for (const processor of appConfig.processors.values()) {
+    await processor.prepareBuildContributions();
+    if (processor.plugins) {
+      runtimePlugins.push(...processor.plugins);
+    }
+    if (processor.buildPlugins) {
+      browserBundlePlugins.push(...processor.buildPlugins);
+    }
+  }
+  for (const integration of appConfig.integrations) {
+    integration.setConfig(appConfig);
+    await integration.prepareBuildContributions();
+    runtimePlugins.push(...integration.plugins);
+  }
+  return {
+    runtimePlugins,
+    browserBundlePlugins
+  };
+}
+async function setupAppRuntimePlugins(options) {
+  for (const processor of options.appConfig.processors.values()) {
+    await processor.setup();
+    if (processor.plugins) {
+      for (const plugin of processor.plugins) {
+        options.onRuntimePlugin?.(plugin);
+      }
+    }
+  }
+  for (const integration of options.appConfig.integrations) {
+    integration.setConfig(options.appConfig);
+    integration.setRuntimeOrigin(options.runtimeOrigin);
+    if (options.hmrManager) {
+      integration.setHmrManager(options.hmrManager);
+    }
+    await integration.setup();
+    for (const plugin of integration.plugins) {
+      options.onRuntimePlugin?.(plugin);
+    }
+  }
+}
+function getAppServerBuildPlugins(appConfig) {
+  return getServerBuildPlugins(getAppBuildManifest(appConfig));
+}
+function getAppBrowserBuildPlugins(appConfig) {
+  return getBrowserBuildPlugins(getAppBuildManifest(appConfig));
+}
+function getAppBuildExecutor(appConfig) {
+  return appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
+}
+function setAppBuildExecutor(appConfig, buildExecutor) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildExecutor
+  };
+}
+function build(options, executor = defaultBuildAdapter) {
+  return executor.build(options);
+}
+function getTranspileOptions(profile) {
+  return defaultBuildAdapter.getTranspileOptions(profile);
+}
+export {
+  BunBuildAdapter,
+  EsbuildBuildAdapter2 as EsbuildBuildAdapter,
+  build,
+  collectConfiguredAppBuildManifestContributions,
+  createBuildAdapter,
+  createConfiguredAppBuildManifest,
+  defaultBuildAdapter,
+  getAppBrowserBuildPlugins,
+  getAppBuildAdapter,
+  getAppBuildExecutor,
+  getAppBuildManifest,
+  getAppServerBuildPlugins,
+  getTranspileOptions,
+  setAppBuildAdapter,
+  setAppBuildExecutor,
+  setAppBuildManifest,
+  setupAppRuntimePlugins,
+  updateAppBuildManifest
+};

package/src/build/build-manifest.d.ts

@@ -0,0 +1,27 @@
+import type { EcoBuildPlugin } from './build-types.js';
+export interface AppBuildManifest {
+    loaderPlugins: EcoBuildPlugin[];
+    runtimePlugins: EcoBuildPlugin[];
+    browserBundlePlugins: EcoBuildPlugin[];
+}
+/**
+ * Merges plugin lists while preserving first-registration precedence by name.
+ *
+ * @remarks
+ * Build manifests treat plugin names as stable identities. The first plugin
+ * with a given name wins so config-time assembly stays deterministic across
+ * loader, runtime, and browser buckets.
+ */
+export declare function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[];
+/**
+ * Creates one app-owned build manifest from the supplied plugin buckets.
+ */
+export declare function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Returns the plugin list used for server-oriented builds.
+ */
+export declare function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];
+/**
+ * Returns the plugin list used for browser-oriented builds.
+ */
+export declare function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];

package/src/build/build-manifest.js

@@ -0,0 +1,30 @@
+function mergeEcoBuildPlugins(...pluginLists) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const plugins of pluginLists) {
+    for (const plugin of plugins ?? []) {
+      if (!byName.has(plugin.name)) {
+        byName.set(plugin.name, plugin);
+      }
+    }
+  }
+  return Array.from(byName.values());
+}
+function createAppBuildManifest(input) {
+  return {
+    loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
+    runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
+    browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins)
+  };
+}
+function getServerBuildPlugins(manifest) {
+  return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
+}
+function getBrowserBuildPlugins(manifest) {
+  return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, manifest.browserBundlePlugins);
+}
+export {
+  createAppBuildManifest,
+  getBrowserBuildPlugins,
+  getServerBuildPlugins,
+  mergeEcoBuildPlugins
+};

package/src/build/build-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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/dev-build-coordinator.d.ts

@@ -0,0 +1,74 @@
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildResult, EsbuildBuildAdapter } from './build-adapter.js';
+import type { EcoBuildPlugin } from './build-types.js';
+export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
+/**
+ * Serialized development build coordinator for the shared esbuild adapter.
+ *
+ * The underlying adapter remains responsible for plain build execution. This
+ * coordinator owns the policy that must be shared across callers in dev mode:
+ *
+ * - serialized access to the shared esbuild service
+ * - warm-service recycling for Node-target builds
+ * - recovery from known esbuild worker protocol faults
+ *
+ * Unlike the previous design, the coordinator does not monkey-patch the adapter
+ * or install process-level fault handlers. The owning app/runtime passes this
+ * executor explicitly to build consumers that need coordinated development
+ * builds.
+ */
+export declare class DevBuildCoordinator implements BuildExecutor {
+    private buildQueue;
+    private esbuildSessionWarm;
+    private esbuildModuleGeneration;
+    private readonly adapter;
+    constructor(adapter: EsbuildBuildAdapter);
+    /**
+     * Executes a build through the serialized development queue.
+     *
+     * Node-target builds recycle the warmed esbuild service between requests to
+     * avoid stale worker state accumulating across long-lived dev sessions.
+     *
+     * If an esbuild protocol fault is detected, the coordinator resets the queue,
+     * stops the corrupted service, increments the module generation, and retries
+     * the build once.
+     */
+    build(options: BuildOptions): Promise<BuildResult>;
+    /**
+     * Attempts recovery from a known esbuild worker protocol fault.
+     *
+     * Returns `true` only when the error matches the protocol-fault signature and
+     * the coordinator successfully reset its shared state.
+     */
+    recoverFromProtocolFault(error: unknown): Promise<boolean>;
+    /**
+     * Clears internal coordinator state for isolated tests.
+     */
+    resetForTests(): void;
+    /**
+     * Overrides the internal queue promise for fault-recovery tests.
+     */
+    setBuildQueueForTests(queue: Promise<void>): void;
+    /**
+     * Returns the current internal queue promise for fault-recovery tests.
+     */
+    getBuildQueueForTests(): Promise<void>;
+    private shouldRecycleEsbuildService;
+    private runSerialized;
+}
+/**
+ * Creates the appropriate build executor for one app/runtime instance.
+ *
+ * Development runtimes get a dedicated coordinator around the shared esbuild
+ * adapter. Non-development runtimes use the adapter directly.
+ */
+export declare function createAppBuildExecutor(options: {
+    development: boolean;
+    adapter?: BuildAdapter;
+    getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor;
+export declare function createOrReuseAppBuildExecutor(options: {
+    development: boolean;
+    adapter?: BuildAdapter;
+    currentExecutor?: BuildExecutor;
+    getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor;

package/src/build/dev-build-coordinator.js

@@ -0,0 +1,161 @@
+import { appLogger } from "../global/app-logger.js";
+import {
+  defaultBuildAdapter,
+  EsbuildBuildAdapter
+} from "./build-adapter.js";
+import { mergeEcoBuildPlugins } from "./build-manifest.js";
+function mergeBuildPlugins(options, appPlugins) {
+  if (appPlugins.length === 0) {
+    return options;
+  }
+  return {
+    ...options,
+    plugins: mergeEcoBuildPlugins(options.plugins, appPlugins)
+  };
+}
+class BuildExecutorWithPlugins {
+  executor;
+  getPlugins;
+  constructor(executor, getPlugins) {
+    this.executor = executor;
+    this.getPlugins = getPlugins;
+  }
+  async build(options) {
+    return await this.executor.build(mergeBuildPlugins(options, this.getPlugins()));
+  }
+  unwrap() {
+    return this.executor;
+  }
+}
+function unwrapBuildExecutor(executor) {
+  if (executor instanceof BuildExecutorWithPlugins) {
+    return unwrapBuildExecutor(executor.unwrap());
+  }
+  return executor;
+}
+function withBuildExecutorPlugins(executor, getPlugins) {
+  return new BuildExecutorWithPlugins(executor, getPlugins);
+}
+class DevBuildCoordinator {
+  buildQueue = Promise.resolve();
+  esbuildSessionWarm = false;
+  esbuildModuleGeneration = 0;
+  adapter;
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  /**
+   * Executes a build through the serialized development queue.
+   *
+   * Node-target builds recycle the warmed esbuild service between requests to
+   * avoid stale worker state accumulating across long-lived dev sessions.
+   *
+   * If an esbuild protocol fault is detected, the coordinator resets the queue,
+   * stops the corrupted service, increments the module generation, and retries
+   * the build once.
+   */
+  async build(options) {
+    return this.runSerialized(async () => {
+      try {
+        if (this.shouldRecycleEsbuildService(options)) {
+          await this.adapter.stopEsbuildService(this.esbuildModuleGeneration);
+          this.esbuildSessionWarm = false;
+        }
+        const result = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+        this.esbuildSessionWarm = true;
+        return result;
+      } catch (error) {
+        if (await this.recoverFromProtocolFault(error)) {
+          appLogger.warn("Recovered from esbuild protocol fault. Retrying build.");
+          try {
+            const retry = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+            this.esbuildSessionWarm = true;
+            return retry;
+          } catch (retryError) {
+            return this.adapter.createFailureResult(retryError);
+          }
+        }
+        return this.adapter.createFailureResult(error);
+      }
+    });
+  }
+  /**
+   * Attempts recovery from a known esbuild worker protocol fault.
+   *
+   * Returns `true` only when the error matches the protocol-fault signature and
+   * the coordinator successfully reset its shared state.
+   */
+  async recoverFromProtocolFault(error) {
+    if (!this.adapter.isEsbuildProtocolError(error)) {
+      return false;
+    }
+    this.buildQueue = Promise.resolve();
+    this.esbuildSessionWarm = false;
+    await this.adapter.stopEsbuildService(this.esbuildModuleGeneration);
+    this.esbuildModuleGeneration += 1;
+    return true;
+  }
+  /**
+   * Clears internal coordinator state for isolated tests.
+   */
+  resetForTests() {
+    this.buildQueue = Promise.resolve();
+    this.esbuildSessionWarm = false;
+    this.esbuildModuleGeneration = 0;
+  }
+  /**
+   * Overrides the internal queue promise for fault-recovery tests.
+   */
+  setBuildQueueForTests(queue) {
+    this.buildQueue = queue;
+  }
+  /**
+   * Returns the current internal queue promise for fault-recovery tests.
+   */
+  getBuildQueueForTests() {
+    return this.buildQueue;
+  }
+  shouldRecycleEsbuildService(options) {
+    return process.env.NODE_ENV === "development" && options.target !== "browser" && this.esbuildSessionWarm;
+  }
+  async runSerialized(operation) {
+    let releaseBuild;
+    const currentBuild = new Promise((resolve) => {
+      releaseBuild = resolve;
+    });
+    const previousBuild = this.buildQueue;
+    this.buildQueue = previousBuild.catch(() => void 0).then(async () => await currentBuild);
+    await previousBuild.catch(() => void 0);
+    try {
+      return await operation();
+    } finally {
+      releaseBuild?.();
+    }
+  }
+}
+function createAppBuildExecutor(options) {
+  const adapter = options.adapter ?? defaultBuildAdapter;
+  const baseExecutor = !options.development || !(adapter instanceof EsbuildBuildAdapter) ? adapter : new DevBuildCoordinator(adapter);
+  if (!options.getPlugins) {
+    return baseExecutor;
+  }
+  return new BuildExecutorWithPlugins(baseExecutor, options.getPlugins);
+}
+function createOrReuseAppBuildExecutor(options) {
+  const adapter = options.adapter ?? defaultBuildAdapter;
+  const currentBaseExecutor = options.currentExecutor ? unwrapBuildExecutor(options.currentExecutor) : void 0;
+  const baseExecutor = options.development && currentBaseExecutor instanceof DevBuildCoordinator ? currentBaseExecutor : createAppBuildExecutor({
+    development: options.development,
+    adapter
+  });
+  if (!options.getPlugins) {
+    return baseExecutor;
+  }
+  return withBuildExecutorPlugins(baseExecutor, options.getPlugins);
+}
+export {
+  DevBuildCoordinator,
+  createAppBuildExecutor,
+  createOrReuseAppBuildExecutor,
+  withBuildExecutorPlugins
+};

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

@@ -0,0 +1,72 @@
+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 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 isMockedEsbuildModule;
+    /**
+     * Detects the subset of runtime faults that indicate esbuild's worker
+     * protocol is corrupted rather than a normal build error.
+     */
+    isEsbuildProtocolError(error: unknown): boolean;
+    stopEsbuildService(moduleGeneration?: number): Promise<void>;
+    buildOrThrow(options: BuildOptions, moduleGeneration?: number): Promise<BuildResult>;
+    private mapEsbuildSourcemap;
+    private mapEsbuildFormat;
+    private hasTemplateTokens;
+    private toEntryNamePattern;
+    private normalizeMetafilePath;
+    private extractDependencyGraph;
+    /**
+     * Normalizes esbuild errors into Ecopages `BuildLog` entries.
+     */
+    private toBuildLogs;
+    createFailureResult(error: unknown): BuildResult;
+    /**
+     * 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;
+    /**
+     * Returns transpile defaults for a known transpile profile.
+     */
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}