@zenithbuild/cli 0.7.10 → 0.7.12

package/dist/dev-server/port-fallback.js

@@ -0,0 +1,61 @@
+const MAX_PORT = 65535;
+const DEFAULT_MAX_ATTEMPTS = 20;
+export function isPortConflict(error) {
+    return error && error.code === 'EADDRINUSE';
+}
+function normalizeRequestedPort(port) {
+    return Number.isInteger(port) && port >= 0 ? port : 3000;
+}
+function waitForListen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off('error', onError);
+            server.off('listening', onListening);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onListening = () => {
+            cleanup();
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+export async function listenWithPortFallback({ server, port, host, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
+    const requestedPort = normalizeRequestedPort(port);
+    let candidatePort = requestedPort;
+    const occupiedPorts = [];
+    for (let attempt = 0; attempt <= maxAttempts; attempt += 1) {
+        try {
+            await waitForListen(server, candidatePort, host);
+            const address = server.address();
+            const actualPort = address && typeof address === 'object' ? address.port : candidatePort;
+            return {
+                port: actualPort,
+                requestedPort,
+                portFallback: occupiedPorts.length > 0
+                    ? {
+                        requestedPort,
+                        occupiedPorts: occupiedPorts.slice(),
+                        finalPort: actualPort
+                    }
+                    : null
+            };
+        }
+        catch (error) {
+            if (requestedPort === 0 ||
+                !isPortConflict(error) ||
+                candidatePort >= MAX_PORT ||
+                attempt >= maxAttempts) {
+                throw error;
+            }
+            occupiedPorts.push(candidatePort);
+            candidatePort += 1;
+        }
+    }
+    throw new Error(`Unable to bind dev server after ${maxAttempts + 1} attempts`);
+}

package/dist/dev-server/request-handler.js

@@ -9,9 +9,20 @@ import { materializeImageMarkup } from '../images/materialize.js';
 import { injectImageRuntimePayload } from '../images/payload.js';
 import { handleImageRequest } from '../images/service.js';
 import { resolveRequestRoute } from '../server/resolve-request-route.js';
+import { respondWithDevBuildError } from './build-error-response.js';
 import { handleRouteCheckRequest } from './route-check.js';
+function respondWithMiddlewareSourceError(res, error) {
+    logServerException('dev server route execution failed', error);
+    res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end(clientFacingRouteMessage(500));
+}
+function hasRouteScopedServerData(route) {
+    return route?.has_scoped_server_data === true &&
+        Array.isArray(route?.scoped_server_data) &&
+        route.scoped_server_data.length > 0;
+}
 export function createDevRequestHandler(options) {
-    const { outDir, projectRoot, imageConfig, configuredBasePath, routeCheckEnabled, isStaticExportTarget, logger, verboseLogging, buildSession, state, serverOrigin, loadRoutesForRequests, readFileForRequest, trace404, looksLikeJsonRequest, classifyNotFound, infer404Cause, buildNotFoundPayload, renderNotFoundHtml, appendSetCookieHeaders, MIME_TYPES, EVENT_STREAM_MIME, LEGACY_DEV_STREAM_PATH, IMAGE_RUNTIME_TAG_RE } = options;
+    const { outDir, projectRoot, imageConfig, configuredBasePath, routeCheckEnabled, isStaticExportTarget, logger, verboseLogging, buildSession, state, serverOrigin, loadRoutesForRequests, loadGlobalMiddlewareForRequests, readFileForRequest, trace404, looksLikeJsonRequest, classifyNotFound, infer404Cause, buildNotFoundPayload, renderNotFoundHtml, appendSetCookieHeaders, MIME_TYPES, EVENT_STREAM_MIME, LEGACY_DEV_STREAM_PATH, IMAGE_RUNTIME_TAG_RE } = options;
     return async function handleDevRequest(req, res) {
         const url = new URL(req.url, serverOrigin());
         const pathname = url.pathname;
@@ -204,6 +215,16 @@ export function createDevRequestHandler(options) {
             canonicalUrl.pathname = canonicalPath;
             const resolvedResource = resolveRequestRoute(canonicalUrl, routes.resourceRoutes || []);
             if (resolvedResource.matched && resolvedResource.route) {
+                let globalMiddleware = null;
+                try {
+                    globalMiddleware = loadGlobalMiddlewareForRequests
+                        ? await loadGlobalMiddlewareForRequests()
+                        : null;
+                }
+                catch (error) {
+                    respondWithMiddlewareSourceError(res, error);
+                    return;
+                }
                 const requestMethod = req.method || 'GET';
                 const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
                     ? null
@@ -219,7 +240,9 @@ export function createDevRequestHandler(options) {
                     routePattern: resolvedResource.route.path,
                     routeFile: resolvedResource.route.server_script_path || '',
                     routeId: resolvedResource.route.route_id || '',
-                    routeKind: 'resource'
+                    routeKind: 'resource',
+                    globalMiddlewareSource: globalMiddleware?.source || '',
+                    globalMiddlewareSourcePath: globalMiddleware?.sourcePath || ''
                 });
                 const descriptor = buildResourceResponseDescriptor(execution?.result, configuredBasePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
                 res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
@@ -230,6 +253,16 @@ export function createDevRequestHandler(options) {
                 res.end(descriptor.body);
                 return;
             }
+            if (state.buildStatus === 'error' && (!requestExt || requestExt === '.html')) {
+                respondWithDevBuildError({
+                    req,
+                    res,
+                    pathname,
+                    state,
+                    looksLikeJsonRequest
+                });
+                return;
+            }
             const resolved = resolveRequestRoute(canonicalUrl, routes.pageRoutes || []);
             let filePath = null;
             if (isStaticExportTarget) {
@@ -245,7 +278,7 @@ export function createDevRequestHandler(options) {
                 filePath = resolveWithinDist(outDir, output);
             }
             else {
-                filePath = toStaticFilePath(outDir, canonicalPath);
+                filePath = null;
             }
             resolvedPathFor404 = filePath;
             staticRootFor404 = outDir;
@@ -254,7 +287,19 @@ export function createDevRequestHandler(options) {
             }
             let ssrPayload = null;
             let routeExecution = null;
-            if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
+            if (resolved.matched &&
+                resolved.route?.prerender !== true &&
+                (resolved.route?.server_script || hasRouteScopedServerData(resolved.route))) {
+                let globalMiddleware = null;
+                try {
+                    globalMiddleware = loadGlobalMiddlewareForRequests
+                        ? await loadGlobalMiddlewareForRequests()
+                        : null;
+                }
+                catch (error) {
+                    respondWithMiddlewareSourceError(res, error);
+                    return;
+                }
                 try {
                     const requestMethod = req.method || 'GET';
                     const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
@@ -270,7 +315,15 @@ export function createDevRequestHandler(options) {
                         requestBodyBuffer,
                         routePattern: resolved.route.path,
                         routeFile: resolved.route.server_script_path || '',
-                        routeId: resolved.route.route_id || ''
+                        routeId: resolved.route.route_id || '',
+                        globalMiddlewareSource: globalMiddleware?.source || '',
+                        globalMiddlewareSourcePath: globalMiddleware?.sourcePath || '',
+                        scopedServerData: Array.isArray(resolved.route.scoped_server_data)
+                            ? resolved.route.scoped_server_data
+                            : [],
+                        scopedServerModuleSources: Array.isArray(resolved.route.scoped_server_modules)
+                            ? resolved.route.scoped_server_modules
+                            : []
                     });
                 }
                 catch (error) {

package/dist/dev-server/watcher.js

@@ -3,6 +3,8 @@ import { performance } from 'node:perf_hooks';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { readChangeFingerprint } from '../dev-watch.js';
 import { loadRouteSurfaceState } from '../preview.js';
+const CONFIG_FILE_NAMES = new Set(['zenith.config.js', 'zenith.config.ts']);
+const CONFIG_CHANGED_MESSAGE = 'Config changed. Restart `zenith dev` to apply config updates.';
 export function createDevWatcher(options) {
     const { watchRoots, resolvedOutDir, resolvedOutDirTmp, projectRoot, rebuildDebounceMs, queuedRebuildDebounceMs, buildSession, outDir, configuredBasePath, logger, startupProfile, state, syncCssStateFromBuild, broadcastEvent, trace } = options;
     /** @type {import('fs').FSWatcher[]} */
@@ -42,6 +44,10 @@ export function createDevWatcher(options) {
             || segments.includes('target')
             || segments.includes('.turbo');
     }
+    function isConfigFileChange(absPath) {
+        const rel = relative(projectRoot, absPath).replace(/\\/g, '/');
+        return CONFIG_FILE_NAMES.has(rel);
+    }
     const triggerBuildDrain = (delayMs = rebuildDebounceMs) => {
         if (buildDebounce !== null) {
             clearTimeout(buildDebounce);
@@ -166,6 +172,15 @@ export function createDevWatcher(options) {
                     if (shouldIgnoreChange(changedPath)) {
                         return;
                     }
+                    if (isConfigFileChange(changedPath)) {
+                        logger.warn(CONFIG_CHANGED_MESSAGE, {
+                            onceKey: `config-change:${changedPath}`
+                        });
+                        trace('config_change_restart_required', {
+                            path: toDisplayPath(changedPath)
+                        });
+                        return;
+                    }
                     void (async () => {
                         const fingerprint = await readChangeFingerprint(changedPath);
                         if (lastQueuedFingerprints.get(changedPath) === fingerprint) {

package/dist/dev-server.d.ts

@@ -1,12 +1,13 @@
 /**
  * Create and start a development server.
  *
- * @param {{ pagesDir: string, outDir: string, port?: number, host?: string, config?: object, logger?: object | null }} options
- * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
+ * @param {{ pagesDir: string, outDir: string, projectRoot?: string, port?: number, host?: string, config?: object, logger?: object | null }} options
+ * @returns {Promise<{ server: import('http').Server, port: number, requestedPort: number, portFallback: object | null, close: () => void }>}
  */
 export function createDevServer(options: {
     pagesDir: string;
     outDir: string;
+    projectRoot?: string;
     port?: number;
     host?: string;
     config?: object;
@@ -14,5 +15,7 @@ export function createDevServer(options: {
 }): Promise<{
     server: import("http").Server;
     port: number;
+    requestedPort: number;
+    portFallback: object | null;
     close: () => void;
 }>;

package/dist/dev-server.js

@@ -11,11 +11,15 @@
 // V0: Uses Node.js http module + fs.watch. No external deps.
 // ---------------------------------------------------------------------------
 import { createServer } from 'node:http';
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { basename, dirname, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { normalizeBasePath } from './base-path.js';
 import { resolveBuildAdapter } from './adapters/resolve-adapter.js';
 import { createDevBuildSession } from './dev-build-session.js';
+import { generateManifest } from './manifest.js';
+import { buildComponentRegistry } from './resolve-components.js';
 import { createStartupProfiler } from './startup-profile.js';
 import { createSilentLogger } from './ui/logger.js';
 import { createTrustedOriginResolver, publicHost } from './request-origin.js';
@@ -25,6 +29,9 @@ import { syncCssStateFromBuild } from './dev-server/css-state.js';
 import { buildNotFoundPayload, classifyNotFound, infer404Cause, looksLikeJsonRequest, renderNotFoundHtml, traceNotFound } from './dev-server/not-found.js';
 import { createDevRequestHandler } from './dev-server/request-handler.js';
 import { createDevWatcher } from './dev-server/watcher.js';
+import { listenWithPortFallback } from './dev-server/port-fallback.js';
+import { loadDevGlobalMiddlewareSource } from './global-middleware-runtime-source.js';
+const SCOPED_SERVER_DATA_LOWERING_HELPER_UNAVAILABLE = '[Zenith:ScopedServerData] Server-output lowering helper is unavailable. Run the CLI build step before packaging scoped server data modules.';
 const MIME_TYPES = {
     '.html': 'text/html',
     '.js': 'application/javascript',
@@ -41,6 +48,24 @@ const MIME_TYPES = {
 const IMAGE_RUNTIME_TAG_RE = new RegExp('<' + 'script\\b[^>]*\\bid=(["\'])zenith-image-runtime\\1[^>]*>[\\s\\S]*?<\\/' + 'script>', 'i');
 const EVENT_STREAM_MIME = ['text', 'event-stream'].join('/');
 const LEGACY_DEV_STREAM_PATH = ['/__zenith', '_hmr'].join('');
+let scopedServerDataLoweringPromise = null;
+function resolveScopedServerDataLoweringPath() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    return [
+        join(moduleDir, 'scoped-server-data', 'lowering.js'),
+        join(moduleDir, '..', 'dist', 'scoped-server-data', 'lowering.js')
+    ].find((candidate) => existsSync(candidate)) || null;
+}
+async function getScopedServerDataLowering() {
+    const helperPath = resolveScopedServerDataLoweringPath();
+    if (!helperPath) {
+        throw new Error(SCOPED_SERVER_DATA_LOWERING_HELPER_UNAVAILABLE);
+    }
+    if (!scopedServerDataLoweringPromise) {
+        scopedServerDataLoweringPromise = import(pathToFileURL(helperPath).href);
+    }
+    return scopedServerDataLoweringPromise;
+}
 function appendSetCookieHeaders(headers, setCookies = []) {
     if (Array.isArray(setCookies) && setCookies.length > 0) {
         headers['Set-Cookie'] = setCookies.slice();
@@ -52,26 +77,28 @@ function appendSetCookieHeaders(headers, setCookies = []) {
 /**
  * Create and start a development server.
  *
- * @param {{ pagesDir: string, outDir: string, port?: number, host?: string, config?: object, logger?: object | null }} options
- * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
+ * @param {{ pagesDir: string, outDir: string, projectRoot?: string, port?: number, host?: string, config?: object, logger?: object | null }} options
+ * @returns {Promise<{ server: import('http').Server, port: number, requestedPort: number, portFallback: object | null, close: () => void }>}
  */
 export async function createDevServer(options) {
     const startupProfile = createStartupProfiler('cli-dev-server');
-    const { pagesDir, outDir, port = 3000, host = '127.0.0.1', config = {}, logger: providedLogger = null } = options;
+    const { pagesDir, outDir, projectRoot: providedProjectRoot = null, port = 3000, host = '127.0.0.1', config = {}, logger: providedLogger = null } = options;
     const logger = providedLogger || createSilentLogger();
     const buildSession = createDevBuildSession({ pagesDir, outDir, config, logger });
     const configuredBasePath = normalizeBasePath(config.basePath || '/');
     const resolvedTarget = resolveBuildAdapter(config).target;
     const routeCheckEnabled = supportsTargetRouteCheck(resolvedTarget);
     const isStaticExportTarget = resolvedTarget === 'static-export';
+    const compilerOpts = { typescriptDefault: config.typescriptDefault === true, experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true, strictDomLints: config.strictDomLints === true };
     const resolvedPagesDir = resolve(pagesDir);
     const resolvedOutDir = resolve(outDir);
     const resolvedOutDirTmp = resolve(dirname(resolvedOutDir), `${basename(resolvedOutDir)}.tmp`);
     const pagesParentDir = dirname(resolvedPagesDir);
-    const projectRoot = basename(pagesParentDir) === 'src'
+    const inferredProjectRoot = basename(pagesParentDir) === 'src'
         ? dirname(pagesParentDir)
         : pagesParentDir;
-    const watchRoots = new Set([pagesParentDir]);
+    const projectRoot = resolve(providedProjectRoot || inferredProjectRoot);
+    const watchRoots = new Set([projectRoot, pagesParentDir]);
     /** @type {import('http').ServerResponse[]} */
     const hmrClients = [];
     const sseHeartbeat = setInterval(() => {
@@ -97,7 +124,7 @@ export async function createDevServer(options) {
         currentCssContent: '',
         currentRouteState: { pageRoutes: [], resourceRoutes: [] }
     };
-    const traceEnabled = config.devTrace === true || process.env.ZENITH_DEV_TRACE === '1';
+    const traceEnabled = process.env.ZENITH_DEV_TRACE === '1';
     const verboseLogging = traceEnabled || logger.mode?.logLevel === 'verbose';
     let actualPort = port;
     const resolveServerOrigin = createTrustedOriginResolver({
@@ -176,8 +203,9 @@ export async function createDevServer(options) {
             const routeState = await loadRouteSurfaceState(outDir, configuredBasePath);
             if ((Array.isArray(routeState.pageRoutes) && routeState.pageRoutes.length > 0) ||
                 (Array.isArray(routeState.resourceRoutes) && routeState.resourceRoutes.length > 0)) {
-                state.currentRouteState = routeState;
-                return routeState;
+                const mergedRouteState = await _mergeDevScopedServerData(routeState);
+                state.currentRouteState = mergedRouteState;
+                return mergedRouteState;
             }
         }
         catch (error) {
@@ -188,6 +216,67 @@ export async function createDevServer(options) {
         }
         return state.currentRouteState;
     }
+    async function _mergeDevScopedServerData(routeState) {
+        const scopedByPath = await _loadDevScopedServerDataByPath();
+        if (scopedByPath.size === 0) {
+            return routeState;
+        }
+        return {
+            ...routeState,
+            pageRoutes: (Array.isArray(routeState.pageRoutes) ? routeState.pageRoutes : []).map((route) => {
+                const scoped = scopedByPath.get(route.path);
+                return scoped ? { ...route, ...scoped } : route;
+            })
+        };
+    }
+    async function _loadDevScopedServerDataByPath() {
+        const srcDir = resolve(resolvedPagesDir, '..');
+        const registry = buildComponentRegistry(srcDir);
+        const manifest = await generateManifest(resolvedPagesDir, '.zen', {
+            srcDir,
+            registry,
+            compilerOpts
+        });
+        const pageEntries = manifest.filter((entry) => entry?.route_kind !== 'resource' &&
+            entry?.has_scoped_server_data === true &&
+            Array.isArray(entry?.scoped_server_data) &&
+            entry.scoped_server_data.length > 0);
+        const scopedByPath = new Map();
+        if (pageEntries.length === 0) {
+            return scopedByPath;
+        }
+        const lowering = await getScopedServerDataLowering();
+        for (const entry of pageEntries) {
+            const pageFile = resolve(resolvedPagesDir, entry.file);
+            const pageSource = await readFile(pageFile, 'utf8');
+            const lowered = lowering.lowerRouteScopedServerData({
+                pageSource,
+                pageFile,
+                registry,
+                srcDir,
+                projectRoot,
+                compilerOpts,
+                scopedServerData: entry.scoped_server_data
+            });
+            scopedByPath.set(entry.path, {
+                has_scoped_server_data: true,
+                scoped_server_data: lowered.scopedServerData,
+                scoped_server_modules: lowered.modules.map((module) => ({
+                    module: module.module,
+                    source: module.source,
+                    sourcePath: module.sourcePath
+                }))
+            });
+        }
+        return scopedByPath;
+    }
+    async function _loadGlobalMiddlewareForRequests() {
+        return loadDevGlobalMiddlewareSource({
+            projectRoot,
+            pagesDir: resolvedPagesDir,
+            target: resolvedTarget
+        });
+    }
     function _broadcastEvent(type, payload = {}) {
         const eventBuildId = Number.isInteger(payload.buildId) ? payload.buildId : state.buildId;
         const data = JSON.stringify({
@@ -219,7 +308,7 @@ export async function createDevServer(options) {
             logger.build('Initial build (id=0)', { onceKey: 'dev-initial-build' });
             const initialBuild = await buildSession.build();
             const cssReady = await _syncCssStateFromBuild(initialBuild, state.buildId);
-            state.currentRouteState = await loadRouteSurfaceState(outDir, configuredBasePath);
+            state.currentRouteState = await _mergeDevScopedServerData(await loadRouteSurfaceState(outDir, configuredBasePath));
             state.buildStatus = 'ok';
             state.buildError = null;
             state.lastBuildMs = Date.now();
@@ -284,6 +373,7 @@ export async function createDevServer(options) {
         state,
         serverOrigin: _serverOrigin,
         loadRoutesForRequests: _loadRoutesForRequests,
+        loadGlobalMiddlewareForRequests: _loadGlobalMiddlewareForRequests,
         readFileForRequest: _readFileForRequest,
         trace404: _trace404,
         looksLikeJsonRequest,
@@ -324,46 +414,36 @@ export async function createDevServer(options) {
             catch { }
         }
         hmrClients.length = 0;
-        server.close();
+        try {
+            server.close();
+        }
+        catch { }
     };
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        server.once('error', (error) => {
-            if (!settled) {
-                settled = true;
-                reject(error);
-            }
+    try {
+        const listenResult = await listenWithPortFallback({ server, port, host });
+        actualPort = listenResult.port;
+        startupProfile.emit('server_bound', {
+            host: _publicHost(),
+            port: actualPort,
+            buildStatus: state.buildStatus
         });
-        server.listen(port, host, async () => {
-            actualPort = server.address().port;
-            startupProfile.emit('server_bound', {
-                host: _publicHost(),
-                port: actualPort,
-                buildStatus: state.buildStatus
-            });
-            _trace('server_bound', {
-                host: _publicHost(),
-                port: actualPort,
-                buildStatus: state.buildStatus
-            });
-            try {
-                await _runInitialBuild();
-                watcherController.start();
-                if (!settled) {
-                    settled = true;
-                    resolve({
-                        server,
-                        port: actualPort,
-                        close: closeServer
-                    });
-                }
-            }
-            catch (error) {
-                if (!settled) {
-                    settled = true;
-                    reject(error);
-                }
-            }
+        _trace('server_bound', {
+            host: _publicHost(),
+            port: actualPort,
+            buildStatus: state.buildStatus
         });
-    });
+        await _runInitialBuild();
+        watcherController.start();
+        return {
+            server,
+            port: actualPort,
+            requestedPort: listenResult.requestedPort,
+            portFallback: listenResult.portFallback,
+            close: closeServer
+        };
+    }
+    catch (error) {
+        closeServer();
+        throw error;
+    }
 }

package/dist/global-middleware-runtime-source.d.ts

@@ -0,0 +1,15 @@
+export function loadDevGlobalMiddlewareSource({ projectRoot, pagesDir, target }: {
+    projectRoot: any;
+    pagesDir: any;
+    target: any;
+}): Promise<{
+    source: string;
+    sourcePath: string;
+} | null>;
+export function loadPreviewGlobalMiddlewareSource({ projectRoot, distDir }: {
+    projectRoot: any;
+    distDir: any;
+}): Promise<{
+    source: string;
+    sourcePath: string;
+} | null>;

package/dist/global-middleware-runtime-source.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { resolveGlobalMiddleware, validateGlobalMiddlewareSource } from './global-middleware.js';
+const INVALID_PREVIEW_SOURCE_FILE = '[Zenith:Middleware] Invalid global middleware source_file in manifest.';
+function isWithinPath(root, candidate) {
+    const relativePath = relative(resolve(root), resolve(candidate));
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+function assertPreviewSourceFile(projectRoot, sourceFile) {
+    if (typeof sourceFile !== 'string' || sourceFile.length === 0 || !sourceFile.endsWith('.ts')) {
+        throw new Error(INVALID_PREVIEW_SOURCE_FILE);
+    }
+    const sourcePath = resolve(projectRoot, sourceFile);
+    if (!isWithinPath(projectRoot, sourcePath)) {
+        throw new Error(INVALID_PREVIEW_SOURCE_FILE);
+    }
+    return sourcePath;
+}
+function createReadError(sourceFile) {
+    return new Error(`[Zenith:Middleware] Cannot read global middleware source file "${sourceFile}".`);
+}
+async function readMiddlewareSource(sourcePath, sourceFile) {
+    try {
+        return await readFile(sourcePath, 'utf8');
+    }
+    catch {
+        throw createReadError(sourceFile);
+    }
+}
+export async function loadDevGlobalMiddlewareSource({ projectRoot, pagesDir, target }) {
+    const globalMiddleware = await resolveGlobalMiddleware({ projectRoot, pagesDir, target });
+    if (!globalMiddleware) {
+        return null;
+    }
+    const source = await readMiddlewareSource(globalMiddleware.sourcePath, globalMiddleware.sourceFile);
+    validateGlobalMiddlewareSource(source, globalMiddleware.sourceFile, projectRoot);
+    return {
+        source,
+        sourcePath: globalMiddleware.sourcePath
+    };
+}
+export async function loadPreviewGlobalMiddlewareSource({ projectRoot, distDir }) {
+    let manifest = null;
+    const manifestDir = basename(resolve(distDir)) === 'static' ? dirname(distDir) : distDir;
+    try {
+        manifest = JSON.parse(await readFile(join(manifestDir, 'manifest.json'), 'utf8'));
+    }
+    catch {
+        manifest = null;
+    }
+    const sourceFile = manifest?.global_middleware?.source_file;
+    if (!sourceFile) {
+        return null;
+    }
+    const sourcePath = assertPreviewSourceFile(projectRoot, sourceFile);
+    const source = await readMiddlewareSource(sourcePath, sourceFile);
+    validateGlobalMiddlewareSource(source, sourceFile, projectRoot);
+    return {
+        source,
+        sourcePath
+    };
+}

package/dist/global-middleware.d.ts

@@ -0,0 +1,13 @@
+export function validateGlobalMiddlewareSource(source: any, sourceFile: any, projectRoot?: string): void;
+export function normalizeGlobalMiddlewareMetadata(globalMiddleware: any): {
+    source_file: any;
+} | null;
+export function assertGlobalMiddlewareTargetSupported(target: any, globalMiddleware: any): void;
+export function resolveGlobalMiddleware({ projectRoot, pagesDir, target }?: {}): Promise<{
+    sourcePath: string;
+    sourceFile: string;
+    root: string;
+    metadata: {
+        source_file: any;
+    };
+} | null>;