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

package/README.md

@@ -5,6 +5,11 @@
 
 The command-line interface for developing and building Zenith applications.
 
+## Canonical Docs
+
+- CLI contract: `../zenith-docs/documentation/cli-contract.md`
+- Script server/data contract: `../zenith-docs/documentation/contracts/server-data.md`
+
 ## Overview
 
 `@zenithbuild/cli` provides the toolchain needed to manage Zenith projects. While `create-zenith` is for scaffolding, this CLI is for the daily development loop: serving apps, building for production, and managing plugins.

package/dist/build.js

@@ -68,6 +68,24 @@ const BUNDLER_BIN = resolveBinary([
     resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
 ]);
 
+/**
+ * Build a per-build warning emitter that deduplicates repeated compiler lines.
+ *
+ * @param {(line: string) => void} sink
+ * @returns {(line: string) => void}
+ */
+export function createCompilerWarningEmitter(sink = (line) => console.warn(line)) {
+    const emitted = new Set();
+    return (line) => {
+        const text = String(line || '').trim();
+        if (!text || emitted.has(text)) {
+            return;
+        }
+        emitted.add(text);
+        sink(text);
+    };
+}
+
 /**
  * Run the compiler process and parse its JSON stdout.
  *
@@ -77,9 +95,12 @@ const BUNDLER_BIN = resolveBinary([
  *
  * @param {string} filePath — path for diagnostics (and file reading when no stdinSource)
  * @param {string} [stdinSource] — if provided, piped to compiler via stdin
+ * @param {object} compilerRunOptions
+ * @param {(warning: string) => void} [compilerRunOptions.onWarning]
+ * @param {boolean} [compilerRunOptions.suppressWarnings]
  * @returns {object}
  */
-function runCompiler(filePath, stdinSource, compilerOpts = {}) {
+function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRunOptions = {}) {
     const args = stdinSource !== undefined
         ? ['--stdin', filePath]
         : [filePath];
@@ -102,6 +123,20 @@ function runCompiler(filePath, stdinSource, compilerOpts = {}) {
         );
     }
 
