zexus 1.8.1 → 1.8.3

package/README.md

@@ -2,14 +2,14 @@
 
 <div align="center">
 
-![Zexus Logo](https://img.shields.io/badge/Zexus-v1.8.1-FF6B35?style=for-the-badge)
+![Zexus Logo](https://img.shields.io/badge/Zexus-v1.8.3-FF6B35?style=for-the-badge)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)
 [![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=for-the-badge&logo=python)](https://python.org)
 [![GitHub](https://img.shields.io/badge/GitHub-Zaidux/zexus--interpreter-181717?style=for-the-badge&logo=github)](https://github.com/Zaidux/zexus-interpreter)
 
 **A modern, security-first programming language with built-in blockchain support, VM-accelerated execution, advanced memory management, and policy-as-code**
 
-[What's New](#-whats-new-in-v171) • [Features](#-key-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Keywords](#-complete-keyword-reference) • [Documentation](#-documentation) • [Examples](#-examples) • [Troubleshooting](#-getting-help--troubleshooting)
+[What's New](#-whats-new-in-v183) • [Features](#-key-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Keywords](#-complete-keyword-reference) • [Documentation](#-documentation) • [Examples](#-examples) • [Troubleshooting](#-getting-help--troubleshooting)
 
 </div>
 
@@ -18,7 +18,7 @@
 ## 📋 Table of Contents
 
 - [What is Zexus?](#-what-is-zexus)
-- [What's New](#-whats-new-in-v171)
+- [What's New](#-whats-new-in-v183)
 - [Key Features](#-key-features)
   - [VM-Accelerated Performance](#-vm-accelerated-performance-new)
   - [Security & Policy-as-Code](#-security--policy-as-code--verify-enhanced)
@@ -67,71 +67,96 @@ Zexus is a next-generation, general-purpose programming language designed for se
 
 ---
 
-## 🎉 What's New in v1.8.1
-
-### Latest Features (v1.8.1)
-
-✅ **FIND Keyword** - Declarative project search that resolves exact module paths with scope filtering and smart suggestions  
-✅ **LOAD Keyword & Manager** - Provider-aware configuration loader with built-in ENV, JSON, and YAML support plus caching  
-✅ **VM + Bytecode Support** - FIND/LOAD now compile to bytecode with helper bridges so scripts run identically in the VM and interpreter  
-✅ **Targeted Test Coverage** - Added regression tests that exercise both interpreter and VM paths for FIND/LOAD workflows  
-
-### Previous Features (v1.6.3)
-
-✅ **Complete Database Ecosystem** - Production-ready database drivers  
-✅ **4 Database Drivers** - SQLite, PostgreSQL, MySQL, MongoDB fully tested  
-✅ **HTTP Server** - Build web servers with routing (GET, POST, PUT, DELETE)  
-✅ **Socket/TCP Primitives** - Low-level network programming  
-✅ **Testing Framework** - Write and run tests with assertions  
-✅ **ZPM Package Manager** - Fully functional package management system  
-✅ **Comprehensive Documentation** - 900+ lines of ecosystem guides  
-
-### Previous Features (v1.5.0)
-
-✅ **World-Class Error Reporting** - Production-grade error messages rivaling Rust  
-✅ **Advanced DATA System** - Generic types, pattern matching, operator overloading  
-✅ **Stack Trace Formatter** - Beautiful, readable stack traces with source context  
-✅ **Smart Error Suggestions** - Actionable hints for fixing common errors  
-✅ **Pattern Matching** - Complete pattern matching with exhaustiveness checking  
-✅ **CONTINUE Keyword** - Error recovery mode for graceful degradation and batch processing  
-
-### Recent Enhancements (v0.1.3)
-
-✅ **130+ Keywords Fully Operational** - All core language features tested and verified  
-✅ **Dual-Mode DEBUG** - Function mode (`debug(x)`) and statement mode (`debug x;`)  
-✅ **Conditional Print** - `print(condition, message)` for dynamic output control  
-✅ **Multiple Syntax Styles** - `let x = 5`, `let x : 5`, `let x : int = 5` all supported  
-✅ **Enterprise Keywords** - MIDDLEWARE, AUTH, THROTTLE, CACHE, INJECT fully functional  
-✅ **Async/Await Runtime** - Complete Promise-based async system with context propagation  
-✅ **Main Entry Point** - 15+ builtins for program lifecycle management  
-✅ **UI Renderer** - SCREEN, COMPONENT, THEME keywords with 120+ tests  
-✅ **Enhanced VERIFY** - Email, URL, phone validation, pattern matching, database checks  
-✅ **Blockchain Keywords** - implements, pure, view, payable, modifier, this, emit  
-✅ **Loop Control** - BREAK keyword for early loop exit  
-✅ **Error Handling** - THROW keyword for explicit error raising, THIS for instance reference  
-✅ **100+ Built-in Functions** - Comprehensive standard library  
-✅ **LOG Keyword Enhancements** - `read_file()` and `eval_file()` for dynamic code generation  
-✅ **REQUIRE Tolerance Blocks** - Conditional bypasses for VIP/admin/emergency scenarios  
-✅ **Function-Level Scoping** - LET/CONST documented with scope behavior and shadowing rules  
-✅ **Advanced Error Patterns** - Retry, circuit breaker, error aggregation patterns
-
-### Bug Fixes & Improvements
-
-✅ Fixed array literal parsing (no more duplicate elements)  
-✅ Fixed ENUM value accessibility  
-✅ Fixed WHILE condition parsing without parentheses  
-✅ Fixed loop execution and variable reassignment  
-✅ Fixed DEFER cleanup execution  
-✅ Fixed SANDBOX return values  
-✅ Fixed dependency injection container creation  
-✅ Added tolerance blocks for REQUIRE  
-✅ Improved error messages and debugging output
+## 🎉 What's New in v1.8.3
+
+### v1.8.3 — Phase 0 Audit Fixes, Closure Scoping Overhaul & VM Hardening (2026-03-01)
+
+19 issues from the [Ziver-Chain Phase 0 rewrite audit](issues/ISSUE8.md) resolved — including 3 VM-specific critical fixes. Key changes:
+
+**VM Fixes & Hardening:**
+- **R-001:** Entity field access on VM now works — proper `EntityDefinition`/`EntityInstance` construction from bytecode
+- **R-002:** Contract `state` declarations now compile correctly (`_compile_StateStatement`)
+- **R-010:** Complex programs no longer silently fail — added `_vm_warn()` diagnostics, replaced 15 silent error handlers
+- Native fast-path (`_vm_native_call`) for `push`/`append`/`length`/`str`/`range` operations on VM-native types
+- `VMRuntimeError(Exception)` replaces non-raisable `ZEvaluationError(Object)` in 15 raise sites
+- Stack overflow protection, execution timeout (30s), opcode limit (100M), configurable VM pool sizing
+- **Rust VM status indicator** — CLI/runner show "Rust VM: active", "available but disabled", or "not compiled"
+
+**Closure & Scoping Fixes:**
+- Entity/`let` declarations before a contract no longer break contract visibility — declaration order is now flexible
+- Module-level helper functions called from contract methods now correctly propagate side-effects (`list.push()`, `map[k]=v`)
+- `action protect` now works at module level (policy enforcement added to function call path)
+- Storage sync-back in contract methods improved — `list.push()` after `map[key]=val` no longer silently ignored
+- Exported entities can now be used as constructors in importing files
+
+**Contract & Language Fixes:**
+- `self` keyword works as alias for `this` inside contracts
+- `init()` auto-called on `Contract()` construction
+- `state { field1: val, field2: val }` multi-field blocks work correctly
+- `for each i, item in list` (indexed) and `for each key, val in map` now supported
+- `INTEGER * FLOAT` implicit coercion and `%` modulo on floats now work
+- Added `range()`, `typeof()`, `abs()`, `str()`, `length()` builtins; 8 parser edge-case fixes
+
+**Stats:** 1852 tests pass, 0 regressions. 5 new extreme test suites (83 tests across speed, stability, security, features, VM). See [CHANGELOG](CHANGELOG.md) for full details.
+
+### v1.8.2 — Concurrency & Channel Support (2026-02-25)
+
+- `watch =>` arrow-lambda fallback no longer hijacks the strategy parser
+- Channel support in VM compiler (`_compile_ChannelStatement`, `_compile_SendStatement`, `_compile_ReceiveStatement`)
+- SPAWN/AWAIT opcodes in sync path using `threading.Thread(daemon=True)`
+- Strategy parser channel/async handlers added
+- Fixed 10+ missing VM node types; zero VM fallbacks achieved
+- All versions bumped to 1.8.2; Rust VM builds with `maturin develop --release`
+
+### v1.8.1 — ISSUE7 Audit & Security Remediation (2026-02-23)
+
+All 21 issues from the Phase 0 audit resolved:
+- `emit`, `protocol`, `implements` keywords fully operational in all parsers
+- Entity compilation crash in VM fixed; imported functions no longer return raw Action objects
+- `map.has()` / `map.get()` key normalization fixed
+- ExportStatement supported in VM; entity constructor arity validation relaxed
+- `persistent storage` now wires to SQLite backend with `set_persistent`/`get_persistent`
+- 5 new builtins: `track_memory()`, `cache()`, `throttle()`, `audit()`, `verify()`
+- Complete security remediation Phases 0–5 (sandboxing, ReDoS, import sandboxing, compiler parity, dead-code removal, bounded logs)
+- 1852 tests pass
+
+### v1.8.0 — Rust VM Pipeline & Major Features (2026-02-23)
+
+**Language Features:** Compound assignment (`+=`, `-=`, etc.), string interpolation (`"Hello ${name}"`), block comments (`/* */`), multiline strings, single-quoted strings, exponentiation (`**`), `finally` clause, destructuring assignment.
+
+**Developer Tooling:** Circular import detection, LSP go-to-definition, remote ZPM registry, static type checker.
+
+**Major Capabilities:** Debug Adapter Protocol (DAP) server, GUI backend (Tk + Web), true concurrent EventLoop, WASM compilation target.
+
+**Rust-First Execution (Phases 0–6):** Complete migration achieving **102,000+ TPS** with zero Python fallbacks. Includes binary `.zxc` format, Rust bytecode interpreter (22 MIPS, 20.7x speedup), adaptive VM routing, `RustContractVM` orchestration, GIL-free batch execution (221,593 TPS peak), and 40+ Rust builtins.
+
+### v1.7.x — FIND/LOAD Keywords & Performance (2026-01)
+
+- **v1.7.2:** Major interpreter speed improvements, smart storage for lists, optimized stack traces, blockchain perf fix
+- **v1.7.1:** FIND keyword (declarative module search), LOAD keyword (provider-aware config loader), VM bytecode support for both, regression tests
+
+### v1.6.x — Database Ecosystem & Security (2025-12 – 2026-01)
+
+- **v1.6.8:** Parser fix for indexed assignments on new lines; contract DATA member declarations
+- **v1.6.7:** Semicolon handling fix, context-aware keyword recognition, standalone block statements
+- **v1.6.6:** Repeated contract action calls, multiple indexed assignments
+- **v1.6.5:** Entity property access, keyword restrictions (`from`/`to` as params), multiple map assignments
+- **v1.6.3:** Comprehensive security remediation (10 OWASP categories), RBAC, bcrypt, input sanitization, resource limits, path traversal prevention
+- **v1.6.2:** 4 database drivers (SQLite, PostgreSQL, MySQL, MongoDB), HTTP server, socket/TCP, testing framework, ZPM
+
+### v1.5.0 — Error Reporting & Type System (2025-12)
+
+World-class error messages (rivaling Rust), generic types, pattern matching, operator overloading, stack trace formatter, smart suggestions, CONTINUE keyword.
+
+### v0.1.3 — Foundation (2025-11)
+
+130+ keywords, dual-mode DEBUG, conditional print, multiple syntax styles, enterprise keywords, async/await, UI renderer, enhanced VERIFY, blockchain keywords, 100+ builtins.
 
 ---
 
-## 🔒 Latest Security Patches & Features (v1.6.3)
+## 🔒 Security Features
 
-Zexus v1.6.3 introduces **comprehensive security enhancements** and developer-friendly safety features. These improvements make Zexus one of the most secure interpreted languages available, with enterprise-grade protection built into the language itself.
+Zexus includes **comprehensive security enhancements** and developer-friendly safety features, making it one of the most secure interpreted languages available with enterprise-grade protection built into the language itself.
 
 ### 🛡️ Security Features Added
 

package/bin/zexus

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zpics

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus.pics "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus.pics', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zpm

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus.zpm "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus.zpm', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zx

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zx-deploy

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus.deploy "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus.deploy', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zx-dev

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus.dev "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus.dev', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/bin/zx-run

@@ -1,2 +1,12 @@
-#!/usr/bin/env bash
-python3 -m zexus.runner "$@"
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const proc = spawn('python3', ['-m', 'zexus.runner', ...process.argv.slice(2)], { stdio: 'inherit' });
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. Please install Python 3.8+ to use Zexus.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+proc.on('close', (code) => process.exit(code ?? 1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zexus",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "A modern, security-first programming language with blockchain support",
   "main": "index.js",
   "bin": {

package/rust_core/Cargo.lock

@@ -578,7 +578,7 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "zeroize"
-version = "1.8.2"
+version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
 

package/scripts/postinstall.js

@@ -3,74 +3,225 @@
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 console.log('\n🚀 Installing Zexus Programming Language...\n');
 
-// Check if Python is available
-try {
-  const pythonVersion = execSync('python3 --version', { encoding: 'utf-8' });
-  console.log(`✓ Found ${pythonVersion.trim()}`);
-} catch (error) {
-  console.error('❌ Python 3.8+ is required but not found.');
-  console.error('Please install Python 3.8 or higher: https://www.python.org/downloads/');
-  process.exit(1);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hasCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-// Check Python version
-try {
-  const versionCheck = execSync('python3 -c "import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)"');
-  console.log('✓ Python version is 3.8 or higher');
-} catch (error) {
-  console.error('❌ Python 3.8 or higher is required.');
+function run(cmd, opts = {}) {
+  return execSync(cmd, { encoding: 'utf-8', stdio: 'inherit', ...opts });
+}
+
+function runQuiet(cmd) {
+  return execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' });
+}
+
+const isWin = os.platform() === 'win32';
+const pip = isWin ? 'pip' : 'pip3';
+const python = isWin ? 'python' : 'python3';
+
+// ---------------------------------------------------------------------------
+// 1. Python — check or install
+// ---------------------------------------------------------------------------
+
+let pythonAvailable = false;
+
+if (hasCommand(python)) {
+  try {
+    const ver = runQuiet(`${python} --version`).trim();
+    console.log(`✓ Found ${ver}`);
+    // Verify >= 3.8
+    runQuiet(`${python} -c "import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)"`);
+    console.log('✓ Python version is 3.8 or higher');
+    pythonAvailable = true;
+  } catch {
+    console.error('❌ Python was found but version is below 3.8.');
+    console.error('   Please upgrade to Python 3.8+: https://www.python.org/downloads/');
+  }
+} else {
+  console.warn('⚠️  python3 not found on PATH.');
+  // Attempt auto-install on common platforms
+  if (os.platform() === 'linux') {
+    console.log('   Attempting to install python3 via apt...');
+    try {
+      run('sudo apt-get update -qq && sudo apt-get install -y -qq python3 python3-pip python3-venv');
+      pythonAvailable = true;
+      console.log('✓ Python 3 installed via apt');
+    } catch {
+      console.warn('   Could not auto-install Python. Please install manually:');
+      console.warn('   https://www.python.org/downloads/');
+    }
+  } else if (os.platform() === 'darwin') {
+    if (hasCommand('brew')) {
+      console.log('   Attempting to install python3 via Homebrew...');
+      try {
+        run('brew install python@3');
+        pythonAvailable = true;
+        console.log('✓ Python 3 installed via Homebrew');
+      } catch {
+        console.warn('   Could not auto-install Python. Please install manually:');
+        console.warn('   https://www.python.org/downloads/');
+      }
+    } else {
+      console.warn('   Please install Python 3.8+: https://www.python.org/downloads/');
+    }
+  } else {
+    console.warn('   Please install Python 3.8+: https://www.python.org/downloads/');
+  }
+}
+
+if (!pythonAvailable) {
+  console.error('\n❌ Python 3.8+ is required but could not be found or installed.');
+  console.error('   Install it from: https://www.python.org/downloads/');
+  console.error('   Then re-run: npm rebuild zexus');
   process.exit(1);
 }
 
-// Install Zexus Python package
+// ---------------------------------------------------------------------------
+// 2. pip — ensure available
+// ---------------------------------------------------------------------------
+
+if (!hasCommand(pip) && !hasCommand('pip')) {
+  console.log('   pip not found — bootstrapping...');
+  try {
+    run(`${python} -m ensurepip --upgrade`);
+  } catch {
+    try {
+      run(`${python} -m pip install --upgrade pip`);
+    } catch {
+      console.warn('⚠️  Could not bootstrap pip. Python package install may fail.');
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 3. Install Zexus Python package
+// ---------------------------------------------------------------------------
+
 console.log('\n📦 Installing Zexus Python package...');
+
+// Check if zexus is already installed and up-to-date
+let zexusInstalled = false;
 try {
-  // Install with "full" extras so blockchain/network/security features work out of the box.
-  // Use --user to avoid permission issues on global Python installs.
-  execSync('pip3 install --user "zexus[full]"', { stdio: 'inherit' });
-  console.log('\n✓ Zexus Python package installed successfully');
-} catch (error) {
-  console.error('\n❌ Failed to install Zexus Python package.');
-  console.error('Please run manually: pip3 install --user "zexus[full]"');
-  process.exit(1);
+  runQuiet(`${python} -c "import zexus"`);
+  zexusInstalled = true;
+  console.log('✓ Zexus Python package already installed');
+} catch {
+  // Not installed yet
 }
 
-// Best-effort: build/install Rust VM extension from bundled sources when available.
-// This requires a Rust toolchain and may fail on systems without build tooling.
-function hasCommand(cmd) {
+if (!zexusInstalled) {
   try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
+    run(`${python} -m pip install --user "zexus[full]"`);
+    console.log('✓ Zexus Python package installed successfully');
   } catch {
-    return false;
+    // Retry without --user (some environments like venvs don't need it)
+    try {
+      run(`${python} -m pip install "zexus[full]"`);
+      console.log('✓ Zexus Python package installed successfully');
+    } catch {
+      console.error('❌ Failed to install Zexus Python package.');
+      console.error(`   Please run manually: ${python} -m pip install "zexus[full]"`);
+      // Don't exit — commands that don't need Python may still work
+    }
   }
 }
 
+// ---------------------------------------------------------------------------
+// 4. Rust toolchain — check or install, then build rust_core
+// ---------------------------------------------------------------------------
+
 const pkgRoot = path.resolve(__dirname, '..');
 const cargoToml = path.join(pkgRoot, 'rust_core', 'Cargo.toml');
 
-if (fs.existsSync(cargoToml) && hasCommand('cargo')) {
-  console.log('\n🦀 Rust toolchain detected — attempting to build zexus_core...');
-  try {
-    execSync('python3 -m pip install --user --upgrade maturin', { stdio: 'inherit' });
-    execSync(`python3 -m maturin develop -m "${cargoToml}" --release`, { stdio: 'inherit' });
-    execSync('python3 -c "import zexus_core; print(\"zexus_core OK\", zexus_core.version())"', { stdio: 'inherit' });
-    console.log('✓ Rust VM extension built and installed');
-  } catch (error) {
-    console.warn('\n⚠️  Rust VM build failed; continuing with pure-Python VM.');
-    console.warn('   To retry manually (from source repo):');
-    console.warn('     pip install maturin && maturin develop -m rust_core/Cargo.toml --release');
+if (fs.existsSync(cargoToml)) {
+  let cargoReady = hasCommand('cargo');
+
+  if (!cargoReady) {
+    console.log('\n🦀 Rust toolchain (cargo) not found.');
+    console.log('   Attempting to install Rust via rustup...');
+    try {
+      if (isWin) {
+        // On Windows, download and run rustup-init
+        console.log('   Please install Rust manually: https://rustup.rs');
+      } else {
+        // Unix: install rustup non-interactively
+        run('curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y');
+        // Source the cargo env so it's available in this session
+        const cargoEnv = path.join(os.homedir(), '.cargo', 'env');
+        if (fs.existsSync(cargoEnv)) {
+          // Read the cargo bin path and add to PATH for child processes
+          const cargoBin = path.join(os.homedir(), '.cargo', 'bin');
+          process.env.PATH = `${cargoBin}${path.delimiter}${process.env.PATH}`;
+        }
+        cargoReady = hasCommand('cargo');
+        if (cargoReady) {
+          console.log('✓ Rust toolchain installed via rustup');
+        }
+      }
+    } catch (err) {
+      console.warn('⚠️  Could not auto-install Rust. Continuing with pure-Python VM.');
+      console.warn('   To install manually: https://rustup.rs');
+    }
+  } else {
+    console.log('\n✓ Rust toolchain detected');
+  }
+
+  if (cargoReady) {
+    // Check if zexus_core is already importable
+    let rustVmInstalled = false;
+    try {
+      runQuiet(`${python} -c "import zexus_core"`);
+      rustVmInstalled = true;
+      console.log('✓ Rust VM extension (zexus_core) already installed');
+    } catch {
+      // Need to build
+    }
+
+    if (!rustVmInstalled) {
+      console.log('🔨 Building Rust VM extension (zexus_core)...');
+      try {
+        // Ensure maturin is available
+        try {
+          runQuiet(`${python} -m maturin --version`);
+        } catch {
+          console.log('   Installing maturin build tool...');
+          run(`${python} -m pip install --user --upgrade maturin`);
+        }
+        run(`${python} -m maturin develop -m "${cargoToml}" --release`);
+        runQuiet(`${python} -c "import zexus_core"`);
+        console.log('✓ Rust VM extension built and installed');
+      } catch (error) {
+        console.warn('\n⚠️  Rust VM build failed; continuing with pure-Python VM.');
+        console.warn('   To retry manually:');
+        console.warn(`     ${python} -m pip install maturin && ${python} -m maturin develop -m rust_core/Cargo.toml --release`);
+      }
+    }
   }
 } else {
-  console.log('\nℹ️  Skipping Rust VM build (cargo not found or rust_core not bundled).');
+  console.log('\nℹ️  rust_core/Cargo.toml not bundled; skipping Rust VM build.');
 }
 
+// ---------------------------------------------------------------------------
+// Done
+// ---------------------------------------------------------------------------
+
 console.log('\n✅ Zexus installed successfully!\n');
 console.log('Get started:');
 console.log('  zexus --help       # Show help');
 console.log('  zx --version       # Check version');
+console.log('  zx run file.zx     # Run a Zexus file');
 console.log('  zexus examples/    # Explore examples\n');
 console.log('Documentation: https://github.com/Zaidux/zexus-interpreter\n');

package/src/zexus/__init__.py

@@ -4,7 +4,7 @@ Zexus Programming Language
 A declarative, intent-based programming language for modern applications.
 """
 
-__version__ = "1.8.1"
+__version__ = "1.8.3"
 __author__ = "Ziver Labs"
 __email__ = "ziverofficial567@gmail.com"