@zenithbuild/cli 0.6.5 → 0.6.7

package/dist/dev-server.js

@@ -10,22 +10,15 @@
 //
 // V0: Uses Node.js http module + fs.watch. No external deps.
 // ---------------------------------------------------------------------------
-
 import { createServer } from 'node:http';
 import { existsSync, watch } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { build } from './build.js';
 import { createSilentLogger } from './ui/logger.js';
-import {
-    executeServerRoute,
-    injectSsrPayload,
-    loadRouteManifest,
-    resolveWithinDist,
-    toStaticFilePath
-} from './preview.js';
+import { readChangeFingerprint } from './dev-watch.js';
+import { executeServerRoute, injectSsrPayload, loadRouteManifest, resolveWithinDist, toStaticFilePath } from './preview.js';
 import { resolveRequestRoute } from './server/resolve-request-route.js';
-
 const MIME_TYPES = {
     '.html': 'text/html',
     '.js': 'application/javascript',
@@ -35,10 +28,8 @@ const MIME_TYPES = {
     '.jpg': 'image/jpeg',
     '.svg': 'image/svg+xml'
 };
-
 // Note: V0 HMR script injection has been moved to the runtime client.
 // This server purely hosts the V1 HMR contract endpoints.
-
 /**
  * Create and start a development server.
  *
@@ -46,16 +37,8 @@ const MIME_TYPES = {
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createDevServer(options) {
-    const {
-        pagesDir,
-        outDir,
-        port = 3000,
-        host = '127.0.0.1',
-        config = {},
-        logger: providedLogger = null
-    } = options;
+    const { pagesDir, outDir, port = 3000, host = '127.0.0.1', config = {}, logger: providedLogger = null } = options;
     const logger = providedLogger || createSilentLogger();
-
     const resolvedPagesDir = resolve(pagesDir);
     const resolvedOutDir = resolve(outDir);
     const resolvedOutDirTmp = resolve(dirname(resolvedOutDir), `${basename(resolvedOutDir)}.tmp`);
@@ -64,7 +47,6 @@ export async function createDevServer(options) {
         ? dirname(pagesParentDir)
         : pagesParentDir;
     const watchRoots = new Set([pagesParentDir]);
-
     /** @type {import('http').ServerResponse[]} */
     const hmrClients = [];
     /** @type {import('fs').FSWatcher[]} */
@@ -73,12 +55,12 @@ export async function createDevServer(options) {
         for (const client of hmrClients) {
             try {
                 client.write(': ping\n\n');
-            } catch {
+            }
+            catch {
                 // client disconnected
             }
         }
     }, 15000);
-
     let buildId = 0;
     let pendingBuildId = 0;
     let buildStatus = 'ok'; // 'ok' | 'error' | 'building'
