@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

package/src/build/dev-build-coordinator.d.ts

@@ -1,74 +0,0 @@
-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

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

@@ -1,221 +0,0 @@
-import { appLogger } from '../global/app-logger.ts';
-import {
-	defaultBuildAdapter,
-	type BuildAdapter,
-	type BuildExecutor,
-	type BuildOptions,
-	type BuildResult,
-	EsbuildBuildAdapter,
-} from './build-adapter.ts';
-import { mergeEcoBuildPlugins } from './build-manifest.ts';
-import type { EcoBuildPlugin } from './build-types.ts';
-
-function mergeBuildPlugins(options: BuildOptions, appPlugins: EcoBuildPlugin[]): BuildOptions {
-	if (appPlugins.length === 0) {
-		return options;
-	}
-
-	return {
-		...options,
-		plugins: mergeEcoBuildPlugins(options.plugins, appPlugins),
-	};
-}
-
-class BuildExecutorWithPlugins implements BuildExecutor {
-	private readonly executor: BuildExecutor;
-	private readonly getPlugins: () => EcoBuildPlugin[];
-
-	constructor(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]) {
-		this.executor = executor;
-		this.getPlugins = getPlugins;
-	}
-
-	async build(options: BuildOptions): Promise<BuildResult> {
-		return await this.executor.build(mergeBuildPlugins(options, this.getPlugins()));
-	}
-
-	unwrap(): BuildExecutor {
-		return this.executor;
-	}
-}
-
-function unwrapBuildExecutor(executor: BuildExecutor): BuildExecutor {
-	if (executor instanceof BuildExecutorWithPlugins) {
-		return unwrapBuildExecutor(executor.unwrap());
-	}
-
-	return executor;
-}
-
-export function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor {
-	return new BuildExecutorWithPlugins(executor, getPlugins);
-}
-
-/**
- * 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 class DevBuildCoordinator implements BuildExecutor {
-	private buildQueue: Promise<void> = Promise.resolve();
-	private esbuildSessionWarm = false;
-	private esbuildModuleGeneration = 0;
-	private readonly adapter: EsbuildBuildAdapter;
-
-	constructor(adapter: EsbuildBuildAdapter) {
-		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: BuildOptions): Promise<BuildResult> {
-		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: unknown): Promise<boolean> {
-		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(): void {
-		this.buildQueue = Promise.resolve();
-		this.esbuildSessionWarm = false;
-		this.esbuildModuleGeneration = 0;
-	}
-
-	/**
-	 * Overrides the internal queue promise for fault-recovery tests.
-	 */
-	setBuildQueueForTests(queue: Promise<void>): void {
-		this.buildQueue = queue;
-	}
-
-	/**
-	 * Returns the current internal queue promise for fault-recovery tests.
-	 */
-	getBuildQueueForTests(): Promise<void> {
-		return this.buildQueue;
-	}
-
-	private shouldRecycleEsbuildService(options: BuildOptions): boolean {
-		return process.env.NODE_ENV === 'development' && options.target !== 'browser' && this.esbuildSessionWarm;
-	}
-
-	private async runSerialized<T>(operation: () => Promise<T>): Promise<T> {
-		let releaseBuild: (() => void) | undefined;
-		const currentBuild = new Promise<void>((resolve) => {
-			releaseBuild = resolve;
-		});
-		const previousBuild = this.buildQueue;
-
-		this.buildQueue = previousBuild.catch(() => undefined).then(async () => await currentBuild);
-		await previousBuild.catch(() => undefined);
-
-		try {
-			return await operation();
-		} finally {
-			releaseBuild?.();
-		}
-	}
-}
-
-/**
- * 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 function createAppBuildExecutor(options: {
-	development: boolean;
-	adapter?: BuildAdapter;
-	getPlugins?: () => EcoBuildPlugin[];
-}): BuildExecutor {
-	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);
-}
-
-export function createOrReuseAppBuildExecutor(options: {
-	development: boolean;
-	adapter?: BuildAdapter;
-	currentExecutor?: BuildExecutor;
-	getPlugins?: () => EcoBuildPlugin[];
-}): BuildExecutor {
-	const adapter = options.adapter ?? defaultBuildAdapter;
-	const currentBaseExecutor = options.currentExecutor ? unwrapBuildExecutor(options.currentExecutor) : undefined;
-	const baseExecutor =
-		options.development && currentBaseExecutor instanceof DevBuildCoordinator
-			? currentBaseExecutor
-			: createAppBuildExecutor({
-					development: options.development,
-					adapter,
-				});
-
-	if (!options.getPlugins) {
-		return baseExecutor;
-	}
-
-	return withBuildExecutorPlugins(baseExecutor, options.getPlugins);
-}

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

@@ -1,72 +0,0 @@
-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;
-}