@zenithbuild/cli 0.7.4 → 0.7.7

package/dist/preview/paths.js

@@ -0,0 +1,38 @@
+import { access } from 'node:fs/promises';
+import { extname, normalize, resolve, sep } from 'node:path';
+export function toStaticFilePath(distDir, pathname) {
+    let resolved = pathname;
+    if (resolved === '/') {
+        resolved = '/index.html';
+    }
+    else if (!extname(resolved)) {
+        resolved += '/index.html';
+    }
+    return resolveWithinDist(distDir, resolved);
+}
+export function resolveWithinDist(distDir, requestPath) {
+    let decoded = requestPath;
+    try {
+        decoded = decodeURIComponent(requestPath);
+    }
+    catch {
+        return null;
+    }
+    const normalized = normalize(decoded).replace(/\\/g, '/');
+    const relative = normalized.replace(/^\/+/, '');
+    const root = resolve(distDir);
+    const candidate = resolve(root, relative);
+    if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
+        return candidate;
+    }
+    return null;
+}
+export async function fileExists(fullPath) {
+    try {
+        await access(fullPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/preview/payload.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {string} html
+ * @param {Record<string, unknown>} payload
+ * @returns {string}
+ */
+export function injectSsrPayload(html: string, payload: Record<string, unknown>): string;

package/dist/preview/payload.js

@@ -0,0 +1,34 @@
+/**
+ * @param {string} html
+ * @param {Record<string, unknown>} payload
+ * @returns {string}
+ */
+export function injectSsrPayload(html, payload) {
+    const serialized = serializeInlineScriptJson(payload);
+    const scriptTag = `<script id="zenith-ssr-data">window.__zenith_ssr_data = ${serialized};</script>`;
+    const existingTagRe = /<script\b[^>]*\bid=(["'])zenith-ssr-data\1[^>]*>[\s\S]*?<\/script>/i;
+    if (existingTagRe.test(html)) {
+        return html.replace(existingTagRe, scriptTag);
+    }
+    const headClose = html.match(/<\/head>/i);
+    if (headClose) {
+        return html.replace(/<\/head>/i, `${scriptTag}</head>`);
+    }
+    const bodyOpen = html.match(/<body\b[^>]*>/i);
+    if (bodyOpen) {
+        return html.replace(bodyOpen[0], `${bodyOpen[0]}${scriptTag}`);
+    }
+    return `${scriptTag}${html}`;
+}
+/**
+ * @param {Record<string, unknown>} payload
+ * @returns {string}
+ */
+function serializeInlineScriptJson(payload) {
+    return JSON.stringify(payload)
+        .replace(/</g, '\\u003C')
+        .replace(/>/g, '\\u003E')
+        .replace(/\//g, '\\u002F')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}

package/dist/preview/request-handler.d.ts

@@ -0,0 +1 @@
+export function createPreviewRequestHandler(options: any): (req: any, res: any) => Promise<void>;

package/dist/preview/request-handler.js

@@ -0,0 +1,300 @@
+import { readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { appLocalRedirectLocation, imageEndpointPath, routeCheckPath, stripBasePath } from '../base-path.js';
+import { materializeImageMarkup } from '../images/materialize.js';
+import { createImageRuntimePayload, injectImageRuntimePayload } from '../images/payload.js';
+import { handleImageRequest } from '../images/service.js';
+import { readRequestBodyBuffer } from '../request-body.js';
+import { buildResourceResponseDescriptor } from '../resource-response.js';
+import { clientFacingRouteMessage, logServerException, sanitizeRouteResult } from '../server-error.js';
+import { resolveRequestRoute } from '../server/resolve-request-route.js';
+import { loadRouteSurfaceState } from './manifest.js';
+import { injectSsrPayload } from './payload.js';
+import { fileExists, resolveWithinDist, toStaticFilePath } from './paths.js';
+import { executeServerRoute, routeIdFromSourcePath } from './server-runner.js';
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.gif': 'image/gif'
+};
+const IMAGE_RUNTIME_TAG_RE = /<script\b[^>]*\bid=(["'])zenith-image-runtime\1[^>]*>[\s\S]*?<\/script>/i;
+function appendSetCookieHeaders(headers, setCookies = []) {
+    if (Array.isArray(setCookies) && setCookies.length > 0) {
+        headers['Set-Cookie'] = setCookies.slice();
+    }
+    return headers;
+}
+export function createPreviewRequestHandler(options) {
+    const { distDir, projectRoot, config, logger, verboseLogging, configuredBasePath, routeCheckEnabled, isStaticExportTarget, serverOrigin } = options;
+    async function loadImageManifest() {
+        try {
+            const manifestRaw = await readFile(join(distDir, '_zenith', 'image', 'manifest.json'), 'utf8');
+            const parsed = JSON.parse(manifestRaw);
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return async function previewRequestHandler(req, res) {
+        const url = new URL(req.url, serverOrigin());
+        const { basePath, pageRoutes, resourceRoutes } = await loadRouteSurfaceState(distDir, configuredBasePath);
+        const canonicalPath = stripBasePath(url.pathname, basePath);
+        try {
+            if (url.pathname === routeCheckPath(basePath)) {
+                if (!routeCheckEnabled) {
+                    res.writeHead(501, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'route_check_unsupported' }));
+                    return;
+                }
+                // Security: Require explicitly designated header to prevent public oracle probing
+                if (req.headers['x-zenith-route-check'] !== '1') {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'forbidden', message: 'invalid request context' }));
+                    return;
+                }
+                const targetPath = String(url.searchParams.get('path') || '/');
+                // Security: Prevent protocol/domain injection in path
+                if (targetPath.includes('://') || targetPath.startsWith('//') || /[\r\n]/.test(targetPath)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'invalid_path_format' }));
+                    return;
+                }
+                const targetUrl = new URL(targetPath, url.origin);
+                if (targetUrl.origin !== url.origin) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
+                    return;
+                }
+                const canonicalTargetPath = stripBasePath(targetUrl.pathname, basePath);
+                if (canonicalTargetPath === null) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'route_not_found' }));
+                    return;
+                }
+                const canonicalTargetUrl = new URL(targetUrl.toString());
+                canonicalTargetUrl.pathname = canonicalTargetPath;
+                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, pageRoutes);
+                if (!resolvedCheck.matched || !resolvedCheck.route) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'route_not_found' }));
+                    return;
+                }
+                const checkResult = await executeServerRoute({
+                    source: resolvedCheck.route.server_script || '',
+                    sourcePath: resolvedCheck.route.server_script_path || '',
+                    params: resolvedCheck.params,
+                    requestUrl: targetUrl.toString(),
+                    requestMethod: req.method || 'GET',
+                    requestHeaders: req.headers,
+                    routePattern: resolvedCheck.route.path,
+                    routeFile: resolvedCheck.route.server_script_path || '',
+                    routeId: resolvedCheck.route.route_id || routeIdFromSourcePath(resolvedCheck.route.server_script_path || ''),
+                    guardOnly: true
+                });
+                // Security: Enforce relative or same-origin redirects
+                if (checkResult && checkResult.result && checkResult.result.kind === 'redirect') {
+                    const loc = appLocalRedirectLocation(checkResult.result.location || '/', basePath);
+                    checkResult.result.location = loc;
+                    if (loc.includes('://') || loc.startsWith('//')) {
+                        try {
+                            const parsedLoc = new URL(loc);
+                            if (parsedLoc.origin !== targetUrl.origin) {
+                                checkResult.result.location = appLocalRedirectLocation('/', basePath);
+                            }
+                        }
+                        catch {
+                            checkResult.result.location = appLocalRedirectLocation('/', basePath);
+                        }
+                    }
+                }
+                res.writeHead(200, {
+                    'Content-Type': 'application/json',
+                    'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+                    'Pragma': 'no-cache',
+                    'Expires': '0',
+                    'Vary': 'Cookie'
+                });
+                res.end(JSON.stringify({
+                    result: sanitizeRouteResult(checkResult?.result || checkResult),
+                    routeId: resolvedCheck.route.route_id || '',
+                    to: targetUrl.toString()
+                }));
+                return;
+            }
+            if (url.pathname === imageEndpointPath(basePath)) {
+                if (isStaticExportTarget) {
+                    throw new Error('not found');
+                }
+                await handleImageRequest(req, res, {
+                    requestUrl: url,
+                    projectRoot,
+                    config: config.images
+                });
+                return;
+            }
+            if (canonicalPath === null) {
+                throw new Error('not found');
+            }
+            if (extname(canonicalPath) && extname(canonicalPath) !== '.html') {
+                const staticPath = isStaticExportTarget
+                    ? resolveWithinDist(distDir, url.pathname)
+                    : resolveWithinDist(distDir, canonicalPath);
+                if (!staticPath || !(await fileExists(staticPath))) {
+                    throw new Error('not found');
+                }
+                const content = await readFile(staticPath);
+                const mime = MIME_TYPES[extname(staticPath)] || 'application/octet-stream';
+                res.writeHead(200, { 'Content-Type': mime });
+                res.end(content);
+                return;
+            }
+            if (isStaticExportTarget) {
+                const directHtmlPath = toStaticFilePath(distDir, url.pathname);
+                if (!directHtmlPath || !(await fileExists(directHtmlPath))) {
+                    throw new Error('not found');
+                }
+                const html = await readFile(directHtmlPath, 'utf8');
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(html);
+                return;
+            }
+            const canonicalUrl = new URL(url.toString());
+            canonicalUrl.pathname = canonicalPath;
+            const resolvedResource = resolveRequestRoute(canonicalUrl, resourceRoutes);
+            if (resolvedResource.matched && resolvedResource.route) {
+                const requestMethod = req.method || 'GET';
+                const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                    ? null
+                    : await readRequestBodyBuffer(req);
+                const execution = await executeServerRoute({
+                    source: resolvedResource.route.server_script || '',
+                    sourcePath: resolvedResource.route.server_script_path || '',
+                    params: resolvedResource.params,
+                    requestUrl: url.toString(),
+                    requestMethod,
+                    requestHeaders: req.headers,
+                    requestBodyBuffer,
+                    routePattern: resolvedResource.route.path,
+                    routeFile: resolvedResource.route.server_script_path || '',
+                    routeId: resolvedResource.route.route_id || routeIdFromSourcePath(resolvedResource.route.server_script_path || ''),
+                    routeKind: 'resource'
+                });
+                const descriptor = buildResourceResponseDescriptor(execution?.result, basePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
+                res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
+                if ((req.method || 'GET').toUpperCase() === 'HEAD') {
+                    res.end();
+                    return;
+                }
+                res.end(descriptor.body);
+                return;
+            }
+            const resolved = resolveRequestRoute(canonicalUrl, pageRoutes);
+            let htmlPath = null;
+            if (resolved.matched && resolved.route) {
+                if (verboseLogging) {
+                    logger.router(`${req.method || 'GET'} ${url.pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`);
+                }
+                const output = resolved.route.output.startsWith('/')
+                    ? resolved.route.output.slice(1)
+                    : resolved.route.output;
+                htmlPath = resolveWithinDist(distDir, output);
+            }
+            else {
+                htmlPath = toStaticFilePath(distDir, url.pathname);
+            }
+            if (!htmlPath || !(await fileExists(htmlPath))) {
+                throw new Error('not found');
+            }
+            let ssrPayload = null;
+            let routeExecution = null;
+            if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
+                try {
+                    const requestMethod = req.method || 'GET';
+                    const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                        ? null
+                        : await readRequestBodyBuffer(req);
+                    routeExecution = await executeServerRoute({
+                        source: resolved.route.server_script,
+                        sourcePath: resolved.route.server_script_path || '',
+                        params: resolved.params,
+                        requestUrl: url.toString(),
+                        requestMethod,
+                        requestHeaders: req.headers,
+                        requestBodyBuffer,
+                        routePattern: resolved.route.path,
+                        routeFile: resolved.route.server_script_path || '',
+                        routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
+                    });
+                }
+                catch (error) {
+                    logServerException('preview server route execution failed', error);
+                    ssrPayload = {
+                        __zenith_error: {
+                            status: 500,
+                            code: 'LOAD_FAILED',
+                            message: error instanceof Error ? error.message : String(error || '')
+                        }
+                    };
+                }
+                const trace = routeExecution?.trace || { guard: 'none', action: 'none', load: 'none' };
+                const routeId = resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '');
+                const setCookies = Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : [];
+                if (verboseLogging) {
+                    logger.router(`${routeId} guard=${trace.guard} action=${trace.action} load=${trace.load}`);
+                }
+                const result = routeExecution?.result;
+                if (result && result.kind === 'redirect') {
+                    const status = Number.isInteger(result.status) ? result.status : 302;
+                    res.writeHead(status, appendSetCookieHeaders({
+                        Location: appLocalRedirectLocation(result.location, basePath),
+                        'Cache-Control': 'no-store'
+                    }, setCookies));
+                    res.end('');
+                    return;
+                }
+                if (result && result.kind === 'deny') {
+                    const status = Number.isInteger(result.status) ? result.status : 403;
+                    res.writeHead(status, appendSetCookieHeaders({ 'Content-Type': 'text/plain; charset=utf-8' }, setCookies));
+                    res.end(clientFacingRouteMessage(status, result.message));
+                    return;
+                }
+                if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+                    ssrPayload = result.data;
+                }
+            }
+            let html = await readFile(htmlPath, 'utf8');
+            if (resolved.matched) {
+                html = await materializeImageMarkup({
+                    html,
+                    payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath),
+                    imageMaterialization: Array.isArray(resolved.route?.image_materialization)
+                        ? resolved.route.image_materialization
+                        : []
+                });
+            }
+            if (ssrPayload) {
+                html = injectSsrPayload(html, ssrPayload);
+            }
+            if (!IMAGE_RUNTIME_TAG_RE.test(html)) {
+                html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath));
+            }
+            res.writeHead(Number.isInteger(routeExecution?.status) ? routeExecution.status : 200, appendSetCookieHeaders({
+                'Content-Type': 'text/html'
+            }, Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : []));
+            res.end(html);
+        }
+        catch {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('404 Not Found');
+        }
+    };
+}