@@ -87,44 +69,44 @@ export async function createDevServer(options) {
     let buildError = null;
     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.
     let currentCssAssetPath = '';
     let currentCssHref = '';
     let currentCssContent = '';
     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}`;
     }
-
     function _trace(event, payload = {}) {
-        if (!traceEnabled) return;
+        if (!traceEnabled)
+            return;
         try {
             const detail = Object.keys(payload).length > 0
                 ? `${event} ${JSON.stringify(payload)}`
                 : event;
             logger.verbose('BUILD', detail);
-        } catch {
+        }
+        catch {
             // tracing must never break the dev server
         }
     }
-
     function _classifyPath(pathname) {
-        if (pathname.startsWith('/__zenith_dev/events')) return 'dev_events';
-        if (pathname.startsWith('/__zenith_dev/state')) return 'dev_state';
-        if (pathname.startsWith('/__zenith_dev/styles.css')) return 'dev_styles';
-        if (pathname.startsWith('/assets/')) return 'asset';
+        if (pathname.startsWith('/__zenith_dev/events'))
+            return 'dev_events';
+        if (pathname.startsWith('/__zenith_dev/state'))
+            return 'dev_state';
+        if (pathname.startsWith('/__zenith_dev/styles.css'))
+            return 'dev_styles';
+        if (pathname.startsWith('/assets/'))
+            return 'asset';
         return 'other';
     }
-
     function _trace404(req, url, details = {}) {
         _trace('http_404', {
             method: req.method || 'GET',
@@ -133,7 +115,6 @@ export async function createDevServer(options) {
             ...details
         });
     }
-
     function _pickCssAsset(assets) {
         if (!Array.isArray(assets) || assets.length === 0) {
             return '';
@@ -147,11 +128,9 @@ export async function createDevServer(options) {
         const preferred = cssAssets.find((entry) => /\/styles(\.|\/|$)/.test(entry));
         return preferred || cssAssets[0];
     }
-
     function _delay(ms) {
         return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
     }
-
     async function _waitForCssFile(absolutePath, retries = 16, delayMs = 40) {
         for (let i = 0; i <= retries; i++) {
             try {
@@ -159,7 +138,8 @@ export async function createDevServer(options) {
                 if (info.isFile()) {
                     return true;
                 }
-            } catch {
+            }
+            catch {
                 // keep retrying
             }
             if (i < retries) {
@@ -168,7 +148,6 @@ export async function createDevServer(options) {
         }
         return false;
     }
-
     async function _syncCssStateFromBuild(buildResult, nextBuildId) {
         currentCssHref = `/__zenith_dev/styles.css?buildId=${nextBuildId}`;
         const candidate = _pickCssAsset(buildResult?.assets);
@@ -176,7 +155,6 @@ export async function createDevServer(options) {
             _trace('css_sync_skipped', { reason: 'no_css_asset', buildId: nextBuildId });
             return false;
         }
-
         const absoluteCssPath = join(outDir, candidate);
         const ready = await _waitForCssFile(absoluteCssPath);
         if (!ready) {
@@ -188,11 +166,11 @@ export async function createDevServer(options) {
             });
             return false;
         }
-
         let cssContent = '';
         try {
             cssContent = await readFile(absoluteCssPath, 'utf8');
-        } catch {
+        }
+        catch {
             _trace('css_sync_skipped', {
                 reason: 'css_read_failed',
                 buildId: nextBuildId,
@@ -219,12 +197,10 @@ export async function createDevServer(options) {
             });
             cssContent = '/* zenith-dev: empty css */';
         }
-
         currentCssAssetPath = candidate;
         currentCssContent = cssContent;
         return true;
     }
-
     function _broadcastEvent(type, payload = {}) {
         const eventBuildId = Number.isInteger(payload.buildId) ? payload.buildId : buildId;
         const data = JSON.stringify({
@@ -241,12 +217,12 @@ export async function createDevServer(options) {
         for (const client of hmrClients) {
             try {
                 client.write(`event: ${type}\ndata: ${data}\n\n`);
-            } catch {
+            }
+            catch {
                 // client disconnected
             }
         }
     }
-
     // Initial build
     try {
         logger.build('Initial build (id=0)', { onceKey: 'dev-initial-build' });
@@ -255,7 +231,8 @@ export async function createDevServer(options) {
         if (currentCssHref.length > 0) {
             logger.css(`ready (${currentCssHref})`, { onceKey: `css-ready:${buildId}:${currentCssHref}` });
         }
-    } catch (err) {
+    }
+    catch (err) {
         buildStatus = 'error';
         buildError = { message: err instanceof Error ? err.message : String(err) };
         logger.error('initial build failed', {
@@ -263,14 +240,12 @@ export async function createDevServer(options) {
             error: err
         });
     }
-
     const server = createServer(async (req, res) => {
         const requestBase = typeof req.headers.host === 'string' && req.headers.host.length > 0
             ? `http://${req.headers.host}`
             : _serverOrigin();
         const url = new URL(req.url, requestBase);
         let pathname = url.pathname;
