@zenithbuild/cli 0.5.0-beta.2.5 → 0.6.0

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/format.js

@@ -13,6 +13,9 @@ const ANSI = {
     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';
 
 function colorize(mode, token, text) {
     if (!mode.color) {
@@ -62,21 +65,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) {
@@ -102,22 +137,26 @@ export function normalizeError(err) {
  */
 export function formatErrorBlock(err, mode) {
     const normalized = normalizeError(err);
-    const maybe = /** @type {{ code?: unknown, phase?: unknown, kind?: unknown }} */ (normalized);
+    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) : '';
-    const code = maybe.code ? sanitizeErrorMessage(maybe.code) : '';
+    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 file = normalizePathForDisplay(
+        sanitizeErrorMessage(maybe.file || extractFileFromMessage(message) || DEFAULT_FILE)
+    );
+    const hint = sanitizeErrorMessage(maybe.hint || formatHintUrl(code));
 
     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] 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}`);
 
     if (mode.debug && normalized.stack) {

package/package.json

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