@xaidenlabs/uso 1.1.62 → 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.62",
+  "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/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 };