-
         // Legacy HMR endpoint (deprecated but kept alive to avoid breaking old caches instantly)
         if (pathname === '/__zenith_hmr') {
             res.writeHead(200, {
@@ -287,11 +262,11 @@ export async function createDevServer(options) {
             hmrClients.push(res);
             req.on('close', () => {
                 const idx = hmrClients.indexOf(res);
-                if (idx !== -1) hmrClients.splice(idx, 1);
+                if (idx !== -1)
+                    hmrClients.splice(idx, 1);
             });
             return;
         }
-
         // V1 Dev State Endpoint
         if (pathname === '/__zenith_dev/state') {
             res.writeHead(200, {
@@ -309,7 +284,6 @@ export async function createDevServer(options) {
             }));
             return;
         }
-
         // V1 Dev Events Endpoint (SSE)
         if (pathname === '/__zenith_dev/events') {
             res.writeHead(200, {
@@ -323,11 +297,11 @@ export async function createDevServer(options) {
             hmrClients.push(res);
             req.on('close', () => {
                 const idx = hmrClients.indexOf(res);
-                if (idx !== -1) hmrClients.splice(idx, 1);
+                if (idx !== -1)
+                    hmrClients.splice(idx, 1);
             });
             return;
         }
-
         if (pathname === '/__zenith_dev/styles.css') {
             if (typeof currentCssContent === 'string' && currentCssContent.length > 0) {
                 res.writeHead(200, {
@@ -345,7 +319,8 @@ export async function createDevServer(options) {
                     if (typeof css === 'string' && css.length > 0) {
                         currentCssContent = css;
                     }
-                } catch {
+                }
+                catch {
                     // keep serving last known CSS body below
                 }
             }
@@ -364,7 +339,6 @@ export async function createDevServer(options) {
             res.end(currentCssContent);
             return;
         }
-
         if (pathname === '/__zenith/route-check') {
             try {
                 // Security: Require explicitly designated header to prevent public oracle probing
@@ -373,23 +347,19 @@ export async function createDevServer(options) {
                     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(outDir);
                 const resolvedCheck = resolveRequestRoute(targetUrl, routes);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
@@ -397,7 +367,6 @@ export async function createDevServer(options) {
                     res.end(JSON.stringify({ error: 'route_not_found' }));
                     return;
                 }
-
                 const checkResult = await executeServerRoute({
                     source: resolvedCheck.route.server_script || '',
                     sourcePath: resolvedCheck.route.server_script_path || '',
@@ -419,12 +388,12 @@ export async function createDevServer(options) {
                             if (parsedLoc.origin !== targetUrl.origin) {
                                 checkResult.result.location = '/'; // Fallback to root for open redirect attempt
                             }
-                        } catch {
+                        }
+                        catch {
                             checkResult.result.location = '/';
                         }
                     }
                 }
-
                 res.writeHead(200, {
                     'Content-Type': 'application/json',
                     'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
@@ -438,13 +407,13 @@ export async function createDevServer(options) {
                     to: targetUrl.toString()
                 }));
                 return;
-            } catch {
+            }
+            catch {
                 res.writeHead(500, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'route_check_failed' }));
                 return;
             }
         }
-
         let resolvedPathFor404 = null;
         let staticRootFor404 = null;
         try {
@@ -459,32 +428,26 @@ export async function createDevServer(options) {
                 res.end(asset);
                 return;
             }
-
             const routes = await loadRouteManifest(outDir);
             const resolved = resolveRequestRoute(url, routes);
             let filePath = null;
-
             if (resolved.matched && resolved.route) {
                 if (verboseLogging) {
-                    logger.router(
-                        `${req.method || 'GET'} ${pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`
-                    );
+                    logger.router(`${req.method || 'GET'} ${pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`);
                 }
                 const output = resolved.route.output.startsWith('/')
                     ? resolved.route.output.slice(1)
                     : resolved.route.output;
                 filePath = resolveWithinDist(outDir, output);
-            } else {
+            }
+            else {
                 filePath = toStaticFilePath(outDir, pathname);
             }
-
             resolvedPathFor404 = filePath;
             staticRootFor404 = outDir;
-
             if (!filePath) {
                 throw new Error('not found');
             }
-
             let ssrPayload = null;
             if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
                 let routeExecution = null;
@@ -500,7 +463,8 @@ export async function createDevServer(options) {
                         routeFile: resolved.route.server_script_path || '',
                         routeId: resolved.route.route_id || ''
                     });
-                } catch (error) {
+                }
+                catch (error) {
                     ssrPayload = {
                         __zenith_error: {
                             code: 'LOAD_FAILED',
@@ -508,15 +472,11 @@ export async function createDevServer(options) {
                         }
                     };
                 }
-
                 const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
                 const routeId = resolved.route.route_id || '';
                 if (verboseLogging) {
-                    logger.router(
-                        `${routeId || resolved.route.path} guard=${trace.guard} load=${trace.load}`
-                    );
+                    logger.router(`${routeId || resolved.route.path} guard=${trace.guard} load=${trace.load}`);
                 }
-
                 const result = routeExecution?.result;
                 if (result && result.kind === 'redirect') {
                     const status = Number.isInteger(result.status) ? result.status : 302;
@@ -537,14 +497,14 @@ export async function createDevServer(options) {
                     ssrPayload = result.data;
                 }
             }
-
             let content = await readFile(filePath, 'utf8');
             if (ssrPayload) {
                 content = injectSsrPayload(content, ssrPayload);
             }
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(content);
-        } catch {
+        }
+        catch {
             _trace404(req, url, {
                 reason: 'not_found',
                 staticRoot: staticRootFor404,
@@ -554,7 +514,6 @@ export async function createDevServer(options) {
             res.end('404 Not Found');
         }
     });
-
     /**
      * Broadcast HMR reload to all connected clients.
      */
@@ -562,30 +521,29 @@ export async function createDevServer(options) {
         for (const client of hmrClients) {
             try {
                 client.write('data: reload\n\n');
-            } catch {
+            }
+            catch {
                 // client disconnected
             }
         }
     }
-
     let _buildDebounce = null;
     let _queuedFiles = new Set();
+    const _lastQueuedFingerprints = new Map();
     let _buildInFlight = false;
-
     function _isWithin(parent, child) {
         const rel = relative(parent, child);
         return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
     }
-
     function _toDisplayPath(absPath) {
         const rel = relative(projectRoot, absPath);
-        if (rel === '') return '.';
+        if (rel === '')
+            return '.';
         if (!rel.startsWith('..') && !isAbsolute(rel)) {
             return rel;
         }
         return absPath;
     }
-
     function _shouldIgnoreChange(absPath) {
         if (_isWithin(resolvedOutDir, absPath)) {
             return true;
@@ -604,7 +562,6 @@ export async function createDevServer(options) {
             || segments.includes('target')
             || segments.includes('.turbo');
     }
-
     /**
      * Start watching source roots for changes.
      */
@@ -618,7 +575,6 @@ export async function createDevServer(options) {
                 void drainBuildQueue();
             }, delayMs);
         };
-
         const drainBuildQueue = async () => {
             if (_buildInFlight) {
                 return;
@@ -628,39 +584,33 @@ export async function createDevServer(options) {
                 return;
             }
             _queuedFiles.clear();
-
             _buildInFlight = true;
             const cycleBuildId = pendingBuildId + 1;
             pendingBuildId = cycleBuildId;
             buildStatus = 'building';
             logger.build(`Rebuild (id=${cycleBuildId})`);
             _broadcastEvent('build_start', { buildId: cycleBuildId, changedFiles: changed });
-
             const startTime = Date.now();
             const previousCssAssetPath = currentCssAssetPath;
             const previousCssContent = currentCssContent;
             try {
                 const buildResult = await build({ pagesDir, outDir, config, logger });
                 const cssReady = await _syncCssStateFromBuild(buildResult, cycleBuildId);
-                const cssChanged = cssReady && (
-                    currentCssAssetPath !== previousCssAssetPath ||
-                    currentCssContent !== previousCssContent
-                );
+                const cssChanged = cssReady && (currentCssAssetPath !== previousCssAssetPath ||
+                    currentCssContent !== previousCssContent);
                 buildId = cycleBuildId;
                 buildStatus = 'ok';
                 buildError = null;
                 lastBuildMs = Date.now();
                 durationMs = lastBuildMs - startTime;
                 logger.build(`Complete (id=${cycleBuildId}, ${durationMs}ms)`);
-
                 _broadcastEvent('build_complete', {
                     buildId: cycleBuildId,
                     durationMs,
                     status: buildStatus,
                     cssHref: currentCssHref,
                     changedFiles: changed
-                }
-                );
+                });
                 _trace('state_snapshot', {
                     status: buildStatus,
                     buildId: cycleBuildId,
@@ -668,18 +618,17 @@ export async function createDevServer(options) {
                     durationMs,
                     changedFiles: changed
                 });
-
                 if (cssChanged && currentCssHref.length > 0) {
                     logger.css(`ready (${currentCssHref})`);
                     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 });
-                } else {
+                }
+                else {
                     _trace('css_only_update', {
                         buildId: cycleBuildId,
                         cssHref: currentCssHref,
@@ -687,7 +636,8 @@ export async function createDevServer(options) {
                         changedFiles: changed
                     });
                 }
-            } catch (err) {
+            }
+            catch (err) {
                 const fullError = err instanceof Error ? err.message : String(err);
                 buildStatus = 'error';
                 buildError = { message: fullError.length > 10000 ? fullError.slice(0, 10000) + '... (truncated)' : fullError };
@@ -697,7 +647,6 @@ export async function createDevServer(options) {
                     hint: 'fix the error and save again',
                     error: err
                 });
-
                 _broadcastEvent('build_error', { buildId: cycleBuildId, ...buildError, changedFiles: changed });
                 _trace('state_snapshot', {
                     status: buildStatus,
@@ -706,17 +655,18 @@ export async function createDevServer(options) {
                     durationMs,
                     error: buildError
                 });
-            } finally {
+            }
+            finally {
                 _buildInFlight = false;
                 if (_queuedFiles.size > 0) {
                     triggerBuildDrain(20);
                 }
             }
         };
-
         const roots = Array.from(watchRoots);
         for (const root of roots) {
-            if (!existsSync(root)) continue;
+            if (!existsSync(root))
+                continue;
             try {
                 const watcher = watch(root, { recursive: true }, (_eventType, filename) => {
                     if (!filename) {
@@ -726,21 +676,27 @@ export async function createDevServer(options) {
                     if (_shouldIgnoreChange(changedPath)) {
                         return;
                     }
-                    _queuedFiles.add(changedPath);
-                    triggerBuildDrain();
+                    void (async () => {
+                        const fingerprint = await readChangeFingerprint(changedPath);
+                        if (_lastQueuedFingerprints.get(changedPath) === fingerprint) {
+                            return;
+                        }
+                        _lastQueuedFingerprints.set(changedPath, fingerprint);
+                        _queuedFiles.add(changedPath);
+                        triggerBuildDrain();
+                    })();
                 });
                 _watchers.push(watcher);
-            } catch {
+            }
+            catch {
                 // fs.watch recursive may not be supported on this platform/root
             }
         }
     }
-
     return new Promise((resolve) => {
         server.listen(port, host, () => {
             actualPort = server.address().port;
             _startWatcher();
-
             resolve({
                 server,
                 port: actualPort,
@@ -749,13 +705,17 @@ export async function createDevServer(options) {
                     for (const watcher of _watchers) {
                         try {
                             watcher.close();
-                        } catch {
+                        }
+                        catch {
                             // ignore close errors
                         }
                     }
                     _watchers = [];
                     for (const client of hmrClients) {
-                        try { client.end(); } catch { }
+                        try {
+                            client.end();
+                        }
+                        catch { }
                     }
                     hmrClients.length = 0;
                     server.close();

package/dist/dev-watch.d.ts

@@ -0,0 +1 @@
+export function readChangeFingerprint(absPath: any): Promise<string>;

package/dist/dev-watch.js

@@ -0,0 +1,19 @@
+import { stat } from 'node:fs/promises';
+export async function readChangeFingerprint(absPath) {
+    try {
+        const info = await stat(absPath);
+        const kind = info.isDirectory()
+            ? 'dir'
+            : info.isFile()
+                ? 'file'
+                : 'other';
+        return `${kind}:${info.mtimeMs}:${info.size}`;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' ? error.code : '';
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return 'missing';
+        }
+        return `error:${String(code || 'unknown')}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point.
+ *
+ * @param {string[]} args - Process arguments (without node and script paths)
+ * @param {string} [cwd] - Working directory override
+ */
+export function cli(args: string[], cwd?: string): Promise<void>;