@zenithbuild/cli 0.7.1 → 0.7.3

package/dist/images/shared.js

@@ -1,3 +1,4 @@
+import { imageEndpointPath, normalizeBasePath, prependBasePath } from '../base-path.js';
 const DEFAULT_DEVICE_SIZES = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
 const DEFAULT_IMAGE_SIZES = [16, 32, 48, 64, 96, 128, 256, 384];
 const DEFAULT_FORMATS = ['webp', 'avif'];
@@ -253,11 +254,14 @@ export function buildLocalImageKey(publicPath) {
     }
     return (hash >>> 0).toString(16).padStart(8, '0');
 }
-export function buildLocalVariantPath(publicPath, width, quality, format) {
+export function buildLocalVariantAssetPath(publicPath, width, quality, format) {
     const key = buildLocalImageKey(publicPath);
     return `/_zenith/image/local/${key}/w${width}-q${quality}.${normalizeImageFormat(format)}`;
 }
-export function buildRemoteVariantPath(remoteUrl, width, quality, format) {
+export function buildLocalVariantPath(publicPath, width, quality, format, basePath = '/') {
+    return prependBasePath(basePath, buildLocalVariantAssetPath(publicPath, width, quality, format));
+}
+export function buildRemoteVariantPath(remoteUrl, width, quality, format, basePath = '/') {
     const query = new URLSearchParams();
     query.set('url', String(remoteUrl || ''));
     query.set('w', String(width));
@@ -265,7 +269,7 @@ export function buildRemoteVariantPath(remoteUrl, width, quality, format) {
     if (format) {
         query.set('f', normalizeImageFormat(format));
     }
-    return `/_zenith/image?${query.toString()}`;
+    return `${imageEndpointPath(basePath)}?${query.toString()}`;
 }
 export function resolveWidthCandidates(width, sizes, config, manifestEntry) {
     const base = new Set([
@@ -300,6 +304,7 @@ export function normalizeImageRuntimePayload(payload) {
     }
     return {
         mode: payload.mode === 'endpoint' ? 'endpoint' : 'passthrough',
+        basePath: normalizeBasePath(payload.basePath || '/'),
         config: normalizeImageConfig(payload.config || {}),
         localImages: isPlainObject(payload.localImages) ? payload.localImages : {}
     };

package/dist/index.js

@@ -4,16 +4,16 @@
 // ---------------------------------------------------------------------------
 // Commands:
 //   zenith dev      — Development server + HMR
-//   zenith build    — Static site generation to /dist
-//   zenith preview  — Serve /dist statically
+//   zenith build    — Static site generation to the configured output dir
+//   zenith preview  — Serve the configured output dir statically
 //
 // Minimal arg parsing. No heavy dependencies.
 // ---------------------------------------------------------------------------
-import { resolve, join, dirname } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { resolve, join, dirname, relative } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createZenithLogger } from './ui/logger.js';
-import { loadConfig } from './config.js';
+import { loadConfig, resolveConfigOutDir, resolveConfigPagesDir } from './config.js';
 const COMMANDS = ['dev', 'build', 'preview'];
 const DEFAULT_VERSION = '0.0.0';
 const __filename = fileURLToPath(import.meta.url);
@@ -32,14 +32,24 @@ 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('  zenith build                         Build static site to the configured output dir');
+    logger.print('  zenith preview [port|--port <port>]  Preview the configured output dir 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 formatOutputDir(projectRoot, outDir) {
+    const relativePath = relative(projectRoot, outDir);
+    if (!relativePath || relativePath.length === 0) {
+        return '.';
+    }
+    if (relativePath.startsWith('..')) {
+        return outDir;
+    }
+    return `./${relativePath}`;
+}
 function resolvePort(args, fallback) {
     if (!Array.isArray(args) || args.length === 0) {
         return fallback;
@@ -83,11 +93,9 @@ export async function cli(args, cwd) {
         process.exit(command ? 1 : 0);
     }
     const projectRoot = resolve(cwd || process.cwd());
-    const rootPagesDir = join(projectRoot, 'pages');
-    const srcPagesDir = join(projectRoot, 'src', 'pages');
-    const pagesDir = existsSync(rootPagesDir) ? rootPagesDir : srcPagesDir;
-    const outDir = join(projectRoot, 'dist');
     const config = await loadConfig(projectRoot);
+    const pagesDir = resolveConfigPagesDir(projectRoot, config);
+    const outDir = resolveConfigOutDir(projectRoot, config);
     if (command === 'build' || command === 'dev') {
         const { maybeWarnAboutZenithVersionMismatch } = await import('./version-check.js');
         await maybeWarnAboutZenithVersionMismatch({
@@ -101,7 +109,7 @@ export async function cli(args, cwd) {
         logger.build('Building…');
         const result = await build({ pagesDir, outDir, config, logger, showBundlerInfo: false });
         logger.ok(`Built ${result.pages} page(s), ${result.assets.length} asset(s)`);
-        logger.summary([{ label: 'Output', value: './dist' }], 'BUILD');
+        logger.summary([{ label: 'Output', value: formatOutputDir(projectRoot, outDir) }], 'BUILD');
     }
     if (command === 'dev') {
         const { createDevServer } = await import('./dev-server.js');
@@ -123,11 +131,24 @@ export async function cli(args, cwd) {
         });
     }
     if (command === 'preview') {
-        const { createPreviewServer } = await import('./preview.js');
         const port = resolvePort(args.slice(1), 4000);
         const host = process.env.ZENITH_PREVIEW_HOST || '127.0.0.1';
         logger.dev('Starting preview server…');
-        const preview = await createPreviewServer({ distDir: outDir, port, host, logger, config, projectRoot });
+        const preview = config.target === 'node'
+            ? await import(pathToFileURL(join(outDir, 'index.js')).href).then(async (mod) => {
+                if (typeof mod.createNodeServer !== 'function') {
+                    throw new Error('[Zenith:Preview] Node target output is missing createNodeServer()');
+                }
+                return mod.createNodeServer({ distDir: outDir, port, host });
+            })
+            : await import('./preview.js').then((mod) => mod.createPreviewServer({
+                distDir: outDir,
+                port,
+                host,
+                logger,
+                config,
+                projectRoot
+            }));
         logger.ok(`http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${preview.port}`);
         process.on('SIGINT', () => {
             preview.close();

package/dist/manifest.d.ts

@@ -1,14 +1,23 @@
 /**
- * @typedef {{ path: string, file: string }} ManifestEntry
+ * @typedef {{
+ *   path: string,
+ *   file: string,
+ *   path_kind: 'static' | 'dynamic',
+ *   render_mode: 'prerender' | 'server',
+ *   params: string[]
+ * }} ManifestEntry
  */
 /**
  * Scan a pages directory and produce a deterministic RouteManifest.
  *
  * @param {string} pagesDir - Absolute path to /pages directory
  * @param {string} [extension='.zen'] - File extension to scan for
+ * @param {{ compilerOpts?: object }} [options]
  * @returns {Promise<ManifestEntry[]>}
  */
-export function generateManifest(pagesDir: string, extension?: string): Promise<ManifestEntry[]>;
+export function generateManifest(pagesDir: string, extension?: string, options?: {
+    compilerOpts?: object;
+}): Promise<ManifestEntry[]>;
 /**
  * Generate a JavaScript module string from manifest entries.
  * Used for writing the manifest file to disk.
@@ -20,4 +29,7 @@ export function serializeManifest(entries: ManifestEntry[]): string;
 export type ManifestEntry = {
     path: string;
     file: string;
+    path_kind: "static" | "dynamic";
+    render_mode: "prerender" | "server";
+    params: string[];
 };

package/dist/manifest.js

@@ -14,20 +14,30 @@
 //   - Deterministic precedence: static > :param > *catchall
 //   - Tie-breaker: lexicographic route path
 // ---------------------------------------------------------------------------
+import { readFileSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative, sep, basename, extname, dirname } from 'node:path';
+import { extractServerScript } from './build/server-script.js';
+import { composeServerScriptEnvelope, resolveAdjacentServerModules } from './server-script-composition.js';
 /**
- * @typedef {{ path: string, file: string }} ManifestEntry
+ * @typedef {{
+ *   path: string,
+ *   file: string,
+ *   path_kind: 'static' | 'dynamic',
+ *   render_mode: 'prerender' | 'server',
+ *   params: string[]
+ * }} ManifestEntry
  */
 /**
  * Scan a pages directory and produce a deterministic RouteManifest.
  *
  * @param {string} pagesDir - Absolute path to /pages directory
  * @param {string} [extension='.zen'] - File extension to scan for
+ * @param {{ compilerOpts?: object }} [options]
  * @returns {Promise<ManifestEntry[]>}
  */
-export async function generateManifest(pagesDir, extension = '.zen') {
-    const entries = await _scanDir(pagesDir, pagesDir, extension);
+export async function generateManifest(pagesDir, extension = '.zen', options = {}) {
+    const entries = await _scanDir(pagesDir, pagesDir, extension, options.compilerOpts || {});
     // Validate: no repeated param names in any single route
     for (const entry of entries) {
         _validateParams(entry.path);
@@ -44,7 +54,7 @@ export async function generateManifest(pagesDir, extension = '.zen') {
  * @param {string} ext - Extension to match
  * @returns {Promise<ManifestEntry[]>}
  */
-async function _scanDir(dir, root, ext) {
+async function _scanDir(dir, root, ext, compilerOpts) {
     /** @type {ManifestEntry[]} */
     const entries = [];
     let items;
@@ -60,16 +70,49 @@ async function _scanDir(dir, root, ext) {
         const fullPath = join(dir, item);
         const info = await stat(fullPath);
         if (info.isDirectory()) {
-            const nested = await _scanDir(fullPath, root, ext);
+            const nested = await _scanDir(fullPath, root, ext, compilerOpts);
             entries.push(...nested);
         }
         else if (item.endsWith(ext)) {
             const routePath = _fileToRoute(fullPath, root, ext);
-            entries.push({ path: routePath, file: relative(root, fullPath) });
+            entries.push(buildManifestEntry({
+                fullPath,
+                root,
+                routePath,
+                compilerOpts
+            }));
         }
     }
     return entries;
 }
+function buildManifestEntry({ fullPath, root, routePath, compilerOpts }) {
+    const rawSource = readFileSync(fullPath, 'utf8');
+    const inlineServerScript = extractServerScript(rawSource, fullPath, compilerOpts).serverScript;
+    const { guardPath, loadPath } = resolveAdjacentServerModules(fullPath);
+    const composed = composeServerScriptEnvelope({
+        sourceFile: fullPath,
+        inlineServerScript,
+        adjacentGuardPath: guardPath,
+        adjacentLoadPath: loadPath
+    });
+    return {
+        path: routePath,
+        file: relative(root, fullPath),
+        path_kind: _isDynamic(routePath) ? 'dynamic' : 'static',
+        render_mode: composed.serverScript && composed.serverScript.prerender !== true ? 'server' : 'prerender',
+        params: extractRouteParams(routePath)
+    };
+}
+function extractRouteParams(routePath) {
+    return routePath
+        .split('/')
+        .filter(Boolean)
+        .filter((segment) => segment.startsWith(':') || segment.startsWith('*'))
+        .map((segment) => {
+        const raw = segment.slice(1);
+        return raw.endsWith('?') ? raw.slice(0, -1) : raw;
+    });
+}
 /**
  * Convert a file path to a route path.
  *

package/dist/preview.js

@@ -13,7 +13,8 @@ import { createServer } from 'node:http';
 import { access, readFile } from 'node:fs/promises';
 import { extname, join, normalize, resolve, sep, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadConfig } from './config.js';
+import { appLocalRedirectLocation, imageEndpointPath, normalizeBasePath, routeCheckPath, stripBasePath } from './base-path.js';
+import { isConfigKeyExplicit, loadConfig, validateConfig } from './config.js';
 import { materializeImageMarkup } from './images/materialize.js';
 import { createImageRuntimePayload, injectImageRuntimePayload } from './images/payload.js';
 import { handleImageRequest } from './images/service.js';
@@ -391,14 +392,25 @@ try {
  */
 export async function createPreviewServer(options) {
     const resolvedProjectRoot = options?.projectRoot ? resolve(options.projectRoot) : resolve(options.distDir, '..');
+    const loadedConfig = await loadConfig(resolvedProjectRoot);
     const resolvedConfig = options?.config && typeof options.config === 'object'
-        ? options.config
-        : await loadConfig(resolvedProjectRoot);
+        ? (() => {
+            const overrideConfig = validateConfig(options.config);
+            const mergedConfig = { ...loadedConfig };
+            for (const key of Object.keys(overrideConfig)) {
+                if (isConfigKeyExplicit(overrideConfig, key)) {
+                    mergedConfig[key] = overrideConfig[key];
+                }
+            }
+            return mergedConfig;
+        })()
+        : loadedConfig;
     const { distDir, port = 4000, host = '127.0.0.1', logger: providedLogger = null } = options;
     const projectRoot = resolvedProjectRoot;
     const config = resolvedConfig;
     const logger = providedLogger || createSilentLogger();
     const verboseLogging = logger.mode?.logLevel === 'verbose';
+    const configuredBasePath = normalizeBasePath(config.basePath || '/');
     let actualPort = port;
     async function loadImageManifest() {
         try {
@@ -424,8 +436,10 @@ export async function createPreviewServer(options) {
             ? `http://${req.headers.host}`
             : serverOrigin();
         const url = new URL(req.url, requestBase);
+        const { basePath, routes } = await loadRouteManifestState(distDir, configuredBasePath);
+        const canonicalPath = stripBasePath(url.pathname, basePath);
         try {
-            if (url.pathname === '/__zenith/route-check') {
+            if (url.pathname === routeCheckPath(basePath)) {
                 // 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' });
@@ -445,8 +459,15 @@ export async function createPreviewServer(options) {
                     res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
                     return;
                 }
-                const routes = await loadRouteManifest(distDir);
-                const resolvedCheck = resolveRequestRoute(targetUrl, routes);
+                const canonicalTargetPath = stripBasePath(targetUrl.pathname, basePath);
+                if (canonicalTargetPath === null) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'route_not_found' }));
+                    return;
+                }
+                const canonicalTargetUrl = new URL(targetUrl.toString());
+                canonicalTargetUrl.pathname = canonicalTargetPath;
+                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, routes);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
                     res.writeHead(404, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'route_not_found' }));
@@ -466,16 +487,17 @@ export async function createPreviewServer(options) {
                 });
                 // Security: Enforce relative or same-origin redirects
                 if (checkResult && checkResult.result && checkResult.result.kind === 'redirect') {
-                    const loc = String(checkResult.result.location || '/');
+                    const loc = appLocalRedirectLocation(checkResult.result.location || '/', basePath);
+                    checkResult.result.location = loc;
                     if (loc.includes('://') || loc.startsWith('//')) {
                         try {
                             const parsedLoc = new URL(loc);
                             if (parsedLoc.origin !== targetUrl.origin) {
-                                checkResult.result.location = '/'; // Fallback to root for open redirect attempt
+                                checkResult.result.location = appLocalRedirectLocation('/', basePath);
                             }
                         }
                         catch {
-                            checkResult.result.location = '/';
+                            checkResult.result.location = appLocalRedirectLocation('/', basePath);
                         }
                     }
                 }
@@ -493,7 +515,7 @@ export async function createPreviewServer(options) {
                 }));
                 return;
             }
-            if (url.pathname === '/_zenith/image') {
+            if (url.pathname === imageEndpointPath(basePath)) {
                 await handleImageRequest(req, res, {
                     requestUrl: url,
                     projectRoot,
@@ -501,8 +523,11 @@ export async function createPreviewServer(options) {
                 });
                 return;
             }
-            if (extname(url.pathname) && extname(url.pathname) !== '.html') {
-                const staticPath = resolveWithinDist(distDir, url.pathname);
+            if (canonicalPath === null) {
+                throw new Error('not found');
+            }
+            if (extname(canonicalPath) && extname(canonicalPath) !== '.html') {
+                const staticPath = resolveWithinDist(distDir, canonicalPath);
                 if (!staticPath || !(await fileExists(staticPath))) {
                     throw new Error('not found');
                 }
@@ -512,8 +537,9 @@ export async function createPreviewServer(options) {
                 res.end(content);
                 return;
             }
-            const routes = await loadRouteManifest(distDir);
-            const resolved = resolveRequestRoute(url, routes);
+            const canonicalUrl = new URL(url.toString());
+            canonicalUrl.pathname = canonicalPath;
+            const resolved = resolveRequestRoute(canonicalUrl, routes);
             let htmlPath = null;
             if (resolved.matched && resolved.route) {
                 if (verboseLogging) {
@@ -563,7 +589,7 @@ export async function createPreviewServer(options) {
                 if (result && result.kind === 'redirect') {
                     const status = Number.isInteger(result.status) ? result.status : 302;
                     res.writeHead(status, {
-                        Location: result.location,
+                        Location: appLocalRedirectLocation(result.location, basePath),
                         'Cache-Control': 'no-store'
                     });
                     res.end('');
@@ -585,15 +611,15 @@ export async function createPreviewServer(options) {
                 html = await materializeImageMarkup({
                     html,
                     pageAssetPath,
-                    payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint'),
+                    payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath),
                     ssrData: ssrPayload,
-                    routePathname: resolved.route.path || url.pathname
+                    routePathname: url.pathname
                 });
             }
             if (ssrPayload) {
                 html = injectSsrPayload(html, ssrPayload);
             }
-            html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint'));
+            html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath));
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(html);
         }
@@ -636,20 +662,30 @@ export async function createPreviewServer(options) {
  * @returns {Promise<PreviewRoute[]>}
  */
 export async function loadRouteManifest(distDir) {
+    const state = await loadRouteManifestState(distDir, '/');
+    return state.routes;
+}
+async function loadRouteManifestState(distDir, fallbackBasePath = '/') {
     const manifestPath = join(distDir, 'assets', 'router-manifest.json');
     try {
         const source = await readFile(manifestPath, 'utf8');
         const parsed = JSON.parse(source);
         const routes = Array.isArray(parsed?.routes) ? parsed.routes : [];
-        return routes
-            .filter((entry) => entry &&
-            typeof entry === 'object' &&
-            typeof entry.path === 'string' &&
-            typeof entry.output === 'string')
-            .sort((a, b) => compareRouteSpecificity(a.path, b.path));
+        return {
+            basePath: normalizeBasePath(parsed?.base_path || fallbackBasePath || '/'),
+            routes: routes
+                .filter((entry) => entry &&
+                typeof entry === 'object' &&
+                typeof entry.path === 'string' &&
+                typeof entry.output === 'string')
+                .sort((a, b) => compareRouteSpecificity(a.path, b.path))
+        };
     }
     catch {
-        return [];
+        return {
+            basePath: normalizeBasePath(fallbackBasePath || '/'),
+            routes: []
+        };
     }
 }
 export const matchRoute = matchManifestRoute;

package/dist/server-output.d.ts

@@ -0,0 +1,26 @@
+export function writeServerOutput({ coreOutputDir, staticDir, projectRoot, config, basePath }: {
+    coreOutputDir: any;
+    staticDir: any;
+    projectRoot: any;
+    config: any;
+    basePath?: string | undefined;
+}): Promise<{
+    serverDir: string;
+    routes: {
+        name: any;
+        path: any;
+        output: any;
+        base_path: string;
+        page_asset: any;
+        page_asset_file: string | null;
+        route_id: any;
+        server_script_path: any;
+        guard_module_ref: any;
+        load_module_ref: any;
+        has_guard: boolean;
+        has_load: boolean;
+        params: string[];
+        image_manifest_file: string | null;
+        image_config: any;
+    }[];
+}>;