package/dist/preview/server-runner.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, requestBodyBuffer?: Buffer | null, routePattern?: string, routeFile?: string, routeId?: string, routeKind?: 'page' | 'resource' }} input
+ * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
+ */
+export function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind, guardOnly }: {
+    source: string;
+    sourcePath: string;
+    params: Record<string, string>;
+    requestUrl?: string;
+    requestMethod?: string;
+    requestHeaders?: Record<string, string | string[] | undefined>;
+    requestBodyBuffer?: Buffer | null;
+    routePattern?: string;
+    routeFile?: string;
+    routeId?: string;
+    routeKind?: "page" | "resource";
+}): Promise<{
+    result: {
+        kind: string;
+        [key: string]: unknown;
+    };
+    trace: {
+        guard: string;
+        action: string;
+        load: string;
+    };
+    status?: number;
+    setCookies?: string[];
+}>;
+/**
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export function executeServerScript(input: {
+    source: string;
+    sourcePath: string;
+    params: Record<string, string>;
+    requestUrl?: string;
+    requestMethod?: string;
+    requestHeaders?: Record<string, string | string[] | undefined>;
+    routePattern?: string;
+    routeFile?: string;
+    routeId?: string;
+}): Promise<Record<string, unknown> | null>;
+/**
+ * @param {string} sourcePath
+ * @returns {string}
+ */
+export function routeIdFromSourcePath(sourcePath: string): string;

