@zenithbuild/cli 0.5.0-beta.2.5 → 0.6.0

package/README.md

@@ -5,6 +5,11 @@
 
 The command-line interface for developing and building Zenith applications.
 
+## Canonical Docs
+
+- CLI contract: `../zenith-docs/documentation/cli-contract.md`
+- Script server/data contract: `../zenith-docs/documentation/contracts/server-data.md`
+
 ## Overview
 
 `@zenithbuild/cli` provides the toolchain needed to manage Zenith projects. While `create-zenith` is for scaffolding, this CLI is for the daily development loop: serving apps, building for production, and managing plugins.

package/dist/build.js

@@ -15,7 +15,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { generateManifest } from './manifest.js';
 import { buildComponentRegistry, expandComponents, extractTemplate, isDocumentMode } from './resolve-components.js';
@@ -63,10 +63,34 @@ const COMPILER_BIN = resolveBinary([
     resolve(CLI_ROOT, '../zenith-compiler/target/release/zenith-compiler')
 ]);
 
-const BUNDLER_BIN = resolveBinary([
-    resolve(CLI_ROOT, '../bundler/target/release/zenith-bundler'),
-    resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
-]);
+function getBundlerBin() {
+    const envBin = process.env.ZENITH_BUNDLER_BIN;
+    if (envBin && typeof envBin === 'string' && existsSync(envBin)) {
+        return envBin;
+    }
+    return resolveBinary([
+        resolve(CLI_ROOT, '../bundler/target/release/zenith-bundler'),
+        resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
+    ]);
+}
+
+/**
+ * Build a per-build warning emitter that deduplicates repeated compiler lines.
+ *
+ * @param {(line: string) => void} sink
+ * @returns {(line: string) => void}
+ */
+export function createCompilerWarningEmitter(sink = (line) => console.warn(line)) {
+    const emitted = new Set();
+    return (line) => {
+        const text = String(line || '').trim();
+        if (!text || emitted.has(text)) {
+            return;
+        }
+        emitted.add(text);
+        sink(text);
+    };
+}
 
 /**
  * Run the compiler process and parse its JSON stdout.
@@ -77,14 +101,20 @@ const BUNDLER_BIN = resolveBinary([
  *
  * @param {string} filePath — path for diagnostics (and file reading when no stdinSource)
  * @param {string} [stdinSource] — if provided, piped to compiler via stdin
+ * @param {object} compilerRunOptions
+ * @param {(warning: string) => void} [compilerRunOptions.onWarning]
+ * @param {boolean} [compilerRunOptions.suppressWarnings]
  * @returns {object}
  */
-function runCompiler(filePath, stdinSource, compilerOpts = {}) {
+function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRunOptions = {}) {
     const args = stdinSource !== undefined
         ? ['--stdin', filePath]
         : [filePath];
     if (compilerOpts?.experimentalEmbeddedMarkup) {
-        args.push('--experimental-embedded-markup');
+        args.push('--embedded-markup-expressions');
+    }
+    if (compilerOpts?.strictDomLints) {
+        args.push('--strict-dom-lints');
     }
     const opts = { encoding: 'utf8' };
     if (stdinSource !== undefined) {
@@ -102,6 +132,20 @@ function runCompiler(filePath, stdinSource, compilerOpts = {}) {
         );
     }
 
+    if (result.stderr && result.stderr.trim().length > 0 && compilerRunOptions.suppressWarnings !== true) {
+        const lines = String(result.stderr)
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const line of lines) {
+            if (typeof compilerRunOptions.onWarning === 'function') {
+                compilerRunOptions.onWarning(line);
+            } else {
+                console.warn(line);
+            }
+        }
+    }
+
     try {
         return JSON.parse(result.stdout);
     } catch (err) {
@@ -143,7 +187,7 @@ function buildComponentExpressionRewrite(compPath, componentSource, compIr, comp
 
     let templateIr;
     try {
-        templateIr = runCompiler(compPath, templateOnly, compilerOpts);
+        templateIr = runCompiler(compPath, templateOnly, compilerOpts, { suppressWarnings: true });
     } catch {
         return out;
     }
@@ -232,6 +276,9 @@ function applyExpressionRewrites(pageIr, expressionMap, ambiguous) {
             bindings[index].literal === current
         ) {
             bindings[index].literal = rewritten;
+            if (bindings[index].compiled_expr === current) {
+                bindings[index].compiled_expr = rewritten;
+            }
         }
     }
 }
