@zenithbuild/cli 0.5.0-beta.2.6 → 0.6.2

package/dist/resolve-components.js

@@ -245,6 +245,9 @@ function findNextKnownTag(source, registry, startIndex) {
         if (!registry.has(name)) {
             continue;
         }
+        if (isInsideExpressionScope(source, match.index)) {
+            continue;
+        }
         return {
             name,
             start: match.index,
@@ -256,6 +259,111 @@ function findNextKnownTag(source, registry, startIndex) {
     return null;
 }
 
+/**
+ * Detect whether `index` is inside a `{ ... }` expression scope.
+ *
+ * This prevents component macro expansion inside embedded markup expressions,
+ * which must remain expression-local so the compiler can lower them safely.
+ *
+ * @param {string} source
+ * @param {number} index
+ * @returns {boolean}
+ */
+function isInsideExpressionScope(source, index) {
+    let depth = 0;
+    let mode = 'code';
+    let escaped = false;
+    const lower = source.toLowerCase();
+
+    for (let i = 0; i < index; i++) {
+        if (mode === 'code') {
+            if (lower.startsWith('<script', i)) {
+                const close = lower.indexOf('</script>', i + 7);
+                if (close < 0 || close >= index) {
+                    return false;
+                }
+                i = close + '</script>'.length - 1;
+                continue;
+            }
+            if (lower.startsWith('<style', i)) {
+                const close = lower.indexOf('</style>', i + 6);
+                if (close < 0 || close >= index) {
+                    return false;
+                }
+                i = close + '</style>'.length - 1;
+                continue;
+            }
+        }
+
+        const ch = source[i];
+        const next = i + 1 < index ? source[i + 1] : '';
+
+        if (mode === 'line-comment') {
+            if (ch === '\n') {
+                mode = 'code';
+            }
+            continue;
+        }
+        if (mode === 'block-comment') {
+            if (ch === '*' && next === '/') {
+                mode = 'code';
+                i += 1;
+            }
+            continue;
+        }
+        if (mode === 'single-quote' || mode === 'double-quote' || mode === 'template') {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (
+                (mode === 'single-quote' && ch === "'") ||
+                (mode === 'double-quote' && ch === '"') ||
+                (mode === 'template' && ch === '`')
+            ) {
+                mode = 'code';
+            }
+            continue;
+        }
+
+        if (ch === '/' && next === '/') {
+            mode = 'line-comment';
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            mode = 'block-comment';
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            mode = 'single-quote';
+            continue;
+        }
+        if (ch === '"') {
+            mode = 'double-quote';
+            continue;
+        }
+        if (ch === '`') {
+            mode = 'template';
+            continue;
+        }
+        if (ch === '{') {
+            depth += 1;
+            continue;
+        }
+        if (ch === '}') {
+            depth = Math.max(0, depth - 1);
+        }
+    }
+
+    return depth > 0;
+}
+
 /**
  * Find the matching </Name> for an opening tag, accounting for nested
  * tags with the same name.

package/dist/server-contract.js

@@ -2,9 +2,73 @@
 // ---------------------------------------------------------------------------
 // Shared validation and payload resolution logic for <script server> blocks.
 
-const NEW_KEYS = new Set(['data', 'load', 'prerender']);
+const NEW_KEYS = new Set(['data', 'load', 'guard', 'prerender']);
 const LEGACY_KEYS = new Set(['ssr_data', 'props', 'ssr', 'prerender']);
-const ALLOWED_KEYS = new Set(['data', 'load', 'prerender', 'ssr_data', 'props', 'ssr']);
+const ALLOWED_KEYS = new Set(['data', 'load', 'guard', 'prerender', 'ssr_data', 'props', 'ssr']);
+
+const ROUTE_RESULT_KINDS = new Set(['allow', 'redirect', 'deny', 'data']);
+
+export function allow() {
+    return { kind: 'allow' };
+}
+
+export function redirect(location, status = 302) {
+    return {
+        kind: 'redirect',
+        location: String(location || ''),
+        status: Number.isInteger(status) ? status : 302
+    };
+}
+
+export function deny(status = 403, message = undefined) {
+    return {
+        kind: 'deny',
+        status: Number.isInteger(status) ? status : 403,
+        message: typeof message === 'string' ? message : undefined
+    };
+}
+
+export function data(payload) {
+    return { kind: 'data', data: payload };
+}
+
+function isRouteResultLike(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const kind = value.kind;
+    return typeof kind === 'string' && ROUTE_RESULT_KINDS.has(kind);
+}
+
+function assertValidRouteResultShape(value, where, allowedKinds) {
+    if (!isRouteResultLike(value)) {
+        throw new Error(`[Zenith] ${where}: invalid route result. Expected object with kind.`);
+    }
+    const kind = value.kind;
+    if (!allowedKinds.has(kind)) {
+        throw new Error(
+            `[Zenith] ${where}: kind "${kind}" is not allowed here (allowed: ${Array.from(allowedKinds).join(', ')}).`
+        );
+    }
+
+    if (kind === 'redirect') {
+        if (typeof value.location !== 'string' || value.location.length === 0) {
+            throw new Error(`[Zenith] ${where}: redirect requires non-empty string location.`);
+        }
+        if (value.status !== undefined && (!Number.isInteger(value.status) || value.status < 300 || value.status > 399)) {
+            throw new Error(`[Zenith] ${where}: redirect status must be an integer 3xx.`);
+        }
+    }
+
+    if (kind === 'deny') {
+        if (!Number.isInteger(value.status) || (value.status !== 401 && value.status !== 403)) {
+            throw new Error(`[Zenith] ${where}: deny status must be 401 or 403.`);
+        }
+        if (value.message !== undefined && typeof value.message !== 'string') {
+            throw new Error(`[Zenith] ${where}: deny message must be a string when provided.`);
+        }
+    }
+}
 
 export function validateServerExports({ exports, filePath }) {
     const exportKeys = Object.keys(exports);
@@ -16,6 +80,7 @@ export function validateServerExports({ exports, filePath }) {
 
     const hasData = 'data' in exports;
     const hasLoad = 'load' in exports;
+    const hasGuard = 'guard' in exports;
 
     const hasNew = hasData || hasLoad;
     const hasLegacy = ('ssr_data' in exports) || ('props' in exports) || ('ssr' in exports);
@@ -47,6 +112,20 @@ export function validateServerExports({ exports, filePath }) {
             throw new Error(`[Zenith] ${filePath}: "load(ctx)" must not contain rest parameters.`);
         }
     }
+
+    if (hasGuard && typeof exports.guard !== 'function') {
+        throw new Error(`[Zenith] ${filePath}: "guard" must be a function.`);
+    }
+    if (hasGuard) {
+        if (exports.guard.length !== 1) {
+            throw new Error(`[Zenith] ${filePath}: "guard(ctx)" must take exactly 1 argument.`);
+        }
+        const fnStr = exports.guard.toString();
+        const paramsMatch = fnStr.match(/^[^{=]+\(([^)]*)\)/);
+        if (paramsMatch && paramsMatch[1].includes('...')) {
+            throw new Error(`[Zenith] ${filePath}: "guard(ctx)" must not contain rest parameters.`);
+        }
+    }
 }
 
 export function assertJsonSerializable(value, where = 'payload') {
@@ -110,37 +189,97 @@ export function assertJsonSerializable(value, where = 'payload') {
     walk(value, '$');
 }
 
-export async function resolveServerPayload({ exports, ctx, filePath }) {
+export async function resolveRouteResult({ exports, ctx, filePath, guardOnly = false }) {
     validateServerExports({ exports, filePath });
 
+    const trace = {
+        guard: 'none',
+        load: 'none'
+    };
+
+    if ('guard' in exports) {
+        const guardRaw = await exports.guard(ctx);
+        const guardResult = guardRaw == null ? allow() : guardRaw;
+        if (guardResult.kind === 'data') {
+            throw new Error(`[Zenith] ${filePath}: guard(ctx) returned data(payload) which is a critical invariant violation. guard() can only return allow(), redirect(), or deny(). Use load(ctx) for data injection.`);
+        }
+        assertValidRouteResultShape(
+            guardResult,
+            `${filePath}: guard(ctx) return`,
+            new Set(['allow', 'redirect', 'deny'])
+        );
+        trace.guard = guardResult.kind;
+        if (guardResult.kind === 'redirect' || guardResult.kind === 'deny') {
+            return { result: guardResult, trace };
+        }
+    }
+
+    if (guardOnly) {
+        return { result: allow(), trace };
+    }
+
     let payload;
     if ('load' in exports) {
-        payload = await exports.load(ctx);
-        assertJsonSerializable(payload, `${filePath}: load(ctx) return`);
-        return payload;
+        const loadRaw = await exports.load(ctx);
+        let loadResult = null;
+        if (isRouteResultLike(loadRaw)) {
+            loadResult = loadRaw;
+            assertValidRouteResultShape(
+                loadResult,
+                `${filePath}: load(ctx) return`,
+                new Set(['data', 'redirect', 'deny'])
+            );
+        } else {
+            assertJsonSerializable(loadRaw, `${filePath}: load(ctx) return`);
+            loadResult = data(loadRaw);
+        }
+        trace.load = loadResult.kind;
+        return { result: loadResult, trace };
     }
     if ('data' in exports) {
         payload = exports.data;
         assertJsonSerializable(payload, `${filePath}: data export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
 
     // legacy fallback
     if ('ssr_data' in exports) {
         payload = exports.ssr_data;
         assertJsonSerializable(payload, `${filePath}: ssr_data export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
     if ('props' in exports) {
         payload = exports.props;
         assertJsonSerializable(payload, `${filePath}: props export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
     }
     if ('ssr' in exports) {
         payload = exports.ssr;
         assertJsonSerializable(payload, `${filePath}: ssr export`);
-        return payload;
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+
+    return { result: data({}), trace };
+}
+
+export async function resolveServerPayload({ exports, ctx, filePath }) {
+    const resolved = await resolveRouteResult({ exports, ctx, filePath });
+    if (!resolved || !resolved.result || typeof resolved.result !== 'object') {
+        return {};
+    }
+
+    if (resolved.result.kind === 'data') {
+        return resolved.result.data;
+    }
+    if (resolved.result.kind === 'allow') {
+        return {};
     }
 
-    return {};
+    throw new Error(
+        `[Zenith] ${filePath}: resolveServerPayload() expected data but received ${resolved.result.kind}. Use resolveRouteResult() for guard/load flows.`
+    );
 }

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,50 +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 colorize(mode, token, text) {
+function getColors(mode) {
+    return pc.createColors(Boolean(mode?.color));
+}
+
+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 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) {
+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');
 }
 
@@ -62,21 +90,53 @@ function normalizeFileLinePath(line) {
 
     const prefix = match[1];
     const filePath = match[2].trim();
-    if (!filePath.startsWith('/') && !/^[A-Za-z]:\\/.test(filePath)) {
-        return line;
+    const normalized = normalizePathForDisplay(filePath);
+    return `${prefix}${normalized}`;
+}
+
+function normalizePathForDisplay(filePath) {
+    const value = String(filePath || '').trim();
+    if (!value) {
+        return DEFAULT_FILE;
+    }
+    if (!value.startsWith('/') && !/^[A-Za-z]:\\/.test(value)) {
+        return value;
     }
 
     const cwd = process.cwd();
     const cwdWithSep = cwd.endsWith(sep) ? cwd : `${cwd}${sep}`;
-    if (filePath === cwd) {
-        return `${prefix}.`;
+    if (value === cwd) {
+        return DEFAULT_FILE;
     }
-    if (filePath.startsWith(cwdWithSep)) {
-        const relativePath = relative(cwd, filePath).replaceAll('\\', '/');
-        return `${prefix}${relativePath || '.'}`;
+    if (value.startsWith(cwdWithSep)) {
+        const relativePath = relative(cwd, value).replaceAll('\\', '/');
+        return relativePath || DEFAULT_FILE;
     }
 
-    return line;
+    return value;
+}
+
+function inferPhaseFromArgv() {
+    const knownPhases = new Set(['build', 'dev', 'preview']);
+    for (const arg of process.argv.slice(2)) {
+        if (knownPhases.has(arg)) {
+            return arg;
+        }
+    }
+    return DEFAULT_PHASE;
+}
+
+function extractFileFromMessage(message) {
+    const match = String(message || '').match(/\bFile:\s+([^\n]+)/);
+    return match ? match[1].trim() : '';
+}
+
+function formatHintUrl(code) {
+    const slug = String(code || 'CLI_ERROR')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${DEFAULT_HINT_BASE}#${slug || 'cli-error'}`;
 }
 
 export function normalizeErrorMessagePaths(message) {
@@ -96,32 +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 }} */ (normalized);
-    const kind = sanitizeErrorMessage(maybe.kind || maybe.code || 'CLI_ERROR');
-    const phase = maybe.phase ? sanitizeErrorMessage(maybe.phase) : '';
-    const code = maybe.code ? sanitizeErrorMessage(maybe.code) : '';
+    const maybe = /** @type {{ code?: unknown, phase?: unknown, kind?: unknown, file?: unknown, hint?: unknown }} */ (normalized);
+    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}`);
-    if (phase) {
-        lines.push(`[zenith] Phase: ${phase}`);
-    }
-    if (code) {
-        lines.push(`[zenith] Code: ${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));
     }