xypriss 9.3.56 → 9.3.58

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xypriss",
-    "version": "9.3.56",
+    "version": "9.3.58",
     "description": "XyPriss is a lightweight, TypeScript-first, open-source Node.js web framework crafted for developers seeking a familiar Express-like API without Express dependencies. It features built-in security middleware, a robust routing system, and performance optimizations to build scalable, secure web applications effortlessly. Join our community and contribute on GitHub!",
     "author": {
         "name": "Nehonix",
@@ -125,6 +125,7 @@
     "files": [
         "dist/",
         "shared/",
+        "scripts/",
         "README.md",
         "LICENSE",
         "CONTRIBUTING.md"

package/scripts/install-memory-cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+/**
+ * XyPriss Memory CLI Installer
+ * Downloads platform-specific memory CLI binary during npm install
+ */
+
+import https from "https";
+import fs from "fs";
+import path from "path";
+import { execSync, spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const CDN_BASE_URL = "https://dll.nehonix.com/dl/mds/xypriss/bin";
+const BIN_DIR = path.join(__dirname, "..", "bin");
+const TIMEOUT = 40000;
+
+/**
+ * Get platform-specific binary information
+ */
+function getPlatformBinary() {
+    const platform = process.platform;
+    const arch = process.arch;
+
+    let binaryTarget;
+    if (platform === "win32") {
+        binaryTarget = arch === "arm64" ? "windows-arm64" : "windows-x64";
+    } else if (platform === "darwin") {
+        binaryTarget = arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+    } else if (platform === "linux") {
+        binaryTarget = arch === "arm64" ? "linux-arm64" : "linux-x64";
+    } else {
+        return null;
+    }
+
+    const binaryName = `memory-cli-${binaryTarget}${platform === "win32" ? ".exe" : ""}`;
+
+    return {
+        binaryName,
+        url: `${CDN_BASE_URL}/${binaryName}`,
+        localPath: path.join(BIN_DIR, binaryName),
+        genericPath: path.join(
+            BIN_DIR,
+            "memory-cli" + (platform === "win32" ? ".exe" : ""),
+        ),
+    };
+}
+
+/**
+ * Download file from URL with Redirect support
+ */
+function downloadFile(url, destination) {
+    return new Promise((resolve, reject) => {
+        const file = fs.createWriteStream(destination);
+        const request = https.get(url, { timeout: TIMEOUT }, (response) => {
+            if (
+                response.statusCode >= 300 &&
+                response.statusCode < 400 &&
+                response.headers.location
+            ) {
+                file.close();
+                fs.unlinkSync(destination);
+                return downloadFile(response.headers.location, destination)
+                    .then(resolve)
+                    .catch(reject);
+            }
+
+            if (response.statusCode === 200) {
+                response.pipe(file);
+                file.on("finish", () => {
+                    file.close();
+                    resolve();
+                });
+            } else {
+                file.close();
+                fs.unlinkSync(destination);
+                reject(new Error(`HTTP ${response.statusCode}`));
+            }
+        });
+
+        request.on("error", (error) => {
+            file.close();
+            if (fs.existsSync(destination)) fs.unlinkSync(destination);
+            reject(error);
+        });
+    });
+}
+
+/**
+ * Verify downloaded binary works
+ */
+function verifyBinary(filePath) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(filePath, ["--help"], {
+                stdio: "pipe",
+                timeout: 5000,
+            });
+
+            let output = "";
+            child.stdout.on("data", (data) => {
+                output += data.toString();
+            });
+
+            child.on("close", (code) => {
+                if (code === 0 && output.includes("XyPriss Memory Info CLI")) {
+                    resolve(true);
+                } else {
+                    resolve(false);
+                }
+            });
+
+            child.on("error", () => resolve(false));
+        } catch (error) {
+            resolve(false);
+        }
+    });
+}
+
+async function installMemoryCLI() {
+    if (!fs.existsSync(BIN_DIR)) {
+        fs.mkdirSync(BIN_DIR, { recursive: true });
+    }
+
+    const info = getPlatformBinary();
+    if (!info) return;
+
+    console.log(`📂 Target directory: ${BIN_DIR}`);
+    console.log(`📦 Binary: ${info.binaryName}`);
+
+    if (fs.existsSync(info.genericPath)) {
+        console.log(
+            `✨ Memory CLI already present at ${info.genericPath}, skipping.`,
+        );
+        return;
+    }
+
+    try {
+        console.log(`📥 Fetching Memory CLI from:`);
+        console.log(`   🔗 URL: ${info.url}`);
+        await downloadFile(info.url, info.localPath);
+        console.log("✅ Downloaded successfully.");
+
+        if (process.platform !== "win32") {
+            fs.chmodSync(info.localPath, 0o755);
+        }
+
+        if (process.platform === "win32") {
+            fs.copyFileSync(info.localPath, info.genericPath);
+        } else {
+            if (fs.existsSync(info.genericPath))
+                fs.unlinkSync(info.genericPath);
+            fs.symlinkSync(path.basename(info.localPath), info.genericPath);
+        }
+
+        const isValid = await verifyBinary(info.localPath);
+        if (isValid) {
+            console.log(
+                `🎉 XyPriss MCLI installed successfully at: ${info.genericPath}`,
+            );
+        } else {
+            console.warn(
+                "⚠️  MCLI verification failed, it might not work as expected.",
+            );
+        }
+    } catch (error) {
+        console.error("❌ Failed to install Memory CLI:", error.message);
+    }
+}
+
+// Only run if this is the main module (not being imported)
+if (import.meta.url === `file://${process.argv[1]}`) {
+    installMemoryCLI().catch((error) => {
+        console.error("💥 Installation failed:", error);
+        process.exit(0);
+    });
+}
+
+export { installMemoryCLI, getPlatformBinary, downloadFile, verifyBinary };
+

