@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/build/cache/cache-keys.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+let cachedCorePackageVersion;
+/**
+ * Returns the installed `@ecopages/core` package version for cache invalidation.
+ */
+export function getCorePackageVersion() {
+    if (cachedCorePackageVersion) {
+        return cachedCorePackageVersion;
+    }
+    const packageJsonPath = new URL('../../../package.json', import.meta.url);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    cachedCorePackageVersion = packageJson.version ?? '0.0.0';
+    return cachedCorePackageVersion;
+}
+/** Stable fingerprint for JSX options used in build and disk cache keys. */
+export function createJsxCacheKey(jsx) {
+    if (!jsx) {
+        return 'jsx:default';
+    }
+    return JSON.stringify({
+        development: jsx.development ?? false,
+        factory: jsx.factory ?? null,
+        fragment: jsx.fragment ?? null,
+        importSource: jsx.importSource ?? null,
+        runtime: jsx.runtime ?? null,
+        sideEffects: jsx.sideEffects ?? null,
+    });
+}
+/** Stable fingerprint for ordered build plugins. */
+export function createPluginCacheKey(plugins) {
+    if (!plugins || plugins.length === 0) {
+        return 'plugins:default';
+    }
+    return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashFunctionIdentity(plugin.setup)}`).join(',')}`;
+}
+/** Stable fingerprint for ordered source transforms. */
+export function createSourceTransformCacheKey(sourceTransforms) {
+    if (!sourceTransforms || sourceTransforms.length === 0) {
+        return 'sourceTransforms:default';
+    }
+    return `sourceTransforms:${sourceTransforms
+        .map((transform) => {
+        const filterSource = transform.filter.source;
+        const filterFlags = transform.filter.flags;
+        return [
+            transform.name,
+            transform.enforce ?? 'default',
+            filterSource,
+            filterFlags,
+            hashFunctionIdentity(transform.transform),
+        ].join(':');
+    })
+        .join(',')}`;
+}
+/**
+ * Stable fingerprint of a function body for cache and request identity keys.
+ *
+ * @remarks
+ * Hashes `fn.toString()`. Suitable for in-process and persisted keys that must
+ * agree within one install; not stable across minifiers or renames.
+ */
+export function hashFunctionIdentity(fn) {
+    let hash = 0;
+    const source = fn.toString();
+    for (let index = 0; index < source.length; index += 1) {
+        hash = (hash * 31 + source.charCodeAt(index)) | 0;
+    }
+    return (hash >>> 0).toString(36);
+}
+/** @deprecated Use {@link hashFunctionIdentity}. */
+export const hashPluginSetup = hashFunctionIdentity;

package/src/build/cache/pages-unified-graph-build.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Unified pages Rolldown graph (Phase A build + Phase C import).
+ *
+ * Enabled by default in production builds. Opt out with
+ * `ECOPAGES_UNIFIED_PAGES_GRAPH=0`. Covers all static page template extensions
+ * registered on the app config.
+ */
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export declare const PAGES_UNIFIED_GRAPH_CACHE_DIR = ".server-pages-graph";
+export declare const PAGES_UNIFIED_GRAPH_CACHE_FILENAME = ".build-cache.json";
+export interface PagesUnifiedGraphCacheManifest {
+    invalidationVersion: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    builtAt: number;
+    outputs: Record<string, string>;
+}
+export declare function isPagesUnifiedGraphEnabled(): boolean;
+/** True when the unified graph should build or serve prebuilt page modules. */
+export declare function shouldBuildPagesUnifiedGraph(): boolean;
+export declare function isPagesUnifiedGraphPage(filePath: string, appConfig: EcoPagesAppConfig): boolean;
+/**
+ * Builds eligible static pages in one Rolldown invocation and seeds route-module disk cache.
+ */
+export declare function ensurePagesUnifiedGraphBuilt(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPaths: readonly string[];
+    outdir: string;
+    force?: boolean;
+}): Promise<PagesUnifiedGraphCacheManifest | undefined>;
+export declare function importPagesUnifiedGraphModule<T>(appConfig: EcoPagesAppConfig, filePath: string): Promise<T | undefined>;

