Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver/install.ps1): auto-add bin dir to User PATH (#1576)

Francesco Bonacci1f9a6a954ac2
diff --git a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
index 4c5724d50e..b7cec3001e 100644
--- a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
+++ b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
@@ -74,6 +74,13 @@ The Windows installer auto-detects host architecture (x64 / arm64) via `[System.
It runs **without admin** and **without Developer Mode**.
+It also appends `%LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin` to your **User-scope `Path`** so `cua-driver --version` resolves in any new PowerShell window. The write is idempotent (re-running the installer never duplicates the entry) and falls back to printing manual `[Environment]::SetEnvironmentVariable(...)` instructions if the registry write is blocked (group policy, locked-down account). Pass `-NoPathUpdate` to suppress the auto-add — useful when you manage `Path` out-of-band via chezmoi / dotfiles / GPO:
+
+```powershell
+# Fetch + invoke explicitly so we can pass the switch:
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1))) -NoPathUpdate
+```
+
The install layout is wired with NTFS directory junctions (`IO_REPARSE_TAG_MOUNT_POINT`), which any unprivileged user can create — no elevated symlink privilege required.
#### Versioned-dirs install layout
@@ -144,7 +151,7 @@ Clear `$env:CUA_DRIVER_RS_VERSION` and re-run to roll forward to the newest rele
| `CUA_DRIVER_RS_VERSION` | unset → use baked version | unset → use baked version | Pin a specific release (e.g. `0.2.0`). |
| `CUA_DRIVER_RS_INSTALL_DIR` | `~/.local/bin` | `%LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin` | The visible PATH-entry directory. On Windows this is itself a junction. |
| `CUA_DRIVER_RS_HOME` | `~/.cua-driver-rs` | `%USERPROFILE%\.cua-driver-rs` | Package home — holds `packages/releases/<v>/` and `packages/current`. |
-| `CUA_DRIVER_RS_NO_MODIFY_PATH` *(Linux/macOS only)* | `0` | n/a — Windows installer never auto-edits PATH | Skip the rc-file PATH append. |
+| `CUA_DRIVER_RS_NO_MODIFY_PATH` *(Linux/macOS only)* | `0` | use `-NoPathUpdate` switch on `install.ps1` | Skip the PATH append. On Windows the installer appends `%LOCALAPPDATA%\Programs\trycua\cua-driver-rs\bin` to the User-scope `Path` by default; use the fetch+invoke form with `-NoPathUpdate` to opt out (see the Windows install section above for the exact one-liner). |
| `CUA_DRIVER_RS_KEEP_VERSIONS` *(Linux/Windows only)* | `5` | `5` | Keep the N most recent per-version release dirs after install (`0` disables GC). See the **Old-version cleanup** callout below for per-target and active-install invariants. |
<Callout type="info">
diff --git a/libs/cua-driver/scripts/install.ps1 b/libs/cua-driver/scripts/install.ps1
index 9d62830773..2b025a9aca 100644
--- a/libs/cua-driver/scripts/install.ps1
+++ b/libs/cua-driver/scripts/install.ps1
@@ -55,6 +55,14 @@
# to function. Default off; the post-install message prints
# the registration command so you can opt in later. Safe to
# re-run: existing task is replaced.
+# -NoPathUpdate
+# skip the auto-append of $VisibleBinDir to the User PATH.
+# Default off — the installer auto-adds the bin dir so
+# `cua-driver --version` works in new shells without manual
+# `[Environment]::SetEnvironmentVariable` gymnastics. Pass
+# this when you manage PATH out-of-band (chezmoi, a dotfiles
+# repo, group policy). Idempotent either way: if the dir is
+# already on PATH, nothing changes.
#
# WARNING — BETA: cua-driver-rs is the cross-platform Rust port of the
# Swift cua-driver. Windows and Linux support is feature-complete;
@@ -63,7 +71,8 @@
[CmdletBinding()]
param(
[string]$Release = "latest",
- [switch]$AutoStart
+ [switch]$AutoStart,
+ [switch]$NoPathUpdate
)
Set-StrictMode -Version Latest
@@ -852,48 +861,88 @@ if (Test-Path -LiteralPath $installedBinary) {
}
}
-# ---------- PATH check (info only — we don't auto-edit on Windows) --------
+# ---------- PATH update (User scope, idempotent, fallback to manual) ------
#
-# Modifying the user's PATH from PowerShell is doable
-# ([Environment]::SetEnvironmentVariable("Path", ..., "User")) but it
-# (a) requires the user's old PATH be sane, (b) doesn't take effect in
-# the calling shell anyway, and (c) is the kind of side-effect that
-# surprises power users. So we print a hint with the exact command
-# instead and let the user opt in.
-$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
-$onPath = $false
-if ($userPath) {
- $entries = $userPath.Split(';') | Where-Object { $_ }
- foreach ($entry in $entries) {
- if ($entry.TrimEnd('\') -ieq $VisibleBinDir.TrimEnd('\')) {
- $onPath = $true
- break
- }
+# We append $VisibleBinDir to the User-scope PATH so `cua-driver` resolves
+# in any newly-spawned shell. User scope (not Machine) keeps the installer
+# non-admin — Machine scope would require elevation. The write doesn't
+# affect the calling shell's $env:Path; the post-install message tells the
+# user to open a new shell (or stitch $env:Path manually for this session).
+#
+# Failure modes we tolerate gracefully:
+# - Locked-down accounts where SetEnvironmentVariable throws (group
+# policy, OneDrive-redirected HKCU, etc.). We catch, print the
+# manual command, and exit success.
+# - User passed -NoPathUpdate. Same fallback message, no write attempt.
+#
+# Idempotency: if $VisibleBinDir is already on the User PATH we no-op
+# silently (same shape as the existing "already added" branch).
+function Get-UserPathEntries {
+ $raw = [Environment]::GetEnvironmentVariable("Path", "User")
+ if (-not $raw) { return @() }
+ return @($raw.Split(';') | Where-Object { $_ })
+}
+
+function Test-OnUserPath([string]$dir) {
+ $needle = $dir.TrimEnd('\')
+ foreach ($entry in (Get-UserPathEntries)) {
+ if ($entry.TrimEnd('\') -ieq $needle) { return $true }
}
+ return $false
}
-Write-Host ""
-Write-Host "cua-driver-rs $version installed."
-Write-Host ""
-Write-Host "Try it:"
-Write-Host " $installedBinary --version"
-Write-Host ""
+function Add-UserPathEntry([string]$dir) {
+ $existing = [Environment]::GetEnvironmentVariable("Path", "User")
+ if ($existing) {
+ $newValue = ($existing.TrimEnd(';')) + ';' + $dir
+ } else {
+ $newValue = $dir
+ }
+ [Environment]::SetEnvironmentVariable("Path", $newValue, "User")
+}
-if (-not $onPath) {
- Write-Host "$VisibleBinDir is not on your user PATH yet." -ForegroundColor Yellow
+function Write-ManualPathInstructions([string]$dir) {
+ Write-Host "$dir is not on your user PATH yet." -ForegroundColor Yellow
Write-Host "Add it for future shells with:" -ForegroundColor Yellow
Write-Host ""
- Write-Host " [Environment]::SetEnvironmentVariable('Path', `"`$([Environment]::GetEnvironmentVariable('Path','User'));$VisibleBinDir`", 'User')"
+ Write-Host " [Environment]::SetEnvironmentVariable('Path', `"`$([Environment]::GetEnvironmentVariable('Path','User'));$dir`", 'User')"
Write-Host ""
Write-Host "Then open a new PowerShell window. To use it in the current session:"
Write-Host ""
- Write-Host " `$env:Path += `";$VisibleBinDir`""
+ Write-Host " `$env:Path += `";$dir`""
Write-Host ""
}
-else {
+
+Write-Host ""
+Write-Host "cua-driver-rs $version installed."
+Write-Host ""
+Write-Host "Try it:"
+Write-Host " $installedBinary --version"
+Write-Host ""
+
+$onPath = Test-OnUserPath $VisibleBinDir
+if ($onPath) {
Write-Host "$VisibleBinDir is on your user PATH — cua-driver should resolve in any new shell."
Write-Host ""
}
+elseif ($NoPathUpdate) {
+ Write-Host "Skipping PATH update (-NoPathUpdate set)." -ForegroundColor Yellow
+ Write-ManualPathInstructions $VisibleBinDir
+}
+else {
+ try {
+ Add-UserPathEntry $VisibleBinDir
+ Write-Host "Added $VisibleBinDir to your User PATH." -ForegroundColor Green
+ Write-Host ' Open a new PowerShell window for cua-driver to resolve.'
+ Write-Host " Use in the current session: `$env:Path += `";$VisibleBinDir`""
+ Write-Host ' Opt out next time with: install.ps1 -NoPathUpdate'
+ Write-Host ""
+ }
+ catch {
+ Write-WarningStep "could not auto-update User PATH: $($_.Exception.Message)"
+ Write-ManualPathInstructions $VisibleBinDir
+ }
+}
if ($AutoStart) {
Write-Host ""