package/scripts/install-xems.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * XEMS Installer Script
+ * Downloads the XEMS (XyPriss Entry Management System) binary from GitHub Releases.
+ * Supports cross-platform: Windows, Linux, and macOS (Intel & Silicon).
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import https from "https";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ─────────────────────────────────────────────
+//  ANSI Color Palette
+// ─────────────────────────────────────────────
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+
+    // Foreground
+    white: "\x1b[97m",
+    gray: "\x1b[90m",
+    red: "\x1b[91m",
+    green: "\x1b[92m",
+    yellow: "\x1b[93m",
+    blue: "\x1b[94m",
+    magenta: "\x1b[95m",
+    cyan: "\x1b[96m",
+};
+
+// ─────────────────────────────────────────────
+//  Logger
+// ─────────────────────────────────────────────
+const log = {
+    info: (msg) =>
+        console.log(
+            `${c.cyan}${c.bold}  ℹ ${c.reset}${c.white}${msg}${c.reset}`,
+        ),
+    success: (msg) =>
+        console.log(
+            `${c.green}${c.bold}  ✔ ${c.reset}${c.green}${msg}${c.reset}`,
+        ),
+    warn: (msg) =>
+        console.log(
+            `${c.yellow}${c.bold}  ⚠ ${c.reset}${c.yellow}${msg}${c.reset}`,
+        ),
+    error: (msg) =>
+        console.log(`${c.red}${c.bold}  ✖ ${c.reset}${c.red}${msg}${c.reset}`),
+    step: (msg) =>
+        console.log(
+            `${c.magenta}${c.bold}  ▶ ${c.reset}${c.magenta}${msg}${c.reset}`,
+        ),
+    link: (label, url) =>
+        console.log(
+            `${c.gray}    └─ ${c.dim}${label}:${c.reset} ${c.blue}${url}${c.reset}`,
+        ),
+    detail: (msg) => console.log(`${c.gray}    ${msg}${c.reset}`),
+    divider: () => console.log(`${c.gray}  ${"─".repeat(52)}${c.reset}`),
+    blank: () => console.log(),
+};
+
+// ─────────────────────────────────────────────
+//  Constants
+// ─────────────────────────────────────────────
+const BIN_DIR = path.join(__dirname, "..", "bin");
+const REPO = "Nehonix-Team/XyPriss-XEMS";
+const CDN_BASE_URL = "https://dll.nehonix.com/dl/mds/xems/bin";
+
+// ─────────────────────────────────────────────
+//  Platform Detection
+// ─────────────────────────────────────────────
+
+/**
+ * Returns platform-specific binary metadata for XEMS.
+ * Maps to the files in tools/XEMS/dist/
+ */
+function getPlatformBinary() {
+    const platform = process.platform;
+    const arch = process.arch;
+
+    let binaryTarget;
+    if (platform === "win32") {
+        binaryTarget = arch === "arm64" ? "windows-arm64" : "windows-x64";
+    } else if (platform === "darwin") {
+        binaryTarget = arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+    } else if (platform === "linux") {
+        binaryTarget = arch === "arm64" ? "linux-arm64" : "linux-x64";
+    } else {
+        return null;
+    }
+
+    const ext = platform === "win32" ? ".exe" : "";
+    const binaryName = `xems-${binaryTarget}${ext}`;
+
+    return {
+        binaryName,
+        platform,
+        arch,
+        url: `https://github.com/${REPO}/releases/latest/download/${binaryName}`,
+        fallbackUrl: `${CDN_BASE_URL}/${binaryName}`,
+        localPath: path.join(BIN_DIR, binaryName),
+        genericPath: path.join(BIN_DIR, `xems${ext}`),
+    };
+}
+
+// ─────────────────────────────────────────────
+//  Downloader (with redirect support)
+// ─────────────────────────────────────────────
+
+function downloadFile(url, dest) {
+    return new Promise((resolve, reject) => {
+        const file = fs.createWriteStream(dest);
+        const request = https.get(
+            url,
+            { headers: { "User-Agent": "XyPriss-Installer" } },
+            (response) => {
+                // Follow redirects
+                if (
+                    response.statusCode >= 300 &&
+                    response.statusCode < 400 &&
+                    response.headers.location
+                ) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    return downloadFile(response.headers.location, dest)
+                        .then(resolve)
+                        .catch(reject);
+                }
+
+                if (response.statusCode !== 200) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    return reject(
+                        new Error(
+                            `Server responded with HTTP ${response.statusCode}`,
+                        ),
+                    );
+                }
+
+                // Stream progress dots
+                let received = 0;
+                process.stdout.write(`${c.gray}    └─ Downloading `);
+                response.on("data", (chunk) => {
+                    received += chunk.length;
+                    if (received % (50 * 1024) < chunk.length)
+                        process.stdout.write(`${c.blue}.${c.reset}`);
+                });
+
+                response.pipe(file);
+                file.on("finish", () => {
+                    process.stdout.write(` ${c.green}done${c.reset}\n`);
+                    file.close();
+                    resolve();
+                });
+            },
+        );
+
+        request.on("error", (err) => {
+            file.close();
+            if (fs.existsSync(dest)) fs.unlinkSync(dest);
+            reject(err);
+        });
+    });
+}
+
+// ─────────────────────────────────────────────
+//  Main Installer
+// ─────────────────────────────────────────────
+
+async function installXems() {
+    log.blank();
+    log.divider();
+    console.log(
+        `${c.cyan}${c.bold}  XEMS Installer — XyPriss Entry Management System${c.reset}`,
+    );
+    log.divider();
+    log.blank();
+
+    // Ensure bin directory exists
+    if (!fs.existsSync(BIN_DIR)) {
+        fs.mkdirSync(BIN_DIR, { recursive: true });
+        log.detail(`Created bin directory: ${BIN_DIR}`);
+    }
+
+    const info = getPlatformBinary();
+    if (!info) {
+        log.error(
+            "Unsupported platform/architecture. XEMS cannot be installed.",
+        );
+        return;
+    }
+
+    log.info(
+        `Platform  : ${c.yellow}${info.platform}${c.reset} ${c.gray}(${info.arch})${c.reset}`,
+    );
+    log.info(`Binary    : ${c.yellow}${info.binaryName}${c.reset}`);
+    log.info(`Target    : ${c.yellow}${BIN_DIR}${c.reset}`);
+    log.blank();
+
+    // Skip if already installed
+    if (fs.existsSync(info.genericPath)) {
+        log.success(`XEMS is already installed → ${info.genericPath}`);
+        log.blank();
+        return;
+    }
+
+    // Attempt GitHub download, then fallback CDN
+    log.step("Downloading XEMS binary…");
+    try {
+        try {
+            log.link("GitHub", info.url);
+            await downloadFile(info.url, info.localPath);
+            log.success("Downloaded from GitHub.");
+        } catch (githubErr) {
+            log.warn(`GitHub download failed: ${githubErr.message}`);
+            log.step("Retrying with fallback CDN…");
+            log.link("CDN", info.fallbackUrl);
+            await downloadFile(info.fallbackUrl, info.localPath);
+            log.success("Downloaded from fallback CDN.");
+        }
+
+        // Set executable bit on Unix
+        if (process.platform !== "win32") {
+            fs.chmodSync(info.localPath, 0o755);
+            log.detail("Executable permission set (chmod 755).");
+        }
+
+        // Create generic alias (symlink on Unix, copy on Windows)
+        if (process.platform === "win32") {
+            fs.copyFileSync(info.localPath, info.genericPath);
+            log.detail(`Copied binary → ${info.genericPath}`);
+        } else {
+            if (fs.existsSync(info.genericPath))
+                fs.unlinkSync(info.genericPath);
+            fs.symlinkSync(path.basename(info.localPath), info.genericPath);
+            log.detail(`Symlink created → ${info.genericPath}`);
+        }
+
+        log.blank();
+        log.success(
+            `XEMS successfully installed at: ${c.bold}${info.genericPath}${c.reset}`,
+        );
+    } catch (err) {
+        log.blank();
+        log.error(`XEMS installation failed: ${err.message}`);
+    }
+
+    log.blank();
+    log.divider();
+    log.blank();
+}
+
+// ─────────────────────────────────────────────
+//  Entry Point
+// ─────────────────────────────────────────────
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    installXems().catch((error) => {
+        log.error(`Fatal error: ${error.message}`);
+        process.exit(0);
+    });
+}
+
+export { installXems };

