@zenithbuild/cli 0.6.3 → 0.6.4

package/dist/build.js

@@ -16,13 +16,11 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 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';
+import { resolveBundlerBin, resolveCompilerBin } from './toolchain-paths.js';
+import { maybeWarnAboutZenithVersionMismatch } from './version-check.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const CLI_ROOT = resolve(__dirname, '..');
 const require = createRequire(import.meta.url);
 let cachedTypeScript = undefined;
 
@@ -40,40 +38,6 @@ function loadTypeScriptApi() {
     return cachedTypeScript;
 }
 
-/**
- * Resolve a binary path from deterministic candidates.
- *
- * Supports both repository layout (../zenith-*) and installed package layout
- * under node_modules/@zenithbuild (../compiler, ../bundler).
- *
- * @param {string[]} candidates
- * @returns {string}
- */
-function resolveBinary(candidates) {
-    for (const candidate of candidates) {
-        if (existsSync(candidate)) {
-            return candidate;
-        }
-    }
-    return candidates[0];
-}
-
-const COMPILER_BIN = resolveBinary([
-    resolve(CLI_ROOT, '../compiler/target/release/zenith-compiler'),
-    resolve(CLI_ROOT, '../zenith-compiler/target/release/zenith-compiler')
-]);
-
-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.
  *
@@ -133,9 +97,11 @@ function forwardStreamLines(stream, onLine) {
  * @param {object} compilerRunOptions
  * @param {(warning: string) => void} [compilerRunOptions.onWarning]
  * @param {boolean} [compilerRunOptions.suppressWarnings]
+ * @param {string} [compilerRunOptions.compilerBin]
  * @returns {object}
  */
 function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRunOptions = {}) {
+    const compilerBin = compilerRunOptions.compilerBin || resolveCompilerBin();
     const args = stdinSource !== undefined
         ? ['--stdin', filePath]
         : [filePath];
@@ -150,7 +116,7 @@ function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRunOption
         opts.input = stdinSource;
     }
 
