@zenithbuild/cli 0.7.3 → 0.7.5

package/dist/server-runtime/route-render.js

@@ -1,9 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
+import { attachRouteAuth } from '../auth/route-auth.js';
 import { appLocalRedirectLocation, normalizeBasePath, prependBasePath } from '../base-path.js';
 import { createImageRuntimePayload, injectImageRuntimePayload } from '../images/payload.js';
 import { materializeImageMarkup } from '../images/materialize.js';
-import { allow, data, deny, redirect, resolveRouteResult } from '../server-contract.js';
+import { buildResourceResponseDescriptor } from '../resource-response.js';
+import { clientFacingRouteMessage, defaultRouteDenyMessage, logServerException } from '../server-error.js';
+import { allow, data, deny, download, invalid, json, redirect, resolveRouteResult, text } from '../server-contract.js';
 const MODULE_CACHE = new Map();
 const INTERNAL_QUERY_PREFIX = '__zenith_param_';
 function parseCookies(rawCookieHeader) {
@@ -40,24 +43,29 @@ function escapeInlineJson(payload) {
         .replace(/\u2028/g, '\\u2028')
         .replace(/\u2029/g, '\\u2029');
 }
-function defaultRouteDenyMessage(status) {
-    if (status === 401) {
-        return 'Unauthorized';
+function appendSetCookieHeaders(headers, setCookies = []) {
+    for (const value of Array.isArray(setCookies) ? setCookies : []) {
+        headers.append('Set-Cookie', value);
     }
-    if (status === 403) {
-        return 'Forbidden';
-    }
-    if (status === 404) {
-        return 'Not Found';
-    }
-    return 'Internal Server Error';
+    return headers;
 }
-function createTextResponse(status, message) {
+function createTextResponse(status, message, setCookies = []) {
+    const headers = new Headers({
+        'Content-Type': 'text/plain; charset=utf-8'
+    });
+    appendSetCookieHeaders(headers, setCookies);
     return new Response(message || defaultRouteDenyMessage(status), {
         status,
-        headers: {
-            'Content-Type': 'text/plain; charset=utf-8'
-        }
+        headers
+    });
+}
+function createResourceResponse(result, basePath, setCookies = []) {
+    const descriptor = buildResourceResponseDescriptor(result, basePath, setCookies);
+    const headers = new Headers(descriptor.headers);
+    appendSetCookieHeaders(headers, descriptor.setCookies);
+    return new Response(descriptor.body, {
+        status: descriptor.status,
+        headers
     });
 }
 function injectSsrPayload(html, payload) {
@@ -151,9 +159,9 @@ async function loadRouteExports(routeModulePath) {
     MODULE_CACHE.set(cacheKey, value);
     return value;
 }
-function createRouteContext({ request, route, params, publicUrl }) {
+function createRouteContext({ request, route, params, publicUrl, guardOnly = false }) {
     const requestHeaders = Object.fromEntries(request.headers.entries());
-    return {
+    const ctx = {
         params: { ...params },
         url: publicUrl,
         headers: { ...requestHeaders },
@@ -166,19 +174,23 @@ function createRouteContext({ request, route, params, publicUrl }) {
             file: route.file || route.server_script_path || route.route_id || route.path
         },
         env: {},
-        auth: {
-            async getSession() {
-                return null;
-            },
-            async requireSession() {
-                throw redirect('/login', 302);
-            }
-        },
+        action: null,
         allow,
         redirect,
         deny,
-        data
+        invalid,
+        data,
+        json,
+        text,
+        download
     };
+    attachRouteAuth(ctx, {
+        requestUrl: publicUrl,
+        guardOnly,
+        redirect,
+        deny
+    });
+    return ctx;
 }
 /**
  * @param {{
@@ -188,23 +200,26 @@ function createRouteContext({ request, route, params, publicUrl }) {
  *   routeModulePath: string,
  *   guardOnly?: boolean
  * }} options
- * @returns {Promise<{ publicUrl: URL, result: { kind: string, [key: string]: unknown }, trace: { guard: string, load: string } }>}
+ * @returns {Promise<{ publicUrl: URL, result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
  */
 export async function executeRouteRequest(options) {
     const { request, route, params, routeModulePath, guardOnly = false } = options;
     const publicUrl = buildPublicUrl(request.url, route, params);
-    const ctx = createRouteContext({ request, route, params, publicUrl });
+    const ctx = createRouteContext({ request, route, params, publicUrl, guardOnly });
     const exports = await loadRouteExports(routeModulePath);
     const resolved = await resolveRouteResult({
         exports,
         ctx,
         filePath: route.file || route.server_script_path || route.path,
-        guardOnly
+        guardOnly,
+        routeKind: route.route_kind === 'resource' ? 'resource' : 'page'
     });
     return {
         publicUrl,
         result: resolved.result,
-        trace: resolved.trace
+        trace: resolved.trace,
+        status: resolved.status,
+        setCookies: Array.isArray(resolved.setCookies) ? resolved.setCookies : []
     };
 }
 /**
@@ -214,33 +229,34 @@ export async function executeRouteRequest(options) {
  *   params: Record<string, string>,
  *   routeModulePath: string,
  *   shellHtmlPath: string,
- *   pageAssetPath?: string | null,
  *   imageManifestPath?: string | null,
  *   imageConfig?: Record<string, unknown>
  * }} options
  * @returns {Promise<Response>}
  */
 export async function renderRouteRequest(options) {
-    const { request, route, params, routeModulePath, shellHtmlPath, pageAssetPath = null, imageManifestPath = null, imageConfig = {} } = options;
+    const { request, route, params, routeModulePath, shellHtmlPath, imageManifestPath = null, imageConfig = {} } = options;
     try {
-        const { publicUrl, result } = await executeRouteRequest({
+        const { publicUrl, result, status, setCookies = [] } = await executeRouteRequest({
             request,
             route,
             params,
             routeModulePath
         });
         if (result.kind === 'redirect') {
+            const headers = new Headers({
+                Location: appLocalRedirectLocation(result.location, route.base_path || '/'),
+                'Cache-Control': 'no-store'
+            });
+            appendSetCookieHeaders(headers, setCookies);
             return new Response('', {
                 status: Number.isInteger(result.status) ? result.status : 302,
-                headers: {
-                    Location: appLocalRedirectLocation(result.location, route.base_path || '/'),
-                    'Cache-Control': 'no-store'
-                }
+                headers
             });
         }
         if (result.kind === 'deny') {
             const status = Number.isInteger(result.status) ? result.status : 403;
-            return createTextResponse(status, result.message || defaultRouteDenyMessage(status));
+            return createTextResponse(status, clientFacingRouteMessage(status, result.message), setCookies);
         }
         const ssrPayload = result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)
             ? result.data
@@ -248,26 +264,51 @@ export async function renderRouteRequest(options) {
         const localImages = await loadImageManifest(imageManifestPath);
         const imagePayload = createImageRuntimePayload(imageConfig, localImages, 'passthrough', route.base_path || '/');
         let html = await readFile(shellHtmlPath, 'utf8');
-        if (pageAssetPath) {
-            html = await materializeImageMarkup({
-                html,
-                pageAssetPath,
-                payload: imagePayload,
-                ssrData: ssrPayload,
-                routePathname: publicUrl.pathname
-            });
-        }
+        html = await materializeImageMarkup({
+            html,
+            payload: imagePayload,
+            imageMaterialization: Array.isArray(route.image_materialization)
+                ? route.image_materialization
+                : []
+        });
         html = injectSsrPayload(html, ssrPayload);
         html = injectImageRuntimePayload(html, imagePayload);
+        const headers = new Headers({
+            'Content-Type': 'text/html; charset=utf-8'
+        });
+        appendSetCookieHeaders(headers, setCookies);
         return new Response(html, {
-            status: 200,
-            headers: {
-                'Content-Type': 'text/html; charset=utf-8'
-            }
+            status: Number.isInteger(status) ? status : 200,
+            headers
+        });
+    }
+    catch (error) {
+        logServerException('node route render failed', error);
+        return createTextResponse(500, defaultRouteDenyMessage(500));
+    }
+}
+/**
+ * @param {{
+ *   request: Request,
+ *   route: { path: string, params?: string[], route_id?: string | null, server_script_path?: string | null, file?: string | null, route_kind?: string | null, base_path?: string | null },
+ *   params: Record<string, string>,
+ *   routeModulePath: string
+ * }} options
+ * @returns {Promise<Response>}
+ */
+export async function renderResourceRouteRequest(options) {
+    const { request, route, params, routeModulePath } = options;
+    try {
+        const { result, setCookies = [] } = await executeRouteRequest({
+            request,
+            route: { ...route, route_kind: 'resource' },
+            params,
+            routeModulePath
         });
+        return createResourceResponse(result, route.base_path || '/', setCookies);
     }
     catch (error) {
-        const message = String(error);
-        return createTextResponse(500, message || defaultRouteDenyMessage(500));
+        logServerException('node resource route render failed', error);
+        return createTextResponse(500, defaultRouteDenyMessage(500));
     }
 }

package/dist/server-script-composition.d.ts

@@ -1,39 +1,47 @@
 /**
  * @param {{
  *   sourceFile: string,
- *   inlineServerScript?: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null,
+ *   inlineServerScript?: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, has_action: boolean, source_path: string, export_paths?: string[] } | null,
  *   adjacentGuardPath?: string | null,
- *   adjacentLoadPath?: string | null
+ *   adjacentLoadPath?: string | null,
+ *   adjacentActionPath?: string | null
  * }} input
- * @returns {{ serverScript: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null, guardPath: string | null, loadPath: string | null }}
+ * @returns {{ serverScript: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, has_action: boolean, source_path: string, export_paths?: string[] } | null, guardPath: string | null, loadPath: string | null, actionPath: string | null }}
  */
-export function composeServerScriptEnvelope({ sourceFile, inlineServerScript, adjacentGuardPath, adjacentLoadPath }: {
+export function composeServerScriptEnvelope({ sourceFile, inlineServerScript, adjacentGuardPath, adjacentLoadPath, adjacentActionPath }: {
     sourceFile: string;
     inlineServerScript?: {
         source: string;
         prerender: boolean;
         has_guard: boolean;
         has_load: boolean;
+        has_action: boolean;
         source_path: string;
+        export_paths?: string[];
     } | null;
     adjacentGuardPath?: string | null;
     adjacentLoadPath?: string | null;
+    adjacentActionPath?: string | null;
 }): {
     serverScript: {
         source: string;
         prerender: boolean;
         has_guard: boolean;
         has_load: boolean;
+        has_action: boolean;
         source_path: string;
+        export_paths?: string[];
     } | null;
     guardPath: string | null;
     loadPath: string | null;
+    actionPath: string | null;
 };
 /**
  * @param {string} sourceFile
- * @returns {{ guardPath: string | null, loadPath: string | null }}
+ * @returns {{ guardPath: string | null, loadPath: string | null, actionPath: string | null }}
  */
 export function resolveAdjacentServerModules(sourceFile: string): {
     guardPath: string | null;
     loadPath: string | null;
+    actionPath: string | null;
 };

package/dist/server-script-composition.js

@@ -4,7 +4,7 @@ const DATA_EXPORT_RE = /\bexport\s+const\s+data\b/;
 const LEGACY_EXPORT_RE = /\bexport\s+const\s+(?:ssr_data|props|ssr)\b/;
 /**
  * @param {string} sourceFile
- * @param {'guard' | 'load'} kind
+ * @param {'guard' | 'load' | 'action'} kind
  * @returns {string[]}
  */
 function adjacentModuleCandidates(sourceFile, kind) {
@@ -22,7 +22,7 @@ function adjacentModuleCandidates(sourceFile, kind) {
 }
 /**
  * @param {string} sourceFile
- * @param {'guard' | 'load'} kind
+ * @param {'guard' | 'load' | 'action'} kind
  * @returns {string | null}
  */
 function resolveAdjacentModule(sourceFile, kind) {
@@ -65,16 +65,18 @@ function classifyInlineServerSource(source) {
 /**
  * @param {{
  *   sourceFile: string,
- *   inlineServerScript?: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null,
+ *   inlineServerScript?: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, has_action: boolean, source_path: string, export_paths?: string[] } | null,
  *   adjacentGuardPath?: string | null,
- *   adjacentLoadPath?: string | null
+ *   adjacentLoadPath?: string | null,
+ *   adjacentActionPath?: string | null
  * }} input
- * @returns {{ serverScript: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null, guardPath: string | null, loadPath: string | null }}
+ * @returns {{ serverScript: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, has_action: boolean, source_path: string, export_paths?: string[] } | null, guardPath: string | null, loadPath: string | null, actionPath: string | null }}
  */
-export function composeServerScriptEnvelope({ sourceFile, inlineServerScript = null, adjacentGuardPath = null, adjacentLoadPath = null }) {
+export function composeServerScriptEnvelope({ sourceFile, inlineServerScript = null, adjacentGuardPath = null, adjacentLoadPath = null, adjacentActionPath = null }) {
     const inlineSource = String(inlineServerScript?.source || '').trim();
     const inlineHasGuard = inlineServerScript?.has_guard === true;
     const inlineHasLoad = inlineServerScript?.has_load === true;
+    const inlineHasAction = inlineServerScript?.has_action === true;
     const { hasData, hasLegacy } = classifyInlineServerSource(inlineSource);
     if (inlineHasGuard && adjacentGuardPath) {
         throw new Error(`Zenith server script contract violation:\n` +
@@ -88,6 +90,12 @@ export function composeServerScriptEnvelope({ sourceFile, inlineServerScript = n
             `  Reason: load is defined both inline and in an adjacent module\n` +
             `  Example: keep load in either <script server> or ${basename(adjacentLoadPath)}, not both`);
     }
+    if (inlineHasAction && adjacentActionPath) {
+        throw new Error(`Zenith server script contract violation:\n` +
+            `  File: ${sourceFile}\n` +
+            `  Reason: action is defined both inline and in an adjacent module\n` +
+            `  Example: keep action in either <script server> or ${basename(adjacentActionPath)}, not both`);
+    }
     if (adjacentLoadPath && (hasData || hasLegacy)) {
         throw new Error(`Zenith server script contract violation:\n` +
             `  File: ${sourceFile}\n` +
@@ -101,12 +109,16 @@ export function composeServerScriptEnvelope({ sourceFile, inlineServerScript = n
     if (adjacentLoadPath) {
         prologue.push(`export { load } from '${renderRelativeSpecifier(sourceFile, adjacentLoadPath)}';`);
     }
+    if (adjacentActionPath) {
+        prologue.push(`export { action } from '${renderRelativeSpecifier(sourceFile, adjacentActionPath)}';`);
+    }
     const mergedSource = [...prologue, inlineSource].filter(Boolean).join('\n');
     if (!mergedSource.trim()) {
         return {
             serverScript: null,
             guardPath: adjacentGuardPath,
-            loadPath: adjacentLoadPath
+            loadPath: adjacentLoadPath,
+            actionPath: adjacentActionPath
         };
     }
     return {
@@ -115,19 +127,25 @@ export function composeServerScriptEnvelope({ sourceFile, inlineServerScript = n
             prerender: inlineServerScript?.prerender === true,
             has_guard: inlineHasGuard || Boolean(adjacentGuardPath),
             has_load: inlineHasLoad || Boolean(adjacentLoadPath),
-            source_path: sourceFile
+            has_action: inlineHasAction || Boolean(adjacentActionPath),
+            source_path: sourceFile,
+            export_paths: Array.isArray(inlineServerScript?.export_paths)
+                ? [...inlineServerScript.export_paths]
+                : []
         },
         guardPath: adjacentGuardPath,
-        loadPath: adjacentLoadPath
+        loadPath: adjacentLoadPath,
+        actionPath: adjacentActionPath
     };
 }
 /**
  * @param {string} sourceFile
- * @returns {{ guardPath: string | null, loadPath: string | null }}
+ * @returns {{ guardPath: string | null, loadPath: string | null, actionPath: string | null }}
  */
 export function resolveAdjacentServerModules(sourceFile) {
     return {
         guardPath: resolveAdjacentModule(sourceFile, 'guard'),
-        loadPath: resolveAdjacentModule(sourceFile, 'load')
+        loadPath: resolveAdjacentModule(sourceFile, 'load'),
+        actionPath: resolveAdjacentModule(sourceFile, 'action')
     };
 }

package/dist/static-export-paths.d.ts

@@ -0,0 +1,3 @@
+export function extractStaticExportPaths(source: any, sourceFile: any): string[] | null;
+export function validateStaticExportPaths(routePath: any, exportPaths: any, sourceFile: any): string[];
+export function toStaticHtmlFilePath(pathname: any): string;

package/dist/static-export-paths.js

@@ -0,0 +1,160 @@
+import { resolveRequestRoute } from './server/resolve-request-route.js';
+function skipWhitespace(source, start) {
+    let index = start;
+    while (index < source.length) {
+        const char = source[index];
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+        if (source.startsWith('//', index)) {
+            const nextLine = source.indexOf('\n', index + 2);
+            return nextLine === -1 ? source.length : skipWhitespace(source, nextLine + 1);
+        }
+        if (source.startsWith('/*', index)) {
+            const close = source.indexOf('*/', index + 2);
+            if (close === -1) {
+                throw new Error('[Zenith] Unterminated block comment in exportPaths literal.');
+            }
+            index = close + 2;
+            continue;
+        }
+        break;
+    }
+    return index;
+}
+function parseQuotedStringLiteral(source, start, sourceFile) {
+    const quote = source[start];
+    if (quote !== '"' && quote !== '\'') {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths must be a literal array of string paths.`);
+    }
+    let index = start + 1;
+    let value = '';
+    while (index < source.length) {
+        const char = source[index];
+        if (char === '\\') {
+            const next = source[index + 1];
+            if (next === undefined) {
+                throw new Error(`[Zenith] ${sourceFile}: exportPaths contains an invalid escape sequence.`);
+            }
+            value += char + next;
+            index += 2;
+            continue;
+        }
+        if (char === quote) {
+            try {
+                return {
+                    value: JSON.parse(`"${value.replace(/"/g, '\\"')}"`),
+                    nextIndex: index + 1
+                };
+            }
+            catch {
+                throw new Error(`[Zenith] ${sourceFile}: exportPaths contains an invalid string literal.`);
+            }
+        }
+        if (char === '\n' || char === '\r') {
+            throw new Error(`[Zenith] ${sourceFile}: exportPaths string literals must stay on one line.`);
+        }
+        value += char;
+        index += 1;
+    }
+    throw new Error(`[Zenith] ${sourceFile}: exportPaths contains an unterminated string literal.`);
+}
+function parseStringArrayLiteral(source, start, sourceFile) {
+    if (source[start] !== '[') {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths must be assigned a literal array of string paths.`);
+    }
+    const values = [];
+    let index = start + 1;
+    while (index < source.length) {
+        index = skipWhitespace(source, index);
+        if (source[index] === ']') {
+            return { values, nextIndex: index + 1 };
+        }
+        const parsed = parseQuotedStringLiteral(source, index, sourceFile);
+        values.push(parsed.value);
+        index = skipWhitespace(source, parsed.nextIndex);
+        if (source[index] === ',') {
+            index += 1;
+            continue;
+        }
+        if (source[index] === ']') {
+            return { values, nextIndex: index + 1 };
+        }
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths must be a comma-delimited literal array of string paths.`);
+    }
+    throw new Error(`[Zenith] ${sourceFile}: exportPaths array is missing a closing "]".`);
+}
+function normalizeConcretePath(value, sourceFile) {
+    if (typeof value !== 'string') {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must be strings.`);
+    }
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('/')) {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must start with "/".`);
+    }
+    if (trimmed.includes('://') || trimmed.startsWith('//')) {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must be same-origin pathnames.`);
+    }
+    if (trimmed.includes('?') || trimmed.includes('#') || /[\r\n]/.test(trimmed)) {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must be pathnames without query or hash.`);
+    }
+    const segments = trimmed
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    for (const segment of segments) {
+        if (segment === '.' || segment === '..') {
+            throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must not contain path traversal segments.`);
+        }
+        if (segment.startsWith(':') || segment.startsWith('*')) {
+            throw new Error(`[Zenith] ${sourceFile}: exportPaths entries must be concrete public URLs.`);
+        }
+    }
+    return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
+export function extractStaticExportPaths(source, sourceFile) {
+    const match = /\bexport\s+const\s+exportPaths\b/.exec(String(source || ''));
+    if (!match) {
+        return null;
+    }
+    const equalsIndex = String(source || '').indexOf('=', match.index + match[0].length);
+    if (equalsIndex === -1) {
+        throw new Error(`[Zenith] ${sourceFile}: exportPaths must use the form export const exportPaths = [...].`);
+    }
+    const valueStart = skipWhitespace(String(source || ''), equalsIndex + 1);
+    const { values } = parseStringArrayLiteral(String(source || ''), valueStart, sourceFile);
+    return values.map((value) => normalizeConcretePath(value, sourceFile));
+}
+export function validateStaticExportPaths(routePath, exportPaths, sourceFile) {
+    if (!Array.isArray(exportPaths)) {
+        return [];
+    }
+    const deduped = [];
+    const seen = new Set();
+    for (const rawPath of exportPaths) {
+        const concretePath = normalizeConcretePath(rawPath, sourceFile);
+        if (seen.has(concretePath)) {
+            throw new Error(`[Zenith] ${sourceFile}: exportPaths contains a duplicate path "${concretePath}".`);
+        }
+        seen.add(concretePath);
+        const resolved = resolveRequestRoute(new URL(concretePath, 'http://localhost'), [{ path: routePath }]);
+        if (!resolved.matched || resolved.route?.path !== routePath) {
+            throw new Error(`[Zenith] ${sourceFile}: exportPaths entry "${concretePath}" does not match route "${routePath}".`);
+        }
+        deduped.push(concretePath);
+    }
+    return deduped;
+}
+export function toStaticHtmlFilePath(pathname) {
+    const normalized = normalizeConcretePath(pathname, 'static-export');
+    if (normalized === '/') {
+        return 'index.html';
+    }
+    const relativePath = normalized.replace(/^\//, '');
+    if (/\.[a-zA-Z0-9]+$/.test(relativePath)) {
+        return relativePath;
+    }
+    return `${relativePath}/index.html`;
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@zenithbuild/cli",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Deterministic project orchestrator for Zenith framework",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
+  "bin": {
+    "zenith": "./dist/index.js"
+  },
   "exports": {
     ".": "./dist/index.js"
   },
@@ -35,8 +38,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@zenithbuild/compiler": "0.7.3",
-    "@zenithbuild/bundler": "0.7.3",
+    "@zenithbuild/compiler": "0.7.5",
+    "@zenithbuild/bundler": "0.7.5",
     "picocolors": "^1.1.1",
     "sharp": "^0.34.4"
   },