package/scripts/monitor_memory.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+
+set -euo pipefail
+
+readonly BLUE='\033[0;34m'
+readonly GREEN='\033[0;32m'
+readonly YELLOW='\033[1;33m'
+readonly NC='\033[0m'
+
+log_section() {
+    echo -e "\n${BLUE}========================================${NC}"
+    echo -e "${BLUE}$*${NC}"
+    echo -e "${BLUE}========================================${NC}"
+}
+
+get_xsys_pid() {
+    pgrep -f "xsys server start" | head -n 1 || echo ""
+}
+
+bytes_to_mb() {
+    echo "scale=2; $1 / 1024" | bc
+}
+
+monitor_memory() {
+    local xsys_pid
+    xsys_pid=$(get_xsys_pid)
+    
+    if [ -z "$xsys_pid" ]; then
+        echo "xsys process not found"
+        exit 1
+    fi
+    
+    log_section "XyPriss Memory Usage Monitor"
+    
+    echo -e "${GREEN}Parent Process (PID: $xsys_pid)${NC}"
+    ps -p "$xsys_pid" -o pid,%mem,rss,vsz,cmd --no-headers | while read -r line; do
+        local pid=$(echo "$line" | awk '{print $1}')
+        local mem_percent=$(echo "$line" | awk '{print $2}')
+        local rss=$(echo "$line" | awk '{print $3}')
+        local vsz=$(echo "$line" | awk '{print $4}')
+        local cmd=$(echo "$line" | awk '{$1=$2=$3=$4=""; print $0}' | xargs)
+        
+        local rss_mb=$(bytes_to_mb "$rss")
+        local vsz_mb=$(bytes_to_mb "$vsz")
+        
+        printf "  PID: %-8s | MEM: %6s%% | RSS: %8s MB | VSZ: %8s MB\n" \
+            "$pid" "$mem_percent" "$rss_mb" "$vsz_mb"
+        printf "  CMD: %s\n" "$cmd"
+    done
+    
+    echo ""
+    echo -e "${GREEN}Worker Processes${NC}"
+    
+    local worker_pids
+    worker_pids=$(pgrep -P "$xsys_pid" 2>/dev/null || true)
+    
+    if [ -z "$worker_pids" ]; then
+        echo "  No worker processes found"
+    else
+        local worker_count=0
+        local total_rss=0
+        
+        printf "  %-8s | %-8s | %-12s | %-12s\n" "PID" "MEM %" "RSS (MB)" "VSZ (MB)"
+        echo "  ----------------------------------------------------------------"
+        
+        ps --ppid "$xsys_pid" -o pid,%mem,rss,vsz --no-headers | while read -r pid mem rss vsz; do
+            local rss_mb=$(bytes_to_mb "$rss")
+            local vsz_mb=$(bytes_to_mb "$vsz")
+            
+            printf "  %-8s | %6s%% | %10s   | %10s\n" \
+                "$pid" "$mem" "$rss_mb" "$vsz_mb"
+            
+            worker_count=$((worker_count + 1))
+            total_rss=$((total_rss + rss))
+        done
+        
+        local worker_count=$(echo "$worker_pids" | wc -w)
+        local total_rss=$(ps --ppid "$xsys_pid" -o rss --no-headers | awk '{sum+=$1} END {print sum}')
+        local total_rss_mb=$(bytes_to_mb "$total_rss")
+        
+        echo "  ----------------------------------------------------------------"
+        printf "  ${YELLOW}Total: %d workers | Total RSS: %s MB${NC}\n" \
+            "$worker_count" "$total_rss_mb"
+    fi
+    
+    log_section "System Memory Overview"
+    
+    free -h | grep -E "(total|Mem|Swap)"
+    
+    log_section "Pre-allocated Memory Check"
+    
+    local parent_rss=$(ps -p "$xsys_pid" -o rss --no-headers)
+    local parent_rss_mb=$(bytes_to_mb "$parent_rss")
+    
+    echo "Parent process RSS: ${parent_rss_mb} MB"
+    
+    if (( $(echo "$parent_rss_mb > 100" | bc -l) )); then
+        echo -e "${GREEN}✓ Parent has significant memory footprint (pre-allocation likely active)${NC}"
+    else
+        echo -e "${YELLOW}âš  Parent has low memory footprint (pre-allocation may not be active)${NC}"
+    fi
+    
+    log_section "Top 10 Memory Consumers (System-wide)"
+    
+    ps aux --sort=-%mem | head -11 | awk 'NR==1 || /xsys/ || NR<=11 {print}' | \
+        awk '{printf "%-8s %-8s %6s%% %10s %s\n", $2, $1, $4, $6, $11}'
+}
+
+continuous_monitor() {
+    while true; do
+        clear
+        monitor_memory
+        echo ""
+        echo "Press Ctrl+C to stop. Refreshing in 3 seconds..."
+        sleep 3
+    done
+}
+
+if [ "${1:-}" = "-c" ] || [ "${1:-}" = "--continuous" ]; then
+    continuous_monitor
+else
+    monitor_memory
+    echo ""
+    echo "Tip: Use './monitor_memory.sh -c' for continuous monitoring"
+fi