package/src/build/cache/pages-unified-graph-build.js

@@ -0,0 +1,199 @@
+/**
+ * Unified pages Rolldown graph (Phase A build + Phase C import).
+ *
+ * Enabled by default in production builds. Opt out with
+ * `ECOPAGES_UNIFIED_PAGES_GRAPH=0`. Covers all static page template extensions
+ * registered on the app config.
+ */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../../global/app-logger.js';
+import { build } from '../build-adapter.js';
+import { requireBuildRuntime } from '../runtime/build-runtime.js';
+import { createServerBuildRequest, resolveServerAppBuildPlugins } from '../runtime/build-request-policy.js';
+import { createBuildInputsFingerprint, hashAppConfigFile } from './build-input-fingerprint.js';
+import { isProductionCacheManifestCurrent, matchesProductionCacheBuildKey, matchesProductionCacheFingerprint, readProductionCacheManifest, writeProductionCacheManifest, } from './production-build-cache.js';
+import { getCorePackageVersion } from './cache-keys.js';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+import { getSharedRouteModuleBuildCache } from '../../services/module-loading/route-module-build-cache-registry.js';
+import { resolveRouteModuleDependencyPaths } from '../../services/module-loading/route-module-dependency-hasher.js';
+export const PAGES_UNIFIED_GRAPH_CACHE_DIR = '.server-pages-graph';
+export const PAGES_UNIFIED_GRAPH_CACHE_FILENAME = '.build-cache.json';
+export function isPagesUnifiedGraphEnabled() {
+    if (process.env.ECOPAGES_UNIFIED_PAGES_GRAPH === '0') {
+        return false;
+    }
+    if (process.env.ECOPAGES_UNIFIED_PAGES_GRAPH === '1') {
+        return true;
+    }
+    return process.env.NODE_ENV === 'production';
+}
+/** True when the unified graph should build or serve prebuilt page modules. */
+export function shouldBuildPagesUnifiedGraph() {
+    return isPagesUnifiedGraphEnabled() && process.env.NODE_ENV === 'production';
+}
+export function isPagesUnifiedGraphPage(filePath, appConfig) {
+    const normalizedPath = path.normalize(filePath);
+    return appConfig.templatesExt.some((extension) => normalizedPath.endsWith(extension));
+}
+function getPagesUnifiedGraphCachePath(appConfig) {
+    return path.join(resolveInternalExecutionDir(appConfig), PAGES_UNIFIED_GRAPH_CACHE_DIR, PAGES_UNIFIED_GRAPH_CACHE_FILENAME);
+}
+function createPagesUnifiedGraphBuildKey(appConfig, outdir) {
+    const pluginNames = resolveServerAppBuildPlugins(appConfig)
+        .map((plugin) => plugin.name)
+        .sort()
+        .join('|');
+    const templateExtensions = [...appConfig.templatesExt].sort().join('|');
+    return [
+        path.resolve(outdir),
+        hashAppConfigFile(appConfig),
+        templateExtensions,
+        pluginNames,
+        'es2022',
+        'esm',
+        'external-packages',
+    ].join('::');
+}
+function readPagesUnifiedGraphManifest(appConfig) {
+    const manifest = readProductionCacheManifest(getPagesUnifiedGraphCachePath(appConfig));
+    if (!manifest?.outputs) {
+        return undefined;
+    }
+    return manifest;
+}
+function writePagesUnifiedGraphManifest(appConfig, manifest) {
+    writeProductionCacheManifest(getPagesUnifiedGraphCachePath(appConfig), manifest);
+}
+function createSafeGraphEntryKey(entryPath, rootDir) {
+    const relativePath = path.relative(rootDir, entryPath).replace(/\.[^.]+$/u, '');
+    const safeKey = relativePath.replace(/[^a-zA-Z0-9]+/gu, '-').replace(/^-+|-+$/gu, '');
+    return safeKey.length > 0 ? safeKey : 'page';
+}
+/**
+ * @remarks
+ * Uses {@link BuildResult.entryOutputs} when present so resolution follows the
+ * bundler's `facadeModuleId` instead of guessing from sanitized entry keys.
+ * Basename prefix matching remains only as a fallback for backends that omit
+ * `entryOutputs`; it can mis-associate keys such as `pages-blog` and
+ * `pages-blog-index`.
+ */
+function resolveOutputForEntrypoint(entryPath, entryKey, buildResult) {
+    const exactOutput = buildResult.entryOutputs?.[path.resolve(entryPath)];
+    if (exactOutput) {
+        return exactOutput;
+    }
+    for (const { path: outputPath } of buildResult.outputs) {
+        const outputBaseName = path.basename(outputPath);
+        if (outputBaseName.startsWith(`${entryKey}-`) && /\.(?:m?js)$/u.test(outputBaseName)) {
+            return outputPath;
+        }
+        if (outputBaseName === `${entryKey}.js` || outputBaseName === `${entryKey}.mjs`) {
+            return outputPath;
+        }
+    }
+    return undefined;
+}
+function isManifestValidForEntries(manifest, appConfig, outdir, entryPaths) {
+    if (!isProductionCacheManifestCurrent(manifest, getCorePackageVersion())) {
+        return false;
+    }
+    if (!matchesProductionCacheFingerprint(manifest, createBuildInputsFingerprint(appConfig))) {
+        return false;
+    }
+    if (!matchesProductionCacheBuildKey(manifest, createPagesUnifiedGraphBuildKey(appConfig, outdir))) {
+        return false;
+    }
+    return entryPaths.every((entryPath) => {
+        const resolvedEntryPath = path.resolve(entryPath);
+        const outputPath = manifest.outputs[resolvedEntryPath];
+        return outputPath ? fileSystem.exists(outputPath) : false;
+    });
+}
+/**
+ * Builds eligible static pages in one Rolldown invocation and seeds route-module disk cache.
+ */
+export async function ensurePagesUnifiedGraphBuilt(options) {
+    if (!shouldBuildPagesUnifiedGraph()) {
+        return undefined;
+    }
+    const eligibleEntryPaths = options.entryPaths
+        .map((entryPath) => path.resolve(entryPath))
+        .filter((entryPath) => isPagesUnifiedGraphPage(entryPath, options.appConfig));
+    if (eligibleEntryPaths.length === 0) {
+        return undefined;
+    }
+    const outdir = path.resolve(options.outdir);
+    const existingManifest = options.force ? undefined : readPagesUnifiedGraphManifest(options.appConfig);
+    if (existingManifest &&
+        isManifestValidForEntries(existingManifest, options.appConfig, outdir, eligibleEntryPaths)) {
+        appLogger.debug('Reusing pages unified graph cache');
+        return existingManifest;
+    }
+    const routeModuleBuildCache = getSharedRouteModuleBuildCache(outdir, options.appConfig);
+    const entryRecord = {};
+    const entryKeysByPath = new Map();
+    for (const entryPath of eligibleEntryPaths) {
+        const entryKey = createSafeGraphEntryKey(entryPath, options.appConfig.rootDir);
+        entryRecord[entryKey] = entryPath;
+        entryKeysByPath.set(entryPath, entryKey);
+    }
+    appLogger.debugTime('pagesUnifiedGraphBuild');
+    const buildOptions = createServerBuildRequest(options.appConfig, {
+        profile: 'route-module',
+        entrypoints: entryRecord,
+        outdir,
+        splitting: true,
+        naming: '[name]-[hash].[ext]',
+    });
+    const plugins = buildOptions.plugins ?? [];
+    const buildResult = await build(buildOptions, requireBuildRuntime(options.appConfig).getProfile('route-module'));
+    appLogger.debugTimeEnd('pagesUnifiedGraphBuild');
+    if (!buildResult.success) {
+        const details = buildResult.logs.map((log) => log.message).join(' | ');
+        throw new Error(`Pages unified graph build failed: ${details}`);
+    }
+    const outputs = {};
+    for (const entryPath of eligibleEntryPaths) {
+        const fileHash = fileSystem.hash(entryPath);
+        const entryKey = entryKeysByPath.get(entryPath);
+        const compiledOutput = entryKey ? resolveOutputForEntrypoint(entryPath, entryKey, buildResult) : undefined;
+        if (!compiledOutput) {
+            throw new Error(`Pages unified graph build produced no output for ${entryPath}`);
+        }
+        outputs[entryPath] = compiledOutput;
+        routeModuleBuildCache.recordBuild({
+            filePath: entryPath,
+            rootDir: options.appConfig.rootDir,
+            outdir,
+            fileHash,
+            outputPath: compiledOutput,
+            dependencyModulePaths: resolveRouteModuleDependencyPaths(buildResult, entryPath, options.appConfig.rootDir),
+            externalPackages: true,
+            plugins,
+        });
+    }
+    const manifest = {
+        invalidationVersion: getCorePackageVersion(),
+        buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+        buildKey: createPagesUnifiedGraphBuildKey(options.appConfig, outdir),
+        builtAt: Date.now(),
+        outputs,
+    };
+    writePagesUnifiedGraphManifest(options.appConfig, manifest);
+    appLogger.debug(`Built pages unified graph for ${eligibleEntryPaths.length} entries`);
+    return manifest;
+}
+export async function importPagesUnifiedGraphModule(appConfig, filePath) {
+    const manifest = readPagesUnifiedGraphManifest(appConfig);
+    if (!manifest) {
+        return undefined;
+    }
+    const resolvedFilePath = path.resolve(filePath);
+    const outputPath = manifest.outputs[resolvedFilePath];
+    if (!outputPath || !fileSystem.exists(outputPath)) {
+        return undefined;
+    }
+    return (await import(/* @vite-ignore */ pathToFileURL(outputPath).href));
+}

