@zenithbuild/cli 0.5.0-beta.2.5 → 0.6.0

package/dist/index.js

@@ -10,11 +10,62 @@
 // Minimal arg parsing. No heavy dependencies.
 // ---------------------------------------------------------------------------
 
-import { resolve, join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { createLogger } from './ui/logger.js';
 
 const COMMANDS = ['dev', 'build', 'preview'];
+const DEFAULT_VERSION = '0.0.0';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getCliVersion() {
+    try {
+        const pkgPath = join(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : DEFAULT_VERSION;
+    } catch {
+        return DEFAULT_VERSION;
+    }
+}
+
+function printUsage(logger) {
+    logger.heading('V0');
+    logger.print('Usage:');
+    logger.print('  zenith dev [port|--port <port>]      Start development server');
+    logger.print('  zenith build                         Build static site to /dist');
+    logger.print('  zenith preview [port|--port <port>]  Preview /dist statically');
+    logger.print('');
+    logger.print('Options:');
+    logger.print('  -h, --help        Show this help message');
+    logger.print('  -v, --version     Print Zenith CLI version');
+    logger.print('');
+}
+
+function resolvePort(args, fallback) {
+    if (!Array.isArray(args) || args.length === 0) {
+        return fallback;
+    }
+
+    const flagIndex = args.findIndex((arg) => arg === '--port' || arg === '-p');
+    if (flagIndex >= 0 && args[flagIndex + 1]) {
+        const parsed = Number.parseInt(args[flagIndex + 1], 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+
+    const positional = args.find((arg) => /^[0-9]+$/.test(arg));
+    if (positional) {
+        const parsed = Number.parseInt(positional, 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+
+    return fallback;
+}
 
 /**
  * Load zenith.config.js from project root.
@@ -41,14 +92,20 @@ async function loadConfig(projectRoot) {
 export async function cli(args, cwd) {
     const logger = createLogger(process);
     const command = args[0];
+    const cliVersion = getCliVersion();
+
+    if (args.includes('--version') || args.includes('-v')) {
+        logger.print(`zenith ${cliVersion}`);
+        process.exit(0);
+    }
+
+    if (args.includes('--help') || args.includes('-h')) {
+        printUsage(logger);
+        process.exit(0);
+    }
 
     if (!command || !COMMANDS.includes(command)) {
-        logger.heading('V0');
-        logger.print('Usage:');
-        logger.print('  zenith dev       Start development server');
-        logger.print('  zenith build     Build static site to /dist');
-        logger.print('  zenith preview   Preview /dist statically');
-        logger.print('');
+        printUsage(logger);
         process.exit(command ? 1 : 0);
     }
 
@@ -69,10 +126,13 @@ export async function cli(args, cwd) {
 
     if (command === 'dev') {
         const { createDevServer } = await import('./dev-server.js');
-        const port = parseInt(args[1]) || 3000;
+        const port = process.env.ZENITH_DEV_PORT
+            ? Number.parseInt(process.env.ZENITH_DEV_PORT, 10)
+            : resolvePort(args.slice(1), 3000);
+        const host = process.env.ZENITH_DEV_HOST || '127.0.0.1';
         logger.info('Starting dev server...');
-        const dev = await createDevServer({ pagesDir, outDir, port, config });
-        logger.success(`Dev server running at http://localhost:${dev.port}`);
+        const dev = await createDevServer({ pagesDir, outDir, port, host, config });
+        logger.success(`Dev server running at http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${dev.port}`);
 
         // Graceful shutdown
         process.on('SIGINT', () => {
@@ -87,10 +147,11 @@ export async function cli(args, cwd) {
 
     if (command === 'preview') {
         const { createPreviewServer } = await import('./preview.js');
-        const port = parseInt(args[1]) || 4000;
+        const port = resolvePort(args.slice(1), 4000);
+        const host = process.env.ZENITH_PREVIEW_HOST || '127.0.0.1';
         logger.info('Starting preview server...');
-        const preview = await createPreviewServer({ distDir: outDir, port });
-        logger.success(`Preview server running at http://localhost:${preview.port}`);
+        const preview = await createPreviewServer({ distDir: outDir, port, host });
+        logger.success(`Preview server running at http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${preview.port}`);
 
         process.on('SIGINT', () => {
             preview.close();

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');
@@ -158,6 +159,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 +218,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 +318,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 +361,14 @@ 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'
+    filePath: sourcePath || 'server_script',
+    guardOnly: guardOnly
   });
 
-  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(
@@ -318,17 +386,106 @@ try {
 /**
  * Create and start a preview server.
  *
- * @param {{ distDir: string, port?: number }} options
+ * @param {{ distDir: string, port?: number, host?: string }} options
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createPreviewServer(options) {
-  const { distDir, port = 4000 } = options;
+  const { distDir, port = 4000, host = '127.0.0.1' } = options;
+  let actualPort = port;
+
+  function publicHost() {
+    if (host === '0.0.0.0' || host === '::') {
+      return '127.0.0.1';
+    }
+    return host;
+  }
+
+  function serverOrigin() {
+    return `http://${publicHost()}:${actualPort}`;
+  }
 
   const server = createServer(async (req, res) => {
-    const url = new URL(req.url, `http://localhost:${port}`);
+    const requestBase = typeof req.headers.host === 'string' && req.headers.host.length > 0
+      ? `http://${req.headers.host}`
+      : serverOrigin();
+    const url = new URL(req.url, requestBase);
 
     try {
-      if (extname(url.pathname)) {
+      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, 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 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 || ''),
+          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.end(JSON.stringify({
+          result: checkResult?.result || checkResult,
+          routeId: resolvedCheck.route.route_id || '',
+          to: targetUrl.toString()
+        }));
+        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 +515,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 +528,48 @@ 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 = {
+          ssrPayload = {
             __zenith_error: {
-              status: 500,
               code: 'LOAD_FAILED',
               message: error instanceof Error ? error.message : String(error)
             }
           };
         }
-        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 {
@@ -396,8 +579,8 @@ export async function createPreviewServer(options) {
   });
 
   return new Promise((resolveServer) => {
-    server.listen(port, () => {
-      const actualPort = server.address().port;
+    server.listen(port, host, () => {
+      actualPort = server.address().port;
       resolveServer({
         server,
         port: actualPort,
@@ -416,6 +599,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,28 +636,120 @@ 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({
+  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' }
+    };
+  }
+
   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) {
-    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 {};
 }
 
 /**
@@ -491,6 +773,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']
@@ -609,7 +892,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();