package/scripts/postinstall-xsys.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * XSYS Installer Script
+ * Downloads the XSYS (XyPriss System Core) binary from GitHub Releases.
+ * Supports cross-platform: Windows, Linux, and macOS (Intel & Silicon).
+ */
+
+import fs from "fs";
+import { join, dirname, basename } from "path";
+import { platform, arch } from "os";
+import https from "https";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ─────────────────────────────────────────────
+//  ANSI Color Palette
+// ─────────────────────────────────────────────
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    white: "\x1b[97m",
+    gray: "\x1b[90m",
+    red: "\x1b[91m",
+    green: "\x1b[92m",
+    yellow: "\x1b[93m",
+    blue: "\x1b[94m",
+    magenta: "\x1b[95m",
+    cyan: "\x1b[96m",
+};
+
+// ─────────────────────────────────────────────
+//  Logger
+// ─────────────────────────────────────────────
+const log = {
+    info: (msg) =>
+        console.log(
+            `${c.cyan}${c.bold}  ℹ ${c.reset}${c.white}${msg}${c.reset}`,
+        ),
+    success: (msg) =>
+        console.log(
+            `${c.green}${c.bold}  ✔ ${c.reset}${c.green}${msg}${c.reset}`,
+        ),
+    warn: (msg) =>
+        console.log(
+            `${c.yellow}${c.bold}  ⚠ ${c.reset}${c.yellow}${msg}${c.reset}`,
+        ),
+    error: (msg) =>
+        console.log(`${c.red}${c.bold}  ✖ ${c.reset}${c.red}${msg}${c.reset}`),
+    step: (msg) =>
+        console.log(
+            `${c.magenta}${c.bold}  ▶ ${c.reset}${c.magenta}${msg}${c.reset}`,
+        ),
+    link: (label, url) =>
+        console.log(
+            `${c.gray}    └─ ${c.dim}${label}:${c.reset} ${c.blue}${url}${c.reset}`,
+        ),
+    detail: (msg) => console.log(`${c.gray}    ${msg}${c.reset}`),
+    divider: () => console.log(`${c.gray}  ${"─".repeat(52)}${c.reset}`),
+    blank: () => console.log(),
+};
+
+// ─────────────────────────────────────────────
+//  Constants
+// ─────────────────────────────────────────────
+const REPO = "Nehonix-Team/XyPriss";
+const BIN_NAME = "xsys";
+const BIN_DIR = join(__dirname, "..", "bin");
+
+// ─────────────────────────────────────────────
+//  Downloader (with redirect support)
+// ─────────────────────────────────────────────
+
+function downloadFile(url, dest) {
+    return new Promise((resolve, reject) => {
+        const file = fs.createWriteStream(dest);
+        const request = https.get(
+            url,
+            { headers: { "User-Agent": "XyPriss-Installer" } },
+            (response) => {
+                // Follow redirects
+                if (
+                    response.statusCode >= 300 &&
+                    response.statusCode < 400 &&
+                    response.headers.location
+                ) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    return downloadFile(response.headers.location, dest)
+                        .then(resolve)
+                        .catch(reject);
+                }
+
+                if (response.statusCode !== 200) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    return reject(
+                        new Error(
+                            `Server responded with HTTP ${response.statusCode}`,
+                        ),
+                    );
+                }
+
+                // Stream progress dots
+                let received = 0;
+                process.stdout.write(`${c.gray}    └─ Downloading `);
+                response.on("data", (chunk) => {
+                    received += chunk.length;
+                    if (received % (50 * 1024) < chunk.length)
+                        process.stdout.write(`${c.blue}.${c.reset}`);
+                });
+
+                response.pipe(file);
+                file.on("finish", () => {
+                    process.stdout.write(` ${c.green}done${c.reset}\n`);
+                    file.close();
+                    resolve();
+                });
+            },
+        );
+
+        request.on("error", (err) => {
+            file.close();
+            if (fs.existsSync(dest)) fs.unlinkSync(dest);
+            reject(err);
+        });
+    });
+}
+
+// ─────────────────────────────────────────────
+//  Main Installer
+// ─────────────────────────────────────────────
+
+async function installXsys() {
+    log.blank();
+    log.divider();
+    console.log(
+        `${c.cyan}${c.bold}  XSYS Installer — XyPriss System Core${c.reset}`,
+    );
+    log.divider();
+    log.blank();
+
+    // Ensure bin directory exists
+    if (!fs.existsSync(BIN_DIR)) {
+        fs.mkdirSync(BIN_DIR, { recursive: true });
+        log.detail(`Created bin directory: ${BIN_DIR}`);
+    }
+
+    const osName = platform();
+    const archName = arch();
+
+    // Map to binary target name
+    let binaryTarget = "";
+    if (osName === "linux") {
+        binaryTarget = archName === "arm64" ? "linux-arm64" : "linux-amd64";
+    } else if (osName === "darwin") {
+        binaryTarget = archName === "arm64" ? "darwin-arm64" : "darwin-amd64";
+    } else if (osName === "win32") {
+        binaryTarget = archName === "arm64" ? "windows-arm64" : "windows-amd64";
+    } else {
+        log.error(`Unsupported platform: ${osName}`);
+        return;
+    }
+
+    const ext = osName === "win32" ? ".exe" : "";
+    const binaryFileName = `${BIN_NAME}-${binaryTarget}${ext}`;
+    const url = `https://github.com/${REPO}/releases/latest/download/${binaryFileName}`;
+    const localPath = join(BIN_DIR, binaryFileName);
+    const genericPath = join(BIN_DIR, `${BIN_NAME}${ext}`);
+
+    log.info(
+        `Platform  : ${c.yellow}${osName}${c.reset} ${c.gray}(${archName})${c.reset}`,
+    );
+    log.info(`Binary    : ${c.yellow}${binaryFileName}${c.reset}`);
+    log.info(`Target    : ${c.yellow}${BIN_DIR}${c.reset}`);
+    log.blank();
+
+    // Skip if already installed
+    if (fs.existsSync(genericPath)) {
+        log.success(`XSYS is already installed → ${genericPath}`);
+        log.blank();
+        return;
+    }
+
+    // Download
+    log.step("Downloading XSYS binary…");
+    log.link("GitHub", url);
+
+    try {
+        await downloadFile(url, localPath);
+
+        // Set executable bit on Unix
+        if (osName !== "win32") {
+            fs.chmodSync(localPath, 0o755);
+            log.detail("Executable permission set (chmod 755).");
+        }
+
+        // Create generic alias (symlink on Unix, copy on Windows)
+        if (osName === "win32") {
+            fs.copyFileSync(localPath, genericPath);
+            log.detail(`Copied binary → ${genericPath}`);
+        } else {
+            if (fs.existsSync(genericPath)) fs.unlinkSync(genericPath);
+            fs.symlinkSync(basename(localPath), genericPath);
+            log.detail(`Symlink created → ${genericPath}`);
+        }
+
+        log.blank();
+        log.success(
+            `XSYS successfully installed at: ${c.bold}${genericPath}${c.reset}`,
+        );
+    } catch (err) {
+        log.blank();
+        log.error(`XSYS installation failed: ${err.message}`);
+    }
+
+    log.blank();
+    log.divider();
+    log.blank();
+}
+
+// ─────────────────────────────────────────────
+//  Entry Point - EP
+// ─────────────────────────────────────────────
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    installXsys().catch(() => process.exit(0));
+}
+
+export { installXsys };