package/dist/preview/server-runner.js

@@ -0,0 +1,220 @@
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { clientFacingRouteMessage, defaultRouteDenyMessage } from '../server-error.js';
+import { SERVER_SCRIPT_RUNNER } from './server-script-runner-template.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, requestBodyBuffer?: Buffer | null, routePattern?: string, routeFile?: string, routeId?: string, routeKind?: 'page' | 'resource' }} input
+ * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
+ */
+export async function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind = 'page', guardOnly = false }) {
+    if (!source || !String(source).trim()) {
+        return {
+            result: { kind: 'data', data: {} },
+            trace: { guard: 'none', action: 'none', load: 'none' }
+        };
+    }
+    const payload = await spawnNodeServerRunner({
+        source,
+        sourcePath,
+        params,
+        requestUrl: requestUrl || 'http://localhost/',
+        requestMethod: requestMethod || 'GET',
+        requestHeaders: sanitizeRequestHeaders(requestHeaders || {}),
+        requestBodyBuffer: Buffer.isBuffer(requestBodyBuffer) ? requestBodyBuffer : null,
+        routePattern: routePattern || '',
+        routeFile: routeFile || sourcePath || '',
+        routeId: routeId || routeIdFromSourcePath(sourcePath || ''),
+        routeKind,
+        guardOnly
+    });
+    if (payload === null || payload === undefined) {
+        return {
+            result: { kind: 'data', data: {} },
+            trace: { guard: 'none', action: 'none', load: 'none' }
+        };
+    }
+    if (typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('[zenith-preview] server script payload must be an object');
+    }
+    const errorEnvelope = payload.__zenith_error;
+    if (errorEnvelope && typeof errorEnvelope === 'object') {
+        return {
+            result: {
+                kind: 'deny',
+                status: 500,
+                message: defaultRouteDenyMessage(500)
+            },
+            trace: { guard: 'none', action: 'none', load: 'deny' }
+        };
+    }
+    const result = payload.result;
+    const trace = payload.trace;
+    if (result && typeof result === 'object' && !Array.isArray(result) && typeof result.kind === 'string') {
+        return {
+            result,
+            trace: trace && typeof trace === 'object'
+                ? {
+                    guard: String(trace.guard || 'none'),
+                    action: String(trace.action || 'none'),
+                    load: String(trace.load || 'none')
+                }
+                : { guard: 'none', action: 'none', load: 'none' },
+            status: Number.isInteger(payload.status) ? payload.status : undefined,
+            setCookies: Array.isArray(payload.setCookies)
+                ? payload.setCookies.filter((value) => typeof value === 'string' && value.length > 0)
+                : []
+        };
+    }
+    return {
+        result: {
+            kind: 'data',
+            data: payload
+        },
+        trace: { guard: 'none', action: 'none', load: 'data' }
+    };
+}
+/**
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export async function executeServerScript(input) {
+    const execution = await executeServerRoute(input);
+    const result = execution?.result;
+    if (!result || typeof result !== 'object') {
+        return null;
+    }
+    if (result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+        return result.data;
+    }
+    if (result.kind === 'redirect') {
+        return {
+            __zenith_error: {
+                status: Number.isInteger(result.status) ? result.status : 302,
+                code: 'REDIRECT',
+                message: `Redirect to ${String(result.location || '')}`
+            }
+        };
+    }
+    if (result.kind === 'deny') {
+        const status = Number.isInteger(result.status) ? result.status : 403;
+        return {
+            __zenith_error: {
+                status,
+                code: status >= 500 ? 'LOAD_FAILED' : (status === 404 ? 'NOT_FOUND' : 'ACCESS_DENIED'),
+                message: clientFacingRouteMessage(status, result.message)
+            }
+        };
+    }
+    return {};
+}
+/**
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl: string, requestMethod: string, requestHeaders: Record<string, string>, requestBodyBuffer?: Buffer | null, routePattern: string, routeFile: string, routeId: string, routeKind?: 'page' | 'resource' }} input
+ * @returns {Promise<unknown>}
+ */
+function spawnNodeServerRunner(input) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, ['--experimental-vm-modules', '--input-type=module', '-e', SERVER_SCRIPT_RUNNER], {
+            env: {
+                ...process.env,
+                ZENITH_SERVER_SOURCE: input.source,
+                ZENITH_SERVER_SOURCE_PATH: input.sourcePath || '',
+                ZENITH_SERVER_PARAMS: JSON.stringify(input.params || {}),
+                ZENITH_SERVER_REQUEST_URL: input.requestUrl || 'http://localhost/',
+                ZENITH_SERVER_REQUEST_METHOD: input.requestMethod || 'GET',
+                ZENITH_SERVER_REQUEST_HEADERS: JSON.stringify(input.requestHeaders || {}),
+                ZENITH_SERVER_ROUTE_PATTERN: input.routePattern || '',
+                ZENITH_SERVER_ROUTE_FILE: input.routeFile || input.sourcePath || '',
+                ZENITH_SERVER_ROUTE_ID: input.routeId || '',
+                ZENITH_SERVER_ROUTE_KIND: input.routeKind || 'page',
+                ZENITH_SERVER_GUARD_ONLY: input.guardOnly ? '1' : '',
+                ZENITH_SERVER_CONTRACT_PATH: join(__dirname, '..', 'server-contract.js'),
+                ZENITH_SERVER_ROUTE_AUTH_PATH: join(__dirname, '..', 'auth', 'route-auth.js')
+            },
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        const runnerRequestBody = Buffer.isBuffer(input.requestBodyBuffer) ? input.requestBodyBuffer : null;
+        child.stdin.on('error', () => {
+            // ignore broken pipes when the runner exits before consuming stdin
+        });
+        child.stdin.end(runnerRequestBody && runnerRequestBody.length > 0 ? runnerRequestBody : undefined);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', (error) => {
+            rejectPromise(error);
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                rejectPromise(new Error(`[zenith-preview] server script execution failed (${code}): ${stderr.trim() || stdout.trim()}`));
+                return;
+            }
+            const stderrOutput = stderr.trim();
+            const internalErrorIndex = stderrOutput.indexOf('[Zenith:Server]');
+            if (internalErrorIndex >= 0) {
+                console.error(stderrOutput.slice(internalErrorIndex).trim());
+            }
+            const raw = stdout.trim();
+            if (!raw || raw === 'null') {
+                resolvePromise(null);
+                return;
+            }
+            try {
+                resolvePromise(JSON.parse(raw));
+            }
+            catch (error) {
+                rejectPromise(new Error(`[zenith-preview] invalid server payload JSON: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        });
+    });
+}
+/**
+ * @param {Record<string, string | string[] | undefined>} headers
+ * @returns {Record<string, string>}
+ */
+function sanitizeRequestHeaders(headers) {
+    const out = Object.create(null);
+    const denyExact = new Set(['proxy-authorization', 'set-cookie']);
+    const denyPrefixes = ['x-forwarded-', 'cf-'];
+    for (const [rawKey, rawValue] of Object.entries(headers || {})) {
+        const key = String(rawKey || '').toLowerCase();
+        if (!key)
+            continue;
+        if (denyExact.has(key))
+            continue;
+        if (denyPrefixes.some((prefix) => key.startsWith(prefix)))
+            continue;
+        let value = '';
+        if (Array.isArray(rawValue)) {
+            value = rawValue.filter((entry) => entry !== undefined).map(String).join(', ');
+        }
+        else if (rawValue !== undefined) {
+            value = String(rawValue);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * @param {string} sourcePath
+ * @returns {string}
+ */
+export function routeIdFromSourcePath(sourcePath) {
+    const normalized = String(sourcePath || '').replaceAll('\\', '/');
+    const marker = '/pages/';
+    const markerIndex = normalized.lastIndexOf(marker);
+    let routeId = markerIndex >= 0
+        ? normalized.slice(markerIndex + marker.length)
+        : normalized.split('/').pop() || normalized;
+    routeId = routeId.replace(/\.zen$/i, '');
+    if (routeId.endsWith('/index')) {
+        routeId = routeId.slice(0, -('/index'.length));
+    }
+    return routeId || 'index';
+}

package/dist/preview/server-script-runner-template.d.ts

@@ -0,0 +1 @@
+export const SERVER_SCRIPT_RUNNER: string;