@zenithbuild/cli 0.6.0 → 0.6.2

package/dist/build.js

@@ -92,6 +92,35 @@ export function createCompilerWarningEmitter(sink = (line) => console.warn(line)
     };
 }
 
+/**
+ * Forward child-process output line-by-line through the structured logger.
+ *
+ * @param {import('node:stream').Readable | null | undefined} stream
+ * @param {(line: string) => void} onLine
+ */
+function forwardStreamLines(stream, onLine) {
+    if (!stream || typeof stream.on !== 'function') {
+        return;
+    }
+    let pending = '';
+    stream.setEncoding?.('utf8');
+    stream.on('data', (chunk) => {
+        pending += String(chunk || '');
+        const lines = pending.split(/\r?\n/);
+        pending = lines.pop() || '';
+        for (const line of lines) {
+            if (line.trim().length > 0) {
+                onLine(line);
+            }
+        }
+    });
+    stream.on('end', () => {
+        if (pending.trim().length > 0) {
+            onLine(pending);
+        }
+    });
+}
+
 /**
  * Run the compiler process and parse its JSON stdout.
  *
@@ -244,6 +273,57 @@ function mergeExpressionRewriteMaps(pageMap, pageAmbiguous, componentRewrite) {
     }
 }
 
+function resolveStateKeyFromBindings(identifier, stateBindings, preferredKeys = null) {
+    const ident = String(identifier || '').trim();
+    if (!ident) {
+        return null;
+    }
+
+    const exact = stateBindings.find((entry) => String(entry?.key || '') === ident);
+    if (exact && typeof exact.key === 'string') {
+        return exact.key;
+    }
+
+    const suffix = `_${ident}`;
+    const matches = stateBindings
+        .map((entry) => String(entry?.key || ''))
+        .filter((key) => key.endsWith(suffix));
+
+    if (preferredKeys instanceof Set && preferredKeys.size > 0) {
+        const preferredMatches = matches.filter((key) => preferredKeys.has(key));
+        if (preferredMatches.length === 1) {
+            return preferredMatches[0];
+        }
+    }
+
+    if (matches.length === 1) {
+        return matches[0];
+    }
+
+    return null;
+}
+
+function rewriteRefBindingIdentifiers(pageIr, preferredKeys = null) {
+    if (!Array.isArray(pageIr?.ref_bindings) || pageIr.ref_bindings.length === 0) {
+        return;
+    }
+
+    const stateBindings = Array.isArray(pageIr?.hoisted?.state) ? pageIr.hoisted.state : [];
+    if (stateBindings.length === 0) {
+        return;
+    }
+
+    for (const binding of pageIr.ref_bindings) {
+        if (!binding || typeof binding !== 'object' || typeof binding.identifier !== 'string') {
+            continue;
+        }
+        const resolved = resolveStateKeyFromBindings(binding.identifier, stateBindings, preferredKeys);
+        if (resolved) {
+            binding.identifier = resolved;
+        }
+    }
+}
+
 /**
  * Rewrite unresolved page expressions using component script-aware mappings.
  *
@@ -751,7 +831,7 @@ function collectComponentUsageAttrs(source, registry) {
  * @param {{ includeCode: boolean, cssImportsOnly: boolean, documentMode?: boolean, componentAttrs?: string }} options
  * @param {Set<string>} seenStaticImports
  */
