@mcesystems/usbmuxd-instance-manager 1.0.72

package/scripts/README.md

@@ -0,0 +1,191 @@
+# usbmuxd Instance Manager Scripts
+
+Collection of PowerShell scripts for setting up and managing the usbmuxd instance manager on Windows.
+
+## Scripts
+
+### install-windows.ps1
+
+**Purpose**: Complete installation of all prerequisites for the usbmuxd instance manager.
+
+**Features**:
+- Auto-elevates to Administrator if needed
+- Installs/updates WSL2
+- Installs usbipd-win
+- Imports Alpine Linux distribution with usbmuxd
+- Verifies installation
+
+**Usage**:
+```powershell
+.\install-windows.ps1
+```
+
+**Options**:
+- `-AlpineImagePath <path>`: Custom path to Alpine image (default: `../prebuilt/alpine-usbmuxd.tar.gz`)
+- `-WslDistroName <name>`: Custom WSL distribution name (default: `alpine-usbmuxd-build`)
+- `-SkipUsbipd`: Skip usbipd-win installation
+- `-SkipWSLUpdate`: Skip WSL2 update
+- `-Force`: Reinstall even if already installed
+
+**Examples**:
+```powershell
+# Standard installation
+.\install-windows.ps1
+
+# Reinstall everything
+.\install-windows.ps1 -Force
+
+# Skip WSL update (if already up to date)
+.\install-windows.ps1 -SkipWSLUpdate
+
+# Install with custom distribution name
+.\install-windows.ps1 -WslDistroName "my-usbmuxd-instance"
+```
+
+---
+
+### attach-device.ps1
+
+**Purpose**: Attach Apple devices to the Alpine WSL2 distribution for use with usbmuxd.
+
+**Features**:
+- Auto-elevates to Administrator if needed
+- Auto-detects Apple devices
+- Binds devices for sharing
+- Starts WSL distribution
+- Attaches devices to WSL2
+- Verifies device accessibility
+
+**Usage**:
+```powershell
+.\attach-device.ps1
+```
+
+**Options**:
+- `-BusId <id>`: Specific USB BusId to attach (auto-detected if not specified)
+- `-WslDistroName <name>`: WSL distribution name (default: `alpine-usbmuxd-build`)
+- `-List`: List all USB devices and exit
+- `-DetachAll`: Detach all devices from WSL
+
+**Examples**:
+```powershell
+# Auto-attach first Apple device
+.\attach-device.ps1
+
+# List all USB devices
+.\attach-device.ps1 -List
+
+# Attach specific device
+.\attach-device.ps1 -BusId 4-5
+
+# Detach all devices
+.\attach-device.ps1 -DetachAll
+```
+
+---
+
+## Workflow
+
+### First-Time Setup
+
+1. **Install prerequisites**:
+```powershell
+.\install-windows.ps1
+```
+
+2. **Connect iOS device** via USB
+
+3. **Attach device to WSL**:
+```powershell
+.\attach-device.ps1
+```
+
+4. **Test the setup**:
+```powershell
+cd ..
+pnpm run example
+```
+
+### Daily Usage
+
+If you've already installed, you only need to attach devices:
+
+```powershell
+# Connect device via USB
+.\attach-device.ps1
+```
+
+### Troubleshooting
+
+```powershell
+# Check if devices are attached
+.\attach-device.ps1 -List
+
+# Detach all devices and start fresh
+.\attach-device.ps1 -DetachAll
+.\attach-device.ps1
+
+# Reinstall everything
+.\install-windows.ps1 -Force
+```
+
+## Common Issues
+
+### "Access Denied" or "Admin Required"
+
+**Solution**: Scripts automatically request Administrator privileges. Make sure to accept the UAC prompt.
+
+### "Distribution not found"
+
+**Solution**: Run the installer:
+```powershell
+.\install-windows.ps1
+```
+
+### "Device not detected in WSL"
+
+**Solution**: 
+1. Make sure device is attached:
+```powershell
+.\attach-device.ps1 -List
+```
+
+2. Re-attach if needed:
+```powershell
+.\attach-device.ps1 -DetachAll
+.\attach-device.ps1
+```
+
+### "WSL keeps shutting down"
+
+**Solution**: The attach script starts a 10-minute keep-alive job. For longer sessions:
+```powershell
+# Start a 24-hour keep-alive
+Start-Job { wsl -d alpine-usbmuxd-build sleep 86400 }
+```
+
+## Technical Details
+
+### Alpine Image
+
+- **Location**: `../prebuilt/alpine-usbmuxd.tar.gz`
+- **Size**: ~26 MB
+- **Contents**: Alpine Linux 3.19 with usbmuxd v1.1.1
+
+### WSL Distribution
+
+- **Default Name**: `alpine-usbmuxd-build`
+- **Install Location**: `%LOCALAPPDATA%\usbmuxd-alpine`
+- **Storage**: Dynamic (starts small, grows as needed)
+
+### Ports
+
+- **Instance 1**: 27015
+- **Instance 2**: 27016
+- **Instance N**: 27015 + N - 1
+
+## See Also
+
+- [SETUP.md](../SETUP.md) - Complete setup guide
+- [README.md](../README.md) - Package documentation
+- [Examples](../src/examples/) - Usage examples