@@ -271,6 +318,15 @@ function rewriteLegacyMarkupIdentifiers(pageIr) {
             _LEGACY_MARKUP_RE.lastIndex = 0;
             bindings[i].literal = bindings[i].literal.replace(_LEGACY_MARKUP_RE, '__ZENITH_INTERNAL_ZENHTML');
         }
+        if (
+            bindings[i] &&
+            typeof bindings[i] === 'object' &&
+            typeof bindings[i].compiled_expr === 'string' &&
+            bindings[i].compiled_expr.includes(_LEGACY_MARKUP_IDENT)
+        ) {
+            _LEGACY_MARKUP_RE.lastIndex = 0;
+            bindings[i].compiled_expr = bindings[i].compiled_expr.replace(_LEGACY_MARKUP_RE, '__ZENITH_INTERNAL_ZENHTML');
+        }
     }
 }
 
@@ -452,7 +508,7 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
     const scriptRe = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
     const serverMatches = [];
     const reservedServerExportRe =
-        /\bexport\s+const\s+(?:data|prerender)\b|\bexport\s+(?:async\s+)?function\s+load\s*\(|\bexport\s+const\s+load\s*=/;
+        /\bexport\s+const\s+(?:data|prerender|guard|load)\b|\bexport\s+(?:async\s+)?function\s+(?:load|guard)\s*\(|\bexport\s+const\s+(?:load|guard)\s*=/;
 
     for (const match of source.matchAll(scriptRe)) {
         const attrs = String(match[1] || '');
@@ -463,8 +519,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             throw new Error(
                 `Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
-                `  Reason: data/load/prerender exports are only allowed in <script server lang="ts">\n` +
-                `  Example: move export const data or export const load into <script server lang="ts">`
+                `  Reason: guard/load/data exports are only allowed in <script server lang="ts"> or adjacent .guard.ts / .load.ts files\n` +
+                `  Example: move the export into <script server lang="ts">`
             );
         }
 
@@ -535,6 +591,25 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         );
     }
 
+    const guardFnMatch = serverSource.match(/\bexport\s+(?:async\s+)?function\s+guard\s*\(([^)]*)\)/);
+    const guardConstParenMatch = serverSource.match(/\bexport\s+const\s+guard\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>/);
+    const guardConstSingleArgMatch = serverSource.match(
+        /\bexport\s+const\s+guard\s*=\s*(?:async\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/
+    );
+    const hasGuard = Boolean(guardFnMatch || guardConstParenMatch || guardConstSingleArgMatch);
+    const guardMatchCount =
+        Number(Boolean(guardFnMatch)) +
+        Number(Boolean(guardConstParenMatch)) +
+        Number(Boolean(guardConstSingleArgMatch));
+    if (guardMatchCount > 1) {
+        throw new Error(
+            `Zenith server script contract violation:\n` +
+            `  File: ${sourceFile}\n` +
+            `  Reason: multiple guard exports detected\n` +
+            `  Example: keep exactly one export const guard = async (ctx) => ({ ... })`
+        );
+    }
+
     const hasData = /\bexport\s+const\s+data\b/.test(serverSource);
     const hasSsrData = /\bexport\s+const\s+ssr_data\b/.test(serverSource);
     const hasSsr = /\bexport\s+const\s+ssr\b/.test(serverSource);
@@ -575,6 +650,24 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         }
     }
 
+    if (hasGuard) {
+        const singleArg = String(guardConstSingleArgMatch?.[1] || '').trim();
+        const paramsText = String((guardFnMatch || guardConstParenMatch)?.[1] || '').trim();
+        const arity = singleArg
+            ? 1
+            : paramsText.length === 0
+                ? 0
+                : paramsText.split(',').length;
+        if (arity !== 1) {
+            throw new Error(
+                `Zenith server script contract violation:\n` +
+                `  File: ${sourceFile}\n` +
+                `  Reason: guard(ctx) must accept exactly one argument\n` +
+                `  Example: export const guard = async (ctx) => ({ ... })`
+            );
+        }
+    }
+
     const prerenderMatch = serverSource.match(/\bexport\s+const\s+prerender\s*=\s*([^\n;]+)/);
     let prerender = false;
     if (prerenderMatch) {
@@ -596,6 +689,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             serverScript: {
                 source: serverSource,
                 prerender,
+                has_guard: hasGuard,
+                has_load: hasLoad,
                 source_path: sourceFile
             }
         };
@@ -609,6 +704,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         serverScript: {
             source: serverSource,
             prerender,
+            has_guard: hasGuard,
+            has_load: hasLoad,
             source_path: sourceFile
         }
     };
@@ -741,11 +838,7 @@ function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStati
                 : rebased;
             const withPropsPrelude = injectPropsPrelude(filteredImports, options.componentAttrs || '');
             const transpiled = transpileTypeScriptToJs(withPropsPrelude, compPath);
-            const withRefFallbacks = injectRefFallbacksInZenMount(
-                transpiled,
-                options.refFallbacks || []
-            );
-            const deduped = dedupeStaticImportsInSource(withRefFallbacks, seenStaticImports);
+            const deduped = dedupeStaticImportsInSource(transpiled, seenStaticImports);
             const deferred = deferComponentRuntimeBlock(deduped);
             if (deferred.trim().length > 0 && !pageIr.hoisted.code.includes(deferred)) {
                 pageIr.hoisted.code.push(deferred);
@@ -868,7 +961,7 @@ function transpileTypeScriptToJs(source, sourceFile) {
             fileName: sourceFile,
             compilerOptions: {
                 module: ts.ModuleKind.ESNext,
-                target: ts.ScriptTarget.ES2022,
+                target: ts.ScriptTarget.ES5,
                 importsNotUsedAsValues: ts.ImportsNotUsedAsValues.Preserve,
                 verbatimModuleSyntax: true,
                 newLine: ts.NewLineKind.LineFeed,
@@ -1103,7 +1196,7 @@ function injectPropsPrelude(source, attrs) {
     }
 
     const propsLiteral = renderPropsLiteralFromAttrs(attrs);
-    return `const props = ${propsLiteral};\n${source}`;
+    return `var props = ${propsLiteral};\n${source}`;
 }
 
 /**
@@ -1155,96 +1248,6 @@ function deferComponentRuntimeBlock(source) {
     return wrapped;
 }
 
-/**
- * @param {string} componentSource
- * @returns {Array<{ identifier: string, selector: string }>}
- */
-function extractRefFallbackAssignments(componentSource) {
-    const template = extractTemplate(componentSource);
-    const tagRe = /<[^>]*ref=\{([A-Za-z_$][A-Za-z0-9_$]*)\}[^>]*>/g;
-    const out = [];
-    const seen = new Set();
-
-    let match;
-    while ((match = tagRe.exec(template)) !== null) {
-        const tag = match[0];
-        const identifier = match[1];
-        const attrMatch = tag.match(/\b(data-[a-z0-9-]+-runtime)\b/i)
-            || tag.match(/\b(data-[a-z0-9-]+)\b/i);
-        if (!attrMatch) {
-            continue;
-        }
-
-        const selector = `[${attrMatch[1]}]`;
-        const key = `${identifier}:${selector}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        out.push({ identifier, selector });
-    }
-
-    return out;
-}
-
-/**
- * @param {string} source
- * @param {string} originalIdentifier
- * @returns {string | null}
- */
-function resolveRenamedRefIdentifier(source, originalIdentifier) {
-    const re = /const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*ref\s*\(/g;
-    let match;
-    while ((match = re.exec(source)) !== null) {
-        const candidate = match[1];
-        if (candidate === originalIdentifier || candidate.endsWith(`_${originalIdentifier}`)) {
-            return candidate;
-        }
-    }
-    return null;
-}
-
-/**
- * @param {string} source
- * @param {Array<{ identifier: string, selector: string }>} refFallbacks
- * @returns {string}
- */
-function injectRefFallbacksInZenMount(source, refFallbacks) {
-    if (!Array.isArray(refFallbacks) || refFallbacks.length === 0) {
-        return source;
-    }
-
-    const lines = [];
-    for (let i = 0; i < refFallbacks.length; i++) {
-        const fallback = refFallbacks[i];
-        const refIdentifier = resolveRenamedRefIdentifier(source, fallback.identifier);
-        if (!refIdentifier) {
-            continue;
-        }
-        const selector = JSON.stringify(fallback.selector);
-        const nodeVar = `__zenith_ref_node_${i}`;
-        lines.push(
-            `    if (typeof document !== 'undefined' && ${refIdentifier} && !${refIdentifier}.current) {`,
-            `        const ${nodeVar} = document.querySelector(${selector});`,
-            `        if (${nodeVar}) {`,
-            `            ${refIdentifier}.current = ${nodeVar};`,
-            '        }',
-            '    }'
-        );
-    }
-
-    if (lines.length === 0) {
-        return source;
-    }
-
-    const mountRe = /zenMount\s*\(\s*\([^)]*\)\s*=>\s*\{/;
-    if (!mountRe.test(source)) {
-        return source;
-    }
-
-    return source.replace(mountRe, (match) => `${match}\n${lines.join('\n')}\n`);
-}
-
 /**
  * Run bundler process for one page envelope.
  *
@@ -1255,7 +1258,7 @@ function injectRefFallbacksInZenMount(source, refFallbacks) {
 function runBundler(envelope, outDir) {
     return new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(
-            BUNDLER_BIN,
+            getBundlerBin(),
             ['--out-dir', outDir],
             { stdio: ['pipe', 'inherit', 'inherit'] }
         );
@@ -1333,7 +1336,8 @@ export async function build(options) {
     const softNavigationEnabled = config.softNavigation === true || config.router === true;
     const compilerOpts = {
         typescriptDefault: config.typescriptDefault === true,
-        experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true || config.experimental?.embeddedMarkupExpressions === true
+        experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true || config.experimental?.embeddedMarkupExpressions === true,
+        strictDomLints: config.strictDomLints === true
     };
 
     await rm(outDir, { recursive: true, force: true });
@@ -1356,10 +1360,9 @@ export async function build(options) {
     const componentIrCache = new Map();
     /** @type {Map<string, boolean>} */
     const componentDocumentModeCache = new Map();
-    /** @type {Map<string, Array<{ identifier: string, selector: string }>>} */
-    const componentRefFallbackCache = new Map();
     /** @type {Map<string, { map: Map<string, string>, ambiguous: Set<string> }>} */
     const componentExpressionRewriteCache = new Map();
+    const emitCompilerWarning = createCompilerWarningEmitter((line) => console.warn(line));
 
     const envelopes = [];
     for (const entry of manifest) {
@@ -1367,6 +1370,14 @@ export async function build(options) {
         const rawSource = readFileSync(sourceFile, 'utf8');
         const componentUsageAttrs = collectComponentUsageAttrs(rawSource, registry);
 
+        const baseName = sourceFile.slice(0, -extname(sourceFile).length);
+        let adjacentGuard = null;
+        let adjacentLoad = null;
+        for (const ext of ['.ts', '.js']) {
+            if (!adjacentGuard && existsSync(`${baseName}.guard${ext}`)) adjacentGuard = `${baseName}.guard${ext}`;
+            if (!adjacentLoad && existsSync(`${baseName}.load${ext}`)) adjacentLoad = `${baseName}.load${ext}`;
+        }
+
         // 2a. Expand PascalCase component tags
         const { expandedSource, usedComponents } = expandComponents(
             rawSource, registry, sourceFile
@@ -1375,7 +1386,16 @@ export async function build(options) {
         const compileSource = extractedServer.source;
 
         // 2b. Compile expanded page source via --stdin
-        const pageIr = runCompiler(sourceFile, compileSource, compilerOpts);
+        const pageIr = runCompiler(
+            sourceFile,
+            compileSource,
+            compilerOpts,
+            { onWarning: emitCompilerWarning }
+        );
+
+        const hasGuard = (extractedServer.serverScript && extractedServer.serverScript.has_guard) || adjacentGuard !== null;
+        const hasLoad = (extractedServer.serverScript && extractedServer.serverScript.has_load) || adjacentLoad !== null;
+
         if (extractedServer.serverScript) {
             pageIr.server_script = extractedServer.serverScript;
             pageIr.prerender = extractedServer.serverScript.prerender === true;
@@ -1384,6 +1404,20 @@ export async function build(options) {
             }
         }
 
+        // Static Build Route Protection Policy
+        if (pageIr.prerender === true && (hasGuard || hasLoad)) {
+            throw new Error(
+                `[zenith] Build failed for ${entry.file}: protected routes require SSR/runtime. ` +
+                `Cannot prerender a static route with a \`guard\` or \`load\` function.`
+            );
+        }
+
+        // Apply metadata to IR
+        pageIr.has_guard = hasGuard;
+        pageIr.has_load = hasLoad;
+        pageIr.guard_module_ref = adjacentGuard ? relative(srcDir, adjacentGuard).replaceAll('\\', '/') : null;
+        pageIr.load_module_ref = adjacentLoad ? relative(srcDir, adjacentLoad).replaceAll('\\', '/') : null;
+
         // Ensure IR has required array fields for merging
         pageIr.components_scripts = pageIr.components_scripts || {};
         pageIr.component_instances = pageIr.component_instances || [];
@@ -1409,17 +1443,19 @@ export async function build(options) {
                 compIr = componentIrCache.get(compPath);
             } else {
                 const componentCompileSource = stripStyleBlocks(componentSource);
-                compIr = runCompiler(compPath, componentCompileSource, compilerOpts);
+                compIr = runCompiler(
+                    compPath,
+                    componentCompileSource,
+                    compilerOpts,
+                    { onWarning: emitCompilerWarning }
+                );
                 componentIrCache.set(compPath, compIr);
             }
 
             let isDocMode = componentDocumentModeCache.get(compPath);
-            let refFallbacks = componentRefFallbackCache.get(compPath);
             if (isDocMode === undefined) {
                 isDocMode = isDocumentMode(extractTemplate(componentSource));
-                refFallbacks = extractRefFallbackAssignments(componentSource);
                 componentDocumentModeCache.set(compPath, isDocMode);
-                componentRefFallbackCache.set(compPath, refFallbacks);
             }
 
             let expressionRewrite = componentExpressionRewriteCache.get(compPath);
@@ -1443,8 +1479,7 @@ export async function build(options) {
                     includeCode: true,
                     cssImportsOnly: isDocMode,
                     documentMode: isDocMode,
-                    componentAttrs: (componentUsageAttrs.get(compName) || [])[0] || '',
-                    refFallbacks: refFallbacks || []
+                    componentAttrs: (componentUsageAttrs.get(compName) || [])[0] || ''
                 },
                 seenStaticImports
             );