package/scripts/postinstall.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * XyPriss Post-Install Script
+ * Runs after `npm install` to set up all platform-specific binaries.
+ */
+
+import { installMemoryCLI } from "./install-memory-cli.js";
+import { installXems } from "./install-xems.js";
+import { installXsys } from "./postinstall-xsys.js";
+
+// ─────────────────────────────────────────────
+//  ANSI Color Palette
+// ─────────────────────────────────────────────
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    white: "\x1b[97m",
+    gray: "\x1b[90m",
+    red: "\x1b[91m",
+    green: "\x1b[92m",
+    yellow: "\x1b[93m",
+    blue: "\x1b[94m",
+    magenta: "\x1b[95m",
+    cyan: "\x1b[96m",
+};
+
+// ─────────────────────────────────────────────
+//  Logger
+// ─────────────────────────────────────────────
+const log = {
+    info: (msg) =>
+        console.log(
+            `${c.cyan}${c.bold}  ℹ ${c.reset}${c.white}${msg}${c.reset}`,
+        ),
+    success: (msg) =>
+        console.log(
+            `${c.green}${c.bold}  ✔ ${c.reset}${c.green}${msg}${c.reset}`,
+        ),
+    warn: (msg) =>
+        console.log(
+            `${c.yellow}${c.bold}  ⚠ ${c.reset}${c.yellow}${msg}${c.reset}`,
+        ),
+    error: (msg) =>
+        console.log(`${c.red}${c.bold}  ✖ ${c.reset}${c.red}${msg}${c.reset}`),
+    step: (n, label) =>
+        console.log(
+            `${c.magenta}${c.bold}  [${n}] ${c.reset}${c.magenta}${label}${c.reset}`,
+        ),
+    divider: () => console.log(`${c.gray}  ${"─".repeat(52)}${c.reset}`),
+    blank: () => console.log(),
+};
+
+// ─────────────────────────────────────────────
+//  Steps Definition
+// ─────────────────────────────────────────────
+const STEPS = [
+    { label: "Memory CLI", fn: installMemoryCLI },
+    { label: "XEMS — XyPriss Entry Management System", fn: installXems },
+    { label: "XSYS — XyPriss System Core", fn: installXsys },
+];
+
+// ─────────────────────────────────────────────
+//  Post-Install Orchestrator
+// ─────────────────────────────────────────────
+async function postInstall() {
+    log.blank();
+    log.divider();
+    console.log(`${c.cyan}${c.bold}  XyPriss — Post-Install Setup${c.reset}`);
+    log.divider();
+    log.blank();
+
+    const results = [];
+
+    for (let i = 0; i < STEPS.length; i++) {
+        const { label, fn } = STEPS[i];
+        log.step(`${i + 1}/${STEPS.length}`, label);
+
+        try {
+            await fn();
+            results.push({ label, ok: true });
+        } catch (err) {
+            log.warn(`Step "${label}" encountered an issue: ${err.message}`);
+            results.push({ label, ok: false, err: err.message });
+        }
+
+        log.blank();
+    }
+
+    // ── Summary ──────────────────────────────────
+    log.divider();
+    console.log(`${c.cyan}${c.bold}  Setup Summary${c.reset}`);
+    log.divider();
+
+    let allOk = true;
+    for (const r of results) {
+        if (r.ok) {
+            log.success(r.label);
+        } else {
+            log.warn(`${r.label}  ${c.gray}(skipped: ${r.err})${c.reset}`);
+            allOk = false;
+        }
+    }
+
+    log.blank();
+
+    if (allOk) {
+        log.success("All components installed. XyPriss is ready!");
+    } else {
+        log.warn(
+            "Setup completed with warnings. XyPriss will run in fallback mode.",
+        );
+        log.info(
+            "Some features may be limited until missing binaries are installed.",
+        );
+    }
+
+    log.blank();
+    log.divider();
+    log.blank();
+}
+
+// ─────────────────────────────────────────────
+//  Entry Point
+// ─────────────────────────────────────────────
+if (import.meta.url === `file://${process.argv[1]}`) {
+    postInstall().catch((error) => {
+        log.error(`Fatal error during post-install: ${error.message}`);
+        process.exit(0); // Don't break `npm install`
+    });
+}
+
+export { postInstall };

