@zenithbuild/cli 0.5.0-beta.2.16 → 0.5.0-beta.2.20

package/dist/build.js

@@ -15,7 +15,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { generateManifest } from './manifest.js';
 import { buildComponentRegistry, expandComponents, extractTemplate, isDocumentMode } from './resolve-components.js';
@@ -487,7 +487,7 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
     const scriptRe = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
     const serverMatches = [];
     const reservedServerExportRe =
-        /\bexport\s+const\s+(?:data|prerender)\b|\bexport\s+(?:async\s+)?function\s+load\s*\(|\bexport\s+const\s+load\s*=/;
+        /\bexport\s+const\s+(?:data|prerender|guard|load)\b|\bexport\s+(?:async\s+)?function\s+(?:load|guard)\s*\(|\bexport\s+const\s+(?:load|guard)\s*=/;
 
     for (const match of source.matchAll(scriptRe)) {
         const attrs = String(match[1] || '');
@@ -498,8 +498,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             throw new Error(
                 `Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
-                `  Reason: data/load/prerender exports are only allowed in <script server lang="ts">\n` +
-                `  Example: move export const data or export const load into <script server lang="ts">`
+                `  Reason: guard/load/data exports are only allowed in <script server lang="ts"> or adjacent .guard.ts / .load.ts files\n` +
+                `  Example: move the export into <script server lang="ts">`
             );
         }
 
@@ -570,6 +570,25 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         );
     }
 
+    const guardFnMatch = serverSource.match(/\bexport\s+(?:async\s+)?function\s+guard\s*\(([^)]*)\)/);
+    const guardConstParenMatch = serverSource.match(/\bexport\s+const\s+guard\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>/);
+    const guardConstSingleArgMatch = serverSource.match(
+        /\bexport\s+const\s+guard\s*=\s*(?:async\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/
+    );
+    const hasGuard = Boolean(guardFnMatch || guardConstParenMatch || guardConstSingleArgMatch);
+    const guardMatchCount =
+        Number(Boolean(guardFnMatch)) +
+        Number(Boolean(guardConstParenMatch)) +
+        Number(Boolean(guardConstSingleArgMatch));
+    if (guardMatchCount > 1) {
+        throw new Error(
+            `Zenith server script contract violation:\n` +
+            `  File: ${sourceFile}\n` +
+            `  Reason: multiple guard exports detected\n` +
+            `  Example: keep exactly one export const guard = async (ctx) => ({ ... })`
+        );
+    }
+
     const hasData = /\bexport\s+const\s+data\b/.test(serverSource);
     const hasSsrData = /\bexport\s+const\s+ssr_data\b/.test(serverSource);
     const hasSsr = /\bexport\s+const\s+ssr\b/.test(serverSource);
@@ -610,6 +629,24 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         }
     }
 
+    if (hasGuard) {
+        const singleArg = String(guardConstSingleArgMatch?.[1] || '').trim();
+        const paramsText = String((guardFnMatch || guardConstParenMatch)?.[1] || '').trim();
+        const arity = singleArg
+            ? 1
+            : paramsText.length === 0
+                ? 0
+                : paramsText.split(',').length;
+        if (arity !== 1) {
+            throw new Error(
+                `Zenith server script contract violation:\n` +
+                `  File: ${sourceFile}\n` +
+                `  Reason: guard(ctx) must accept exactly one argument\n` +
+                `  Example: export const guard = async (ctx) => ({ ... })`
+            );
+        }
+    }
+
     const prerenderMatch = serverSource.match(/\bexport\s+const\s+prerender\s*=\s*([^\n;]+)/);
     let prerender = false;
     if (prerenderMatch) {
@@ -631,6 +668,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             serverScript: {
                 source: serverSource,
                 prerender,
+                has_guard: hasGuard,
+                has_load: hasLoad,
                 source_path: sourceFile
             }
         };
@@ -644,6 +683,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         serverScript: {
             source: serverSource,
             prerender,
+            has_guard: hasGuard,
+            has_load: hasLoad,
             source_path: sourceFile
         }
     };
@@ -1403,6 +1444,14 @@ export async function build(options) {
         const rawSource = readFileSync(sourceFile, 'utf8');
         const componentUsageAttrs = collectComponentUsageAttrs(rawSource, registry);
 
+        const baseName = sourceFile.slice(0, -extname(sourceFile).length);
+        let adjacentGuard = null;
+        let adjacentLoad = null;
+        for (const ext of ['.ts', '.js']) {
+            if (!adjacentGuard && existsSync(`${baseName}.guard${ext}`)) adjacentGuard = `${baseName}.guard${ext}`;
+            if (!adjacentLoad && existsSync(`${baseName}.load${ext}`)) adjacentLoad = `${baseName}.load${ext}`;
+        }
+
         // 2a. Expand PascalCase component tags
         const { expandedSource, usedComponents } = expandComponents(
             rawSource, registry, sourceFile
@@ -1417,6 +1466,10 @@ export async function build(options) {
             compilerOpts,
             { onWarning: emitCompilerWarning }
         );
+
+        const hasGuard = (extractedServer.serverScript && extractedServer.serverScript.has_guard) || adjacentGuard !== null;
+        const hasLoad = (extractedServer.serverScript && extractedServer.serverScript.has_load) || adjacentLoad !== null;
+
         if (extractedServer.serverScript) {
             pageIr.server_script = extractedServer.serverScript;
             pageIr.prerender = extractedServer.serverScript.prerender === true;
@@ -1425,6 +1478,20 @@ export async function build(options) {
             }
         }
 
+        // Static Build Route Protection Policy
+        if (pageIr.prerender === true && (hasGuard || hasLoad)) {
+            throw new Error(
+                `[zenith] Build failed for ${entry.file}: protected routes require SSR/runtime. ` +
+                `Cannot prerender a static route with a \`guard\` or \`load\` function.`
+            );
+        }
+
+        // Apply metadata to IR
+        pageIr.has_guard = hasGuard;
+        pageIr.has_load = hasLoad;
+        pageIr.guard_module_ref = adjacentGuard ? relative(srcDir, adjacentGuard).replaceAll('\\', '/') : null;
+        pageIr.load_module_ref = adjacentLoad ? relative(srcDir, adjacentLoad).replaceAll('\\', '/') : null;
+
         // Ensure IR has required array fields for merging
         pageIr.components_scripts = pageIr.components_scripts || {};
         pageIr.component_instances = pageIr.component_instances || [];

package/dist/dev-server.js

@@ -5,16 +5,16 @@
 //
 // - Compiles pages on demand
 // - Rebuilds on file change
-// - Injects HMR client script
+// - Exposes V1 HMR endpoints consumed by runtime dev client
 // - Server route resolution uses manifest matching
 //
 // V0: Uses Node.js http module + fs.watch. No external deps.
 // ---------------------------------------------------------------------------
 
 import { createServer } from 'node:http';
-import { watch } from 'node:fs';
+import { existsSync, watch } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join, extname } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { build } from './build.js';
 import {
     executeServerRoute,
@@ -35,21 +35,8 @@ const MIME_TYPES = {
     '.svg': 'image/svg+xml'
 };
 
-const HMR_CLIENT_SCRIPT = `
-<script>
-// Zenith HMR Client V0
-(function() {
-    const es = new EventSource('/__zenith_hmr');
-    es.onmessage = function(event) {
-        if (event.data === 'reload') {
-            window.location.reload();
-        }
-    };
-    es.onerror = function() {
-        setTimeout(function() { window.location.reload(); }, 1000);
-    };
-})();
-</script>`;
+// Note: V0 HMR script injection has been moved to the runtime client.
+// This server purely hosts the V1 HMR contract endpoints.
 
 /**
  * Create and start a development server.
@@ -65,25 +52,66 @@ export async function createDevServer(options) {
         config = {}
     } = options;
 
+    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'
+        ? dirname(pagesParentDir)
+        : pagesParentDir;
+    const watchRoots = new Set([pagesParentDir]);
+
     /** @type {import('http').ServerResponse[]} */
     const hmrClients = [];
-    let _watcher = null;
+    /** @type {import('fs').FSWatcher[]} */
+    let _watchers = [];
+
+    let buildId = 0;
+    let buildStatus = 'ok'; // 'ok' | 'error' | 'building'
+    let lastBuildMs = Date.now();
+    let durationMs = 0;
+    let buildError = null;
+
+    // We can't know the exact CSS hashed filename here easily without parsing the dist manifest,
+    // but the runtime handles standard HMR updates via generic fetch if we pass a timestamp,
+    // or we can pass an empty string and rely on the client's `swapStylesheet`.
+    let currentCssHref = '';
+
+    function _broadcastEvent(type, payload = {}) {
+        const data = JSON.stringify({
+            buildId,
+            ...payload
+        });
+        for (const client of hmrClients) {
+            try {
+                client.write(`event: ${type}\ndata: ${data}\n\n`);
+            } catch {
+                // client disconnected
+            }
+        }
+    }
 
     // Initial build
-    await build({ pagesDir, outDir, config });
+    try {
+        await build({ pagesDir, outDir, config });
+    } catch (err) {
+        buildStatus = 'error';
+        buildError = { message: err instanceof Error ? err.message : String(err) };
+    }
 
     const server = createServer(async (req, res) => {
         const url = new URL(req.url, `http://localhost:${port}`);
         let pathname = url.pathname;
 
-        // HMR endpoint
+        // Legacy HMR endpoint (deprecated but kept alive to avoid breaking old caches instantly)
         if (pathname === '/__zenith_hmr') {
             res.writeHead(200, {
                 'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                'Connection': 'keep-alive'
+                'Cache-Control': 'no-store',
+                'Connection': 'keep-alive',
+                'X-Zenith-Deprecated': 'true'
             });
-            // Flush headers by sending initial comment
+            console.warn('[zenith] Warning: /__zenith_hmr is legacy; use /__zenith_dev/events');
             res.write(': connected\n\n');
             hmrClients.push(res);
             req.on('close', () => {
@@ -93,10 +121,65 @@ export async function createDevServer(options) {
             return;
         }
 
+        // V1 Dev State Endpoint
+        if (pathname === '/__zenith_dev/state') {
+            res.writeHead(200, {
+                'Content-Type': 'application/json',
+                'Cache-Control': 'no-store'
+            });
+            res.end(JSON.stringify({
+                serverUrl: `http://localhost:${port}`,
+                buildId,
+                status: buildStatus,
+                lastBuildMs,
+                durationMs,
+                cssHref: currentCssHref,
+                error: buildError
+            }));
+            return;
+        }
+
+        // V1 Dev Events Endpoint (SSE)
+        if (pathname === '/__zenith_dev/events') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-store',
+                'Connection': 'keep-alive'
+            });
+            res.write('event: connected\ndata: {}\n\n');
+            hmrClients.push(res);
+            req.on('close', () => {
+                const idx = hmrClients.indexOf(res);
+                if (idx !== -1) hmrClients.splice(idx, 1);
+            });
+            return;
+        }
+
         if (pathname === '/__zenith/route-check') {
             try {
+                // 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, `http://localhost:${port}`);
+                if (targetUrl.origin !== `http://localhost:${port}`) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
+                    return;
+                }
+
                 const routes = await loadRouteManifest(outDir);
                 const resolvedCheck = resolveRequestRoute(targetUrl, routes);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
@@ -114,10 +197,36 @@ export async function createDevServer(options) {
                     requestHeaders: req.headers,
                     routePattern: resolvedCheck.route.path,
                     routeFile: resolvedCheck.route.server_script_path || '',
-                    routeId: resolvedCheck.route.route_id || ''
+                    routeId: resolvedCheck.route.route_id || '',
+                    guardOnly: true
+                });
+                // Security: Enforce relative or same-origin redirects
+                if (checkResult && checkResult.result && checkResult.result.kind === 'redirect') {
+                    const loc = String(checkResult.result.location || '/');
+                    if (loc.includes('://') || loc.startsWith('//')) {
+                        try {
+                            const parsedLoc = new URL(loc);
+                            if (parsedLoc.origin !== targetUrl.origin) {
+                                checkResult.result.location = '/'; // Fallback to root for open redirect attempt
+                            }
+                        } catch {
+                            checkResult.result.location = '/';
+                        }
+                    }
+                }
+
+                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.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(checkResult));
+                res.end(JSON.stringify({
+                    result: checkResult?.result || checkResult,
+                    routeId: resolvedCheck.route.route_id || '',
+                    to: targetUrl.toString()
+                }));
                 return;
             } catch {
                 res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -171,15 +280,10 @@ export async function createDevServer(options) {
                         routeId: resolved.route.route_id || ''
                     });
                 } catch (error) {
-                    routeExecution = {
-                        result: {
-                            kind: 'deny',
-                            status: 500,
+                    ssrPayload = {
+                        __zenith_error: {
+                            code: 'LOAD_FAILED',
                             message: error instanceof Error ? error.message : String(error)
-                        },
-                        trace: {
-                            guard: 'none',
-                            load: 'deny'
                         }
                     };
                 }
@@ -214,7 +318,6 @@ export async function createDevServer(options) {
             if (ssrPayload) {
                 content = injectSsrPayload(content, ssrPayload);
             }
-            content = content.replace('</body>', `${HMR_CLIENT_SCRIPT}</body>`);
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(content);
         } catch {
@@ -236,20 +339,111 @@ export async function createDevServer(options) {
         }
     }
 
+    let _buildDebounce = null;
+    let _queuedFiles = new Set();
+
+    function _isWithin(parent, child) {
+        const rel = relative(parent, child);
+        return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+    }
+
+    function _toDisplayPath(absPath) {
+        const rel = relative(projectRoot, absPath);
+        if (rel === '') return '.';
+        if (!rel.startsWith('..') && !isAbsolute(rel)) {
+            return rel;
+        }
+        return absPath;
+    }
+
+    function _shouldIgnoreChange(absPath) {
+        if (_isWithin(resolvedOutDir, absPath)) {
+            return true;
+        }
+        if (_isWithin(resolvedOutDirTmp, absPath)) {
+            return true;
+        }
+        const rel = relative(projectRoot, absPath);
+        if (rel.startsWith('..') || isAbsolute(rel)) {
+            return false;
+        }
+        const segments = rel.split(/[\\/]+/g);
+        return segments.includes('node_modules')
+            || segments.includes('.git')
+            || segments.includes('.zenith')
+            || segments.includes('target')
+            || segments.includes('.turbo');
+    }
+
     /**
-     * Start watching the pages directory for changes.
+     * Start watching source roots for changes.
      */
     function _startWatcher() {
-        try {
-            _watcher = watch(pagesDir, { recursive: true }, async (eventType, filename) => {
-                if (!filename) return;
+        const queueRebuild = () => {
+            if (_buildDebounce !== null) {
+                clearTimeout(_buildDebounce);
+            }
 
-                // Rebuild
-                await build({ pagesDir, outDir, config });
-                _broadcastReload();
-            });
-        } catch {
-            // fs.watch may not support recursive on all platforms
+            _buildDebounce = setTimeout(async () => {
+                _buildDebounce = null;
+                const changed = Array.from(_queuedFiles).map(_toDisplayPath).sort();
+                _queuedFiles.clear();
+
+                buildId++;
+                buildStatus = 'building';
+                _broadcastEvent('build_start', { changedFiles: changed });
+
+                const startTime = Date.now();
+                try {
+                    await build({ pagesDir, outDir, config });
+                    buildStatus = 'ok';
+                    buildError = null;
+                    lastBuildMs = Date.now();
+                    durationMs = lastBuildMs - startTime;
+
+                    _broadcastEvent('build_complete', {
+                        durationMs,
+                        status: buildStatus
+                    });
+
+                    const onlyCss = changed.length > 0 && changed.every((f) => f.endsWith('.css'));
+                    if (onlyCss) {
+                        // Let the client fetch the updated CSS automatically
+                        _broadcastEvent('css_update', {});
+                    } else {
+                        _broadcastEvent('reload', {});
+                    }
+                } catch (err) {
+                    const fullError = err instanceof Error ? err.message : String(err);
+                    buildStatus = 'error';
+                    buildError = { message: fullError.length > 10000 ? fullError.slice(0, 10000) + '... (truncated)' : fullError };
+                    lastBuildMs = Date.now();
+                    durationMs = lastBuildMs - startTime;
+
+                    _broadcastEvent('build_error', buildError);
+                }
+            }, 50);
+        };
+
+        const roots = Array.from(watchRoots);
+        for (const root of roots) {
+            if (!existsSync(root)) continue;
+            try {
+                const watcher = watch(root, { recursive: true }, (_eventType, filename) => {
+                    if (!filename) {
+                        return;
+                    }
+                    const changedPath = resolve(root, String(filename));
+                    if (_shouldIgnoreChange(changedPath)) {
+                        return;
+                    }
+                    _queuedFiles.add(changedPath);
+                    queueRebuild();
+                });
+                _watchers.push(watcher);
+            } catch {
+                // fs.watch recursive may not be supported on this platform/root
+            }
         }
     }
 
@@ -262,10 +456,14 @@ export async function createDevServer(options) {
                 server,
                 port: actualPort,
                 close: () => {
-                    if (_watcher) {
-                        _watcher.close();
-                        _watcher = null;
+                    for (const watcher of _watchers) {
+                        try {
+                            watcher.close();
+                        } catch {
+                            // ignore close errors
+                        }
                     }
+                    _watchers = [];
                     for (const client of hmrClients) {
                         try { client.end(); } catch { }
                     }

package/dist/preview.js

@@ -47,6 +47,7 @@ const requestHeaders = JSON.parse(process.env.ZENITH_SERVER_REQUEST_HEADERS || '
 const routePattern = process.env.ZENITH_SERVER_ROUTE_PATTERN || '';
 const routeFile = process.env.ZENITH_SERVER_ROUTE_FILE || sourcePath || '';
 const routeId = process.env.ZENITH_SERVER_ROUTE_ID || routePattern || '';
+const guardOnly = process.env.ZENITH_SERVER_GUARD_ONLY === '1';
 
 if (!source.trim()) {
   process.stdout.write('null');
@@ -363,7 +364,8 @@ try {
   const resolved = await context.resolveRouteResult({
     exports: exported,
     ctx: context.ctx,
-    filePath: sourcePath || 'server_script'
+    filePath: sourcePath || 'server_script',
+    guardOnly: guardOnly
   });
 
   process.stdout.write(JSON.stringify(resolved || null));
@@ -395,8 +397,29 @@ export async function createPreviewServer(options) {
 
     try {
       if (url.pathname === '/__zenith/route-check') {
+        // 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, `http://localhost:${port}`);
+        if (targetUrl.origin !== `http://localhost:${port}`) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
+          return;
+        }
+
         const routes = await loadRouteManifest(distDir);
         const resolvedCheck = resolveRequestRoute(targetUrl, routes);
         if (!resolvedCheck.matched || !resolvedCheck.route) {
@@ -414,10 +437,36 @@ export async function createPreviewServer(options) {
           requestHeaders: req.headers,
           routePattern: resolvedCheck.route.path,
           routeFile: resolvedCheck.route.server_script_path || '',
-          routeId: resolvedCheck.route.route_id || routeIdFromSourcePath(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 = String(checkResult.result.location || '/');
+          if (loc.includes('://') || loc.startsWith('//')) {
+            try {
+              const parsedLoc = new URL(loc);
+              if (parsedLoc.origin !== targetUrl.origin) {
+                checkResult.result.location = '/'; // Fallback to root for open redirect attempt
+              }
+            } catch {
+              checkResult.result.location = '/';
+            }
+          }
+        }
+
+        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.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify(checkResult));
+        res.end(JSON.stringify({
+          result: checkResult?.result || checkResult,
+          routeId: resolvedCheck.route.route_id || '',
+          to: targetUrl.toString()
+        }));
         return;
       }
 
@@ -467,15 +516,10 @@ export async function createPreviewServer(options) {
             routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
           });
         } catch (error) {
-          routeExecution = {
-            result: {
-              kind: 'deny',
-              status: 500,
+          ssrPayload = {
+            __zenith_error: {
+              code: 'LOAD_FAILED',
               message: error instanceof Error ? error.message : String(error)
-            },
-            trace: {
-              guard: 'none',
-              load: 'deny'
             }
           };
         }
@@ -579,8 +623,19 @@ export const matchRoute = matchManifestRoute;
  * @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<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, load: string } }>}
  */
-export async function executeServerRoute(input) {
-  if (!input.source || !String(input.source).trim()) {
+export async function executeServerRoute({
+  source,
+  sourcePath,
+  params,
+  requestUrl,
+  requestMethod,
+  requestHeaders,
+  routePattern,
+  routeFile,
+  routeId,
+  guardOnly = false
+}) {
+  if (!source || !String(source).trim()) {
     return {
       result: { kind: 'data', data: {} },
       trace: { guard: 'none', load: 'none' }
@@ -588,15 +643,16 @@ export async function executeServerRoute(input) {
   }
 
   const payload = await spawnNodeServerRunner({
-    source: input.source,
-    sourcePath: input.sourcePath,
-    params: input.params,
-    requestUrl: input.requestUrl || 'http://localhost/',
-    requestMethod: input.requestMethod || 'GET',
-    requestHeaders: sanitizeRequestHeaders(input.requestHeaders || {}),
-    routePattern: input.routePattern || '',
-    routeFile: input.routeFile || input.sourcePath || '',
-    routeId: input.routeId || routeIdFromSourcePath(input.sourcePath || '')
+    source,
+    sourcePath,
+    params,
+    requestUrl: requestUrl || 'http://localhost/',
+    requestMethod: requestMethod || 'GET',
+    requestHeaders: sanitizeRequestHeaders(requestHeaders || {}),
+    routePattern: routePattern || '',
+    routeFile: routeFile || sourcePath || '',
+    routeId: routeId || routeIdFromSourcePath(sourcePath || ''),
+    guardOnly
   });
 
   if (payload === null || payload === undefined) {
@@ -702,6 +758,7 @@ function spawnNodeServerRunner(input) {
           ZENITH_SERVER_ROUTE_PATTERN: input.routePattern || '',
           ZENITH_SERVER_ROUTE_FILE: input.routeFile || input.sourcePath || '',
           ZENITH_SERVER_ROUTE_ID: input.routeId || '',
+          ZENITH_SERVER_GUARD_ONLY: input.guardOnly ? '1' : '',
           ZENITH_SERVER_CONTRACT_PATH: join(__dirname, 'server-contract.js')
         },
         stdio: ['ignore', 'pipe', 'pipe']

package/dist/server-contract.js

@@ -189,7 +189,7 @@ export function assertJsonSerializable(value, where = 'payload') {
     walk(value, '$');
 }
 
-export async function resolveRouteResult({ exports, ctx, filePath }) {
+export async function resolveRouteResult({ exports, ctx, filePath, guardOnly = false }) {
     validateServerExports({ exports, filePath });
 
     const trace = {
@@ -200,6 +200,9 @@ export async function resolveRouteResult({ exports, ctx, filePath }) {
     if ('guard' in exports) {
         const guardRaw = await exports.guard(ctx);
         const guardResult = guardRaw == null ? allow() : guardRaw;
+        if (guardResult.kind === 'data') {
+            throw new Error(`[Zenith] ${filePath}: guard(ctx) returned data(payload) which is a critical invariant violation. guard() can only return allow(), redirect(), or deny(). Use load(ctx) for data injection.`);
+        }
         assertValidRouteResultShape(
             guardResult,
             `${filePath}: guard(ctx) return`,
@@ -211,6 +214,10 @@ export async function resolveRouteResult({ exports, ctx, filePath }) {
         }
     }
 
+    if (guardOnly) {
+        return { result: allow(), trace };
+    }
+
     let payload;
     if ('load' in exports) {
         const loadRaw = await exports.load(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/cli",
-  "version": "0.5.0-beta.2.16",
+  "version": "0.5.0-beta.2.20",
   "description": "Deterministic project orchestrator for Zenith framework",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@zenithbuild/compiler": "0.5.0-beta.2.16"
+    "@zenithbuild/compiler": "0.5.0-beta.2.20"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",