-    const result = spawnSync(COMPILER_BIN, args, opts);
+    const result = spawnSync(compilerBin, args, opts);
 
     if (result.error) {
         throw new Error(`Compiler spawn failed for ${filePath}: ${result.error.message}`);
@@ -200,6 +166,8 @@ function stripStyleBlocks(source) {
  * @param {string} compPath
  * @param {string} componentSource
  * @param {object} compIr
+ * @param {object} compilerOpts
+ * @param {string} compilerBin
  * @returns {{
  *   map: Map<string, string>,
  *   bindings: Map<string, {
@@ -215,7 +183,7 @@ function stripStyleBlocks(source) {
  *   ambiguous: Set<string>
  * }}
  */
-function buildComponentExpressionRewrite(compPath, componentSource, compIr, compilerOpts) {
+function buildComponentExpressionRewrite(compPath, componentSource, compIr, compilerOpts, compilerBin) {
     const out = {
         map: new Map(),
         bindings: new Map(),
@@ -236,7 +204,10 @@ function buildComponentExpressionRewrite(compPath, componentSource, compIr, comp
 
     let templateIr;
     try {
-        templateIr = runCompiler(compPath, templateOnly, compilerOpts, { suppressWarnings: true });
+        templateIr = runCompiler(compPath, templateOnly, compilerOpts, {
+            suppressWarnings: true,
+            compilerBin
+        });
     } catch {
         return out;
     }
@@ -327,7 +298,7 @@ function resolveRewrittenBindingMetadata(pageIr, componentRewrite, binding) {
     }
 
     const pageStateBindings = Array.isArray(pageIr?.hoisted?.state) ? pageIr.hoisted.state : [];
-    const pageSignals = Array.isArray(pageIr?.hoisted?.signals) ? pageIr.hoisted.signals : [];
+    const pageSignals = Array.isArray(pageIr?.signals) ? pageIr.signals : [];
     const pageStateIndexByKey = new Map();
     const pageSignalIndexByStateKey = new Map();
 
@@ -620,6 +591,107 @@ function applyExpressionRewrites(pageIr, expressionMap, bindingMap, ambiguous) {
     }
 }
 
+function applyScopedIdentifierRewrites(pageIr, scopeRewrite) {
+    if (!Array.isArray(pageIr?.expressions) || pageIr.expressions.length === 0) {
+        return;
+    }
+    const bindings = Array.isArray(pageIr.expression_bindings) ? pageIr.expression_bindings : [];
+    const rewriteContext = {
+        scopeRewrite
+    };
+
+    for (let index = 0; index < pageIr.expressions.length; index++) {
+        const current = pageIr.expressions[index];
+        if (typeof current === 'string') {
+            pageIr.expressions[index] = rewritePropsExpression(current, rewriteContext);
+        }
+
+        if (!bindings[index] || typeof bindings[index] !== 'object') {
+            continue;
+        }
+
+        if (typeof bindings[index].literal === 'string') {
+            bindings[index].literal = rewritePropsExpression(bindings[index].literal, rewriteContext);
+        }
+        if (typeof bindings[index].compiled_expr === 'string') {
+            bindings[index].compiled_expr = rewritePropsExpression(bindings[index].compiled_expr, rewriteContext);
+        }
+    }
+}
+
+function synthesizeSignalBackedCompiledExpressions(pageIr) {
+    if (!Array.isArray(pageIr?.expression_bindings) || pageIr.expression_bindings.length === 0) {
+        return;
+    }
+
+    const stateBindings = Array.isArray(pageIr?.hoisted?.state) ? pageIr.hoisted.state : [];
+    const signals = Array.isArray(pageIr?.signals) ? pageIr.signals : [];
+    if (stateBindings.length === 0 || signals.length === 0) {
+        return;
+    }
+
+    const signalIndexByStateKey = new Map();
+    for (let index = 0; index < signals.length; index++) {
+        const stateIndex = signals[index]?.state_index;
+        const stateKey = Number.isInteger(stateIndex) ? stateBindings[stateIndex]?.key : null;
+        if (typeof stateKey === 'string' && stateKey.length > 0) {
+            signalIndexByStateKey.set(stateKey, index);
+        }
+    }
+    if (signalIndexByStateKey.size === 0) {
+        return;
+    }
+
+    for (let index = 0; index < pageIr.expression_bindings.length; index++) {
+        const binding = pageIr.expression_bindings[index];
+        if (!binding || typeof binding !== 'object') {
+            continue;
+        }
+        if (typeof binding.compiled_expr === 'string' && binding.compiled_expr.includes('signalMap.get(')) {
+            continue;
+        }
+
+        const candidate = typeof binding.literal === 'string' && binding.literal.trim().length > 0
+            ? binding.literal
+            : typeof pageIr.expressions?.[index] === 'string'
+                ? pageIr.expressions[index]
+                : null;
+        if (typeof candidate !== 'string' || candidate.trim().length === 0) {
+            continue;
+        }
+
+        let rewritten = candidate;
+        const signalIndices = [];
+        for (const [stateKey, signalIndex] of signalIndexByStateKey.entries()) {
+            if (!rewritten.includes(stateKey)) {
+                continue;
+            }
+            const escaped = stateKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const pattern = new RegExp(`\\b${escaped}\\b`, 'g');
+            if (!pattern.test(rewritten)) {
+                continue;
+            }
+            rewritten = rewritten.replace(pattern, `signalMap.get(${signalIndex}).get()`);
+            signalIndices.push(signalIndex);
+        }
+
+        if (rewritten === candidate || signalIndices.length === 0) {
+            continue;
+        }
+
+        const uniqueSignalIndices = [...new Set(signalIndices)].sort((a, b) => a - b);
+        binding.compiled_expr = rewritten;
+        binding.signal_indices = uniqueSignalIndices;
+        if (uniqueSignalIndices.length === 1) {
+            binding.signal_index = uniqueSignalIndices[0];
+            const stateIndex = signals[uniqueSignalIndices[0]]?.state_index;
+            if (Number.isInteger(stateIndex)) {
+                binding.state_index = stateIndex;
+            }
+        }
+    }
+}
+
 function normalizeExpressionBindingDependencies(pageIr) {
     if (!Array.isArray(pageIr?.expression_bindings) || pageIr.expression_bindings.length === 0) {
         return;
@@ -1653,6 +1725,62 @@ function deriveScopedIdentifierAlias(value) {
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(candidate) ? candidate : ident;
 }
 
+/**
+ * @param {string} source
+ * @returns {string[]}
+ */
+function extractDeclaredIdentifiers(source) {
+    const text = String(source || '').trim();
+    if (!text) {
+        return [];
+    }
+
+    const ts = loadTypeScriptApi();
+    if (ts) {
+        const sourceFile = ts.createSourceFile('zenith-hoisted-declaration.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const identifiers = [];
+        const collectBindingNames = (name) => {
+            if (ts.isIdentifier(name)) {
+                identifiers.push(name.text);
+                return;
+            }
+            if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+                for (const element of name.elements) {
+                    if (ts.isBindingElement(element)) {
+                        collectBindingNames(element.name);
+                    }
+                }
+            }
+        };
+
+        for (const statement of sourceFile.statements) {
+            if (!ts.isVariableStatement(statement)) {
+                continue;
+            }
+            for (const declaration of statement.declarationList.declarations) {
+                collectBindingNames(declaration.name);
+            }
+        }
+
+        if (identifiers.length > 0) {
+            return identifiers;
+        }
+    }
+
+    const fallback = [];
+    const match = text.match(/^\s*(?:const|let|var)\s+([\s\S]+?);?\s*$/);
+    if (!match) {
+        return fallback;
+    }
+    const declarationList = match[1];
+    const identifierRe = /(?:^|,)\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*(?::[^=,]+)?=/g;
+    let found;
+    while ((found = identifierRe.exec(declarationList)) !== null) {
+        fallback.push(found[1]);
+    }
+    return fallback;
+}
+
 /**
  * @param {Map<string, string>} map
  * @param {Set<string>} ambiguous
@@ -1698,9 +1826,131 @@ function buildScopedIdentifierRewrite(ir) {
         recordScopedIdentifierRewrite(out.map, out.ambiguous, deriveScopedIdentifierAlias(fnName), fnName);
     }
 
+    const declarations = Array.isArray(ir?.hoisted?.declarations) ? ir.hoisted.declarations : [];
+    for (const declaration of declarations) {
+        if (typeof declaration !== 'string') {
+            continue;
+        }
+        for (const identifier of extractDeclaredIdentifiers(declaration)) {
+            recordScopedIdentifierRewrite(out.map, out.ambiguous, deriveScopedIdentifierAlias(identifier), identifier);
+        }
+    }
+
     return out;
 }
 
+function rewriteIdentifiersWithinExpression(expr, scopeMap, scopeAmbiguous) {
+    const ts = loadTypeScriptApi();
+    if (!(scopeMap instanceof Map) || !ts) {
+        return expr;
+    }
+
+    const wrapped = `const __zenith_expr__ = (${expr});`;
+    let sourceFile;
+    try {
+        sourceFile = ts.createSourceFile('zenith-expression.ts', wrapped, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    } catch {
+        return expr;
+    }
+
+    const statement = sourceFile.statements[0];
+    if (!statement || !ts.isVariableStatement(statement)) {
+        return expr;
+    }
+    const initializer = statement.declarationList.declarations[0]?.initializer;
+    const root = initializer && ts.isParenthesizedExpression(initializer) ? initializer.expression : initializer;
+    if (!root) {
+        return expr;
+    }
+
+    const replacements = [];
+    const collectBoundNames = (name, target) => {
+        if (ts.isIdentifier(name)) {
+            target.add(name.text);
+            return;
+        }
+        if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+            for (const element of name.elements) {
+                if (ts.isBindingElement(element)) {
+                    collectBoundNames(element.name, target);
+                }
+            }
+        }
+    };
+    const shouldSkipIdentifier = (node, localBindings) => {
+        if (localBindings.has(node.text)) {
+            return true;
+        }
+        const parent = node.parent;
+        if (!parent) {
+            return false;
+        }
+        if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+            return true;
+        }
+        if (ts.isPropertyAssignment(parent) && parent.name === node) {
+            return true;
+        }
+        if (ts.isShorthandPropertyAssignment(parent)) {
+            return true;
+        }
+        if (ts.isBindingElement(parent) && parent.name === node) {
+            return true;
+        }
+        if (ts.isParameter(parent) && parent.name === node) {
+            return true;
+        }
+        return false;
+    };
+    const visit = (node, localBindings) => {
+        let nextBindings = localBindings;
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+            nextBindings = new Set(localBindings);
+            if (node.name && ts.isIdentifier(node.name)) {
+                nextBindings.add(node.name.text);
+            }
+            for (const param of node.parameters) {
+                collectBoundNames(param.name, nextBindings);
+            }
+        }
+
+        if (ts.isIdentifier(node) && !shouldSkipIdentifier(node, nextBindings)) {
+            const rewritten = scopeMap.get(node.text);
+            if (
+                typeof rewritten === 'string' &&
+                rewritten.length > 0 &&
+                rewritten !== node.text &&
+                !(scopeAmbiguous instanceof Set && scopeAmbiguous.has(node.text))
+            ) {
+                replacements.push({
+                    start: node.getStart(sourceFile),
+                    end: node.getEnd(),
+                    text: rewritten
+                });
+            }
+        }
+
+        ts.forEachChild(node, (child) => visit(child, nextBindings));
+    };
+
+    visit(root, new Set());
+    if (replacements.length === 0) {
+        return expr;
+    }
+
+    let rewritten = wrapped;
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        rewritten = `${rewritten.slice(0, replacement.start)}${replacement.text}${rewritten.slice(replacement.end)}`;
+    }
+
+    const prefix = 'const __zenith_expr__ = (';
+    const suffix = ');';
+    if (!rewritten.startsWith(prefix) || !rewritten.endsWith(suffix)) {
+        return expr;
+    }
+    return rewritten.slice(prefix.length, rewritten.length - suffix.length);
+}
+
 /**
  * @param {string} expr
  * @param {{
@@ -1730,18 +1980,21 @@ function rewritePropsExpression(expr, rewriteContext = null) {
     const scopeMap = rewriteContext?.scopeRewrite?.map;
     const scopeAmbiguous = rewriteContext?.scopeRewrite?.ambiguous;
     const rootMatch = trimmed.match(/^([A-Za-z_$][A-Za-z0-9_$]*)([\s\S]*)$/);
-    if (!rootMatch || !(scopeMap instanceof Map)) {
+    if (!(scopeMap instanceof Map)) {
         return trimmed;
     }
+    if (!rootMatch) {
+        return rewriteIdentifiersWithinExpression(trimmed, scopeMap, scopeAmbiguous);
+    }
 
     const root = rootMatch[1];
     if (scopeAmbiguous instanceof Set && scopeAmbiguous.has(root)) {
-        return trimmed;
+        return rewriteIdentifiersWithinExpression(trimmed, scopeMap, scopeAmbiguous);
     }
 
     const rewrittenRoot = scopeMap.get(root);
     if (typeof rewrittenRoot !== 'string' || rewrittenRoot.length === 0 || rewrittenRoot === root) {
-        return trimmed;
+        return rewriteIdentifiersWithinExpression(trimmed, scopeMap, scopeAmbiguous);
     }
 
     return `${rewrittenRoot}${rootMatch[2]}`;
@@ -1874,13 +2127,21 @@ function deferComponentRuntimeBlock(source) {
  * @param {string} projectRoot
  * @param {object | null} [logger]
  * @param {boolean} [showInfo]
+ * @param {string} [bundlerBin]
  * @returns {Promise<void>}
  */
-function runBundler(envelope, outDir, projectRoot, logger = null, showInfo = true) {
+function runBundler(
+    envelope,
+    outDir,
+    projectRoot,
+    logger = null,
+    showInfo = true,
+    bundlerBin = resolveBundlerBin(projectRoot)
+) {
     return new Promise((resolvePromise, rejectPromise) => {
         const useStructuredLogger = Boolean(logger && typeof logger.childLine === 'function');
         const child = spawn(
-            getBundlerBin(),
+            bundlerBin,
             ['--out-dir', outDir],
             {
                 cwd: projectRoot,
@@ -1968,6 +2229,8 @@ async function collectAssets(rootDir) {
 export async function build(options) {
     const { pagesDir, outDir, config = {}, logger = null, showBundlerInfo = true } = options;
     const projectRoot = deriveProjectRootFromPagesDir(pagesDir);
+    const compilerBin = resolveCompilerBin(projectRoot);
+    const bundlerBin = resolveBundlerBin(projectRoot);
     const softNavigationEnabled = config.softNavigation === true || config.router === true;
     const compilerOpts = {
         typescriptDefault: config.typescriptDefault === true,
@@ -1978,6 +2241,15 @@ export async function build(options) {
     await rm(outDir, { recursive: true, force: true });
     await mkdir(outDir, { recursive: true });
 
+    if (logger) {
+        await maybeWarnAboutZenithVersionMismatch({
+            projectRoot,
+            logger,
+            command: 'build',
+            bundlerBinPath: bundlerBin
+        });
+    }
+
     // Derive src/ directory from pages/ directory
     const srcDir = resolve(pagesDir, '..');
 
@@ -2037,7 +2309,10 @@ export async function build(options) {
             sourceFile,
             compileSource,
             compilerOpts,
-            { onWarning: emitCompilerWarning }
+            {
+                compilerBin,
+                onWarning: emitCompilerWarning
+            }
         );
 
         const hasGuard = (extractedServer.serverScript && extractedServer.serverScript.has_guard) || adjacentGuard !== null;
@@ -2082,7 +2357,20 @@ export async function build(options) {
         const pageAmbiguousExpressionMap = new Set();
         const knownRefKeys = new Set();
         const pageScopeRewrite = buildScopedIdentifierRewrite(pageIr);
-        const pageSelfExpressionRewrite = buildComponentExpressionRewrite(sourceFile, compileSource, pageIr, compilerOpts);
+        const pageSelfExpressionRewrite = buildComponentExpressionRewrite(
+            sourceFile,
+            compileSource,
+            pageIr,
+            compilerOpts,
+            compilerBin
+        );
+        mergeExpressionRewriteMaps(
+            pageExpressionRewriteMap,
+            pageExpressionBindingMap,
+            pageAmbiguousExpressionMap,
+            pageSelfExpressionRewrite,
+            pageIr
+        );
         const componentScopeRewriteCache = new Map();
 
         // 2c. Compile each used component separately for its script IR
@@ -2100,7 +2388,10 @@ export async function build(options) {
                     compPath,
                     componentCompileSource,
                     compilerOpts,
-                    { onWarning: emitCompilerWarning }
+                    {
+                        compilerBin,
+                        onWarning: emitCompilerWarning
+                    }
                 );
                 componentIrCache.set(compPath, compIr);
             }
@@ -2113,7 +2404,13 @@ export async function build(options) {
 
             let expressionRewrite = componentExpressionRewriteCache.get(compPath);
             if (!expressionRewrite) {
-                expressionRewrite = buildComponentExpressionRewrite(compPath, componentSource, compIr, compilerOpts);
+                expressionRewrite = buildComponentExpressionRewrite(
+                    compPath,
+                    componentSource,
+                    compIr,
+                    compilerOpts,
+                    compilerBin
+                );
                 componentExpressionRewriteCache.set(compPath, expressionRewrite);
             }
 
@@ -2136,7 +2433,10 @@ export async function build(options) {
                         ownerPath,
                         stripStyleBlocks(ownerSource),
                         compilerOpts,
-                        { onWarning: emitCompilerWarning }
+                        {
+                            compilerBin,
+                            onWarning: emitCompilerWarning
+                        }
                     );
                     componentIrCache.set(ownerPath, ownerIr);
                 }
@@ -2144,7 +2444,13 @@ export async function build(options) {
                 attrExpressionRewrite = componentExpressionRewriteCache.get(ownerPath);
                 if (!attrExpressionRewrite) {
                     const ownerSource = readFileSync(ownerPath, 'utf8');
-                    attrExpressionRewrite = buildComponentExpressionRewrite(ownerPath, ownerSource, ownerIr, compilerOpts);
+                    attrExpressionRewrite = buildComponentExpressionRewrite(
+                        ownerPath,
+                        ownerSource,
+                        ownerIr,
+                        compilerOpts,
+                        compilerBin
+                    );
                     componentExpressionRewriteCache.set(ownerPath, attrExpressionRewrite);
                 }
 
@@ -2190,6 +2496,8 @@ export async function build(options) {
             pageExpressionBindingMap,
             pageAmbiguousExpressionMap
         );
+        applyScopedIdentifierRewrites(pageIr, buildScopedIdentifierRewrite(pageIr));
+        synthesizeSignalBackedCompiledExpressions(pageIr);
         normalizeExpressionBindingDependencies(pageIr);
 
         rewriteLegacyMarkupIdentifiers(pageIr);
@@ -2204,7 +2512,7 @@ export async function build(options) {
     }
 
     if (envelopes.length > 0) {
-    await runBundler(envelopes, outDir, projectRoot, logger, showBundlerInfo);
+        await runBundler(envelopes, outDir, projectRoot, logger, showBundlerInfo, bundlerBin);
     }
 
     const assets = await collectAssets(outDir);

package/dist/index.js

@@ -116,6 +116,15 @@ export async function cli(args, cwd) {
     const outDir = join(projectRoot, 'dist');
     const config = await loadConfig(projectRoot);
 
+    if (command === 'build' || command === 'dev') {
+        const { maybeWarnAboutZenithVersionMismatch } = await import('./version-check.js');
+        await maybeWarnAboutZenithVersionMismatch({
+            projectRoot,
+            logger,
+            command
+        });
+    }
+
     if (command === 'build') {
         const { build } = await import('./build.js');
         logger.build('Building…');

package/dist/toolchain-paths.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CLI_ROOT = resolve(__dirname, '..');
+const localRequire = createRequire(import.meta.url);
+
+function safeCreateRequire(projectRoot) {
+    if (!projectRoot) {
+        return localRequire;
+    }
+    try {
+        return createRequire(resolve(projectRoot, 'package.json'));
+    } catch {
+        return localRequire;
+    }
+}
+
+function safeResolve(requireFn, specifier) {
+    try {
+        return requireFn.resolve(specifier);
+    } catch {
+        return null;
+    }
+}
+
+export function resolveBinary(candidates) {
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0] || '';
+}
+
+export function resolvePackageRoot(packageName, projectRoot = null) {
+    const projectRequire = safeCreateRequire(projectRoot);
+    const projectPath = safeResolve(projectRequire, `${packageName}/package.json`);
+    if (projectPath) {
+        return dirname(projectPath);
+    }
+
+    const localPath = safeResolve(localRequire, `${packageName}/package.json`);
+    return localPath ? dirname(localPath) : null;
+}
+
+export function readInstalledPackageVersion(packageName, projectRoot = null) {
+    const packageRoot = resolvePackageRoot(packageName, projectRoot);
+    if (!packageRoot) {
+        return null;
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : null;
+    } catch {
+        return null;
+    }
+}
+
+export function readCliPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(CLI_ROOT, 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+}
+
+export function compilerBinCandidates(projectRoot = null) {
+    const candidates = [
+        resolve(CLI_ROOT, '../compiler/target/release/zenith-compiler'),
+        resolve(CLI_ROOT, '../zenith-compiler/target/release/zenith-compiler')
+    ];
+    const installedRoot = resolvePackageRoot('@zenithbuild/compiler', projectRoot);
+    if (installedRoot) {
+        candidates.unshift(resolve(installedRoot, 'target/release/zenith-compiler'));
+    }
+    return candidates;
+}
+
+export function resolveCompilerBin(projectRoot = null) {
+    return resolveBinary(compilerBinCandidates(projectRoot));
+}
+
+export function bundlerBinCandidates(projectRoot = null, env = process.env) {
+    const candidates = [];
+    const envBin = env?.ZENITH_BUNDLER_BIN;
+    if (typeof envBin === 'string' && envBin.length > 0) {
+        candidates.push(envBin);
+    }
+
+    const installedRoot = resolvePackageRoot('@zenithbuild/bundler', projectRoot);
+    if (installedRoot) {
+        candidates.push(resolve(installedRoot, 'target/release/zenith-bundler'));
+    }
+
+    candidates.push(
+        resolve(CLI_ROOT, '../bundler/target/release/zenith-bundler'),
+        resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
+    );
+
+    return candidates;
+}
+
+export function resolveBundlerBin(projectRoot = null, env = process.env) {
+    return resolveBinary(bundlerBinCandidates(projectRoot, env));
+}

package/dist/version-check.js

@@ -0,0 +1,378 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+    readCliPackageVersion,
+    readInstalledPackageVersion,
+    resolveBundlerBin
+} from './toolchain-paths.js';
+
+const PACKAGE_KEYS = [
+    ['core', '@zenithbuild/core'],
+    ['compiler', '@zenithbuild/compiler'],
+    ['runtime', '@zenithbuild/runtime'],
+    ['router', '@zenithbuild/router'],
+    ['bundlerPackage', '@zenithbuild/bundler']
+];
+
+function parseVersion(version) {
+    const raw = String(version || '').trim();
+    const match = raw.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        raw,
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10),
+        prerelease: match[4] || '',
+        prereleaseParts: match[4] ? match[4].split('.') : []
+    };
+}
+
+function compareIdentifiers(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        return Number(left) - Number(right);
+    }
+    if (leftNumeric) {
+        return -1;
+    }
+    if (rightNumeric) {
+        return 1;
+    }
+    return left.localeCompare(right);
+}
+
+export function compareVersions(leftVersion, rightVersion) {
+    const left = parseVersion(leftVersion);
+    const right = parseVersion(rightVersion);
+    if (!left && !right) return 0;
+    if (!left) return -1;
+    if (!right) return 1;
+
+    const numberDelta = (
+        (left.major - right.major)
+        || (left.minor - right.minor)
+        || (left.patch - right.patch)
+    );
+    if (numberDelta !== 0) {
+        return numberDelta;
+    }
+
+    if (!left.prerelease && !right.prerelease) {
+        return 0;
+    }
+    if (!left.prerelease) {
+        return 1;
+    }
+    if (!right.prerelease) {
+        return -1;
+    }
+
+    const len = Math.max(left.prereleaseParts.length, right.prereleaseParts.length);
+    for (let index = 0; index < len; index += 1) {
+        const leftPart = left.prereleaseParts[index];
+        const rightPart = right.prereleaseParts[index];
+        if (leftPart === undefined) {
+            return -1;
+        }
+        if (rightPart === undefined) {
+            return 1;
+        }
+        const delta = compareIdentifiers(leftPart, rightPart);
+        if (delta !== 0) {
+            return delta;
+        }
+    }
+
+    return 0;
+}
+
+function prereleaseChannel(parsed) {
+    if (!parsed || !parsed.prerelease) {
+        return 'stable';
+    }
+    const [label = 'prerelease', train] = parsed.prereleaseParts;
+    if (train && /^\d+$/.test(train)) {
+        return `${label}.${train}`;
+    }
+    return label;
+}
+
+function classifyDifference(expectedVersion, actualVersion) {
+    if (!expectedVersion || !actualVersion) {
+        return 'unknown';
+    }
+    if (expectedVersion === actualVersion) {
+        return 'exact';
+    }
+    const expected = parseVersion(expectedVersion);
+    const actual = parseVersion(actualVersion);
+    if (!expected || !actual) {
+        return 'unknown';
+    }
+    if (expected.major !== actual.major || expected.minor !== actual.minor) {
+        return 'hard';
+    }
+    if (prereleaseChannel(expected) !== prereleaseChannel(actual)) {
+        return 'hard';
+    }
+    return 'soft';
+}
+
+function readProjectPackage(projectRoot) {
+    if (!projectRoot) {
+        return null;
+    }
+    try {
+        const manifestPath = resolve(projectRoot, 'package.json');
+        if (!existsSync(manifestPath)) {
+            return null;
+        }
+        return JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function buildFixCommand(projectRoot, targetVersion) {
+    const manifest = readProjectPackage(projectRoot);
+    const dependencyNames = [
+        '@zenithbuild/core',
+        '@zenithbuild/cli',
+        '@zenithbuild/compiler',
+        '@zenithbuild/runtime',
+        '@zenithbuild/router',
+        '@zenithbuild/bundler'
+    ];
+
+    const deps = [];
+    const devDeps = [];
+    for (const name of dependencyNames) {
+        if (manifest?.dependencies && Object.prototype.hasOwnProperty.call(manifest.dependencies, name)) {
+            deps.push(`${name}@${targetVersion}`);
+            continue;
+        }
+        devDeps.push(`${name}@${targetVersion}`);
+    }
+
+    const commands = [];
+    if (deps.length > 0) {
+        commands.push(`npm i ${deps.join(' ')}`);
+    }
+    if (devDeps.length > 0) {
+        commands.push(`npm i -D ${devDeps.join(' ')}`);
+    }
+    if (commands.length === 0) {
+        commands.push(`npm i -D ${dependencyNames.map((name) => `${name}@${targetVersion}`).join(' ')}`);
+    }
+    return commands.join(' && ');
+}
+
+function describeVersions(versions) {
+    const entries = [
+        ['cli', versions.cli],
+        ['project cli', versions.projectCli],
+        ['core', versions.core],
+        ['compiler', versions.compiler],
+        ['runtime', versions.runtime],
+        ['router', versions.router],
+        ['bundler pkg', versions.bundlerPackage],
+        ['bundler bin', versions.bundlerBinary]
+    ];
+    return entries
+        .filter(([, version]) => typeof version === 'string' && version.length > 0)
+        .map(([label, version]) => `${label}=${version}`)
+        .join(' ');
+}
+
+function summarizeIssues(issues) {
+    const preview = issues.slice(0, 3).map((issue) => issue.summary);
+    const suffix = issues.length > 3 ? ` +${issues.length - 3} more` : '';
+    return `${preview.join('; ')}${suffix}`;
+}
+
+function determineTargetVersion(versions) {
+    const candidates = [
+        versions.projectCli,
+        versions.core,
+        versions.compiler,
+        versions.runtime,
+        versions.router,
+        versions.bundlerPackage,
+        versions.cli
+    ].filter((value) => typeof value === 'string' && value.length > 0);
+
+    if (candidates.length === 0) {
+        return '0.0.0';
+    }
+
+    let highest = candidates[0];
+    for (const candidate of candidates.slice(1)) {
+        if (compareVersions(candidate, highest) > 0) {
+            highest = candidate;
+        }
+    }
+    return highest;
+}
+
+export function getBundlerVersion(bundlerBinPath) {
+    const path = String(bundlerBinPath || '').trim();
+    if (!path) {
+        return { version: null, path: '', rawOutput: '', ok: false };
+    }
+    const result = spawnSync(path, ['--version'], { encoding: 'utf8' });
+    if (result.error) {
+        return {
+            version: null,
+            path,
+            rawOutput: result.error.message,
+            ok: false
+        };
+    }
+
+    const rawOutput = `${result.stdout || ''}\n${result.stderr || ''}`.trim();
+    const versionMatch = rawOutput.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+    return {
+        version: versionMatch ? versionMatch[1] : null,
+        path,
+        rawOutput,
+        ok: result.status === 0 && Boolean(versionMatch)
+    };
+}
+
+export function getLocalZenithVersions({ projectRoot, bundlerBinPath } = {}) {
+    const resolvedBundlerBin = bundlerBinPath || resolveBundlerBin(projectRoot);
+    const bundlerVersion = getBundlerVersion(resolvedBundlerBin);
+    const versions = {
+        cli: readCliPackageVersion(),
+        projectCli: readInstalledPackageVersion('@zenithbuild/cli', projectRoot),
+        bundlerBinary: bundlerVersion.version,
+        bundlerBinPath: bundlerVersion.path,
+        bundlerBinRawOutput: bundlerVersion.rawOutput,
+        targetVersion: null
+    };
+
+    for (const [key, packageName] of PACKAGE_KEYS) {
+        versions[key] = readInstalledPackageVersion(packageName, projectRoot);
+    }
+
+    versions.targetVersion = determineTargetVersion(versions);
+    return versions;
+}
+
+export function checkCompatibility(versions) {
+    const targetVersion = versions?.targetVersion || determineTargetVersion(versions || {});
+    const issues = [];
+    const fixCommand = buildFixCommand(versions?.projectRoot, targetVersion);
+
+    const addIssue = (code, summary, message) => {
+        issues.push({
+            code,
+            summary,
+            message,
+            hint: `${fixCommand}  (suppress with ZENITH_SKIP_VERSION_CHECK=1)`,
+            fixCommand
+        });
+    };
+
+    if (versions.projectCli && versions.cli && versions.projectCli !== versions.cli) {
+        const severity = classifyDifference(versions.projectCli, versions.cli);
+        addIssue(
+            severity === 'hard' ? 'CLI_TRAIN_MISMATCH' : 'CLI_OUTDATED',
+            `cli ${versions.cli} != project ${versions.projectCli}`,
+            `Version mismatch detected (may break HMR/refs): executing CLI ${versions.cli} does not match project CLI ${versions.projectCli}.`
+        );
+    }
+
+    for (const [key, label] of [
+        ['core', 'core'],
+        ['compiler', 'compiler'],
+        ['runtime', 'runtime'],
+        ['router', 'router'],
+        ['bundlerPackage', 'bundler package']
+    ]) {
+        const actual = versions[key];
+        const difference = classifyDifference(targetVersion, actual);
+        if (difference === 'hard') {
+            addIssue(
+                'VERSION_TRAIN_MISMATCH',
+                `${label} ${actual} != ${targetVersion}`,
+                `Version mismatch detected (may break HMR/refs): ${label} ${actual} is on a different Zenith train than ${targetVersion}.`
+            );
+        } else if (difference === 'soft') {
+            addIssue(
+                'VERSION_OUTDATED',
+                `${label} ${actual} != ${targetVersion}`,
+                `Version mismatch detected (may break HMR/refs): ${label} ${actual} is not aligned with ${targetVersion}.`
+            );
+        }
+    }
+
+    const bundlerExpected = versions.bundlerPackage || targetVersion;
+    const bundlerDifference = classifyDifference(bundlerExpected, versions.bundlerBinary);
+    if (bundlerDifference === 'hard') {
+        addIssue(
+            'BUNDLER_BINARY_MISMATCH',
+            `bundler bin ${versions.bundlerBinary || 'missing'} != ${bundlerExpected}`,
+            `Version mismatch detected (may break build/IR contracts): bundler binary ${versions.bundlerBinary || 'missing'} does not match ${bundlerExpected}.`
+        );
+    } else if (bundlerDifference === 'soft') {
+        addIssue(
+            'BUNDLER_BINARY_OUTDATED',
+            `bundler bin ${versions.bundlerBinary} != ${bundlerExpected}`,
+            `Version mismatch detected (may break build/IR contracts): bundler binary ${versions.bundlerBinary} is not aligned with ${bundlerExpected}.`
+        );
+    }
+
+    return {
+        status: issues.length === 0 ? 'ok' : 'warn',
+        issues,
+        details: {
+            targetVersion,
+            versions: {
+                ...versions
+            },
+            summary: describeVersions(versions)
+        }
+    };
+}
+
+export async function maybeWarnAboutZenithVersionMismatch({
+    projectRoot,
+    logger,
+    command = 'build',
+    bundlerBinPath = null
+} = {}) {
+    if (!logger || process.env.ZENITH_SKIP_VERSION_CHECK === '1') {
+        return { status: 'ok', issues: [], details: {} };
+    }
+
+    const versions = getLocalZenithVersions({ projectRoot, bundlerBinPath });
+    versions.projectRoot = projectRoot;
+    const result = checkCompatibility(versions);
+    const onceKey = `zenith-version-check:${describeVersions(versions)}:${result.status}`;
+    const verboseTag = command === 'dev' ? 'DEV' : 'BUILD';
+
+    if (result.status === 'ok') {
+        logger.verbose(verboseTag, `toolchain versions ok ${result.details.summary}`);
+        return result;
+    }
+
+    const primary = result.issues[0];
+    logger.warn(
+        `${primary.message} ${summarizeIssues(result.issues)}`,
+        {
+            onceKey,
+            hint: primary.hint
+        }
+    );
+    logger.verbose(verboseTag, `toolchain versions ${result.details.summary}`);
+    if (versions.bundlerBinPath) {
+        logger.verbose(verboseTag, `bundler bin path=${versions.bundlerBinPath}`);
+    }
+    return result;
+}

package/package.json

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