@zenithbuild/cli 0.6.0 → 0.6.3

package/dist/dev-server.js

@@ -16,6 +16,7 @@ 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,
@@ -41,7 +42,7 @@ const MIME_TYPES = {
 /**
  * Create and start a development server.
  *
- * @param {{ pagesDir: string, outDir: string, port?: number, host?: string, config?: object }} options
+ * @param {{ pagesDir: string, outDir: string, port?: number, host?: string, config?: object, logger?: object | null }} options
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createDevServer(options) {
@@ -50,8 +51,10 @@ export async function createDevServer(options) {
         outDir,
         port = 3000,
         host = '127.0.0.1',
-        config = {}
+        config = {},
+        logger: providedLogger = null
     } = options;
+    const logger = providedLogger || createSilentLogger();
 
     const resolvedPagesDir = resolve(pagesDir);
     const resolvedOutDir = resolve(outDir);
@@ -83,6 +86,7 @@ export async function createDevServer(options) {
     let durationMs = 0;
     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 = '';
@@ -104,8 +108,10 @@ export async function createDevServer(options) {
     function _trace(event, payload = {}) {
         if (!traceEnabled) return;
         try {
-            const timestamp = new Date().toISOString();
-            console.log(`[zenith-dev][${timestamp}] ${event} ${JSON.stringify(payload)}`);
+            const detail = Object.keys(payload).length > 0
+                ? `${event} ${JSON.stringify(payload)}`
+                : event;
+            logger.verbose('BUILD', detail);
         } catch {
             // tracing must never break the dev server
         }
@@ -243,11 +249,19 @@ export async function createDevServer(options) {
 
     // Initial build
     try {
-        const initialBuild = await build({ pagesDir, outDir, config });
+        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}` });
+        }
     } 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) => {
@@ -265,7 +279,10 @@ export async function createDevServer(options) {
                 'Connection': 'keep-alive',
                 'X-Zenith-Deprecated': 'true'
             });
-            console.warn('[zenith] Warning: /__zenith_hmr is legacy; use /__zenith_dev/events');
+            logger.warn('legacy HMR endpoint in use', {
+                hint: 'use /__zenith_dev/events',
+                onceKey: 'legacy-hmr-endpoint'
+            });
             res.write(': connected\n\n');
             hmrClients.push(res);
             req.on('close', () => {
@@ -448,7 +465,11 @@ export async function createDevServer(options) {
             let filePath = null;
 
             if (resolved.matched && resolved.route) {
-                console.log(`[zenith] Request: ${pathname} | Route: ${resolved.route.path} | Params: ${JSON.stringify(resolved.params)}`);
+                if (verboseLogging) {
+                    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;
@@ -490,8 +511,11 @@ export async function createDevServer(options) {
 
                 const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
                 const routeId = resolved.route.route_id || '';
-                console.log(`[Zenith] guard(${routeId || resolved.route.path}) -> ${trace.guard}`);
-                console.log(`[Zenith] load(${routeId || resolved.route.path}) -> ${trace.load}`);
+                if (verboseLogging) {
+                    logger.router(
+                        `${routeId || resolved.route.path} guard=${trace.guard} load=${trace.load}`
+                    );
+                }
 
                 const result = routeExecution?.result;
                 if (result && result.kind === 'redirect') {
@@ -609,17 +633,25 @@ export async function createDevServer(options) {
             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 });
+                const buildResult = await build({ pagesDir, outDir, config, logger });
                 const cssReady = await _syncCssStateFromBuild(buildResult, cycleBuildId);
+                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,
@@ -637,12 +669,23 @@ export async function createDevServer(options) {
                     changedFiles: changed
                 });
 
-                const onlyCss = changed.length > 0 && changed.every((f) => f.endsWith('.css'));
-                if (onlyCss && cssReady && currentCssHref.length > 0) {
-                    // Let the client fetch the updated CSS automatically
+                if (cssChanged && currentCssHref.length > 0) {
+                    logger.css(`ready (${currentCssHref})`);
+                    logger.hmr(`css_update (buildId=${cycleBuildId})`);
                     _broadcastEvent('css_update', { href: currentCssHref, changedFiles: changed });
-                } else {
+                }
+
+                const onlyCss = changed.length > 0 && changed.every((f) => f.endsWith('.css'));
+                if (!onlyCss) {
+                    logger.hmr(`reload (buildId=${cycleBuildId})`);
                     _broadcastEvent('reload', { changedFiles: changed });
+                } else {
+                    _trace('css_only_update', {
+                        buildId: cycleBuildId,
+                        cssHref: currentCssHref,
+                        cssChanged,
+                        changedFiles: changed
+                    });
                 }
             } catch (err) {
                 const fullError = err instanceof Error ? err.message : String(err);
@@ -650,6 +693,10 @@ export async function createDevServer(options) {
                 buildError = { message: fullError.length > 10000 ? fullError.slice(0, 10000) + '... (truncated)' : fullError };
                 lastBuildMs = Date.now();
                 durationMs = lastBuildMs - startTime;
+                logger.error('rebuild failed', {
+                    hint: 'fix the error and save again',
+                    error: err
+                });
 
                 _broadcastEvent('build_error', { buildId: cycleBuildId, ...buildError, changedFiles: changed });
                 _trace('state_snapshot', {

package/dist/index.js

@@ -13,7 +13,7 @@
 import { resolve, join, dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { createLogger } from './ui/logger.js';
+import { createZenithLogger } from './ui/logger.js';
 
 const COMMANDS = ['dev', 'build', 'preview'];
 const DEFAULT_VERSION = '0.0.0';
@@ -90,7 +90,7 @@ async function loadConfig(projectRoot) {
  * @param {string} [cwd] - Working directory override
  */
 export async function cli(args, cwd) {
-    const logger = createLogger(process);
+    const logger = createZenithLogger(process);
     const command = args[0];
     const cliVersion = getCliVersion();
 
@@ -118,10 +118,10 @@ export async function cli(args, cwd) {
 
     if (command === 'build') {
         const { build } = await import('./build.js');
-        logger.info('Building...');
-        const result = await build({ pagesDir, outDir, config });
-        logger.success(`Built ${result.pages} page(s), ${result.assets.length} asset(s)`);
-        logger.summary([{ label: 'Output', value: './dist' }]);
+        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');
     }
 
     if (command === 'dev') {
@@ -130,9 +130,9 @@ export async function cli(args, cwd) {
             ? Number.parseInt(process.env.ZENITH_DEV_PORT, 10)
             : resolvePort(args.slice(1), 3000);
         const host = process.env.ZENITH_DEV_HOST || '127.0.0.1';
-        logger.info('Starting dev server...');
-        const dev = await createDevServer({ pagesDir, outDir, port, host, config });
-        logger.success(`Dev server running at http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${dev.port}`);
+        logger.dev('Starting dev server…');
+        const dev = await createDevServer({ pagesDir, outDir, port, host, config, logger });
+        logger.ok(`http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${dev.port}`);
 
         // Graceful shutdown
         process.on('SIGINT', () => {
@@ -149,9 +149,9 @@ export async function cli(args, cwd) {
         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.info('Starting preview server...');
-        const preview = await createPreviewServer({ distDir: outDir, port, host });
-        logger.success(`Preview server running at http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${preview.port}`);
+        logger.dev('Starting preview server…');
+        const preview = await createPreviewServer({ distDir: outDir, port, host, logger });
+        logger.ok(`http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${preview.port}`);
 
         process.on('SIGINT', () => {
             preview.close();
@@ -172,7 +172,7 @@ const isDirectRun = process.argv[1] && (
 
 if (isDirectRun) {
     cli(process.argv.slice(2)).catch((error) => {
-        const logger = createLogger(process);
+        const logger = createZenithLogger(process);
         logger.error(error);
         process.exit(1);
     });

package/dist/preview.js

@@ -14,6 +14,7 @@ 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 { createSilentLogger } from './ui/logger.js';
 import {
   compareRouteSpecificity,
   matchRoute as matchManifestRoute,
@@ -386,11 +387,13 @@ try {
 /**
  * Create and start a preview server.
  *
- * @param {{ distDir: string, port?: number, host?: string }} options
+ * @param {{ distDir: string, port?: number, host?: string, logger?: object | null }} options
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createPreviewServer(options) {
-  const { distDir, port = 4000, host = '127.0.0.1' } = options;
+  const { distDir, port = 4000, host = '127.0.0.1', logger: providedLogger = null } = options;
+  const logger = providedLogger || createSilentLogger();
+  const verboseLogging = logger.mode?.logLevel === 'verbose';
   let actualPort = port;
 
   function publicHost() {
@@ -502,7 +505,11 @@ export async function createPreviewServer(options) {
       let htmlPath = null;
 
       if (resolved.matched && resolved.route) {
-        console.log(`[zenith] Request: ${url.pathname} | Route: ${resolved.route.path} | Params: ${JSON.stringify(resolved.params)}`);
+        if (verboseLogging) {
+          logger.router(
+            `${req.method || 'GET'} ${url.pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`
+          );
+        }
         const output = resolved.route.output.startsWith('/')
           ? resolved.route.output.slice(1)
           : resolved.route.output;
@@ -541,8 +548,9 @@ export async function createPreviewServer(options) {
 
         const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
         const routeId = resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '');
-        console.log(`[Zenith] guard(${routeId}) -> ${trace.guard}`);
-        console.log(`[Zenith] load(${routeId}) -> ${trace.load}`);
+        if (verboseLogging) {
+          logger.router(`${routeId} guard=${trace.guard} load=${trace.load}`);
+        }
 
         const result = routeExecution?.result;
         if (result && result.kind === 'redirect') {

package/dist/ui/env.js

@@ -10,6 +10,14 @@ function flagEnabled(value) {
     return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 }
 
+function parseLogLevel(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'quiet' || normalized === 'verbose') {
+        return normalized;
+    }
+    return 'normal';
+}
+
 /**
  * @param {{ env?: Record<string, string | undefined>, stdout?: { isTTY?: boolean } }} runtime
  */
@@ -21,10 +29,17 @@ export function getUiMode(runtime = process) {
     const noColor = env.NO_COLOR !== undefined && String(env.NO_COLOR).length >= 0;
     const forceColor = flagEnabled(env.FORCE_COLOR);
     const debug = flagEnabled(env.ZENITH_DEBUG);
+    let logLevel = parseLogLevel(env.ZENITH_LOG_LEVEL);
 
     const plain = noUi || ci || !tty;
     const color = !plain && !noColor && (forceColor || tty);
     const spinner = tty && !plain && !ci;
+    if (flagEnabled(env.ZENITH_DEV_TRACE)) {
+        logLevel = 'verbose';
+    }
+    if (debug && logLevel !== 'quiet') {
+        logLevel = 'verbose';
+    }
 
     return {
         plain,
@@ -32,7 +47,8 @@ export function getUiMode(runtime = process) {
         tty,
         ci,
         spinner,
-        debug
+        debug,
+        logLevel
     };
 }
 

package/dist/ui/format.js

@@ -1,53 +1,78 @@
-/**
- * Deterministic text formatters for CLI UX.
- */
-
+import pc from 'picocolors';
 import { relative, sep } from 'node:path';
 
-const ANSI = {
-    reset: '\x1b[0m',
-    bold: '\x1b[1m',
-    dim: '\x1b[2m',
-    red: '\x1b[31m',
-    yellow: '\x1b[33m',
-    green: '\x1b[32m',
-    cyan: '\x1b[36m'
-};
 const DEFAULT_PHASE = 'cli';
 const DEFAULT_FILE = '.';
 const DEFAULT_HINT_BASE = 'https://github.com/zenithbuild/zenith/blob/main/zenith-cli/CLI_CONTRACT.md';
+const PREFIX = '[zenith]';
+const TAG_WIDTH = 6;
+
+const TAG_COLORS = {
+    DEV: (colors, value) => colors.cyan(value),
+    BUILD: (colors, value) => colors.blue(value),
+    HMR: (colors, value) => colors.magenta(value),
+    ROUTER: (colors, value) => colors.cyan(value),
+    CSS: (colors, value) => colors.yellow(value),
+    OK: (colors, value) => colors.green(value),
+    WARN: (colors, value) => colors.bold(colors.yellow(value)),
+    ERR: (colors, value) => colors.bold(colors.red(value))
+};
+
+function getColors(mode) {
+    return pc.createColors(Boolean(mode?.color));
+}
 
-function colorize(mode, token, text) {
+export function formatPrefix(mode) {
+    return mode.color ? getColors(mode).dim(PREFIX) : PREFIX;
+}
+
+function colorizeTag(mode, tag) {
+    const padded = String(tag || '').padEnd(TAG_WIDTH, ' ');
     if (!mode.color) {
-        return text;
+        return padded;
     }
-    return `${ANSI[token]}${text}${ANSI.reset}`;
+    const colors = getColors(mode);
+    const colorizer = TAG_COLORS[tag] || ((_colors, value) => colors.white(value));
+    return colorizer(colors, padded);
 }
 
-export function formatHeading(mode, text) {
-    const label = mode.plain ? 'ZENITH CLI' : colorize(mode, 'bold', 'Zenith CLI');
-    return `${label} ${text}`.trim();
+function colorizeGlyph(mode, glyph, tag) {
+    if (!mode.color) {
+        return glyph;
+    }
+    const colors = getColors(mode);
+    const colorizer = TAG_COLORS[tag] || ((_colors, value) => value);
+    return colorizer(colors, glyph);
 }
 
-export function formatStep(mode, text) {
-    if (mode.plain) {
-        return `[zenith] INFO: ${text}`;
-    }
-    const bullet = colorize(mode, 'cyan', '•');
-    return `[zenith] ${bullet} ${text}`;
+export function formatLine(mode, { glyph = '•', tag = 'DEV', text = '' }) {
+    return `${formatPrefix(mode)} ${colorizeGlyph(mode, glyph, tag)} ${colorizeTag(mode, tag)} ${String(text || '')}`;
 }
 
-export function formatSummaryTable(mode, rows) {
+export function formatStep(mode, text, tag = 'BUILD') {
+    return formatLine(mode, { glyph: '•', tag, text });
+}
+
+export function formatHint(mode, text) {
+    const body = `          hint: ${String(text || '').trim()}`;
+    return mode.color ? getColors(mode).dim(body) : body;
+}
+
+export function formatHeading(mode, text) {
+    const label = mode.color ? getColors(mode).bold('Zenith CLI') : 'Zenith CLI';
+    return `${label} ${String(text || '').trim()}`.trim();
+}
+
+export function formatSummaryTable(mode, rows, tag = 'BUILD') {
     if (!Array.isArray(rows) || rows.length === 0) {
         return '';
     }
-    const maxLabel = rows.reduce((acc, row) => Math.max(acc, String(row.label || '').length), 0);
     return rows
-        .map((row) => {
-            const label = String(row.label || '').padEnd(maxLabel, ' ');
-            const value = String(row.value || '');
-            return `[zenith] ${label} : ${value}`;
-        })
+        .map((row) => formatLine(mode, {
+            glyph: '•',
+            tag,
+            text: `${String(row.label || '')}: ${String(row.value || '')}`
+        }))
         .join('\n');
 }
 
@@ -131,36 +156,49 @@ export function normalizeError(err) {
     return new Error(sanitizeErrorMessage(err));
 }
 
+function firstMeaningfulLine(text) {
+    return String(text || '')
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.length > 0) || '';
+}
+
 /**
  * @param {unknown} err
- * @param {{ plain: boolean, color: boolean, debug: boolean }} mode
+ * @param {{ plain: boolean, color: boolean, debug?: boolean, logLevel?: string }} mode
  */
 export function formatErrorBlock(err, mode) {
     const normalized = normalizeError(err);
     const maybe = /** @type {{ code?: unknown, phase?: unknown, kind?: unknown, file?: unknown, hint?: unknown }} */ (normalized);
-    const kind = sanitizeErrorMessage(maybe.kind || maybe.code || 'CLI_ERROR');
     const phase = maybe.phase ? sanitizeErrorMessage(maybe.phase) : inferPhaseFromArgv();
     const code = maybe.code
         ? sanitizeErrorMessage(maybe.code)
         : `${phase.toUpperCase().replace(/[^A-Z0-9]+/g, '_') || 'CLI'}_FAILED`;
     const rawMessage = sanitizeErrorMessage(normalized.message || String(normalized));
     const message = normalizeErrorMessagePaths(rawMessage);
+    const compactMessage = firstMeaningfulLine(message) || 'Command failed';
     const file = normalizePathForDisplay(
         sanitizeErrorMessage(maybe.file || extractFileFromMessage(message) || DEFAULT_FILE)
     );
     const hint = sanitizeErrorMessage(maybe.hint || formatHintUrl(code));
 
+    if (mode.logLevel !== 'verbose' && !mode.debug) {
+        return [
+            formatLine(mode, { glyph: '✖', tag: 'ERR', text: compactMessage }),
+            formatHint(mode, hint)
+        ].join('\n');
+    }
+
     const lines = [];
-    lines.push('[zenith] ERROR: Command failed');
-    lines.push(`[zenith] Error Kind: ${kind}`);
-    lines.push(`[zenith] Phase: ${phase || DEFAULT_PHASE}`);
-    lines.push(`[zenith] Code: ${code || 'CLI_FAILED'}`);
-    lines.push(`[zenith] File: ${file || DEFAULT_FILE}`);
-    lines.push(`[zenith] Hint: ${hint || formatHintUrl(code)}`);
-    lines.push(`[zenith] Message: ${message}`);
+    lines.push(formatLine(mode, { glyph: '✖', tag: 'ERR', text: compactMessage }));
+    lines.push(formatHint(mode, hint || formatHintUrl(code)));
+    lines.push(`${formatPrefix(mode)}     code: ${code || 'CLI_FAILED'}`);
+    lines.push(`${formatPrefix(mode)}     phase: ${phase || DEFAULT_PHASE}`);
+    lines.push(`${formatPrefix(mode)}     file: ${file || DEFAULT_FILE}`);
+    lines.push(`${formatPrefix(mode)}     detail: ${message}`);
 
     if (mode.debug && normalized.stack) {
-        lines.push('[zenith] Stack:');
+        lines.push(`${formatPrefix(mode)}     stack:`);
         lines.push(...String(normalized.stack).split('\n').slice(0, 20));
     }