@xaidenlabs/uso 1.1.61 → 1.1.63

package/README.md

@@ -61,6 +61,27 @@ The installer will:
 
 ---
 
+### Stealth WSL Mode (Windows Only)
+
+On Windows, USO can install the entire toolchain inside a hidden WSL2 Linux distribution called the **Uso Engine**. This avoids Windows-specific issues like Smart App Control, symlink errors, and "Access Denied" problems entirely.
+
+**Enable Stealth Mode:**
+```bash
+uso init --wsl
+```
+
+Once enabled, all subsequent commands (`uso build`, `uso test`, `uso val`, etc.) are automatically routed through the WSL engine. You stay in PowerShell—the Linux layer is completely invisible.
+
+**How it works:**
+-   USO installs a minimal Ubuntu WSL2 distro and hides it from Windows Terminal.
+-   Rust, Solana CLI, and Anchor are installed inside the distro.
+-   Commands are transparently bridged: you run `uso build` in PowerShell, and it executes `anchor build` inside WSL.
+-   The local validator binds to `localhost`, so your tests connect seamlessly.
+
+**Configuration** is stored in `~/.uso-config.json`. To switch back to native mode, delete this file or reinstall without `--wsl`.
+
+---
+
 ### Granular Installation
 
 Use the `install` command to set up individual components if you do not require the full stack.
@@ -82,8 +103,6 @@ uso install anchor
 
 ---
 
----
-
 ### Project Scaffolding
 
 Start a new project with a robust, pre-configured Anchor template.
@@ -99,6 +118,88 @@ This generates a "batteries-included" workspace with:
 
 ---
 
+### Workflow Commands
+
+USO wraps the core Anchor and Solana CLI commands so you don't need to worry about PATH issues or WSL routing.
+
+**Build your program:**
+```bash
+uso build
+```
+
+**Run tests:**
+```bash
+uso test
+```
+On Windows, USO automatically checks if a validator is running before starting tests, preventing hangs.
+
+**Deploy your program:**
+```bash
+uso deploy
+```
+
+**Clean build artifacts:**
+```bash
+uso clean
+```
+
+---
+
+### Wallet & SOL Commands
+
+Manage your Solana wallet and devnet SOL directly from USO.
+
+**Show your wallet address:**
+```bash
+uso address
+```
+
+**Check your SOL balance:**
+```bash
+uso balance
+```
+
+**Check balance of a specific address:**
+```bash
+uso balance <address>
+```
+
+**Airdrop SOL (devnet/testnet):**
+```bash
+uso airdrop 2
+uso airdrop 5 <recipient-address>
+```
+
+---
+
+### Developer Tools
+
+**Start a local test validator:**
+```bash
+uso validator
+# or the shorthand:
+uso val
+```
+
+Pass flags directly to the validator:
+```bash
+uso val --reset
+```
+
+On Windows, if the validator encounters "Access Denied" errors, USO automatically retries in an elevated Administrator terminal with Windows Defender exclusions applied.
+
+**Full developer mode (Validator + Watcher):**
+```bash
+uso dev
+```
+
+This command:
+1.  Starts (or detects) a local validator.
+2.  Runs your test suite.
+3.  Watches for `.rs` and `.ts` file changes and automatically re-runs tests.
+
+---
+
 ### Verification
 
 After installation, verify that all components are correctly configured and accessible in your system PATH.
@@ -127,7 +228,7 @@ If your builds fail with `os error 4551` or "Access Denied" due to Smart App Con
 
 USO provides a clean uninstallation process to remove the installed toolchains.
 
-**Remove All Components:**
+**Remove All Components (interactive):**
 ```bash
 uso uninstall
 ```
@@ -141,6 +242,29 @@ uso uninstall anchor
 
 ---
 