package/src/build/cache/production-build-cache.d.ts

@@ -0,0 +1,21 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Shared manifest fields for persisted production build caches.
+ */
+export interface ProductionCacheManifestBase {
+    invalidationVersion?: string;
+    corePackageVersion?: string;
+    buildInputsFingerprint?: string;
+    buildKey?: string;
+    builtAt?: number;
+}
+export type ProductionBuildCacheKind = 'server-entry' | 'route-module' | 'pages-graph';
+/** Returns every persisted production cache manifest path for one app. */
+export declare function getProductionBuildCacheManifestPaths(appConfig: EcoPagesAppConfig): string[];
+/** Removes all persisted production cache manifests for one app. */
+export declare function clearPersistedProductionBuildCacheManifests(appConfig: EcoPagesAppConfig): void;
+export declare function readProductionCacheManifest<T extends ProductionCacheManifestBase>(manifestPath: string): T | undefined;
+export declare function writeProductionCacheManifest(manifestPath: string, manifest: unknown): void;
+export declare function isProductionCacheManifestCurrent(manifest: ProductionCacheManifestBase | undefined, packageVersion: string): boolean;
+export declare function matchesProductionCacheFingerprint(manifest: ProductionCacheManifestBase | undefined, buildInputsFingerprint: string): boolean;
+export declare function matchesProductionCacheBuildKey(manifest: ProductionCacheManifestBase | undefined, buildKey: string): boolean;