+    if (result.stderr && result.stderr.trim().length > 0 && compilerRunOptions.suppressWarnings !== true) {
+        const lines = String(result.stderr)
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const line of lines) {
+            if (typeof compilerRunOptions.onWarning === 'function') {
+                compilerRunOptions.onWarning(line);
+            } else {
+                console.warn(line);
+            }
+        }
+    }
+
     try {
         return JSON.parse(result.stdout);
     } catch (err) {
@@ -143,7 +178,7 @@ function buildComponentExpressionRewrite(compPath, componentSource, compIr, comp
 
     let templateIr;
     try {
-        templateIr = runCompiler(compPath, templateOnly, compilerOpts);
+        templateIr = runCompiler(compPath, templateOnly, compilerOpts, { suppressWarnings: true });
     } catch {
         return out;
     }
@@ -868,7 +903,7 @@ function transpileTypeScriptToJs(source, sourceFile) {
             fileName: sourceFile,
             compilerOptions: {
                 module: ts.ModuleKind.ESNext,
-                target: ts.ScriptTarget.ES2022,
+                target: ts.ScriptTarget.ES5,
                 importsNotUsedAsValues: ts.ImportsNotUsedAsValues.Preserve,
                 verbatimModuleSyntax: true,
                 newLine: ts.NewLineKind.LineFeed,
@@ -1103,7 +1138,7 @@ function injectPropsPrelude(source, attrs) {
     }
 
     const propsLiteral = renderPropsLiteralFromAttrs(attrs);
-    return `const props = ${propsLiteral};\n${source}`;
+    return `var props = ${propsLiteral};\n${source}`;
 }
 
 /**
@@ -1360,6 +1395,7 @@ export async function build(options) {
     const componentRefFallbackCache = new Map();
     /** @type {Map<string, { map: Map<string, string>, ambiguous: Set<string> }>} */
     const componentExpressionRewriteCache = new Map();
+    const emitCompilerWarning = createCompilerWarningEmitter((line) => console.warn(line));
 
     const envelopes = [];
     for (const entry of manifest) {
@@ -1375,7 +1411,12 @@ export async function build(options) {
         const compileSource = extractedServer.source;
 
         // 2b. Compile expanded page source via --stdin
-        const pageIr = runCompiler(sourceFile, compileSource, compilerOpts);
+        const pageIr = runCompiler(
+            sourceFile,
+            compileSource,
+            compilerOpts,
+            { onWarning: emitCompilerWarning }
+        );
         if (extractedServer.serverScript) {
             pageIr.server_script = extractedServer.serverScript;
             pageIr.prerender = extractedServer.serverScript.prerender === true;
@@ -1409,7 +1450,12 @@ export async function build(options) {
                 compIr = componentIrCache.get(compPath);
             } else {
                 const componentCompileSource = stripStyleBlocks(componentSource);
-                compIr = runCompiler(compPath, componentCompileSource, compilerOpts);
+                compIr = runCompiler(
+                    compPath,
+                    componentCompileSource,
+                    compilerOpts,
+                    { onWarning: emitCompilerWarning }
+                );
                 componentIrCache.set(compPath, compIr);
             }
 

package/dist/dev-server.js

@@ -17,7 +17,7 @@ import { readFile } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 import { build } from './build.js';
 import {
-    executeServerScript,
+    executeServerRoute,
     injectSsrPayload,
     loadRouteManifest,
     resolveWithinDist,
@@ -93,9 +93,42 @@ export async function createDevServer(options) {
             return;
         }
 
+        if (pathname === '/__zenith/route-check') {
+            try {
+                const targetPath = String(url.searchParams.get('path') || '/');
+                const targetUrl = new URL(targetPath, `http://localhost:${port}`);
+                const routes = await loadRouteManifest(outDir);
+                const resolvedCheck = resolveRequestRoute(targetUrl, routes);
+                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 || ''
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(checkResult));
+                return;
+            } catch {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'route_check_failed' }));
+                return;
+            }
+        }
+
         try {
             const requestExt = extname(pathname);
-            if (requestExt) {
+            if (requestExt && requestExt !== '.html') {
                 const assetPath = join(outDir, pathname);
                 const asset = await readFile(assetPath);
                 const mime = MIME_TYPES[requestExt] || 'application/octet-stream';
@@ -122,11 +155,11 @@ export async function createDevServer(options) {
                 throw new Error('not found');
             }
 
-            let content = await readFile(filePath, 'utf8');
+            let ssrPayload = null;
             if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
-                let payload = null;
+                let routeExecution = null;
                 try {
-                    payload = await executeServerScript({
+                    routeExecution = await executeServerRoute({
                         source: resolved.route.server_script,
                         sourcePath: resolved.route.server_script_path || '',
                         params: resolved.params,
@@ -134,22 +167,53 @@ export async function createDevServer(options) {
                         requestMethod: req.method || 'GET',
                         requestHeaders: req.headers,
                         routePattern: resolved.route.path,
-                        routeFile: resolved.route.server_script_path || ''
+                        routeFile: resolved.route.server_script_path || '',
+                        routeId: resolved.route.route_id || ''
                     });
                 } catch (error) {
-                    payload = {
-                        __zenith_error: {
+                    routeExecution = {
+                        result: {
+                            kind: 'deny',
                             status: 500,
-                            code: 'LOAD_FAILED',
                             message: error instanceof Error ? error.message : String(error)
+                        },
+                        trace: {
+                            guard: 'none',
+                            load: 'deny'
                         }
                     };
                 }
-                if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
-                    content = injectSsrPayload(content, payload);
+
+                const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
+                const routeId = resolved.route.route_id || '';
+                console.log(`[Zenith] guard(${routeId || resolved.route.path}) -> ${trace.guard}`);
+                console.log(`[Zenith] load(${routeId || resolved.route.path}) -> ${trace.load}`);
+
+                const result = routeExecution?.result;
+                if (result && result.kind === 'redirect') {
+                    const status = Number.isInteger(result.status) ? result.status : 302;
+                    res.writeHead(status, {
+                        Location: result.location,
+                        'Cache-Control': 'no-store'
+                    });
+                    res.end('');
+                    return;
+                }
+                if (result && result.kind === 'deny') {
+                    const status = Number.isInteger(result.status) ? result.status : 403;
+                    res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(result.message || (status === 401 ? 'Unauthorized' : 'Forbidden'));
+                    return;
+                }
+                if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+                    ssrPayload = result.data;
                 }
             }
 
+            let content = await readFile(filePath, 'utf8');
+            if (ssrPayload) {
+                content = injectSsrPayload(content, ssrPayload);
+            }
             content = content.replace('</body>', `${HMR_CLIENT_SCRIPT}</body>`);
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(content);

package/dist/preview.js

@@ -158,6 +158,55 @@ const safeRequestHeaders =
   requestHeaders && typeof requestHeaders === 'object'
     ? { ...requestHeaders }
     : {};
+function parseCookies(rawCookieHeader) {
+  const out = Object.create(null);
+  const raw = String(rawCookieHeader || '');
+  if (!raw) return out;
+  const pairs = raw.split(';');
+  for (let i = 0; i < pairs.length; i++) {
+    const part = pairs[i];
+    const eq = part.indexOf('=');
+    if (eq <= 0) continue;
+    const key = part.slice(0, eq).trim();
+    if (!key) continue;
+    const value = part.slice(eq + 1).trim();
+    try {
+      out[key] = decodeURIComponent(value);
+    } catch {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+const cookieHeader = typeof safeRequestHeaders.cookie === 'string'
+  ? safeRequestHeaders.cookie
+  : '';
+const requestCookies = parseCookies(cookieHeader);
+
+function ctxAllow() {
+  return { kind: 'allow' };
+}
+function ctxRedirect(location, status = 302) {
+  return {
+    kind: 'redirect',
+    location: String(location || ''),
+    status: Number.isInteger(status) ? status : 302
+  };
+}
+function ctxDeny(status = 403, message = undefined) {
+  return {
+    kind: 'deny',
+    status: Number.isInteger(status) ? status : 403,
+    message: typeof message === 'string' ? message : undefined
+  };
+}
+function ctxData(payload) {
+  return {
+    kind: 'data',
+    data: payload
+  };
+}
+
 const requestSnapshot = new Request(requestUrl, {
   method: requestMethod,
   headers: new Headers(safeRequestHeaders)
@@ -168,15 +217,32 @@ const routeMeta = {
   pattern: routePattern,
   file: routeFile ? path.relative(process.cwd(), routeFile) : ''
 };
+const routeContext = {
+  params: routeParams,
+  url: new URL(requestUrl),
+  headers: { ...safeRequestHeaders },
+  cookies: requestCookies,
+  request: requestSnapshot,
+  method: requestMethod,
+  route: routeMeta,
+  env: {},
+  auth: {
+    async getSession(_ctx) {
+      return null;
+    },
+    async requireSession(_ctx) {
+      throw ctxRedirect('/login', 302);
+    }
+  },
+  allow: ctxAllow,
+  redirect: ctxRedirect,
+  deny: ctxDeny,
+  data: ctxData
+};
 
 const context = vm.createContext({
   params: routeParams,
-  ctx: {
-    params: routeParams,
-    url: new URL(requestUrl),
-    request: requestSnapshot,
-    route: routeMeta
-  },
+  ctx: routeContext,
   fetch: globalThis.fetch,
   Headers: globalThis.Headers,
   Request: globalThis.Request,
@@ -251,11 +317,11 @@ async function linkModule(specifier, parentIdentifier) {
   return loadFileModule(resolvedUrl);
 }
 
-const allowed = new Set(['data', 'load', 'ssr_data', 'props', 'ssr', 'prerender']);
+const allowed = new Set(['data', 'load', 'guard', 'ssr_data', 'props', 'ssr', 'prerender']);
 const prelude = "const params = globalThis.params;\n" +
   "const ctx = globalThis.ctx;\n" +
-  "import { resolveServerPayload } from 'zenith:server-contract';\n" +
-  "globalThis.resolveServerPayload = resolveServerPayload;\n";
+  "import { resolveRouteResult } from 'zenith:server-contract';\n" +
+  "globalThis.resolveRouteResult = resolveRouteResult;\n";
 const entryIdentifier = sourcePath
   ? pathToFileURL(sourcePath).href
   : 'zenith:server-script';
@@ -294,13 +360,13 @@ for (const key of namespaceKeys) {
 
 const exported = entryModule.namespace;
 try {
-  const payload = await context.resolveServerPayload({
+  const resolved = await context.resolveRouteResult({
     exports: exported,
     ctx: context.ctx,
     filePath: sourcePath || 'server_script'
   });
 
-  process.stdout.write(JSON.stringify(payload === undefined ? null : payload));
+  process.stdout.write(JSON.stringify(resolved || null));
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
   process.stdout.write(
@@ -328,7 +394,34 @@ export async function createPreviewServer(options) {
     const url = new URL(req.url, `http://localhost:${port}`);
 
     try {
-      if (extname(url.pathname)) {
+      if (url.pathname === '/__zenith/route-check') {
+        const targetPath = String(url.searchParams.get('path') || '/');
+        const targetUrl = new URL(targetPath, `http://localhost:${port}`);
+        const routes = await loadRouteManifest(distDir);
+        const resolvedCheck = resolveRequestRoute(targetUrl, routes);
+        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 || '')
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(checkResult));
+        return;
+      }
+
+      if (extname(url.pathname) && extname(url.pathname) !== '.html') {
         const staticPath = resolveWithinDist(distDir, url.pathname);
         if (!staticPath || !(await fileExists(staticPath))) {
           throw new Error('not found');
@@ -358,11 +451,11 @@ export async function createPreviewServer(options) {
         throw new Error('not found');
       }
 
-      let html = await readFile(htmlPath, 'utf8');
+      let ssrPayload = null;
       if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
-        let payload = null;
+        let routeExecution = null;
         try {
-          payload = await executeServerScript({
+          routeExecution = await executeServerRoute({
             source: resolved.route.server_script,
             sourcePath: resolved.route.server_script_path || '',
             params: resolved.params,
@@ -371,22 +464,53 @@ export async function createPreviewServer(options) {
             requestHeaders: req.headers,
             routePattern: resolved.route.path,
             routeFile: resolved.route.server_script_path || '',
-            routeId: routeIdFromSourcePath(resolved.route.server_script_path || '')
+            routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
           });
         } catch (error) {
-          payload = {
-            __zenith_error: {
+          routeExecution = {
+            result: {
+              kind: 'deny',
               status: 500,
-              code: 'LOAD_FAILED',
               message: error instanceof Error ? error.message : String(error)
+            },
+            trace: {
+              guard: 'none',
+              load: 'deny'
             }
           };
         }
-        if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
-          html = injectSsrPayload(html, payload);
+
+        const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
+        const routeId = resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '');
+        console.log(`[Zenith] guard(${routeId}) -> ${trace.guard}`);
+        console.log(`[Zenith] load(${routeId}) -> ${trace.load}`);
+
+        const result = routeExecution?.result;
+        if (result && result.kind === 'redirect') {
+          const status = Number.isInteger(result.status) ? result.status : 302;
+          res.writeHead(status, {
+            Location: result.location,
+            'Cache-Control': 'no-store'
+          });
+          res.end('');
+          return;
+        }
+        if (result && result.kind === 'deny') {
+          const status = Number.isInteger(result.status) ? result.status : 403;
+          res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+          res.end(result.message || (status === 401 ? 'Unauthorized' : 'Forbidden'));
+          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 (ssrPayload) {
+        html = injectSsrPayload(html, ssrPayload);
+      }
+
       res.writeHead(200, { 'Content-Type': 'text/html' });
       res.end(html);
     } catch {
@@ -416,6 +540,13 @@ export async function createPreviewServer(options) {
  *   server_script?: string | null;
  *   server_script_path?: string | null;
  *   prerender?: boolean;
+ *   route_id?: string;
+ *   pattern?: string;
+ *   params_shape?: Record<string, string>;
+ *   has_guard?: boolean;
+ *   has_load?: boolean;
+ *   guard_module_ref?: string | null;
+ *   load_module_ref?: string | null;
  * }} PreviewRoute
  */
 
@@ -446,9 +577,16 @@ 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<Record<string, unknown> | null>}
+ * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, load: string } }>}
  */
-export async function executeServerScript(input) {
+export async function executeServerRoute(input) {
+  if (!input.source || !String(input.source).trim()) {
+    return {
+      result: { kind: 'data', data: {} },
+      trace: { guard: 'none', load: 'none' }
+    };
+  }
+
   const payload = await spawnNodeServerRunner({
     source: input.source,
     sourcePath: input.sourcePath,
@@ -462,12 +600,85 @@ export async function executeServerScript(input) {
   });
 
   if (payload === null || payload === undefined) {
-    return null;
+    return {
+      result: { kind: 'data', data: {} },
+      trace: { guard: 'none', load: 'none' }
+    };
   }
   if (typeof payload !== 'object' || Array.isArray(payload)) {
     throw new Error('[zenith-preview] server script payload must be an object');
   }
-  return payload;
+
+  const errorEnvelope = payload.__zenith_error;
+  if (errorEnvelope && typeof errorEnvelope === 'object') {
+    return {
+      result: {
+        kind: 'deny',
+        status: 500,
+        message: String(errorEnvelope.message || 'Server route execution failed')
+      },
+      trace: { guard: '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'),
+          load: String(trace.load || 'none')
+        }
+        : { guard: 'none', load: 'none' }
+    };
+  }
+
+  return {
+    result: {
+      kind: 'data',
+      data: payload
+    },
+    trace: { guard: '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') {
+    return {
+      __zenith_error: {
+        status: Number.isInteger(result.status) ? result.status : 403,
+        code: 'ACCESS_DENIED',
+        message: String(result.message || 'Access denied')
+      }
+    };
+  }
+
+  return {};
 }
 
 /**
@@ -609,7 +820,7 @@ export function resolveWithinDist(distDir, requestPath) {
  */
 function sanitizeRequestHeaders(headers) {
   const out = Object.create(null);
-  const denyExact = new Set(['authorization', 'cookie', 'proxy-authorization', 'set-cookie']);
+  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();

package/dist/server-contract.js

@@ -2,9 +2,73 @@
 // ---------------------------------------------------------------------------
 // Shared validation and payload resolution logic for <script server> blocks.
 
-const NEW_KEYS = new Set(['data', 'load', 'prerender']);
+const NEW_KEYS = new Set(['data', 'load', 'guard', 'prerender']);
 const LEGACY_KEYS = new Set(['ssr_data', 'props', 'ssr', 'prerender']);
-const ALLOWED_KEYS = new Set(['data', 'load', 'prerender', 'ssr_data', 'props', 'ssr']);
+const ALLOWED_KEYS = new Set(['data', 'load', 'guard', 'prerender', 'ssr_data', 'props', 'ssr']);
+
+const ROUTE_RESULT_KINDS = new Set(['allow', 'redirect', 'deny', 'data']);
+
+export function allow() {
+    return { kind: 'allow' };
+}
+
+export function redirect(location, status = 302) {
+    return {
+        kind: 'redirect',
+        location: String(location || ''),
+        status: Number.isInteger(status) ? status : 302
+    };
+}
+
+export function deny(status = 403, message = undefined) {
+    return {
+        kind: 'deny',
+        status: Number.isInteger(status) ? status : 403,
+        message: typeof message === 'string' ? message : undefined
+    };
+}
+
+export function data(payload) {
+    return { kind: 'data', data: payload };
+}
+
+function isRouteResultLike(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const kind = value.kind;
+    return typeof kind === 'string' && ROUTE_RESULT_KINDS.has(kind);
+}
+
+function assertValidRouteResultShape(value, where, allowedKinds) {
+    if (!isRouteResultLike(value)) {
+        throw new Error(`[Zenith] ${where}: invalid route result. Expected object with kind.`);
+    }
+    const kind = value.kind;
+    if (!allowedKinds.has(kind)) {
+        throw new Error(
+            `[Zenith] ${where}: kind "${kind}" is not allowed here (allowed: ${Array.from(allowedKinds).join(', ')}).`
+        );
+    }
+
+    if (kind === 'redirect') {
+        if (typeof value.location !== 'string' || value.location.length === 0) {
+            throw new Error(`[Zenith] ${where}: redirect requires non-empty string location.`);
+        }
+        if (value.status !== undefined && (!Number.isInteger(value.status) || value.status < 300 || value.status > 399)) {
+            throw new Error(`[Zenith] ${where}: redirect status must be an integer 3xx.`);
+        }
+    }
+
+    if (kind === 'deny') {
+        if (!Number.isInteger(value.status) || (value.status !== 401 && value.status !== 403)) {
+            throw new Error(`[Zenith] ${where}: deny status must be 401 or 403.`);
+        }
+        if (value.message !== undefined && typeof value.message !== 'string') {
+            throw new Error(`[Zenith] ${where}: deny message must be a string when provided.`);
+        }
+    }
+}
 
 export function validateServerExports({ exports, filePath }) {
     const exportKeys = Object.keys(exports);
@@ -16,6 +80,7 @@ export function validateServerExports({ exports, filePath }) {
 
     const hasData = 'data' in exports;
     const hasLoad = 'load' in exports;
+    const hasGuard = 'guard' in exports;
 
     const hasNew = hasData || hasLoad;
     const hasLegacy = ('ssr_data' in exports) || ('props' in exports) || ('ssr' in exports);
@@ -47,6 +112,20 @@ export function validateServerExports({ exports, filePath }) {
             throw new Error(`[Zenith] ${filePath}: "load(ctx)" must not contain rest parameters.`);
         }
     }
+
+    if (hasGuard && typeof exports.guard !== 'function') {
+        throw new Error(`[Zenith] ${filePath}: "guard" must be a function.`);
+    }
+    if (hasGuard) {
+        if (exports.guard.length !== 1) {
+            throw new Error(`[Zenith] ${filePath}: "guard(ctx)" must take exactly 1 argument.`);
+        }
+        const fnStr = exports.guard.toString();
+        const paramsMatch = fnStr.match(/^[^{=]+\(([^)]*)\)/);
+        if (paramsMatch && paramsMatch[1].includes('...')) {
+            throw new Error(`[Zenith] ${filePath}: "guard(ctx)" must not contain rest parameters.`);
+        }
+    }
 }
 
 export function assertJsonSerializable(value, where = 'payload') {
@@ -110,37 +189,90 @@ export function assertJsonSerializable(value, where = 'payload') {
     walk(value, '$');
 }
 
-export async function resolveServerPayload({ exports, ctx, filePath }) {
+export async function resolveRouteResult({ exports, ctx, filePath }) {
     validateServerExports({ exports, filePath });
 
+    const trace = {
+        guard: 'none',
+        load: 'none'
+    };
+
+    if ('guard' in exports) {
+        const guardRaw = await exports.guard(ctx);
+        const guardResult = guardRaw == null ? allow() : guardRaw;
+        assertValidRouteResultShape(
+            guardResult,
+            `${filePath}: guard(ctx) return`,
+            new Set(['allow', 'redirect', 'deny'])
+        );
+        trace.guard = guardResult.kind;
+        if (guardResult.kind === 'redirect' || guardResult.kind === 'deny') {
+            return { result: guardResult, trace };
+        }
+    }
+
     let payload;
     if ('load' in exports) {
-        payload = await exports.load(ctx);
-        assertJsonSerializable(payload, `${filePath}: load(ctx) return`);
-        return payload;
+        const loadRaw = await exports.load(ctx);
+        let loadResult = null;
+        if (isRouteResultLike(loadRaw)) {
+            loadResult = loadRaw;
+            assertValidRouteResultShape(
+                loadResult,
+                `${filePath}: load(ctx) return`,
+                new Set(['data', 'redirect', 'deny'])
+            );
+        } else {
+            assertJsonSerializable(loadRaw, `${filePath}: load(ctx) return`);
+            loadResult = data(loadRaw);
+        }
+        trace.load = loadResult.kind;
+        return { result: loadResult, trace };
     }
     if ('data' in exports) {
         payload = exports.data;
         assertJsonSerializable(payload, `${filePath}: data export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
 
     // legacy fallback
     if ('ssr_data' in exports) {
         payload = exports.ssr_data;
         assertJsonSerializable(payload, `${filePath}: ssr_data export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
     if ('props' in exports) {
         payload = exports.props;
         assertJsonSerializable(payload, `${filePath}: props export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
     if ('ssr' in exports) {
         payload = exports.ssr;
         assertJsonSerializable(payload, `${filePath}: ssr export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+
+    return { result: data({}), trace };
+}
+
+export async function resolveServerPayload({ exports, ctx, filePath }) {
+    const resolved = await resolveRouteResult({ exports, ctx, filePath });
+    if (!resolved || !resolved.result || typeof resolved.result !== 'object') {
+        return {};
+    }
+
+    if (resolved.result.kind === 'data') {
+        return resolved.result.data;
+    }
+    if (resolved.result.kind === 'allow') {
+        return {};
     }
 
-    return {};
+    throw new Error(
+        `[Zenith] ${filePath}: resolveServerPayload() expected data but received ${resolved.result.kind}. Use resolveRouteResult() for guard/load flows.`
+    );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/cli",
-  "version": "0.5.0-beta.2.12",
+  "version": "0.5.0-beta.2.16",
   "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.12"
+    "@zenithbuild/compiler": "0.5.0-beta.2.16"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",