@zenithbuild/cli 0.6.17 → 0.7.1

package/dist/dev-server.js

@@ -13,11 +13,16 @@
 import { createServer } from 'node:http';
 import { existsSync, watch } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
-import { build } from './build.js';
+import { createDevBuildSession } from './dev-build-session.js';
+import { createStartupProfiler } from './startup-profile.js';
 import { createSilentLogger } from './ui/logger.js';
 import { readChangeFingerprint } from './dev-watch.js';
-import { executeServerRoute, injectSsrPayload, loadRouteManifest, resolveWithinDist, toStaticFilePath } from './preview.js';
+import { defaultRouteDenyMessage, executeServerRoute, injectSsrPayload, loadRouteManifest, resolveWithinDist, toStaticFilePath } from './preview.js';
+import { materializeImageMarkup } from './images/materialize.js';
+import { injectImageRuntimePayload } from './images/payload.js';
+import { handleImageRequest } from './images/service.js';
 import { resolveRequestRoute } from './server/resolve-request-route.js';
 const MIME_TYPES = {
     '.html': 'text/html',
@@ -25,8 +30,12 @@ const MIME_TYPES = {
     '.css': 'text/css',
     '.json': 'application/json',
     '.png': 'image/png',
+    '.jpeg': 'image/jpeg',
     '.jpg': 'image/jpeg',
-    '.svg': 'image/svg+xml'
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.gif': 'image/gif'
 };
 // Note: V0 HMR script injection has been moved to the runtime client.
 // This server purely hosts the V1 HMR contract endpoints.
@@ -37,8 +46,10 @@ const MIME_TYPES = {
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createDevServer(options) {
+    const startupProfile = createStartupProfiler('cli-dev-server');
     const { pagesDir, outDir, port = 3000, host = '127.0.0.1', config = {}, logger: providedLogger = null } = options;
     const logger = providedLogger || createSilentLogger();
+    const buildSession = createDevBuildSession({ pagesDir, outDir, config, logger });
     const resolvedPagesDir = resolve(pagesDir);
     const resolvedOutDir = resolve(outDir);
     const resolvedOutDirTmp = resolve(dirname(resolvedOutDir), `${basename(resolvedOutDir)}.tmp`);
@@ -63,10 +74,11 @@ export async function createDevServer(options) {
     }, 15000);
     let buildId = 0;
     let pendingBuildId = 0;
-    let buildStatus = 'ok'; // 'ok' | 'error' | 'building'
+    let buildStatus = 'building'; // 'ok' | 'error' | 'building'
     let lastBuildMs = Date.now();
     let durationMs = 0;
     let buildError = null;
+    let initialBuildSettled = false;
     const traceEnabled = config.devTrace === true || process.env.ZENITH_DEV_TRACE === '1';
     const verboseLogging = traceEnabled || logger.mode?.logLevel === 'verbose';
     // Stable dev CSS endpoint points to this backing asset.
@@ -74,6 +86,9 @@ export async function createDevServer(options) {
     let currentCssHref = '';
     let currentCssContent = '';
     let actualPort = port;
+    let currentRoutes = [];
+    const rebuildDebounceMs = 5;
+    const queuedRebuildDebounceMs = 5;
     function _publicHost() {
         if (host === '0.0.0.0' || host === '::') {
             return '127.0.0.1';
@@ -164,6 +179,34 @@ export async function createDevServer(options) {
         }
         return secFetchDest === 'empty';
     }
+    function _isBuildSwapReadError(error) {
+        const code = typeof error?.code === 'string' ? error.code : '';
+        return code === 'ENOENT' || code === 'ENOTDIR';
+    }
+    function _delay(ms) {
+        return new Promise((resolveDelay) => {
+            setTimeout(resolveDelay, ms);
+        });
+    }
+    async function _readFileForRequest(filePath, encoding = undefined) {
+        const attempts = buildStatus === 'building' ? 200 : 1;
+        let lastError = null;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            try {
+                return encoding === undefined
+                    ? await readFile(filePath)
+                    : await readFile(filePath, encoding);
+            }
+            catch (error) {
+                lastError = error;
+                if (!_isBuildSwapReadError(error) || attempt === attempts - 1) {
+                    throw error;
+                }
+                await _delay(50);
+            }
+        }
+        throw lastError;
+    }
     function _buildNotFoundPayload(pathname, category, cause) {
         const payload = {
             kind: 'zenith_dev_not_found',
@@ -231,6 +274,10 @@ export async function createDevServer(options) {
         if (cssAssets.length === 0) {
             return '';
         }
+        const devStable = cssAssets.find((entry) => entry.endsWith('/styles.dev.css'));
+        if (devStable) {
+            return devStable;
+        }
         const preferred = cssAssets.find((entry) => /\/styles(\.|\/|$)/.test(entry));
         return preferred || cssAssets[0];
     }
@@ -307,6 +354,24 @@ export async function createDevServer(options) {
         currentCssContent = cssContent;
         return true;
     }
+    async function _loadRoutesForRequests() {
+        if (buildStatus === 'building' && Array.isArray(currentRoutes) && currentRoutes.length > 0) {
+            return currentRoutes;
+        }
+        try {
+            const routes = await loadRouteManifest(outDir);
+            if (Array.isArray(routes) && routes.length > 0) {
+                currentRoutes = routes;
+                return routes;
+            }
+        }
+        catch (error) {
+            if (!(Array.isArray(currentRoutes) && currentRoutes.length > 0)) {
+                throw error;
+            }
+        }
+        return currentRoutes;
+    }
     function _broadcastEvent(type, payload = {}) {
         const eventBuildId = Number.isInteger(payload.buildId) ? payload.buildId : buildId;
         const data = JSON.stringify({
@@ -329,22 +394,62 @@ export async function createDevServer(options) {
             }
         }
     }
-    // Initial build
-    try {
-        logger.build('Initial build (id=0)', { onceKey: 'dev-initial-build' });
-        const initialBuild = await build({ pagesDir, outDir, config, logger });
-        await _syncCssStateFromBuild(initialBuild, buildId);
-        if (currentCssHref.length > 0) {
-            logger.css(`ready (${currentCssHref})`, { onceKey: `css-ready:${buildId}:${currentCssHref}` });
+    async function _runInitialBuild() {
+        buildStatus = 'building';
+        buildError = null;
+        const startTime = Date.now();
+        startupProfile.emit('initial_build_start', { buildId });
+        try {
+            logger.build('Initial build (id=0)', { onceKey: 'dev-initial-build' });
+            const initialBuild = await buildSession.build();
+            const cssReady = await _syncCssStateFromBuild(initialBuild, buildId);
+            currentRoutes = await loadRouteManifest(outDir);
+            buildStatus = 'ok';
+            buildError = null;
+            lastBuildMs = Date.now();
+            durationMs = lastBuildMs - startTime;
+            if (cssReady && currentCssHref.length > 0) {
+                logger.css(`ready (${currentCssHref})`, { onceKey: `css-ready:${buildId}:${currentCssHref}` });
+            }
+            _trace('state_snapshot', {
+                status: buildStatus,
+                buildId,
+                cssHref: currentCssHref,
+                durationMs
+            });
+            startupProfile.emit('initial_build_complete', {
+                buildId,
+                status: buildStatus,
+                durationMs,
+                cssReady,
+                routes: Array.isArray(currentRoutes) ? currentRoutes.length : 0
+            });
+        }
+        catch (err) {
+            buildStatus = 'error';
+            buildError = { message: err instanceof Error ? err.message : String(err) };
+            lastBuildMs = Date.now();
+            durationMs = lastBuildMs - startTime;
+            logger.error('initial build failed', {
+                hint: 'fix the error and restart dev',
+                error: err
+            });
+            _trace('state_snapshot', {
+                status: buildStatus,
+                buildId,
+                durationMs,
+                error: buildError
+            });
+            startupProfile.emit('initial_build_complete', {
+                buildId,
+                status: buildStatus,
+                durationMs,
+                error: buildError?.message || ''
+            });
+        }
+        finally {
+            initialBuildSettled = true;
         }
-    }
-    catch (err) {
-        buildStatus = 'error';
-        buildError = { message: err instanceof Error ? err.message : String(err) };
-        logger.error('initial build failed', {
-            hint: 'fix the error and restart dev',
-            error: err
-        });
     }
     const server = createServer(async (req, res) => {
         const requestBase = typeof req.headers.host === 'string' && req.headers.host.length > 0
@@ -460,8 +565,24 @@ export async function createDevServer(options) {
             res.end(currentCssContent);
             return;
         }
+        if (pathname === '/_zenith/image') {
+            await handleImageRequest(req, res, {
+                requestUrl: url,
+                projectRoot,
+                config: config.images
+            });
+            return;
+        }
         if (pathname === '/__zenith/route-check') {
             try {
+                if (!initialBuildSettled && buildStatus === 'building') {
+                    res.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                    res.end(JSON.stringify({
+                        error: 'initial_build_pending',
+                        message: 'initial build still in progress'
+                    }));
+                    return;
+                }
                 // 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' });
@@ -481,7 +602,7 @@ export async function createDevServer(options) {
                     res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
                     return;
                 }
-                const routes = await loadRouteManifest(outDir);
+                const routes = await _loadRoutesForRequests();
                 const resolvedCheck = resolveRequestRoute(targetUrl, routes);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
                     res.writeHead(404, { 'Content-Type': 'application/json' });
@@ -538,18 +659,48 @@ export async function createDevServer(options) {
         let resolvedPathFor404 = null;
         let staticRootFor404 = null;
         try {
+            if (!initialBuildSettled && buildStatus === 'building') {
+                const pendingPayload = {
+                    kind: 'zenith_dev_build_pending',
+                    requestedPath: pathname,
+                    buildId,
+                    buildStatus,
+                    hint: 'Initial build is still running. Retry shortly or inspect /__zenith_dev/state.'
+                };
+                if (_looksLikeJsonRequest(req, pathname)) {
+                    res.writeHead(503, {
+                        'Content-Type': 'application/json',
+                        'Cache-Control': 'no-store'
+                    });
+                    res.end(JSON.stringify(pendingPayload));
+                    return;
+                }
+                res.writeHead(503, {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    'Cache-Control': 'no-store'
+                });
+                res.end([
+                    '<!DOCTYPE html>',
+                    '<html><head><meta charset="utf-8"><title>Zenith Dev Building</title></head>',
+                    '<body style="font-family: ui-monospace, SFMono-Regular, Menlo, monospace; padding: 20px; background: #101216; color: #e6edf3;">',
+                    '<h1 style="margin-top:0;">Zenith Dev Building</h1>',
+                    `<pre style="white-space: pre-wrap; line-height: 1.5;">Requested: ${pathname}\nStatus: initial build running\nHint: ${pendingPayload.hint}</pre>`,
+                    '</body></html>'
+                ].join(''));
+                return;
+            }
             const requestExt = extname(pathname);
             if (requestExt && requestExt !== '.html') {
                 const assetPath = join(outDir, pathname);
                 resolvedPathFor404 = assetPath;
                 staticRootFor404 = outDir;
-                const asset = await readFile(assetPath);
+                const asset = await _readFileForRequest(assetPath);
                 const mime = MIME_TYPES[requestExt] || 'application/octet-stream';
                 res.writeHead(200, { 'Content-Type': mime });
                 res.end(asset);
                 return;
             }
-            const routes = await loadRouteManifest(outDir);
+            const routes = await _loadRoutesForRequests();
             const resolved = resolveRequestRoute(url, routes);
             let filePath = null;
             if (resolved.matched && resolved.route) {
@@ -611,17 +762,28 @@ export async function createDevServer(options) {
                 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'));
+                    res.end(result.message || defaultRouteDenyMessage(status));
                     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');
+            let content = await _readFileForRequest(filePath, 'utf8');
+            if (resolved.matched && resolved.route?.page_asset) {
+                const pageAssetPath = resolveWithinDist(outDir, resolved.route.page_asset);
+                content = await materializeImageMarkup({
+                    html: content,
+                    pageAssetPath,
+                    payload: buildSession.getImageRuntimePayload(),
+                    ssrData: ssrPayload,
+                    routePathname: resolved.route.path || pathname
+                });
+            }
             if (ssrPayload) {
                 content = injectSsrPayload(content, ssrPayload);
             }
+            content = injectImageRuntimePayload(content, buildSession.getImageRuntimePayload());
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(content);
         }
@@ -711,7 +873,8 @@ export async function createDevServer(options) {
      * Start watching source roots for changes.
      */
     function _startWatcher() {
-        const triggerBuildDrain = (delayMs = 50) => {
+        const watcherStartedAt = performance.now();
+        const triggerBuildDrain = (delayMs = rebuildDebounceMs) => {
             if (_buildDebounce !== null) {
                 clearTimeout(_buildDebounce);
             }
@@ -724,7 +887,8 @@ export async function createDevServer(options) {
             if (_buildInFlight) {
                 return;
             }
-            const changed = Array.from(_queuedFiles).map(_toDisplayPath).sort();
+            const changedFiles = Array.from(_queuedFiles);
+            const changed = changedFiles.map(_toDisplayPath).sort();
             if (changed.length === 0) {
                 return;
             }
@@ -738,9 +902,13 @@ export async function createDevServer(options) {
             const startTime = Date.now();
             const previousCssAssetPath = currentCssAssetPath;
             const previousCssContent = currentCssContent;
+            const onlyCss = changed.length > 0 && changed.every((f) => f.endsWith('.css'));
             try {
-                const buildResult = await build({ pagesDir, outDir, config, logger });
+                const buildResult = await buildSession.build({ changedFiles, logger });
                 const cssReady = await _syncCssStateFromBuild(buildResult, cycleBuildId);
+                if (!onlyCss) {
+                    currentRoutes = await loadRouteManifest(outDir);
+                }
                 const cssChanged = cssReady && (currentCssAssetPath !== previousCssAssetPath ||
                     currentCssContent !== previousCssContent);
                 buildId = cycleBuildId;
@@ -768,7 +936,6 @@ export async function createDevServer(options) {
                     logger.hmr(`css_update (buildId=${cycleBuildId})`);
                     _broadcastEvent('css_update', { href: currentCssHref, changedFiles: changed });
                 }
-                const onlyCss = changed.length > 0 && changed.every((f) => f.endsWith('.css'));
                 if (!onlyCss) {
                     logger.hmr(`reload (buildId=${cycleBuildId})`);
                     _broadcastEvent('reload', { changedFiles: changed });
@@ -804,7 +971,7 @@ export async function createDevServer(options) {
             finally {
                 _buildInFlight = false;
                 if (_queuedFiles.size > 0) {
-                    triggerBuildDrain(20);
+                    triggerBuildDrain(queuedRebuildDebounceMs);
                 }
             }
         };
@@ -837,35 +1004,70 @@ export async function createDevServer(options) {
                 // fs.watch recursive may not be supported on this platform/root
             }
         }
+        startupProfile.emit('watcher_ready', {
+            roots: roots.length,
+            activeWatchers: _watchers.length,
+            durationMs: startupProfile.roundMs(performance.now() - watcherStartedAt)
+        });
     }
-    return new Promise((resolve) => {
-        server.listen(port, host, () => {
+    const closeServer = () => {
+        clearInterval(sseHeartbeat);
+        for (const watcher of _watchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // ignore close errors
+            }
+        }
+        _watchers = [];
+        for (const client of hmrClients) {
+            try {
+                client.end();
+            }
+            catch { }
+        }
+        hmrClients.length = 0;
+        server.close();
+    };
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        server.once('error', (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        });
+        server.listen(port, host, async () => {
             actualPort = server.address().port;
-            _startWatcher();
-            resolve({
-                server,
+            startupProfile.emit('server_bound', {
+                host: _publicHost(),
                 port: actualPort,
-                close: () => {
-                    clearInterval(sseHeartbeat);
-                    for (const watcher of _watchers) {
-                        try {
-                            watcher.close();
-                        }
-                        catch {
-                            // ignore close errors
-                        }
-                    }
-                    _watchers = [];
-                    for (const client of hmrClients) {
-                        try {
-                            client.end();
-                        }
-                        catch { }
-                    }
-                    hmrClients.length = 0;
-                    server.close();
-                }
+                buildStatus
             });
+            _trace('server_bound', {
+                host: _publicHost(),
+                port: actualPort,
+                buildStatus
+            });
+            try {
+                await _runInitialBuild();
+                _startWatcher();
+                if (!settled) {
+                    settled = true;
+                    resolve({
+                        server,
+                        port: actualPort,
+                        close: closeServer
+                    });
+                }
+            }
+            catch (error) {
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            }
         });
     });
 }