package/scripts/attach-device.ps1

@@ -0,0 +1,192 @@
+# Device Attachment Script for usbmuxd Instance Manager
+# This script attaches Apple devices to the Alpine WSL2 distribution
+# Requires Administrator privileges (will auto-elevate)
+
+param(
+	[string]$WslDistroName = "alpine-usbmuxd-build",
+	[string]$BusId = "",
+	[switch]$List = $false,
+	[switch]$DetachAll = $false
+)
+
+$ErrorActionPreference = "Stop"
+
+# Check if running as Administrator
+function Test-Administrator {
+	$user = [Security.Principal.WindowsIdentity]::GetCurrent()
+	$principal = New-Object Security.Principal.WindowsPrincipal($user)
+	return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+# Auto-elevate to Administrator if not already running as admin
+if (-not (Test-Administrator)) {
+	Write-Host "Requesting Administrator privileges..." -ForegroundColor Yellow
+	
+	$argList = @(
+		"-NoProfile"
+		"-ExecutionPolicy Bypass"
+		"-File `"$PSCommandPath`""
+	)
+	
+	if ($WslDistroName -ne "alpine-usbmuxd-build") {
+		$argList += "-WslDistroName `"$WslDistroName`""
+	}
+	if ($BusId) { $argList += "-BusId `"$BusId`"" }
+	if ($List) { $argList += "-List" }
+	if ($DetachAll) { $argList += "-DetachAll" }
+	
+	$process = Start-Process powershell.exe -Verb RunAs -ArgumentList ($argList -join " ") -Wait -PassThru
+	exit $process.ExitCode
+}
+
+$programFiles = $env:ProgramFiles
+$usbipdPath = Join-Path $programFiles "usbipd-win\usbipd.exe"
+
+# Check if usbipd is installed
+if (-not (Test-Path $usbipdPath)) {
+	Write-Host "✗ usbipd-win is not installed" -ForegroundColor Red
+	Write-Host "  Please run the installation script first: .\scripts\install-windows.ps1" -ForegroundColor Yellow
+	Read-Host "Press Enter to exit"
+	exit 1
+}
+
+Write-Host "`n=== Apple Device Attachment ===" -ForegroundColor Cyan
+Write-Host ""
+
+# List devices
+if ($List) {
+	Write-Host "Connected USB devices:" -ForegroundColor Cyan
+	& $usbipdPath list
+	Read-Host "`nPress Enter to exit"
+	exit 0
+}
+
+# Detach all devices
+if ($DetachAll) {
+	Write-Host "Detaching all devices from WSL..." -ForegroundColor Yellow
+	$devices = & $usbipdPath list 2>&1 | Select-String "Attached"
+	
+	if ($devices) {
+		foreach ($device in $devices) {
+			$busId = ($device -split "\s+")[0]
+			Write-Host "  Detaching $busId..."
+			& $usbipdPath detach --busid $busId 2>&1 | Out-Null
+		}
+		Write-Host "✓ All devices detached" -ForegroundColor Green
+	} else {
+		Write-Host "  No attached devices found" -ForegroundColor Yellow
+	}
+	Read-Host "`nPress Enter to exit"
+	exit 0
+}
+
+# List all devices
+Write-Host "Step 1: Listing USB devices..." -ForegroundColor Cyan
+$deviceList = & $usbipdPath list 2>&1
+
+# Find Apple devices
+$appleDevices = $deviceList | Select-String "05ac:" | Where-Object { $_ -match "Apple" }
+
+if (-not $appleDevices) {
+	Write-Host "✗ No Apple devices found" -ForegroundColor Red
+	Write-Host "  Please connect an iOS device via USB" -ForegroundColor Yellow
+	Write-Host ""
+	Write-Host "All connected devices:" -ForegroundColor Cyan
+	Write-Host $deviceList
+	Read-Host "`nPress Enter to exit"
+	exit 1
+}
+
+Write-Host "✓ Found Apple device(s):" -ForegroundColor Green
+$appleDevices | ForEach-Object { Write-Host "  $_" }
+Write-Host ""
+
+# If BusId not specified, auto-detect
+if (-not $BusId) {
+	# Parse first Apple device BusId
+	$firstDevice = $appleDevices | Select-Object -First 1
+	$BusId = ($firstDevice -split "\s+")[0]
+	Write-Host "Auto-detected BusId: $BusId" -ForegroundColor Cyan
+}
+
+# Step 2: Bind (share) the device
+Write-Host "`nStep 2: Binding device $BusId..." -ForegroundColor Cyan
+
+$bindResult = & $usbipdPath bind --busid $BusId --force 2>&1
+if ($LASTEXITCODE -ne 0) {
+	# Check if already bound
+	if ($bindResult -match "already") {
+		Write-Host "✓ Device already bound" -ForegroundColor Green
+	} else {
+		Write-Host "✗ Failed to bind device" -ForegroundColor Red
+		Write-Host "  $bindResult" -ForegroundColor Yellow
+		Read-Host "`nPress Enter to exit"
+		exit 1
+	}
+} else {
+	Write-Host "✓ Device bound successfully" -ForegroundColor Green
+}
+
+# Step 3: Start WSL distribution (keep-alive)
+Write-Host "`nStep 3: Starting WSL distribution..." -ForegroundColor Cyan
+
+$wslProcess = Start-Job -ScriptBlock {
+	param($distro)
+	wsl -d $distro sleep 600
+} -ArgumentList $WslDistroName
+
+Start-Sleep -Seconds 2
+
+if ($wslProcess.State -eq "Running") {
+	Write-Host "✓ WSL distribution is running" -ForegroundColor Green
+} else {
+	Write-Host "✗ Failed to start WSL distribution" -ForegroundColor Red
+	Read-Host "`nPress Enter to exit"
+	exit 1
+}
+
+# Step 4: Attach device to WSL
+Write-Host "`nStep 4: Attaching device to WSL..." -ForegroundColor Cyan
+
+& $usbipdPath attach --wsl $WslDistroName --busid $BusId 2>&1
+if ($LASTEXITCODE -ne 0) {
+	Write-Host "✗ Failed to attach device to WSL" -ForegroundColor Red
+	Stop-Job $wslProcess
+	Remove-Job $wslProcess
+	Read-Host "`nPress Enter to exit"
+	exit 1
+}
+
+Write-Host "✓ Device attached to WSL" -ForegroundColor Green
+
+# Step 5: Verify attachment
+Write-Host "`nStep 5: Verifying device in WSL..." -ForegroundColor Cyan
+
+$lsusbOutput = wsl -d $WslDistroName lsusb 2>&1
+if ($LASTEXITCODE -eq 0 -and $lsusbOutput -match "Apple") {
+	Write-Host "✓ Device is visible in WSL" -ForegroundColor Green
+	$appleDeviceInWsl = $lsusbOutput | Select-String "Apple"
+	Write-Host "  $appleDeviceInWsl" -ForegroundColor White
+} else {
+	Write-Host "⚠ Could not verify device in WSL" -ForegroundColor Yellow
+	Write-Host "  $lsusbOutput" -ForegroundColor Yellow
+}
+
+# Success summary
+Write-Host "`n=== Attachment Complete ===" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "✓ Apple device attached successfully!" -ForegroundColor Green
+Write-Host "  BusId: $BusId" -ForegroundColor White
+Write-Host "  WSL Distribution: $WslDistroName" -ForegroundColor White
+Write-Host ""
+Write-Host "The WSL distribution will remain running in the background." -ForegroundColor Yellow
+Write-Host "To stop it, run: wsl --shutdown" -ForegroundColor Yellow
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Cyan
+Write-Host "1. Start the usbmuxd instance manager"
+Write-Host "2. The device will be automatically detected and assigned to a port"
+Write-Host ""
+Write-Host "To detach devices, run:" -ForegroundColor Cyan
+Write-Host "  .\scripts\attach-device.ps1 -DetachAll" -ForegroundColor White
+Write-Host ""
+Read-Host "Press Enter to exit"

package/scripts/install-windows.ps1

@@ -0,0 +1,254 @@
+# usbmuxd Instance Manager - Windows Setup Script
+# This script installs all prerequisites needed for the usbmuxd instance manager on Windows
+#
+# Prerequisites:
+# - Windows 10/11 with WSL2 support
+# - Administrator privileges (will auto-elevate)
+# - Internet connection for downloads
+
+param(
+	[string]$AlpineImagePath = "$PSScriptRoot\..\prebuilt\alpine-usbmuxd.tar.gz",
+	[string]$WslDistroName = "alpine-usbmuxd-build",
+	[switch]$SkipUsbipd = $false,
+	[switch]$SkipWSLUpdate = $false,
+	[switch]$Force = $false
+)
+
+$ErrorActionPreference = "Stop"
+
+# Check if running as Administrator
+function Test-Administrator {
+	$user = [Security.Principal.WindowsIdentity]::GetCurrent()
+	$principal = New-Object Security.Principal.WindowsPrincipal($user)
+	return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+# Auto-elevate to Administrator if not already running as admin
+if (-not (Test-Administrator)) {
+	Write-Host "Requesting Administrator privileges..." -ForegroundColor Yellow
+	
+	# Build argument string
+	$argList = @(
+		"-NoProfile"
+		"-ExecutionPolicy Bypass"
+		"-File `"$PSCommandPath`""
+	)
+	
+	# Add original parameters
+	if ($AlpineImagePath -ne "$PSScriptRoot\..\prebuilt\alpine-usbmuxd.tar.gz") {
+		$argList += "-AlpineImagePath `"$AlpineImagePath`""
+	}
+	if ($WslDistroName -ne "alpine-usbmuxd-build") {
+		$argList += "-WslDistroName `"$WslDistroName`""
+	}
+	if ($SkipUsbipd) { $argList += "-SkipUsbipd" }
+	if ($SkipWSLUpdate) { $argList += "-SkipWSLUpdate" }
+	if ($Force) { $argList += "-Force" }
+	
+	# Start elevated process
+	$process = Start-Process powershell.exe -Verb RunAs -ArgumentList ($argList -join " ") -Wait -PassThru
+	exit $process.ExitCode
+}
+
+# Colors for output
+function Write-Step {
+	param([string]$Message)
+	Write-Host "`n=== $Message ===" -ForegroundColor Cyan
+}
+
+function Write-Success {
+	param([string]$Message)
+	Write-Host "✓ $Message" -ForegroundColor Green
+}
+
+function Write-Info {
+	param([string]$Message)
+	Write-Host "  $Message" -ForegroundColor White
+}
+
+function Write-Warn {
+	param([string]$Message)
+	Write-Host "⚠ $Message" -ForegroundColor Yellow
+}
+
+function Write-Fail {
+	param([string]$Message)
+	Write-Host "✗ $Message" -ForegroundColor Red
+}
+
+Write-Host @"
+
+╔════════════════════════════════════════════════════════════════╗
+║                                                                ║
+║        usbmuxd Instance Manager - Windows Setup               ║
+║                                                                ║
+╚════════════════════════════════════════════════════════════════╝
+
+"@ -ForegroundColor Cyan
+
+Write-Success "Running with Administrator privileges"
+
+# Step 1: Check WSL2
+Write-Step "Step 1: Checking WSL2"
+
+try {
+	$wslVersion = wsl --version 2>&1
+	if ($LASTEXITCODE -ne 0) {
+		Write-Fail "WSL2 is not installed"
+		Write-Info "Installing WSL2..."
+		wsl --install --no-distribution
+		Write-Warn "WSL2 installed. Please reboot your computer and run this script again."
+		Read-Host "Press Enter to exit"
+		exit 0
+	}
+	Write-Success "WSL2 is installed"
+} catch {
+	Write-Fail "Failed to check WSL2: $_"
+	Read-Host "Press Enter to exit"
+	exit 1
+}
+
+# Step 2: Update WSL2
+if (-not $SkipWSLUpdate) {
+	Write-Step "Step 2: Updating WSL2"
+	try {
+		wsl --update
+		Write-Success "WSL2 updated"
+	} catch {
+		Write-Warn "Failed to update WSL2: $_"
+	}
+} else {
+	Write-Info "Skipping WSL2 update (--SkipWSLUpdate specified)"
+}
+
+# Step 3: Install usbipd-win
+if (-not $SkipUsbipd) {
+	Write-Step "Step 3: Installing usbipd-win"
+	
+	try {
+		$programFiles = $env:ProgramFiles
+		$usbipdPath = Join-Path $programFiles "usbipd-win\usbipd.exe"
+		if ((Test-Path $usbipdPath) -and -not $Force) {
+			Write-Success "usbipd-win is already installed"
+			$version = & $usbipdPath --version 2>&1
+			Write-Info "Version: $version"
+		} else {
+			Write-Info "Installing usbipd-win via winget..."
+			winget install --id dorssel.usbipd-win --accept-package-agreements --accept-source-agreements
+			if ($LASTEXITCODE -ne 0) {
+				Write-Fail "Failed to install usbipd-win"
+				Read-Host "Press Enter to exit"
+				exit 1
+			}
+			Write-Success "usbipd-win installed"
+		}
+	} catch {
+		Write-Fail "Failed to install usbipd-win: $_"
+		Read-Host "Press Enter to exit"
+		exit 1
+	}
+} else {
+	Write-Info "Skipping usbipd-win installation (--SkipUsbipd specified)"
+}
+
+# Step 4: Check Alpine image
+Write-Step "Step 4: Checking Alpine Linux image"
+
+if (-not (Test-Path $AlpineImagePath)) {
+	Write-Fail "Alpine image not found at: $AlpineImagePath"
+	Write-Info "Please ensure the prebuilt Alpine image is available"
+	Read-Host "Press Enter to exit"
+	exit 1
+}
+
+$imageSize = (Get-Item $AlpineImagePath).Length / 1MB
+Write-Success "Alpine image found ($([math]::Round($imageSize, 2)) MB)"
+
+# Step 5: Import Alpine WSL2 distribution
+Write-Step "Step 5: Importing Alpine WSL2 distribution"
+
+# Check if distribution already exists
+$existingDistros = wsl --list --quiet 2>&1 | ForEach-Object { $_.Trim() }
+$distroExists = $existingDistros -contains $WslDistroName
+
+if ($distroExists) {
+	if ($Force) {
+		Write-Warn "Distribution '$WslDistroName' already exists. Removing..."
+		wsl --unregister $WslDistroName
+		Write-Success "Existing distribution removed"
+		$distroExists = $false
+	} else {
+		Write-Success "Distribution '$WslDistroName' already exists"
+		Write-Info "Use -Force to reinstall"
+	}
+}
+
+if (-not $distroExists) {
+	Write-Info "Importing Alpine distribution..."
+	$installPath = "$env:LOCALAPPDATA\usbmuxd-alpine"
+	
+	# Create install directory
+	if (-not (Test-Path $installPath)) {
+		New-Item -ItemType Directory -Path $installPath -Force | Out-Null
+	}
+	
+	# Import the distribution
+	wsl --import $WslDistroName $installPath $AlpineImagePath
+	
+	if ($LASTEXITCODE -ne 0) {
+		Write-Fail "Failed to import Alpine distribution"
+		Read-Host "Press Enter to exit"
+		exit 1
+	}
+	
+	Write-Success "Alpine distribution imported"
+	Write-Info "Install location: $installPath"
+}
+
+# Step 6: Verify Alpine distribution
+Write-Step "Step 6: Verifying Alpine distribution"
+
+try {
+	$testOutput = wsl -d $WslDistroName uname -r 2>&1
+	if ($LASTEXITCODE -eq 0) {
+		Write-Success "Alpine distribution is working"
+		Write-Info "Kernel: $testOutput"
+	} else {
+		Write-Fail "Failed to verify Alpine distribution"
+		Read-Host "Press Enter to exit"
+		exit 1
+	}
+	
+	# Check usbmuxd installation
+	$usbmuxdCheck = wsl -d $WslDistroName which usbmuxd 2>&1
+	if ($LASTEXITCODE -eq 0) {
+		Write-Success "usbmuxd is installed in Alpine"
+		Write-Info "Path: $usbmuxdCheck"
+	} else {
+		Write-Fail "usbmuxd not found in Alpine distribution"
+		Read-Host "Press Enter to exit"
+		exit 1
+	}
+} catch {
+	Write-Fail "Failed to verify Alpine distribution: $_"
+	Read-Host "Press Enter to exit"
+	exit 1
+}
+
+# Step 7: Setup complete
+Write-Step "Setup Complete"
+
+Write-Success "All prerequisites installed successfully!"
+Write-Host ""
+Write-Info "Next steps:"
+Write-Info "1. Connect an iOS device via USB"
+Write-Info "2. Run the device attachment script:"
+Write-Info "   .\scripts\attach-device.ps1"
+Write-Info "3. Start using the usbmuxd instance manager"
+Write-Host ""
+Write-Info "Quick test:"
+Write-Info "   cd packages\usbmuxd-instance-manager"
+Write-Info "   pnpm run example"
+Write-Host ""
+Write-Info "Press Enter to exit..."
+Read-Host