package/scripts/test-fs-full.ts

@@ -0,0 +1,96 @@
+import { XyPrissSys } from "../src/sys";
+import { XyPrissRunner } from "../src/sys/XyPrissRunner";
+
+// Mock the global object structure if needed or just instantiate verify
+// Since we are running with bun, we can probably just use the classes directly if we export them or setup the environment.
+// But easier: invoke the existing API logic.
+
+// We need to instantiate the system similar to how index.ts does it
+const runner = new XyPrissRunner(process.cwd());
+const sys = new XyPrissSys(runner);
+
+// Monkey patch global if needed by some internals, but FSApi mainly uses `this.runner`
+// casting to any to access the dynamically mixed-in methods if typescript complains,
+// though we instantiated SysApi which extends FSApi.
+
+console.log("\n--- STARTING DEDICATED FS API VERIFICATION ---");
+
+const testDir = "temp_fs_verification";
+const testFile = `${testDir}/verify.txt`;
+
+try {
+    // 1. Directory Management
+    sys.$rmIfExists(testDir);
+    sys.$ensureDir(testDir);
+    if (!sys.$isDir(testDir)) throw new Error("Dir creation failed");
+    console.log("[PASS] Directory creation");
+
+    // 2. File Writing & Existence
+    // @ts-ignore
+    sys.$writeIfNotExists(testFile, "Line 1\n");
+    if (!sys.$exists(testFile)) throw new Error("File creation failed");
+    // @ts-ignore
+    const wroteAgain = sys.$writeIfNotExists(testFile, "New Content");
+    if (wroteAgain)
+        throw new Error(
+            "writeIfNotExists should return false for existing file"
+        );
+    console.log("[PASS] File writing and existence check");
+
+    // 3. Appending & Reading
+    // @ts-ignore
+    sys.$appendLine(testFile, "Line 2");
+    // @ts-ignore
+    const lines = sys.$readLines(testFile);
+    if (lines.length !== 3)
+        throw new Error(`Expected 3 lines (incl empty), got ${lines.length}`);
+    // @ts-ignore
+    const nonEmpty = sys.$readNonEmptyLines(testFile);
+    if (nonEmpty.length !== 2)
+        throw new Error(`Expected 2 non-empty lines, got ${nonEmpty.length}`);
+    console.log("[PASS] Append and Read Lines");
+
+    // 4. Metadata
+    // @ts-ignore
+    const sizeHuman = sys.$sizeHuman(testFile);
+    if (!sizeHuman.includes("B")) throw new Error("Invalid human size format");
+    // @ts-ignore
+    const createdAt = sys.$createdAt(testFile);
+    if (!(createdAt instanceof Date) || isNaN(createdAt.getTime()))
+        throw new Error("Invalid creation date");
+    console.log("[PASS] Metadata (Size & Dates)");
+
+    // 5. Manipulation
+    const copyFile = "verify_copy.txt";
+    // @ts-ignore
+    sys.$duplicate(testFile, copyFile);
+    if (!sys.$exists(`${testDir}/${copyFile}`))
+        throw new Error("Duplication failed");
+
+    const renamedFile = "verify_renamed.txt";
+    // @ts-ignore
+    sys.$rename(`${testDir}/${copyFile}`, `${testDir}/${renamedFile}`);
+    if (sys.$exists(`${testDir}/${copyFile}`))
+        throw new Error("Old file still exists after rename");
+    if (!sys.$exists(`${testDir}/${renamedFile}`))
+        throw new Error("Renamed file missing");
+    console.log("[PASS] Duplication and Renaming");
+
+    // 6. Search
+    // @ts-ignore
+    const txtFiles = sys.$findByExt(testDir, "txt");
+    if (txtFiles.length < 2) throw new Error("Failed to find .txt files");
+    console.log("[PASS] Extension search");
+
+    // 7. Cleanup
+    // @ts-ignore
+    sys.$rmIfExists(testDir);
+    if (sys.$exists(testDir)) throw new Error("Cleanup failed");
+    console.log("[PASS] Cleanup");
+
+    console.log("\n✅ ALL FS API TESTS PASSED SUCCESSFULLY");
+} catch (error) {
+    console.error("\n❌ TEST FAILED:", error);
+    process.exit(1);
+}
+

