@xaidenlabs/uso 1.1.64 → 1.1.67

package/README.md

@@ -1,277 +1,450 @@
 # Universal Solana Orchestrator (USO)
 
-**The fastest way to build on Solana.**
+> **The fastest way to build on Solana — on any OS.**
 
-USO (Universal Solana Orchestrator) is a "Zero-Friction" toolchain that handles the complex setup of Rust, Anchor, and Solana CLI—instantly.
+USO is a zero-friction CLI toolchain that installs, manages, and runs your entire Solana development environment with a single command. Native or Stealth WSL. Your choice.
 
-**Native or Stealth Mode? Both.**
--   **Universal:** Runs natively on macOS, Linux, and Windows.
--   **Stealth WSL:** On Windows, USO can deploy a hidden "Uso Engine" (WSL2) to run your build, test, and validator commands in a rock-solid Linux environment, while you stay in PowerShell. No "Access Denied" errors. No friction.
+---
 
-This tool is engineered to support developers at all levels, from beginners setting up their first environment to senior engineers managing multiple workstations.
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Stealth WSL Mode (Windows)](#stealth-wsl-mode-windows)
+- [Full Environment Setup](#full-environment-setup)
+- [Granular Installation](#granular-installation)
+- [Project Scaffolding](#project-scaffolding)
+- [Workflow Commands](#workflow-commands)
+- [Wallet & SOL Commands](#wallet--sol-commands)
+- [Developer Tools](#developer-tools)
+- [Diagnostics & Verification](#diagnostics--verification)
+- [Windows Security & Unblocking](#windows-security--unblocking)
+- [Uninstallation](#uninstallation)
+- [Command Reference](#command-reference)
+- [Troubleshooting](#troubleshooting)
 
 ---
 
 ## Installation
 
-Install USO globally using NPM. This ensures the CLI is accessible from any terminal directory.
+Install USO globally via npm. Node.js (LTS recommended) must be installed first.
 
 ```bash
 npm install -g @xaidenlabs/uso
 ```
 
 **Prerequisites:**
-- **Node.js**: Ensure Node.js is installed on your system.
-- **Administrator Privileges**: Some installation steps (successfully creating symlinks, updating system PATH) may require elevated permissions.
-- **Windows Security / Smart App Control**: If installation is blocked, check **Windows Security > Virus & threat protection > Protection history**. You may need to "Allow" the `solana-install.exe` or `rustup-init.exe` or temporarily disable Smart App Control.
+| Requirement | Details |
+|---|---|
+| Node.js | v18+ LTS recommended |
+| npm | Comes with Node.js |
+| Administrator (Windows) | Some steps require elevated privileges — USO handles this automatically |
+| C++ Build Tools (Windows) | Required by Rust. Install via Visual Studio Build Tools → "Desktop development with C++" |
+| WSL2 (Stealth Mode) | Windows Subsystem for Linux 2, enabled in Windows Settings |
 
 ---
 
-## Usage
-
-### System Diagnostics
-
-Before attempting installation, you can run a diagnostic check to evaluate the current state of your environment.
+## Quick Start
 
 ```bash
+# 1. Diagnose your environment first
 uso doctor
-```
 
-This command will inspect your system for existing installations of Git, Rust, Solana CLI, and Anchor.
+# 2. Install the full stack (Rust + Solana + Anchor)
+uso init
+
+# 3. Verify everything is working
+uso verify
+
+# 4. Create your first project
+uso create my-project
+cd my-project && npm install
+
+# 5. Start coding
+uso dev
+```
 
 ---
 
-### Full Environment Setup
+## Stealth WSL Mode (Windows Only)
 
-To perform a complete installation of the entire stack (Rust, Solana, Anchor), use the initialization command:
+**The recommended mode for Windows developers.** Stealth Mode deploys a hidden WSL2 Linux environment (the "Uso Engine") that runs all your tooling inside Linux while you stay in PowerShell.
 
 ```bash
-uso init
+uso init --wsl
+```
+
+**What this does:**
+1. Installs a minimal Ubuntu WSL2 distro hidden from Windows Terminal
+2. Installs Rust, Solana CLI, and Anchor inside the distro
+3. Stores your configuration in `~/.uso-config.json`
+4. All future `uso` commands auto-route through the WSL engine — transparently
+
+**Why use it?**
+- Eliminates `os error 1314` (symlink privilege errors)
+- Bypasses Windows Smart App Control (`os error 4551`)
+- Eliminates "Access Denied" on build artifacts
+- The validator binds to `127.0.0.1` — tests connect seamlessly from Windows
+
+**Check your current mode:**
+```bash
+cat ~/.uso-config.json
+# { "mode": "wsl", "distro": "Ubuntu" }
 ```
 
-The installer will:
-1.  Detect your operating system.
-2.  Check for necessary build tools (C++ Build Tools on Windows).
-3.  Download and install the Rust toolchain (via `rustup`).
-4.  Install the Solana CLI (Agave release).
-5.  Build and install the Anchor Version Manager (AVM) and Anchor Framework.
-6.  Generate a new Solana wallet if one is not detected.
+**Switch back to native mode:**
+```bash
+# Delete the config to use native toolchain
+del %USERPROFILE%\.uso-config.json
+```
 
-**Note:** You may be prompted to approve administrative access during the installation of specific components.
+> **Note:** Even in Stealth Mode, USO prefers native binaries if they're available in PATH. The WSL engine is only used when a native binary is missing.
 
 ---
 
-### Stealth WSL Mode (Windows Only)
+## Full Environment Setup
 
-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.
+Install the complete Solana development stack in one command:
 
-**Enable Stealth Mode:**
 ```bash
-uso init --wsl
+uso init
 ```
 
-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.
+USO will:
+1. Detect your operating system (Windows / macOS / Linux)
+2. Check for C++ Build Tools (Windows only)
+3. Install the Rust toolchain via `rustup`
+4. Install the Solana CLI (Agave release)
+5. Install the Anchor Version Manager (AVM) and Anchor Framework
+6. Generate a new Solana wallet `~/.config/solana/id.json` if none exists
+7. Update your system PATH
 
-**Configuration** is stored in `~/.uso-config.json`. To switch back to native mode, delete this file or reinstall without `--wsl`.
+> **Windows Users:** You may see a UAC prompt. Click **Yes** to allow the installer. USO auto-retries any step that fails with a privilege error.
 
 ---
 
-### Granular Installation
+## Granular Installation
 
-Use the `install` command to set up individual components if you do not require the full stack.
+Already have some tools installed? Install only what you need:
 
-**Install Rust:**
 ```bash
+# Install Rust only
 uso install rust
-```
 
-**Install Solana CLI:**
-```bash
+# Install Solana CLI only
 uso install solana
+
+# Install Anchor Framework only
+uso install anchor
 ```
 
-**Install Anchor Framework:**
+These also work with `uso init <component>`:
 ```bash
-uso install anchor
+uso init rust
+uso init solana
+uso init anchor
 ```
 
 ---
 
-### Project Scaffolding
+## Project Scaffolding
 
-Start a new project with a robust, pre-configured Anchor template.
+Create a new, production-ready Anchor project with all boilerplate pre-configured:
 
 ```bash
 uso create <project-name>
 ```
 
-This generates a "batteries-included" workspace with:
--   **Localnet Configuration**: `Anchor.toml` pre-wired for local development.
--   **Test Suite**: A running example test file using the latest Anchor syntax.
--   **Scripts**: NPM scripts for linting and testing.
+**Example:**
+```bash
+uso create my-nft-program
+cd my-nft-program
+npm install
+```
+
+**What you get:**
+```
+my-nft-program/
+├── Anchor.toml          # Pre-configured for localnet
+├── programs/
+│   └── my-nft-program/
+│       └── src/
+│           └── lib.rs   # Your Rust smart contract
+├── tests/
+│   └── my-nft-program.ts  # TypeScript test suite
+├── package.json
+└── tsconfig.json
+```
+
+Run your first test:
+```bash
+uso test
+```
 
 ---
 
-### Workflow Commands
+## Workflow Commands
+
+All commands work in both Native and Stealth WSL mode. USO routes them correctly automatically.
 
-USO wraps the core Anchor and Solana CLI commands so you don't need to worry about PATH issues or WSL routing.
+### Build
+
+Compile your Anchor program (wraps `anchor build`):
 
-**Build your program:**
 ```bash
 uso build
 ```
 
-**Run tests:**
+On Windows with Smart App Control, USO automatically:
+- Cleans stale blocked build artifacts
+- Retries in an elevated Administrator terminal
+- Mirrors output back to your current window
+
+### Test
+
+Run your Anchor test suite (wraps `anchor test`):
+
 ```bash
 uso test
+
+# Pass flags directly to anchor test
+uso test -- --skip-deploy
 ```
-On Windows, USO automatically checks if a validator is running before starting tests, preventing hangs.
 
-**Deploy your program:**
+> **Windows Smart Behavior:** Before running tests, USO checks if a local validator is running on port `8899`. If one is detected, it adds `--skip-local-validator` automatically to prevent Anchor from hanging.
+
+### Deploy
+
+Deploy your compiled program to the configured cluster:
+
 ```bash
 uso deploy
 ```
 
-**Clean build artifacts:**
+### Clean
+
+Remove all build artifacts (wraps `anchor clean`):
+
 ```bash
 uso clean
 ```
 
 ---
 
-### Wallet & SOL Commands
+## Wallet & SOL Commands
+
+All wallet commands wrap the native `solana` CLI and route through the WSL engine in Stealth Mode.
 
-Manage your Solana wallet and devnet SOL directly from USO.
+### Check Your Wallet Address
 
-**Show your wallet address:**
 ```bash
 uso address
 ```
 
-**Check your SOL balance:**
+### Check SOL Balance
+
 ```bash
+# Your default wallet
 uso balance
-```
 
-**Check balance of a specific address:**
-```bash
-uso balance <address>
+# Any specific address
+uso balance <WALLET_ADDRESS>
 ```
 
-**Airdrop SOL (devnet/testnet):**
+### Airdrop SOL (Devnet/Testnet)
+
 ```bash
+# Airdrop to your default wallet
 uso airdrop 2
-uso airdrop 5 <recipient-address>
+
+# Airdrop to a specific address
+uso airdrop 5 <WALLET_ADDRESS>
 ```
 
+> Airdrops only work on devnet and testnet. Make sure your Solana CLI cluster is set to `devnet`:
+> ```bash
+> solana config set --url devnet
+> ```
+
 ---
 
-### Developer Tools
+## Developer Tools
+
+### Start a Local Validator
 
-**Start a local test validator:**
 ```bash
+# Start with default settings
 uso validator
-# or the shorthand:
+# or shorthand:
 uso val
-```
 
-Pass flags directly to the validator:
-```bash
+# Reset the ledger and start fresh
 uso val --reset
+
+# Pass any solana-test-validator flags
+uso val --bpf-program <PROGRAM_ID> <PROGRAM.so>
 ```
 
-On Windows, if the validator encounters "Access Denied" errors, USO automatically retries in an elevated Administrator terminal with Windows Defender exclusions applied.
+**On Windows:** If the validator fails with "Access Denied", USO automatically:
+1. Spawns an elevated Administrator PowerShell window
+2. Applies Windows Defender exclusions for `solana-test-validator`
+3. Enables Developer Mode for symlink support
+
+### Full Developer Mode
+
+The all-in-one command for active development:
 
-**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.
+This single command:
+1. **Detects** if a local validator is already running
+2. **Starts** the validator if none is running (waits up to 60s for it to be ready)
+3. **Runs** your full test suite
+4. **Watches** `programs/**/*.rs` and `tests/**/*.ts` for changes
+5. **Auto-reruns** tests with a 2-second debounce on every save
+
+Hit `Ctrl+C` to stop everything.
 
 ---
 
-### Verification
+## Diagnostics & Verification
+
+### Doctor
+
+Inspect your environment for any issues:
+
+```bash
+uso doctor
+```
 
-After installation, verify that all components are correctly configured and accessible in your system PATH.
+Checks for:
+- Git installation
+- Rust & Cargo version
+- Solana CLI version and PATH
+- Anchor version
+- WSL2 availability (Windows)
+- C++ Build Tools (Windows)
+- Existing wallet file
+
+### Verify
+
+Perform a real end-to-end verification — builds an actual test Anchor project to confirm everything works:
 
 ```bash
 uso verify
 ```
 
-This process will validate the version of each tool and ensure the environment is ready for development.
+Run this after `uso init` to confirm your environment is fully operational.
 
 ---
 
-### Windows Security & Smart App Control
+## Windows Security & Unblocking
 
-If your builds fail with `os error 4551` or "Access Denied" due to Smart App Control or Windows Defender:
+If builds fail with `os error 4551` or "Application Control policy has blocked", files downloaded from the internet have a "Mark of the Web" (Zone.Identifier) that Windows treats as untrusted.
 
-1.  Run the **unblock** command to remove "Mark of the Web" from your project and toolchain:
-    ```bash
-    uso unblock
-    ```
-2.  Then try running `uso test` again.
+**Fix:**
+```bash
+uso unblock
+```
+
+This removes the Mark of the Web from all files in your project directory and `~/.cargo/bin`, allowing builds to proceed.
+
+After unblocking:
+```bash
+uso test
+```
+
+**Alternative:** Use `uso init --wsl` (Stealth Mode) to sidestep all Windows security restrictions permanently.
 
 ---
 
 ## Uninstallation
 
-USO provides a clean uninstallation process to remove the installed toolchains.
+### Interactive Full Removal
+
+Guides you through removing all installed components with confirmation prompts:
 
-**Remove All Components (interactive):**
 ```bash
 uso uninstall
 ```
 
-**Remove Individual Components:**
+> ⚠️ **Wallet Warning:** The full uninstall will ask about your wallet at `~/.config/solana/id.json`. You must type `DELETE` to confirm its removal. **Back up your keypair first if it holds funds.**
+
+### Remove Individual Components
+
 ```bash
-uso uninstall solana
 uso uninstall rust
+uso uninstall solana
 uso uninstall anchor
 ```
 
+### Remove USO Itself
+
+```bash
+npm uninstall -g @xaidenlabs/uso
+```
+
 ---
 
 ## 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 |
+| Command | Alias | Description |
+|---|---|---|
+| `uso init` | `uso setup` | Install full stack (Rust + Solana + Anchor) |
+| `uso init --wsl` | — | Install via hidden WSL2 Stealth Engine (Windows) |
+| `uso init rust` | `uso install rust` | Install Rust only |
+| `uso init solana` | `uso install solana` | Install Solana CLI only |
+| `uso init anchor` | `uso install anchor` | Install Anchor Framework only |
+| `uso doctor` | — | Diagnose environment |
+| `uso verify` | — | End-to-end verification build |
+| `uso create <name>` | — | Scaffold a new Anchor project |
+| `uso build` | — | Build program (`anchor build`) |
+| `uso test [args]` | — | Run tests (`anchor test`) |
+| `uso deploy` | — | Deploy program (`anchor deploy`) |
+| `uso clean` | — | Clean artifacts (`anchor clean`) |
+| `uso address` | — | Show wallet address |
+| `uso balance [addr]` | — | Show SOL balance |
+| `uso airdrop <n> [addr]` | — | Airdrop SOL (devnet/testnet) |
+| `uso validator [flags]` | `uso val` | Start local test validator |
+| `uso dev` | — | Full dev mode (validator + watcher + tests) |
+| `uso unblock` | — | Remove Mark-of-the-Web (Windows) |
+| `uso uninstall [comp]` | — | Remove installed toolchains |
 
 ---
 
 ## Troubleshooting
 
--   **"Permission Denied" Errors**: If you encounter errors related to permissions or symlinks, try running your terminal as an Administrator.
--   **"Command Not Found"**: After installation, your system PATH is updated. You must restart your terminal (close and reopen) for these changes to take effect.
--   **Windows Build Tools**: If Rust fails to install on Windows, ensure you have the "Desktop development with C++" workload installed via Visual Studio Build Tools.
--   **"OS Error 4551" (Windows Defender/Smart App Control)**: If builds are blocked by antivirus, run `uso unblock` to unblock your project files and toolchain.
+**"Command not found" after install**
+> Restart your terminal. PATH changes require a new session to take effect.
+
+**"Permission Denied" / `os error 1314`**
+> Run from an Administrator terminal, or use `uso init --wsl` to avoid this entirely.
+
+**`os error 4551` / Smart App Control**
+> Run `uso unblock` then retry. Or switch to `uso init --wsl`.
+
+**Rust fails to install on Windows**
+> You need the "Desktop development with C++" workload from Visual Studio Build Tools. Download at [visualstudio.microsoft.com/visual-cpp-build-tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
+
+**`uso test` hangs on Windows**
+> USO auto-detects this but if it still hangs, start the validator manually first:
+> ```bash
+> uso val
+> # in another terminal:
+> uso test
+> ```
+
+**Anchor version mismatch errors**
+> ```bash
+> uso clean
+> uso build
+> ```
+
+**Nothing helps**
+> Run `uso doctor` and share the output to diagnose.
 
 ---
 
-**Developed by Xaiden Labs**
+**Developed by Xaiden Labs · [GitHub](https://github.com/Uso-cli) · [npm](https://www.npmjs.com/package/@xaidenlabs/uso) · [Twitter](https://x.com/uso_cli)**

package/package.json

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

package/src/platforms/linux.js

@@ -4,18 +4,30 @@ const { log } = require('../utils/logger');
 const installLinux = async (shouldInstallRust, shouldInstallSolana) => {
     log.header("🐧 Linux detected.");
 
-    // 1. Install dependencies (Quick check, or just run update? 'update' is harmless mostly)
-    // We can assume if Rust/Solana are missing, deps might be too. 
-    // If both are present, we might skip this? For safety, we only run if installing something.
+    // 1. Install dependencies
     if (shouldInstallRust || shouldInstallSolana) {
         log.info("🐧 Checking Linux dependencies (libudev, pkg-config)...");
-        shell.exec('sudo apt-get update && sudo apt-get install -y libudev-dev pkg-config build-essential');
+        if (shell.which('apt-get')) {
+            shell.exec('sudo apt-get update && sudo apt-get install -y libudev-dev pkg-config build-essential');
+        } else if (shell.which('dnf')) {
+            shell.exec('sudo dnf install -y systemd-devel pkgconf-pkg-config @development-tools');
+        } else if (shell.which('yum')) {
+            shell.exec('sudo yum install -y systemd-devel pkgconfig @development-tools');
+        } else if (shell.which('pacman')) {
+            shell.exec('sudo pacman -Sy --noconfirm systemd pkgconf base-devel');
+        } else {
+            log.warn("⚠️  Could not detect a supported package manager (apt/dnf/yum/pacman). Ensure libudev and pkg-config are installed.");
+        }
     }
 
     // 2. Install Rust
     if (shouldInstallRust) {
         log.info("🦀 Installing Rust...");
-        shell.exec('curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y');
+        const rustInstall = shell.exec('curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y');
+        if (rustInstall.code !== 0) {
+            log.error("❌ Failed to install Rust.");
+            return false;
+        }
         log.success("✅ Rust installed.");
     } else {
         log.info("🦀 Rust is already installed. Skipping.");
@@ -24,7 +36,11 @@ const installLinux = async (shouldInstallRust, shouldInstallSolana) => {
     // 3. Install Solana CLI
     if (shouldInstallSolana) {
         log.info("☀️ Installing Solana CLI...");
-        shell.exec('sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"');
+        const solanaInstall = shell.exec('sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"');
+        if (solanaInstall.code !== 0) {
+            log.error("❌ Failed to install Solana CLI.");
+            return false;
+        }
         log.success("✅ Solana CLI installed.");
     } else {
         log.info("☀️ Solana CLI is already installed. Skipping.");
@@ -33,4 +49,4 @@ const installLinux = async (shouldInstallRust, shouldInstallSolana) => {
     return true;
 };
 
-module.exports = { installLinux };
+module.exports = { installLinux };