+## Command Reference
+
+| Command | Description |
+|---|---|
+| `uso init` | Install full stack (Rust, Solana, Anchor) |
+| `uso init --wsl` | Install via Stealth WSL Engine (Windows) |
+| `uso doctor` | Diagnose environment issues |
+| `uso verify` | Verify toolchain with test build |
+| `uso create <name>` | Scaffold a new Anchor project |
+| `uso build` | Build the Anchor program |
+| `uso test` | Run Anchor tests |
+| `uso deploy` | Deploy the program |
+| `uso clean` | Clean build artifacts |
+| `uso address` | Show wallet address |
+| `uso balance [addr]` | Show SOL balance |
+| `uso airdrop <amt> [to]` | Airdrop SOL |
+| `uso val` / `uso validator` | Start local test validator |
+| `uso dev` | Dev mode (validator + watcher) |
+| `uso unblock` | Unblock files on Windows |
+| `uso uninstall [component]` | Remove installed toolchains |
+
+---
+
 ## Troubleshooting
 
 -   **"Permission Denied" Errors**: If you encounter errors related to permissions or symlinks, try running your terminal as an Administrator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaidenlabs/uso",
-  "version": "1.1.61",
+  "version": "1.1.63",
   "description": "Universal Solana Development Toolchain. Native or Stealth WSL Mode. Build, test, and deploy without the friction.",
   "bin": {
     "uso": "bin/index.js"

package/src/commands/doctor.js

@@ -13,6 +13,44 @@ const checkGit = (silent = false) => {
     return installed;
 };
 
+const checkWsl = (silent = false) => {
+    // Only relevant on Windows
+    if (os.platform() !== 'win32') return true;
+
+    // 1. Check wsl.exe exists
+    const hasWslBinary = !!shell.which('wsl');
+    if (!hasWslBinary) {
+        if (!silent) {
+            log.error("❌ WSL not installed");
+            log.warn("   👉 Run 'uso install' to automatically install WSL (admin permission required).");
+        }
+        return false;
+    }
+
+    // 2. Check WSL feature is active
+    const statusCheck = shell.exec('wsl --status', { silent: true });
+    if (statusCheck.code !== 0) {
+        if (!silent) {
+            log.warn("⚠️  WSL is installed but not fully configured (restart may be pending).");
+            log.warn("   👉 Try restarting your PC, then run 'uso install' again.");
+        }
+        return false;
+    }
+
+    // 3. Check Ubuntu distro is ready
+    const ubuntuCheck = shell.exec('wsl -d Ubuntu -e true', { silent: true });
+    if (ubuntuCheck.code !== 0) {
+        if (!silent) {
+            log.warn("⚠️  WSL installed but Ubuntu distro is not yet set up.");
+            log.warn("   👉 Run 'uso install' to finish the setup.");
+        }
+        return false;
+    }
+
+    if (!silent) log.success("✅ WSL installed and Ubuntu ready");
+    return true;
+};
+
 const checkRust = (silent = false) => {
     const rustc = shell.exec('rustc --version', { silent: true });
     const installed = rustc.code === 0;
@@ -111,6 +149,7 @@ const doctor = async () => {
     log.header(`🩺 Running Doctor for ${platform}...`);
 
     checkGit();
+    if (platform === 'win32') checkWsl();
     checkRust();
     checkSolana();
     checkAnchor();
@@ -120,6 +159,7 @@ const doctor = async () => {
 module.exports = {
     doctor,
     checkGit,
+    checkWsl,
     checkRust,
     checkSolana,
     checkAnchor,

package/src/commands/init.js

@@ -10,23 +10,36 @@ const { ensureWalletInteractive } = require('../utils/wallet');
 const path = require('path');
 const fs = require('fs');
 
-const { installWsl } = require('../platforms/wsl');
+const { installWsl, installWslFeature } = require('../platforms/wsl');
 
 const init = async (component, options) => {
     const platform = os.platform();
 
-    // --- AUTO-DETECT: On Windows, silently use WSL Stealth Mode if available ---
+    // --- On Windows, ALWAYS use the WSL path ---
     if (platform === 'win32') {
-        const forceWsl = options && options.wsl;
-        // Check if WSL + Ubuntu is available (quick check: wsl -d Ubuntu -e true)
-        const wslCheck = shell.exec('wsl -d Ubuntu -e true', { silent: true });
-        const wslAvailable = wslCheck.code === 0;
+        const hasWslBinary = !!shell.which('wsl');
 
-        if (forceWsl || wslAvailable) {
-            await installWsl();
-            return;
+        if (!hasWslBinary) {
+            // WSL is not installed at all — request admin elevation to enable the feature
+            log.header("🐧 Windows Subsystem for Linux (WSL) not found.");
+            log.info("🛡️  Requesting administrator permission to install WSL...");
+            log.info("👉 Please click 'Yes' in the UAC popup that appears to allow this.");
+            console.log("");
+
+            const wslInstalled = await installWslFeature();
+
+            if (!wslInstalled) {
+                // installWslFeature already printed the relevant error/reboot message
+                return;
+            }
+
+            // If we're here, WSL was instantly available (rare — usually needs reboot)
+            // Fall through to installWsl() below
         }
-        // If WSL not available and --wsl not forced, fall through to native install
+
+        // WSL binary is present — run the full WSL toolchain install
+        await installWsl();
+        return;
     }
 
     if (component) {

package/src/commands/uninstall.js

@@ -20,8 +20,6 @@ const askQuestion = (query) => {
  * Runs a command and attempts to elevate privileges if it fails with a permission error.
  */
 const runOrElevate = (command, description) => {
-    log.info(`Running: ${description}...`);
-
     // We run without silent:true initially to let the user see output, 
     // but detecting the error code is what matters.
     // actually, to detect the specific string "os error 1314", we need to capture output.

package/src/commands/workflow.js

@@ -15,19 +15,12 @@ const runProxyCommand = async (command, args = [], binary = 'anchor') => {
     const nativeAvailable = shell.which(binary);
     if (stealth.enabled && !nativeAvailable) {
         const fullCommand = `${binary} ${command} ${args.join(' ')}`;
-        log.header(`🚀 Running: ${fullCommand}`);
-        log.info(`🐧 Routing through Uso Engine...`);
 
         // Source cargo/solana paths inside WSL before running
         const envSetup = 'source $HOME/.cargo/env 2>/dev/null; export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"';
         const wslCwd = toWslPath(process.cwd());
         const execution = runWsl(`${envSetup} && ${fullCommand}`, { distro: stealth.distro, cwd: process.cwd() });
 
-        if (execution.code === 0) {
-            log.success(`✅ '${command}' completed successfully.`);
-        } else {
-            log.error(`❌ '${command}' failed.`);
-        }
         return;
     }
 
@@ -40,12 +33,10 @@ const runProxyCommand = async (command, args = [], binary = 'anchor') => {
     }
 
     const fullCommand = `${binary} ${command} ${args.join(' ')}`;
-    log.header(`🚀 Running: ${fullCommand}`);
 
     const execution = shell.exec(fullCommand);
 
     if (execution.code === 0) {
-        log.success(`✅ '${command}' completed successfully.`);
         return;
     }
 
@@ -61,7 +52,7 @@ const runProxyCommand = async (command, args = [], binary = 'anchor') => {
         } else {
             log.warn("⚠️  Windows requires Administrator privileges for this operation.");
         }
-        log.info("🔑 Requesting elevated access (command will run in background)...\n");
+
 
         // Clean stale blocked artifacts before elevated retry (only for cargo/anchor builds)
         if (isAppControlBlock && binary === 'anchor') {
@@ -72,7 +63,7 @@ const runProxyCommand = async (command, args = [], binary = 'anchor') => {
 
         await runElevatedWithProgress(command, args, binary);
     } else {
-        log.error(`❌ '${command}' failed.`);
+        // Command failed (non-elevated)
     }
 };
 
@@ -91,8 +82,7 @@ const runElevatedWithProgress = (command, args = [], binary = 'anchor') => {
         // 1. Prepare progress file
         try { fs.writeFileSync(progressFile, ''); } catch (e) { }
 
-        log.info("🚀 Spawning visible Administrator terminal...");
-        log.warn("👉 Output will be mirrored below. Keep the new window open!");
+
 
         // 2. Construct Elevated Command
         const innerCmd = `
@@ -239,8 +229,6 @@ const validator = async (args = []) => {
         const cmdArgs = flags.join(' ');
         const fullCmd = `solana-test-validator ${cmdArgs}`;
 
-        log.header(`🚀 Starting Validator via Uso Engine...`);
-        log.info(`🐧 Running: ${fullCmd}`);
         log.info("👉 Press Ctrl+C to stop it.");
 
         const envSetup = 'source $HOME/.cargo/env 2>/dev/null; export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"';
@@ -304,7 +292,6 @@ const validator = async (args = []) => {
     const cmdArgs = flags.join(' ');
     const fullCmd = cmdArgs ? `solana-test-validator ${cmdArgs}` : 'solana-test-validator';
 
-    log.header(`🚀 Starting Solana Test Validator (${fullCmd})...`);
     log.info("👉 Press Ctrl+C to stop it.");
 
     // Run and capture exit code
@@ -324,7 +311,7 @@ const validator = async (args = []) => {
             const flagStr = flags.join(' ');
             const targetCmd = `solana-test-validator ${flagStr}`;
 
-            log.info(`🚀 Spawning visible Administrator terminal for '${targetCmd}'...`);
+
             log.warn("👉 A new window will appear. Keep it open to run the validator!");
 
             // Robust Launch using EncodedCommand to avoid quoting hell and set CWD correctly
@@ -385,7 +372,7 @@ const validator = async (args = []) => {
 
 const unblock = () => {
     const cwd = process.cwd();
-    log.info(`🔓 Unblocking files in ${cwd}...`);
+
 
     if (os.platform() !== 'win32') {
         log.success("✅ Not on Windows, nothing to unblock.");
@@ -424,7 +411,7 @@ module.exports = {
 
 const dev = async () => {
     const stealth = isStealthMode();
-    log.header("🚀 Starting Development Environment...");
+
 
     // 1. Check if validator is running
     const isValidatorRunning = () => {
@@ -440,7 +427,7 @@ const dev = async () => {
     if (isValidatorRunning()) {
         log.success("✅ Validator is already running.");
     } else {
-        log.info("⏳ Spawning Validator...");
+
         // Spawn validator (this will open the Admin window)
         // We use [] args to start cleanly but persistently.
         // If it fails, the user will see it in the new window.
@@ -463,7 +450,7 @@ const dev = async () => {
         }
     }
 
-    log.info("🧪 Running initial tests...");
+
     // Fix: Pass --skip-local-validator directly (without --) so Anchor consumes it
     test(['--skip-local-validator']);
 

package/src/platforms/wsl.js

@@ -7,6 +7,44 @@ const os = require('os');
 const { spawnSync } = require('child_process');
 const chalk = require('chalk');
 
+/**
+ * Installs the WSL Windows Feature via an elevated PowerShell UAC prompt.
+ * This is needed when `wsl.exe` is not present on the system at all.
+ * Returns true if WSL is now available after the attempt, false otherwise.
+ */
+const installWslFeature = async () => {
+    log.warn("⚠️  WSL (Windows Subsystem for Linux) is not installed on this machine.");
+    log.info("🛡️  Administrator permission is required to install WSL.");
+    log.info("👉 A UAC (User Account Control) popup will appear — please click 'Yes' to allow the installation.");
+    console.log("");
+
+    // Run `wsl --install --no-distribution` elevated.
+    // --no-distribution: only enables the WSL feature, does not pull a distro yet.
+    // We wait for it to finish (-Wait) so we can check the result.
+    const elevateCmd = `powershell -Command "Start-Process -FilePath 'wsl.exe' -ArgumentList '--install', '--no-distribution' -Verb RunAs -Wait"`;
+    const result = shell.exec(elevateCmd, { silent: false });
+
+    if (result.code !== 0) {
+        // User likely denied UAC or the command failed
+        log.error("❌ WSL installation was cancelled or failed.");
+        log.warn("👉 To install manually, open PowerShell as Administrator and run:");
+        console.log(chalk.bold.yellow("    wsl --install"));
+        return false;
+    }
+
+    // Verify wsl is now available
+    const check = shell.exec('wsl --status', { silent: true });
+    if (check.code !== 0) {
+        // WSL was just installed — a reboot is almost certainly required
+        log.warn("⚠️  WSL feature has been installed, but a system restart is required to complete setup.");
+        log.warn("👉 Please RESTART your computer, then run `uso install` again to set up the toolchain.");
+        return false; // Signal caller that we need a restart before proceeding
+    }
+
+    log.success("✅ WSL feature installed successfully.");
+    return true;
+};
+
 const installWsl = async () => {
     log.header("🐧 Configuring Stealth WSL Environment...");
 
@@ -272,4 +310,4 @@ const hideFromWindowsTerminal = () => {
     }
 };
 
-module.exports = { installWsl };
+module.exports = { installWslFeature, installWsl };