@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/build/browser-runtime-import-rewrite-plugin.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { parseSync } from "oxc-parser";
+import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
+const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");
+const DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME = "browser-runtime-import-rewrite";
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object";
+}
+function inferLoaderFromPath(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  switch (extension) {
+    case ".mts":
+    case ".cts":
+    case ".ts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    default:
+      return "js";
+  }
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function queueReplacement(options) {
+  if (!isRecord(options.source) || typeof options.source.value !== "string") {
+    return;
+  }
+  const mappedPath = options.specifierMap.get(options.source.value);
+  if (!mappedPath || typeof options.source.start !== "number" || typeof options.source.end !== "number") {
+    return;
+  }
+  const quote = options.code[options.source.start] === "'" ? "'" : '"';
+  options.edits.push({
+    start: options.source.start,
+    end: options.source.end,
+    replacement: `${quote}${mappedPath}${quote}`
+  });
+}
+function rewriteBrowserRuntimeImports(code, specifierMap, filePath = "browser-runtime-imports.js") {
+  if (specifierMap.size === 0) {
+    return code;
+  }
+  const edits = [];
+  try {
+    const result = parseSync(filePath, code, {
+      sourceType: "module",
+      lang: path.extname(filePath).endsWith("x") ? "tsx" : "ts"
+    });
+    const walk = (node) => {
+      if (!isRecord(node)) {
+        return;
+      }
+      if (node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration") {
+        queueReplacement({ code, source: node.source, specifierMap, edits });
+      }
+      if (node.type === "ImportExpression" && isRecord(node.source)) {
+        if (node.source.type === "StringLiteral" || node.source.type === "Literal") {
+          queueReplacement({ code, source: node.source, specifierMap, edits });
+        }
+      }
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            walk(child);
+          }
+        } else {
+          walk(value);
+        }
+      }
+    };
+    walk(result.program);
+  } catch {
+    return code;
+  }
+  if (edits.length === 0) {
+    return code;
+  }
+  edits.sort((left, right) => right.start - left.start);
+  let rewritten = code;
+  for (const edit of edits) {
+    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+  }
+  return rewritten;
+}
+function getBrowserRuntimeImportRewriteMap(plugin) {
+  return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
+}
+function collectBrowserRuntimeImportRewriteMap(plugins) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const plugin of plugins ?? []) {
+    const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
+    if (!specifierMap) {
+      continue;
+    }
+    for (const [specifier, publicPath] of specifierMap.entries()) {
+      if (!merged.has(specifier)) {
+        merged.set(specifier, publicPath);
+      }
+    }
+  }
+  return merged;
+}
+function createBrowserRuntimeImportRewritePlugin(options) {
+  const specifierMap = getBrowserRuntimeSpecifierMap(options.manifest);
+  const publicPathSet = new Set(specifierMap.values());
+  const specifierFilter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const plugin = {
+    name: options.name ?? DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+    setup(build) {
+      build.onResolve({ filter: specifierFilter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external: true
+        };
+      });
+      build.onResolve({ filter: /^\// }, (args) => {
+        if (!publicPathSet.has(args.path)) {
+          return void 0;
+        }
+        return {
+          path: args.path,
+          external: true
+        };
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+        if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+          return void 0;
+        }
+        const code = readFileSync(args.path, "utf-8");
+        const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+        if (rewritten === code) {
+          return void 0;
+        }
+        return {
+          contents: rewritten,
+          loader: inferLoaderFromPath(args.path),
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+  plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
+  return plugin;
+}
+export {
+  DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+  collectBrowserRuntimeImportRewriteMap,
+  createBrowserRuntimeImportRewritePlugin,
+  getBrowserRuntimeImportRewriteMap,
+  rewriteBrowserRuntimeImports
+};

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

@@ -0,0 +1,31 @@
+export type BrowserRuntimeMode = 'development' | 'production';
+export type BrowserRuntimeAssetDeclaration = {
+    /** Bare or virtual specifier used by authored/generated browser modules. */
+    specifier: string;
+    /** Integration, processor, or core subsystem that owns this runtime asset. */
+    owner: string;
+    /** Source import path used to build or resolve the runtime asset. */
+    importPath: string;
+    /** Concrete browser URL emitted or served for this runtime asset. */
+    publicPath: string;
+    /** Runtime mode this declaration applies to. Omit when the URL is mode-independent. */
+    mode?: BrowserRuntimeMode;
+    /** Specifiers that should be treated as external while building this runtime asset. */
+    externals?: readonly string[];
+};
+export type BrowserRuntimeAsset = BrowserRuntimeAssetDeclaration & {
+    externals: readonly string[];
+};
+export type BrowserRuntimeManifest = {
+    assets: readonly BrowserRuntimeAsset[];
+    bySpecifier: ReadonlyMap<string, BrowserRuntimeAsset>;
+};
+export declare class BrowserRuntimeManifestConflictError extends Error {
+    readonly specifier: string;
+    readonly existing: BrowserRuntimeAsset;
+    readonly incoming: BrowserRuntimeAsset;
+    constructor(specifier: string, existing: BrowserRuntimeAsset, incoming: BrowserRuntimeAsset);
+}
+export declare function createBrowserRuntimeManifest(declarations?: readonly BrowserRuntimeAssetDeclaration[]): BrowserRuntimeManifest;
+export declare function mergeBrowserRuntimeManifests(...manifests: Array<BrowserRuntimeManifest | undefined>): BrowserRuntimeManifest;
+export declare function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string>;

package/src/build/browser-runtime-manifest.js

@@ -0,0 +1,61 @@
+class BrowserRuntimeManifestConflictError extends Error {
+  specifier;
+  existing;
+  incoming;
+  constructor(specifier, existing, incoming) {
+    super(
+      `Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ${incoming.owner} maps to ${incoming.publicPath}`
+    );
+    this.name = "BrowserRuntimeManifestConflictError";
+    this.specifier = specifier;
+    this.existing = existing;
+    this.incoming = incoming;
+  }
+}
+function normalizeDeclaration(declaration) {
+  return {
+    ...declaration,
+    externals: declaration.externals ?? []
+  };
+}
+function hasCompatibleRuntimeAsset(existing, incoming) {
+  return existing.owner === incoming.owner && existing.importPath === incoming.importPath && existing.publicPath === incoming.publicPath && existing.mode === incoming.mode && arrayEquals(existing.externals, incoming.externals);
+}
+function arrayEquals(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((value, index) => value === right[index]);
+}
+function createBrowserRuntimeManifest(declarations = []) {
+  const assets = [];
+  const bySpecifier = /* @__PURE__ */ new Map();
+  for (const declaration of declarations) {
+    const asset = normalizeDeclaration(declaration);
+    const existing = bySpecifier.get(asset.specifier);
+    if (existing) {
+      if (!hasCompatibleRuntimeAsset(existing, asset)) {
+        throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+      }
+      continue;
+    }
+    assets.push(asset);
+    bySpecifier.set(asset.specifier, asset);
+  }
+  return {
+    assets,
+    bySpecifier
+  };
+}
+function mergeBrowserRuntimeManifests(...manifests) {
+  return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+function getBrowserRuntimeSpecifierMap(manifest) {
+  return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}
+export {
+  BrowserRuntimeManifestConflictError,
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap,
+  mergeBrowserRuntimeManifests
+};

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

@@ -1,5 +1,9 @@
 import type { EcoBuildPlugin } from './build-types.js';
+import { type AppBuildManifest } from './build-manifest.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IHmrManager } from '../types/public-types.js';
 export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+export type BuildOwnership = 'bun-native' | 'vite-host';
 export interface BuildLog {
     message: string;
 }
@@ -38,6 +42,8 @@ export interface BuildOptions {
     outdir?: string;
     outbase?: string;
     naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
     minify?: boolean;
     treeshaking?: boolean;
     target?: string;
@@ -48,6 +54,14 @@ export interface BuildOptions {
     bundle?: boolean;
     externalPackages?: boolean;
     external?: string[];
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
     plugins?: EcoBuildPlugin[];
     [key: string]: unknown;
 }
@@ -58,18 +72,176 @@ export interface BuildTranspileOptions {
     sourcemap: string;
 }
 export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    /**
+     * Executes one concrete backend build.
+     *
+     * @remarks
+     * `BuildAdapter` is the low-level backend contract. Bun-native execution owns
+     * one adapter directly; Vite-hosted execution is represented as an explicit
+     * host-owned compatibility path rather than an implicit esbuild default.
+     */
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
 /**
- * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
+ * Runtime-owned facade for issuing builds.
+ *
+ * @remarks
+ * This is intentionally narrower than `BuildAdapter`. A build executor answers
+ * only the question "how should this app execute a build right now?".
+ *
+ * In Bun-native production and non-watch flows the executor is usually the
+ * adapter itself. In development watch flows the executor may be a
+ * compatibility coordinator around the Bun-native adapter while the Vite host
+ * path continues migrating toward host-owned execution.
  */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}
 export declare class BunBuildAdapter implements BuildAdapter {
+    readonly ownership: "bun-native";
+    private readonly fallbackAdapter;
+    private getPluginsForBuild;
+    private escapeRegExp;
+    private resolvePluginPath;
+    private inferLoaderFromPath;
+    private normalizeBunLoader;
+    private convertLoadResultToModuleSource;
+    private convertPluginOnLoadResult;
+    private createEcoPluginBridge;
+    private toBuildLogs;
+    private mapBunTarget;
+    private mapBunFormat;
+    private getOutputExtension;
+    private resolveConcreteOutputPath;
+    private normalizePathForMatch;
+    private normalizeOutputPathForMatch;
+    private extractTemplateHashTokens;
+    private applyTemplateHashTokens;
+    private resolveTemplatedOutputPath;
+    private relocateOutputFile;
+    private hasJavaScriptExtension;
+    private rewriteBrowserRuntimeImportsInOutputs;
+    private findOutputMatchForEntrypoint;
+    private normalizeBunOutputs;
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
+export declare class ViteHostBuildAdapter implements BuildAdapter {
+    readonly ownership: "vite-host";
+    build(_options: BuildOptions): Promise<BuildResult>;
+    resolve(_importPath: string, _rootDir: string): string;
+    getTranspileOptions(_profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+export declare function createBunBuildAdapter(): BuildAdapter;
+export declare function createViteHostBuildAdapter(): BuildAdapter;
+export declare function createBuildAdapter(options?: {
+    ownership?: BuildOwnership;
+}): BuildAdapter;
+export declare const defaultBunBuildAdapter: BuildAdapter;
+export declare const defaultViteHostBuildAdapter: BuildAdapter;
+/**
+ * Bun-native fallback export for callsites that still resolve build state
+ * globally.
+ *
+ * New app-aware code should prefer `getAppBuildAdapter()`.
+ */
 export declare const defaultBuildAdapter: BuildAdapter;
+export declare function getDefaultBuildAdapter(ownership?: BuildOwnership): BuildAdapter;
+export declare function getBuildAdapterOwnership(buildAdapter: BuildAdapter | undefined): BuildOwnership;
+export declare function getAppBuildOwnership(appConfig: EcoPagesAppConfig): BuildOwnership;
+export declare function setAppBuildOwnership(appConfig: EcoPagesAppConfig, buildOwnership: BuildOwnership): void;
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder installs an explicit adapter per app. The Bun-native
+ * fallback remains only as compatibility scaffolding for helpers that do not
+ * yet thread app runtime state explicitly.
+ */
+export declare function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter;
+/**
+ * Installs the adapter that should serve future builds for one app instance.
+ */
+export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void;
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ */
+export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
+/**
+ * Installs the build manifest that should be visible to one app instance.
+ */
+export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
+/**
+ * Rebuilds an app-owned manifest from config-owned loaders plus explicit
+ * runtime/browser contribution input.
+ *
+ * @remarks
+ * This keeps loader ownership with config finalization while still letting a
+ * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ */
+export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Replaces the app-owned manifest using config-owned loaders and explicit
+ * contribution input.
+ */
+export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
+/**
+ * Collects the build-facing processor and integration contributions that should
+ * be sealed into the app manifest during config finalization.
+ *
+ * @remarks
+ * This runs `prepareBuildContributions()` only. Runtime-only side effects such
+ * as HMR registration, cache prewarming, and runtime-origin wiring belong to
+ * the startup path and must not be triggered here.
+ */
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
+/**
+ * Runs runtime-only processor and integration setup against an already sealed
+ * app manifest.
+ *
+ * @remarks
+ * Startup paths call this after config build has finalized manifest
+ * contributions. The manifest is reused as-is; this helper only performs the
+ * runtime side effects that still need live startup context.
+ */
+export declare function setupAppRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;
+export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Returns the executor owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder seeds this with the app-owned adapter. Runtime adapters
+ * may replace it with a compatibility coordinator while keeping ownership tied
+ * to the same Bun-native backend.
+ */
+export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+/**
+ * Installs the executor that should serve future builds for one app instance.
+ */
+export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * Callers can pass an explicit executor when builds should be routed through an
+ * app-owned development coordinator. Without one, the Bun-native default
+ * adapter is used directly.
+ */
+export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
+/**
+ * Bun-native fallback helper for callsites without app runtime context.
+ *
+ * New app-aware code should prefer `getAppTranspileOptions()`.
+ */
+export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+export declare function getAppTranspileOptions(appConfig: EcoPagesAppConfig, profile: BuildTranspileProfile): BuildTranspileOptions;