package/scripts/verify-xsys-bridge.ts

@@ -0,0 +1,48 @@
+import { XyPrissFS } from "../src/sys/System";
+
+async function testBridge() {
+    console.log("🚀 Testing XyPrissFS Rust Bridge...");
+
+    const root = process.cwd();
+    const xfs = new XyPrissFS({ __root__: root });
+
+    try {
+        // 1. Test Path Operations (JS)
+        console.log("\n--- Path Operations (JS) ---");
+        const resolved = xfs.$resolve("src", "index.ts");
+        console.log(`Resolved path: ${resolved}`);
+
+        // 2. Test Filesystem Operations (Rust)
+        console.log("\n--- Filesystem Operations (Rust) ---");
+        const items = xfs.$ls(".");
+        console.log(`Found ${items.length} items in root.`);
+        console.log(`First 5 items: ${items.slice(0, 5).join(", ")}`);
+
+        // 3. Test System Operations (Rust)
+        console.log("\n--- System Operations (Rust) ---");
+        const cpuCores = xfs.$cpu(true);
+        if (cpuCores && cpuCores.length > 0) {
+            console.log(`CPU: ${cpuCores[0].brand}`);
+            console.log(`Cores: ${cpuCores[0].core_count} detected`);
+        }
+
+        const memInfo = xfs.$memory();
+        console.log(
+            `Memory: ${(memInfo.total / 1024 / 1024 / 1024).toFixed(2)} GB`
+        );
+
+        // 4. Test Search Operations (Rust)
+        console.log("\n--- Search Operations (Rust) ---");
+        const tsFiles = xfs.$find("src", "\\.ts$");
+        console.log(`Found ${tsFiles.length} TypeScript files in src.`);
+
+        console.log("\n✅ All bridge tests passed!");
+    } catch (error) {
+        console.error("\n--- OUTPUT DEBUG ---");
+        console.error(error);
+        process.exit(1);
+    }
+}
+
+testBridge();
+