-function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStaticImports) {
+function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStaticImports, knownRefKeys = null) {
     // Merge components_scripts
     if (compIr.components_scripts) {
         for (const [hoistId, script] of Object.entries(compIr.components_scripts)) {
@@ -766,6 +846,17 @@ function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStati
         pageIr.component_instances.push(...compIr.component_instances);
     }
 
+    if (knownRefKeys instanceof Set && Array.isArray(compIr.ref_bindings)) {
+        const componentStateBindings = Array.isArray(compIr?.hoisted?.state) ? compIr.hoisted.state : [];
+        for (const binding of compIr.ref_bindings) {
+            if (!binding || typeof binding.identifier !== 'string' || binding.identifier.length === 0) {
+                continue;
+            }
+            const resolved = resolveStateKeyFromBindings(binding.identifier, componentStateBindings);
+            knownRefKeys.add(resolved || binding.identifier);
+        }
+    }
+
     // Merge hoisted imports (deduplicated, rebased to the page file path)
     if (compIr.hoisted?.imports?.length) {
         for (const imp of compIr.hoisted.imports) {
@@ -1253,16 +1344,32 @@ function deferComponentRuntimeBlock(source) {
  *
  * @param {object|object[]} envelope
  * @param {string} outDir
+ * @param {string} projectRoot
+ * @param {object | null} [logger]
+ * @param {boolean} [showInfo]
  * @returns {Promise<void>}
  */
-function runBundler(envelope, outDir) {
+function runBundler(envelope, outDir, projectRoot, logger = null, showInfo = true) {
     return new Promise((resolvePromise, rejectPromise) => {
+        const useStructuredLogger = Boolean(logger && typeof logger.childLine === 'function');
         const child = spawn(
             getBundlerBin(),
             ['--out-dir', outDir],
-            { stdio: ['pipe', 'inherit', 'inherit'] }
+            {
+                cwd: projectRoot,
+                stdio: useStructuredLogger ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'inherit']
+            }
         );
 
+        if (useStructuredLogger) {
+            forwardStreamLines(child.stdout, (line) => {
+                logger.childLine('bundler', line, { stream: 'stdout', showInfo });
+            });
+            forwardStreamLines(child.stderr, (line) => {
+                logger.childLine('bundler', line, { stream: 'stderr', showInfo: true });
+            });
+        }
+
         child.on('error', (err) => {
             rejectPromise(new Error(`Bundler spawn failed: ${err.message}`));
         });
@@ -1328,11 +1435,12 @@ async function collectAssets(rootDir) {
  *      d. Merge component IRs into page IR
  *   3. Send all envelopes to bundler
  *
- * @param {{ pagesDir: string, outDir: string, config?: object }} options
+ * @param {{ pagesDir: string, outDir: string, config?: object, logger?: object | null, showBundlerInfo?: boolean }} options
  * @returns {Promise<{ pages: number, assets: string[] }>}
  */
 export async function build(options) {
-    const { pagesDir, outDir, config = {} } = options;
+    const { pagesDir, outDir, config = {}, logger = null, showBundlerInfo = true } = options;
+    const projectRoot = deriveProjectRootFromPagesDir(pagesDir);
     const softNavigationEnabled = config.softNavigation === true || config.router === true;
     const compilerOpts = {
         typescriptDefault: config.typescriptDefault === true,
@@ -1349,7 +1457,13 @@ export async function build(options) {
     // 1. Build component registry
     const registry = buildComponentRegistry(srcDir);
     if (registry.size > 0) {
-        console.log(`[zenith] Component registry: ${registry.size} components`);
+        if (logger && typeof logger.build === 'function') {
+            logger.build(`registry=${registry.size} components`, {
+                onceKey: `component-registry:${registry.size}`
+            });
+        } else {
+            console.log(`[zenith] Component registry: ${registry.size} components`);
+        }
     }
 
     const manifest = await generateManifest(pagesDir);
@@ -1362,7 +1476,13 @@ export async function build(options) {
     const componentDocumentModeCache = new Map();
     /** @type {Map<string, { map: Map<string, string>, ambiguous: Set<string> }>} */
     const componentExpressionRewriteCache = new Map();
-    const emitCompilerWarning = createCompilerWarningEmitter((line) => console.warn(line));
+    const emitCompilerWarning = createCompilerWarningEmitter((line) => {
+        if (logger && typeof logger.warn === 'function') {
+            logger.warn(line, { onceKey: `compiler-warning:${line}` });
+            return;
+        }
+        console.warn(line);
+    });
 
     const envelopes = [];
     for (const entry of manifest) {
@@ -1431,6 +1551,7 @@ export async function build(options) {
         const seenStaticImports = new Set();
         const pageExpressionRewriteMap = new Map();
         const pageAmbiguousExpressionMap = new Set();
+        const knownRefKeys = new Set();
 
         // 2c. Compile each used component separately for its script IR
         for (const compName of usedComponents) {
@@ -1481,7 +1602,8 @@ export async function build(options) {
                     documentMode: isDocMode,
                     componentAttrs: (componentUsageAttrs.get(compName) || [])[0] || ''
                 },
-                seenStaticImports
+                seenStaticImports,
+                knownRefKeys
             );
         }
 
@@ -1492,6 +1614,7 @@ export async function build(options) {
         );
 
         rewriteLegacyMarkupIdentifiers(pageIr);
+        rewriteRefBindingIdentifiers(pageIr, knownRefKeys);
 
         envelopes.push({
             route: entry.path,
@@ -1502,7 +1625,7 @@ export async function build(options) {
     }
 
     if (envelopes.length > 0) {
-        await runBundler(envelopes, outDir);
+    await runBundler(envelopes, outDir, projectRoot, logger, showBundlerInfo);
     }
 
     const assets = await collectAssets(outDir);

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));
     }
 

package/dist/ui/logger.js

@@ -1,105 +1,270 @@
-import { formatErrorBlock, formatHeading, formatStep, formatSummaryTable } from './format.js';
+import {
+    formatErrorBlock,
+    formatHeading,
+    formatHint,
+    formatLine,
+    formatSummaryTable
+} from './format.js';
 import { getUiMode } from './env.js';
 
-const SPINNER_FRAMES = ['-', '\\', '|', '/'];
-
 function write(out, text) {
     out.write(`${text}\n`);
 }
 
-function createSpinner(mode, stderr) {
-    if (!mode.spinner) {
+const SILENT_MODE = {
+    plain: true,
+    color: false,
+    tty: false,
+    ci: true,
+    spinner: false,
+    debug: false,
+    logLevel: 'quiet'
+};
+
+function createNoopSpinner() {
+    return {
+        start() { },
+        update() { },
+        stop() { },
+        succeed() { },
+        fail() { }
+    };
+}
+
+function normalizeLevel(level) {
+    return level === 'quiet' || level === 'verbose' ? level : 'normal';
+}
+
+function shouldEmit(mode, tag) {
+    const level = normalizeLevel(mode.logLevel);
+    if (level === 'quiet') {
+        return tag === 'OK' || tag === 'WARN' || tag === 'ERR';
+    }
+    return true;
+}
+
+function createWriter(runtime, mode, sink = null) {
+    if (typeof sink === 'function') {
+        return sink;
+    }
+    return (stream, text) => {
+        const out = stream === 'stderr' ? runtime.stderr : runtime.stdout;
+        write(out, text);
+    };
+}
+
+function classifyChildLine(line) {
+    const trimmed = String(line || '').trim();
+    if (!trimmed) {
+        return null;
+    }
+
+    const vendorCache = trimmed.match(/^\[zenith\]\s+Vendor cache (hit|miss):\s+(.+)$/);
+    if (vendorCache) {
+        return {
+            tag: 'BUILD',
+            glyph: '•',
+            message: `vendor cache ${vendorCache[1]} (${vendorCache[2]})`,
+            onceKey: `vendor-cache:${vendorCache[1]}:${vendorCache[2]}`
+        };
+    }
+
+    const vendorBundle = trimmed.match(/^\[zenith\]\s+Vendor bundle:\s+(.+)$/);
+    if (vendorBundle) {
         return {
-            start() { },
-            update() { },
-            stop() { },
-            succeed() { },
-            fail() { }
+            tag: 'BUILD',
+            glyph: '•',
+            message: `vendor bundle ${vendorBundle[1]}`,
+            onceKey: `vendor-bundle:${vendorBundle[1]}`
         };
     }
 
-    let interval = null;
-    let frame = 0;
-    let message = '';
+    const bundler = trimmed.match(/^\[zenith-bundler\]\s*(.+)$/);
+    if (bundler) {
+        const message = bundler[1].trim();
+        const lower = message.toLowerCase();
+        if (lower.includes('warning')) {
+            return {
+                tag: 'WARN',
+                glyph: '⚠',
+                message,
+                onceKey: `bundler-warning:${message}`
+            };
+        }
+        if (lower.includes('error') || lower.includes('failed')) {
+            return {
+                tag: 'ERR',
+                glyph: '✖',
+                message
+            };
+        }
+        return {
+            tag: 'BUILD',
+            glyph: '•',
+            message
+        };
+    }
 
-    const paint = () => {
-        const current = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
-        stderr.write(`\r[zenith] ${current} ${message}`);
-        frame += 1;
-    };
+    const zenith = trimmed.match(/^\[zenith\]\s+(.+)$/);
+    if (zenith) {
+        return {
+            tag: 'BUILD',
+            glyph: '•',
+            message: zenith[1].trim(),
+            onceKey: `zenith-child:${zenith[1].trim()}`
+        };
+    }
 
-    const clear = () => {
-        stderr.write('\r');
-        stderr.write(' '.repeat(message.length + 12));
-        stderr.write('\r');
-    };
+    const compilerWarning = trimmed.match(/warning\[[^\]]+\]/i);
+    if (compilerWarning) {
+        return {
+            tag: 'WARN',
+            glyph: '⚠',
+            message: trimmed,
+            onceKey: `compiler-warning:${trimmed}`
+        };
+    }
 
     return {
-        start(nextMessage) {
-            message = String(nextMessage || '');
-            clearInterval(interval);
-            frame = 0;
-            paint();
-            interval = setInterval(paint, 80);
-        },
-        update(nextMessage) {
-            message = String(nextMessage || '');
-        },
-        stop() {
-            clearInterval(interval);
-            interval = null;
-            clear();
-        },
-        succeed(nextMessage) {
-            this.stop();
-            write(stderr, `[zenith] OK: ${nextMessage}`);
-        },
-        fail(nextMessage) {
-            this.stop();
-            write(stderr, `[zenith] ERROR: ${nextMessage}`);
-        }
+        tag: 'BUILD',
+        glyph: '•',
+        message: trimmed
     };
 }
 
-/**
- * @param {NodeJS.Process} runtime
- */
-export function createLogger(runtime = process) {
-    const mode = getUiMode(runtime);
-    const stdout = runtime.stdout;
-    const stderr = runtime.stderr;
-    const spinner = createSpinner(mode, stderr);
+function createBaseLogger({ runtime = process, mode, sink = null, silent = false } = {}) {
+    const resolvedMode = mode || (silent ? SILENT_MODE : getUiMode(runtime));
+    const once = new Set();
+    const writeLine = createWriter(runtime, resolvedMode, sink);
+
+    function emit(tag, glyph, message, options = {}) {
+        if (options.onceKey) {
+            if (once.has(options.onceKey)) {
+                return false;
+            }
+            once.add(options.onceKey);
+        }
+
+        if (!shouldEmit(resolvedMode, tag)) {
+            return false;
+        }
+
+        const stream = tag === 'WARN' || tag === 'ERR' ? 'stderr' : 'stdout';
+        writeLine(stream, formatLine(resolvedMode, { glyph, tag, text: message }));
+        if (options.hint) {
+            writeLine(stream, formatHint(resolvedMode, options.hint));
+        }
+        return true;
+    }
 
     return {
-        mode,
-        spinner,
+        mode: resolvedMode,
+        spinner: createNoopSpinner(),
         heading(text) {
-            write(stdout, formatHeading(mode, text));
+            writeLine('stdout', formatHeading(resolvedMode, text));
+        },
+        print(text) {
+            writeLine('stdout', String(text));
         },
-        info(text) {
-            if (mode.plain) {
-                write(stdout, `[zenith] INFO: ${text}`);
-                return;
+        summary(rows, tag = 'BUILD') {
+            const table = formatSummaryTable(resolvedMode, rows, tag);
+            if (table) {
+                writeLine('stdout', table);
             }
-            write(stdout, formatStep(mode, text));
         },
-        success(text) {
-            write(stdout, `[zenith] OK: ${text}`);
+        dev(message, options = {}) {
+            return emit('DEV', '•', message, options);
         },
-        warn(text) {
-            write(stderr, `[zenith] WARN: ${text}`);
+        build(message, options = {}) {
+            return emit('BUILD', '•', message, options);
         },
-        error(err) {
-            write(stderr, formatErrorBlock(err, mode));
+        hmr(message, options = {}) {
+            return emit('HMR', '•', message, options);
         },
-        summary(rows) {
-            const table = formatSummaryTable(mode, rows);
-            if (table) {
-                write(stdout, table);
+        router(message, options = {}) {
+            return emit('ROUTER', '•', message, options);
+        },
+        css(message, options = {}) {
+            return emit('CSS', '•', message, options);
+        },
+        ok(message, options = {}) {
+            return emit('OK', '✓', message, options);
+        },
+        warn(message, options = {}) {
+            return emit('WARN', '⚠', message, options);
+        },
+        error(messageOrError, options = {}) {
+            const hasStructuredError = messageOrError instanceof Error || typeof messageOrError === 'object';
+            if (hasStructuredError && !options.hint && !options.onceKey && !options.error) {
+                writeLine('stderr', formatErrorBlock(messageOrError, resolvedMode));
+                return true;
+            }
+            const detail = options.error || messageOrError;
+            const formatted = detail instanceof Error || typeof detail === 'object'
+                ? formatErrorBlock(detail, resolvedMode)
+                : null;
+            if (formatted && (resolvedMode.logLevel === 'verbose' || resolvedMode.debug)) {
+                writeLine('stderr', formatted);
+                return true;
             }
+            const text = typeof messageOrError === 'string'
+                ? messageOrError
+                : (detail instanceof Error ? detail.message : String(detail || 'Command failed'));
+            return emit('ERR', '✖', text, options);
         },
-        print(text) {
-            write(stdout, String(text));
+        verbose(tag, message, options = {}) {
+            if (resolvedMode.logLevel !== 'verbose') {
+                return false;
+            }
+            return emit(tag, '•', message, options);
+        },
+        childLine(source, line, options = {}) {
+            const entry = classifyChildLine(line);
+            if (!entry) {
+                return false;
+            }
+            const streamHint = options.stream === 'stderr';
+            const isVerbose = resolvedMode.logLevel === 'verbose';
+            const isSeverity = entry.tag === 'WARN' || entry.tag === 'ERR';
+            if (!isVerbose && !isSeverity && options.showInfo === false) {
+                return false;
+            }
+            const onceKey = options.onceKey || entry.onceKey;
+            const message = options.prefix
+                ? `${options.prefix}${entry.message}`
+                : entry.message;
+            return emit(entry.tag, entry.glyph, message, {
+                ...options,
+                onceKey,
+                hint: options.hint,
+                stream: streamHint ? 'stderr' : undefined
+            });
+        },
+        info(message) {
+            return emit('DEV', '•', message);
+        },
+        success(message) {
+            return emit('OK', '✓', message);
         }
     };
 }
+
+export function createZenithLogger(runtime = process, options = {}) {
+    const mode = getUiMode(runtime);
+    if (options.logLevel) {
+        mode.logLevel = normalizeLevel(options.logLevel);
+    }
+    return createBaseLogger({ runtime, mode });
+}
+
+export function createSilentLogger() {
+    return createBaseLogger({
+        mode: SILENT_MODE,
+        sink: () => { },
+        silent: true
+    });
+}
+
+export function createLogger(runtime = process, options = {}) {
+    return createZenithLogger(runtime, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/cli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Deterministic project orchestrator for Zenith framework",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@zenithbuild/compiler": "0.6.0"
+    "@zenithbuild/compiler": "0.6.2",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",