package/src/build/cache/production-build-cache.js

@@ -0,0 +1,56 @@
+import { fileSystem } from '@ecopages/file-system';
+import path from 'node:path';
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from './cache-constants.js';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+const ROUTE_MODULE_CACHE_OUTDIRS = ['.server-modules', '.server-route-modules'];
+const PAGES_GRAPH_CACHE_DIR = '.server-pages-graph';
+/** Returns every persisted production cache manifest path for one app. */
+export function getProductionBuildCacheManifestPaths(appConfig) {
+    const executionDir = resolveInternalExecutionDir(appConfig);
+    const paths = [];
+    for (const subdir of ROUTE_MODULE_CACHE_OUTDIRS) {
+        paths.push(path.join(executionDir, subdir, ROUTE_MODULE_BUILD_CACHE_FILENAME));
+    }
+    paths.push(path.join(executionDir, '.server-entry', ROUTE_MODULE_BUILD_CACHE_FILENAME));
+    paths.push(path.join(executionDir, PAGES_GRAPH_CACHE_DIR, ROUTE_MODULE_BUILD_CACHE_FILENAME));
+    return paths;
+}
+/** Removes all persisted production cache manifests for one app. */
+export function clearPersistedProductionBuildCacheManifests(appConfig) {
+    if (process.env.NODE_ENV !== 'production') {
+        return;
+    }
+    for (const manifestPath of getProductionBuildCacheManifestPaths(appConfig)) {
+        if (fileSystem.exists(manifestPath)) {
+            fileSystem.remove(manifestPath);
+        }
+    }
+}
+export function readProductionCacheManifest(manifestPath) {
+    if (!fileSystem.exists(manifestPath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+        if (!parsed || typeof parsed !== 'object') {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeProductionCacheManifest(manifestPath, manifest) {
+    fileSystem.ensureDir(path.dirname(manifestPath));
+    fileSystem.write(manifestPath, `${JSON.stringify(manifest, null, '\t')}\n`);
+}
+export function isProductionCacheManifestCurrent(manifest, packageVersion) {
+    return (manifest?.corePackageVersion ?? manifest?.invalidationVersion) === packageVersion;
+}
+export function matchesProductionCacheFingerprint(manifest, buildInputsFingerprint) {
+    return manifest?.buildInputsFingerprint === buildInputsFingerprint;
+}
+export function matchesProductionCacheBuildKey(manifest, buildKey) {
+    return manifest?.buildKey === buildKey;
+}

package/src/build/cache/server-entry-build-cache.d.ts

@@ -0,0 +1,43 @@
+import type { BuildResult } from '../build-adapter.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export { SERVER_ENTRY_BUILD_CACHE_FILENAME } from './cache-constants.js';
+export declare const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+export interface ServerBundleDeployManifest {
+    serverEntry: string;
+    distDir: string;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheManifest {
+    invalidationVersion: string;
+    entryPath: string;
+    entryHash: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    outputPaths: string[];
+    dependencyHashes: Record<string, string>;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheLookup {
+    manifest: ServerEntryBuildCacheManifest;
+    outputPaths: string[];
+}
+export declare function getServerBundleOutputPaths(appConfig: EcoPagesAppConfig): {
+    distDir: string;
+    serverOutdir: string;
+    serverEntryPath: string;
+    manifestPath: string;
+};
+export declare function readServerEntryBuildCacheManifest(appConfig: EcoPagesAppConfig): ServerEntryBuildCacheManifest | undefined;
+export declare function writeServerBundleDeployManifest(appConfig: EcoPagesAppConfig, serverEntryPath: string): void;
+export declare function lookupServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    force?: boolean;
+}): ServerEntryBuildCacheLookup | undefined;
+export declare function recordServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    buildResult: BuildResult;
+    outputPaths: string[];
+}): void;
+export declare function resolveProductionServerEntry(cwd?: string): string | undefined;

package/src/build/cache/server-entry-build-cache.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { resolveServerAppBuildPlugins } from '../runtime/build-request-policy.js';
+import { createBuildInputsFingerprint } from './build-input-fingerprint.js';
+import { isProductionCacheManifestCurrent, matchesProductionCacheBuildKey, matchesProductionCacheFingerprint, readProductionCacheManifest, writeProductionCacheManifest, } from './production-build-cache.js';
+import { createPluginCacheKey, getCorePackageVersion } from './cache-keys.js';
+import { RouteModuleDependencyHasher, createRouteModuleDependencyHashes, } from '../../services/module-loading/route-module-dependency-hasher.js';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from '../../utils/resolve-entry-file.js';
+import { SERVER_ENTRY_BUILD_CACHE_FILENAME } from './cache-constants.js';
+export { SERVER_ENTRY_BUILD_CACHE_FILENAME } from './cache-constants.js';
+export const SERVER_BUNDLE_MANIFEST_FILENAME = 'manifest.json';
+function getServerEntryCacheDir(appConfig) {
+    return path.join(resolveInternalExecutionDir(appConfig), '.server-entry');
+}
+function getServerEntryCacheManifestPath(appConfig) {
+    return path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME);
+}
+function hashDependencyGraph(entryPath, dependencyGraph, hasher, rootDir) {
+    if (!dependencyGraph) {
+        return { [path.resolve(entryPath)]: fileSystem.hash(entryPath) };
+    }
+    return createRouteModuleDependencyHashes(hasher, { dependencyGraph }, entryPath, rootDir);
+}
+/**
+ * Fingerprints the app-owned output-affecting server request policy.
+ *
+ * @remarks
+ * Includes ordered server plugins and JSX ownership plugins via
+ * {@link resolveServerAppBuildPlugins}. The versioned prefix intentionally
+ * invalidates manifests written before server requests included JSX ownership.
+ */
+function createServerEntryBuildKey(appConfig) {
+    try {
+        return [
+            'server-entry-request-v2',
+            'node',
+            'esm',
+            'external-packages',
+            createPluginCacheKey(resolveServerAppBuildPlugins(appConfig)),
+        ].join('::');
+    }
+    catch {
+        return 'server-entry-request-v2::node::esm::external-packages';
+    }
+}
+export function getServerBundleOutputPaths(appConfig) {
+    const distDir = appConfig.absolutePaths?.distDir ?? path.join(appConfig.rootDir, appConfig.distDir);
+    const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
+    const serverEntryPath = path.join(serverOutdir, SERVER_BUNDLE_FILENAME);
+    const manifestPath = path.join(serverOutdir, SERVER_BUNDLE_MANIFEST_FILENAME);
+    return { distDir, serverOutdir, serverEntryPath, manifestPath };
+}
+export function readServerEntryBuildCacheManifest(appConfig) {
+    return readProductionCacheManifest(getServerEntryCacheManifestPath(appConfig));
+}
+function writeServerEntryBuildCacheManifest(appConfig, manifest) {
+    writeProductionCacheManifest(path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME), manifest);
+}
+export function writeServerBundleDeployManifest(appConfig, serverEntryPath) {
+    const { distDir, manifestPath } = getServerBundleOutputPaths(appConfig);
+    fileSystem.ensureDir(path.dirname(manifestPath));
+    const payload = {
+        serverEntry: path.relative(path.dirname(manifestPath), serverEntryPath) || SERVER_BUNDLE_FILENAME,
+        distDir,
+        builtAt: Date.now(),
+    };
+    fileSystem.write(manifestPath, `${JSON.stringify(payload, null, '\t')}\n`);
+}
+export function lookupServerEntryBuildCache(options) {
+    if (options.force) {
+        return undefined;
+    }
+    if (process.env.NODE_ENV !== 'production') {
+        return undefined;
+    }
+    const entryPath = path.resolve(options.entryPath);
+    const entryHash = fileSystem.hash(entryPath);
+    const buildInputsFingerprint = createBuildInputsFingerprint(options.appConfig);
+    const buildKey = createServerEntryBuildKey(options.appConfig);
+    const manifest = readServerEntryBuildCacheManifest(options.appConfig);
+    if (!manifest) {
+        return undefined;
+    }
+    if (!isProductionCacheManifestCurrent(manifest, getCorePackageVersion())) {
+        return undefined;
+    }
+    if (manifest.entryPath !== entryPath ||
+        manifest.entryHash !== entryHash ||
+        !matchesProductionCacheFingerprint(manifest, buildInputsFingerprint) ||
+        !matchesProductionCacheBuildKey(manifest, buildKey)) {
+        return undefined;
+    }
+    const hasher = new RouteModuleDependencyHasher();
+    if (!hasher.matchesStoredHashes(manifest.dependencyHashes, entryPath, entryHash)) {
+        return undefined;
+    }
+    const existingOutputs = manifest.outputPaths.filter((outputPath) => fileSystem.exists(outputPath));
+    if (existingOutputs.length === 0) {
+        return undefined;
+    }
+    return {
+        manifest,
+        outputPaths: existingOutputs,
+    };
+}
+export function recordServerEntryBuildCache(options) {
+    if (process.env.NODE_ENV !== 'production') {
+        return;
+    }
+    const entryPath = path.resolve(options.entryPath);
+    const entryHash = fileSystem.hash(entryPath);
+    const hasher = new RouteModuleDependencyHasher();
+    const dependencyHashes = hashDependencyGraph(entryPath, options.buildResult.dependencyGraph, hasher, options.appConfig.rootDir);
+    const manifest = {
+        invalidationVersion: getCorePackageVersion(),
+        entryPath,
+        entryHash,
+        buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+        buildKey: createServerEntryBuildKey(options.appConfig),
+        outputPaths: options.outputPaths,
+        dependencyHashes,
+        builtAt: Date.now(),
+    };
+    writeServerEntryBuildCacheManifest(options.appConfig, manifest);
+}
+export function resolveProductionServerEntry(cwd = process.cwd()) {
+    const manifestPath = path.join(cwd, 'dist', SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+    if (fileSystem.exists(manifestPath)) {
+        try {
+            const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+            if (parsed?.serverEntry) {
+                const fromManifest = path.isAbsolute(parsed.serverEntry)
+                    ? parsed.serverEntry
+                    : path.join(path.dirname(manifestPath), parsed.serverEntry);
+                if (fileSystem.exists(fromManifest)) {
+                    return fromManifest;
+                }
+            }
+            if (parsed?.distDir) {
+                const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+                if (fileSystem.exists(fromDistDir)) {
+                    return fromDistDir;
+                }
+            }
+        }
+        catch {
+            // fall through to legacy path
+        }
+    }
+    const legacyPath = path.join(cwd, 'dist', SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+    return fileSystem.exists(legacyPath) ? legacyPath : undefined;
+}

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

@@ -0,0 +1,96 @@
+import type { EcoSourceTransform } from '../../plugins/source-transform.js';
+import type { EcoBuildPlugin } from './build-types.js';
+/**
+ * Which backend owns the app's build pipeline.
+ *
+ * - `'rolldown'`: the default. Ecopages runs the build directly through
+ *   its bundler-backed adapter.
+ * - `'vite-host'`: a host runtime owns the build. {@link ViteHostBuildAdapter}
+ *   is exposed as a boundary marker; any direct call into it throws.
+ */
+export type BuildOwnership = 'vite-host' | 'rolldown';
+/** A single message emitted by the build backend. */
+export interface BuildLog {
+    message: string;
+}
+/** A single artifact emitted by the build backend. */
+export interface BuildOutput {
+    path: string;
+}
+/** Per-entrypoint dependency metadata surfaced alongside a build. */
+export interface BuildDependencyGraph {
+    entrypoints: Record<string, string[]>;
+}
+/** The full result of one `BuildAdapter.build` call. */
+export interface BuildResult {
+    success: boolean;
+    logs: BuildLog[];
+    outputs: BuildOutput[];
+    dependencyGraph?: BuildDependencyGraph;
+    entryOutputs?: Record<string, string>;
+}
+/**
+ * Options accepted by every `BuildAdapter.build` call.
+ *
+ * @remarks
+ * Fields that the adapter can forward are honored. `splitting: false` disables
+ * Rolldown code splitting for single-entrypoint builds. `bundle` and `outbase`
+ * are accepted for call-site compatibility but ignored.
+ */
+export interface BuildOptions {
+    entrypoints: string[] | Record<string, string>;
+    outdir?: string;
+    /**
+     * Base directory for `[dir]` placeholders in `naming`. Currently
+     * the bundled adapter derives the base from `root` directly and
+     * ignores this field.
+     *
+     * @deprecated Accepted for call-site compatibility only. Use record-form
+     * `entrypoints` keys to preserve directory structure.
+     */
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    target?: string;
+    format?: string;
+    sourcemap?: string;
+    /** When `false` with a single entrypoint, inlines dynamic imports into one output file. */
+    splitting?: boolean;
+    root?: string;
+    /** @deprecated Accepted for call-site compatibility only. */
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
+    plugins?: EcoBuildPlugin[];
+    sourceTransforms?: EcoSourceTransform[];
+}
+/** Stable profile identifiers for `BuildAdapter.getTranspileOptions`. */
+export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+/** Resolved transpile settings for a given profile. */
+export interface BuildTranspileOptions {
+    target: string;
+    format: string;
+    sourcemap: string;
+}
+/** Low-level build backend contract. */
+export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+/** Runtime-facing facade for issuing builds. */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}

package/src/build/contracts/build-contracts.js

@@ -0,0 +1 @@
+export {};