package/scripts/xems.run.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/***************************************************************************
+ * XyPrissJS - Fast And Secure
+ *
+ * @author Nehonix
+ * @license Nehonix OSL (NOSL)
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * This License governs the use, modification, and distribution of software
+ * provided by NEHONIX under its open source projects.
+ * NEHONIX is committed to fostering collaborative innovation while strictly
+ * protecting its intellectual property rights.
+ * Violation of any term of this License will result in immediate termination of all granted rights
+ * and may subject the violator to legal action.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+ * AND NON-INFRINGEMENT.
+ * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+ * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ *
+ ***************************************************************************** */
+
+/**
+ * Nehonix XEMS CLI Bridge
+ *
+ * This is the main bridge for the xems command.
+ * It manages the execution of the proprietary Go-based XEMS binary.
+ *
+ * © 2026 Nehonix Team. All rights reserved.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Get the path to the xems binary
+ */
+function getBinaryPath() {
+    const isWin = os.platform() === "win32";
+    const binName = isWin ? "xems.exe" : "xems";
+
+    // Strategic locations for the binary
+    const locations = [
+        path.join(__dirname, "..", "bin", binName), // Production (npm install)
+        path.join(process.cwd(), "bin", binName), // Local development
+        path.join(__dirname, "..", "tools", "XEMS", "bin", binName), // Dev target
+        path.join(__dirname, "..", "tools", "XEMS", "dist", binName), // Dist target
+    ];
+
+    for (const loc of locations) {
+        if (fs.existsSync(loc)) {
+            return loc;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Execute the binary with the provided arguments
+ */
+function main() {
+    const binaryPath = getBinaryPath();
+    const args = process.argv.slice(2);
+
+    if (!binaryPath) {
+        console.error("\x1b[31m[ERROR] XEMS Binary not found.\x1b[0m");
+        console.error(
+            "Please ensure the binary is installed by running: \x1b[36mxfpm update xypriss\x1b[0m",
+        );
+        process.exit(1);
+    }
+
+    // Spawn the binary process
+    const child = spawn(binaryPath, args, {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            XEMS_BINARY_PATH: binaryPath,
+            XEMS_EXEC_CONTEXT: "npm-bin",
+        },
+    });
+
+    // Mirror exit signals and codes
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+        } else {
+            process.exit(code ?? 0);
+        }
+    });
+
+    child.on("error", (err) => {
+        console.error(
+            "\x1b[31m[CRITICAL] Failed to initiate xems execution:\x1b[0m",
+            err.message,
+        );
+        process.exit(1);
+    });
+}
+
+main();
+
+

package/scripts/xys.run.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/* *****************************************************************************
+ * Nehonix XyPriss System CLI
+ * 
+ * ACCESS RESTRICTIONS:
+ * - This software is exclusively for use by Authorized Personnel of NEHONIX
+ * - Intended for Internal Use only within NEHONIX operations
+ * - No rights granted to unauthorized individuals or entities
+ * - All modifications are works made for hire assigned to NEHONIX
+ *
+ * PROHIBITED ACTIVITIES:
+ * - Copying, distributing, or sublicensing without written permission
+ * - Reverse engineering, decompiling, or disassembling
+ * - Creating derivative works without explicit authorization
+ * - External use or commercial distribution outside NEHONIX
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * For questions or permissions, contact:
+ * NEHONIX Legal Department
+ * Email: legal@nehonix.com
+ * Website: www.nehonix.com
+ ***************************************************************************** */
+
+/**
+ * Nehonix XyPriss System CLI Tool - High-performance system & FS management
+ *
+ * This is the main bridge for the xsys command.
+ * It manages the execution of the proprietary Rust-based xsys binary.
+ *
+ * © 2026 Nehonix Team. All rights reserved.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Support ESM __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Get the path to the xsys binary
+ */
+function getBinaryPath() {
+    const isWin = os.platform() === "win32";
+    const binName = isWin ? "xsys.exe" : "xsys";
+
+    // Strategic locations for the binary
+    const locations = [
+        path.join(__dirname, "..", "bin", binName), // Production (npm install)
+        path.join(process.cwd(), "bin", binName), // Local development
+        path.join(
+            __dirname,
+            "..",
+            "tools",
+            "xypriss-sys",
+            "target",
+            "release",
+            binName
+        ), // Dev target
+    ];
+
+    for (const loc of locations) {
+        if (fs.existsSync(loc)) {
+            return loc;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Execute the binary with the provided arguments
+ */
+function main() {
+    const binaryPath = getBinaryPath();
+    const args = process.argv.slice(2);
+
+    if (!binaryPath) {
+        console.error(
+            "\x1b[31m[ERROR] XyPriss System Binary (xsys) not found.\x1b[0m"
+        );
+        console.error(
+            "Please ensure the binary is installed by running: \x1b[36mnpm update xypriss\x1b[0m"
+        );
+        process.exit(1);
+    }
+
+    // Spawn the binary process
+    const child = spawn(binaryPath, args, {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            XYPRISS_BINARY_PATH: binaryPath,
+            XYPRISS_EXEC_CONTEXT: "npm-bin",
+        },
+    });
+
+    // Mirror exit signals and codes
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+        } else {
+            process.exit(code ?? 0);
+        }
+    });
+
+    child.on("error", (err) => {
+        console.error(
+            "\x1b[31m[CRITICAL] Failed to initiate xsys execution:\x1b[0m",
+            err.message
+        );
+        process.exit(1);
+    });
+}
+
+// Execution entry point
+main();
+
+