diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md index e1c465765b..27abc01c35 100644 --- a/libs/cua-driver-rs/PARITY.md +++ b/libs/cua-driver-rs/PARITY.md @@ -1692,6 +1692,48 @@ arrays. --- +## Installer post-install hints + +Not an MCP tool — an installer-text contract. The hint text printed at +the end of every cua-driver-rs install (Try-it / agent skill pack / MCP +setup per client / docs link) is sourced from a single shared file: + +- **Shared text**: `libs/cua-driver/scripts/post-install-hints.txt` + with `{{BINARY}}` placeholder. +- **Renderers**: each of the 4 Rust installers reads the .txt, swaps + `{{BINARY}}` for the installed binary path, prints it, then appends + an OS-specific autostart hint inline: + - `libs/cua-driver/scripts/_install-rust.sh` — `curl` from + raw.githubusercontent.com (remote install path) + bash `sed`. + - `libs/cua-driver/scripts/install.ps1` — `Invoke-WebRequest` from + raw.githubusercontent.com + PowerShell `-replace`. + - `libs/cua-driver-rs/scripts/install-local.sh` — direct disk read + from `../cua-driver/scripts/post-install-hints.txt` + `sed`. + - `libs/cua-driver-rs/scripts/install-local.ps1` — direct disk read + from `..\cua-driver\scripts\post-install-hints.txt` + `-replace`. + +If the .txt is unreachable (network failure on remote installs, repo +layout change on local), each installer falls back to a one-line +essentials string so the user always gets enough to recover. + +**Why not a CLI subcommand**: an earlier draft of this work added +`cua-driver post-install` to the Rust binary and had all 4 installers +delegate via `& $installedBinary post-install`. Reverted — the +chicken-and-egg risk (failed binary install = no hints either) made +the .txt approach the safer choice. The .txt has no runtime +dependency; even a totally broken binary install still prints hints. + +**Why OS-specific hints stay inline**: each script targets one OS +(install.ps1 = Windows; install-local.sh on macOS vs Linux is the +only branching case). The OS-specific block is 4-6 lines, naturally +fits in the script that targets that OS, and is the only part that +would need conditional rendering in a single-file design. + +**Status**: VERIFIED on macOS via `bash libs/cua-driver-rs/scripts/install-local.sh` +end-to-end. Windows VM verification pending. + +--- + ## Focus-steal prevention Cross-cutting infrastructure (not an MCP tool) used by `launch_app` and diff --git a/libs/cua-driver-rs/scripts/install-local.ps1 b/libs/cua-driver-rs/scripts/install-local.ps1 index 66c05a63bd..a7c7640b31 100644 --- a/libs/cua-driver-rs/scripts/install-local.ps1 +++ b/libs/cua-driver-rs/scripts/install-local.ps1 @@ -232,14 +232,37 @@ if ($AutoStart) { try { Register-CuaDriverAutostart -InstalledBinary (Join-Path $VisibleBinDir $BinaryName) Write-Host " Registered. cua-driver serve auto-starts at every interactive logon." -ForegroundColor Green - Write-Host " Start now without re-logging: schtasks /Run /TN cua-driver-serve" - Write-Host " Remove: schtasks /Delete /TN cua-driver-serve /F" } catch { Write-Host " Failed to register: $($_.Exception.Message)" -ForegroundColor Red } +} + +# Unified post-install hints come from a single shared text file so the +# 4 Rust installers (this script + install-local.sh + install.ps1 + +# _install-rust.sh) never drift. The .txt holds the OS-agnostic bulk +# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}} +# placeholders; OS-specific bits stay inline below. +$installedBinary = Join-Path $VisibleBinDir $BinaryName +$HintsTxt = Join-Path $RepoRoot "..\cua-driver\scripts\post-install-hints.txt" +if (Test-Path -LiteralPath $HintsTxt) { + $hintsRaw = Get-Content -Raw -LiteralPath $HintsTxt + Write-Host ($hintsRaw -replace '\{\{BINARY\}\}', $installedBinary) } else { - Write-Host "Auto-start (optional): re-run with -AutoStart to register a logon Scheduled Task," - Write-Host " or use 'schtasks /Run /TN cua-driver-serve' if you registered it previously." + # Repo layout changed or .txt missing — fall back to one-line + # essentials so users still know what to do next. + Write-Host "Next steps: $installedBinary --version | $installedBinary mcp-config | $installedBinary skills install" + Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +} + +# Windows-specific autostart hint (kept inline; per-shell natural location). +if (-not $AutoStart) { + Write-Host "" + Write-Host "Auto-start at logon (Windows-native equivalent of macOS LaunchAgent):" -ForegroundColor Cyan + Write-Host " cua-driver autostart enable (register Scheduled Task at RunLevel=Highest)" -ForegroundColor Cyan + Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan + Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan + Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan + Write-Host " Or re-run install-local.ps1 with -AutoStart for the same result." -ForegroundColor Cyan + Write-Host "" } -Write-Host "" diff --git a/libs/cua-driver-rs/scripts/install-local.sh b/libs/cua-driver-rs/scripts/install-local.sh index 9432eff6f5..37fe279dd5 100755 --- a/libs/cua-driver-rs/scripts/install-local.sh +++ b/libs/cua-driver-rs/scripts/install-local.sh @@ -234,12 +234,25 @@ fi echo "${BOLD}${GREEN}Installed.${NORMAL}" echo " ${BOLD}$INSTALLED_BIN${NORMAL}" echo "" -echo "Verify:" -echo " cua-driver --version" -echo " cua-driver doctor" -echo "" +# Unified post-install hints come from a single shared text file so the +# 4 Rust installers (this script + install-local.ps1 + _install-rust.sh + +# install.ps1) never drift. The .txt holds the OS-agnostic bulk +# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}} +# placeholders; OS-specific bits stay inline below. +HINTS_TXT="$REPO_ROOT/../cua-driver/scripts/post-install-hints.txt" +if [ -f "$HINTS_TXT" ]; then + sed "s|{{BINARY}}|$INSTALLED_BIN|g" "$HINTS_TXT" +else + # Repo layout changed or running from an unexpected location — fall + # back to one-line essentials so users still know what to do next. + echo "Next steps: $INSTALLED_BIN --version | $INSTALLED_BIN mcp-config | $INSTALLED_BIN skills install" + echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +fi + +# OS-specific autostart hint (kept inline; per-shell natural location). if [ "$INSTALL_AUTOSTART" != true ]; then + echo "" if [ "$OS" = "Darwin" ]; then echo "Auto-start (optional): re-run with --autostart to register a LaunchAgent." else diff --git a/libs/cua-driver/scripts/_install-rust.sh b/libs/cua-driver/scripts/_install-rust.sh index e5d9ef4e09..830287a01f 100644 --- a/libs/cua-driver/scripts/_install-rust.sh +++ b/libs/cua-driver/scripts/_install-rust.sh @@ -666,16 +666,38 @@ if [[ "${REPLACED_SWIFT:-0}" == "1" ]]; then echo "" fi -echo "Try it:" -echo " $BIN_LINK list-tools" -echo " $BIN_LINK list_apps" -echo "" -echo "Agent skill pack (optional):" -echo " $BIN_LINK skills install # fetch + link the cua-driver-rs skill pack" -echo " # into Claude Code / Codex / OpenClaw / OpenCode." -echo " # The install never touches your agent dirs." -echo "" -echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +# Unified post-install hints come from a single shared text file so the +# 4 Rust installers (this script + install.ps1 + install-local.sh + +# install-local.ps1) never drift. The .txt holds the OS-agnostic bulk +# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}} +# placeholders; OS-specific bits (autostart / TCC) stay inline below +# in each installer where they're per-shell natural. +HINTS_URL="https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/post-install-hints.txt" +HINTS_TXT="$TMP_DIR/post-install-hints.txt" +if curl -fsSL "$HINTS_URL" -o "$HINTS_TXT" 2>/dev/null && [ -s "$HINTS_TXT" ]; then + sed "s|{{BINARY}}|$BIN_LINK|g" "$HINTS_TXT" +else + # Network fetch failed — print a one-line essentials fallback so the + # user always gets enough to recover, even if hint-text fetching is + # blocked. Skip everything else. + echo "Next steps: $BIN_LINK --version | $BIN_LINK mcp-config | $BIN_LINK skills install" + echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +fi + +case "$(uname -s)" in + Darwin) + echo "" + echo "macOS TCC: grant Accessibility + Screen Recording on first run:" + echo " open -n -g -a CuaDriver --args serve" + echo " $BIN_LINK check_permissions" + ;; + Linux) + echo "" + echo "Auto-start at logon (optional):" + echo " Re-run the local installer with --autostart to register a systemd user unit." + ;; +esac + echo "" echo "⚠️ BETA: cua-driver-rs is a cross-platform Rust port of the Swift" echo " cua-driver. Windows and Linux support is feature-complete; macOS" diff --git a/libs/cua-driver/scripts/install.ps1 b/libs/cua-driver/scripts/install.ps1 index 1b5136a297..1b8415788e 100644 --- a/libs/cua-driver/scripts/install.ps1 +++ b/libs/cua-driver/scripts/install.ps1 @@ -1137,10 +1137,6 @@ function Write-ManualPathInstructions([string]$dir) { 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." @@ -1170,12 +1166,6 @@ if ($AutoStart) { try { Register-CuaDriverAutostart -InstalledBinary $installedBinary Write-Host " cua-driver serve will auto-start at every interactive logon (RunLevel=Highest)." -ForegroundColor Green - Write-Host ' In a new PowerShell window, manage with:' - Write-Host ' cua-driver autostart kick (run now without re-logging)' - Write-Host ' cua-driver autostart status (inspect the task)' - Write-Host ' cua-driver autostart disable (remove)' - Write-Host " In THIS shell, use the full path: $installedBinary" - Write-Host "" } catch { Write-Host " Failed: $($_.Exception.Message)" -ForegroundColor Red @@ -1184,29 +1174,32 @@ if ($AutoStart) { Write-Host "" } } -else { - Write-Host "" -ForegroundColor Cyan - Write-Host "Auto-start at logon (Windows equivalent of macOS LaunchAgent):" -ForegroundColor Cyan - Write-Host " Run cua-driver serve automatically every time you sign in." -ForegroundColor Cyan - Write-Host "" -ForegroundColor Cyan - Write-Host " In a new PowerShell window (will prompt for admin once to register):" -ForegroundColor Cyan - Write-Host " cua-driver autostart enable (register the task at RunLevel=Highest)" -ForegroundColor Cyan - Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan - Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan - Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan - Write-Host "" -ForegroundColor Cyan - Write-Host " In THIS shell, prefix with the full Binary path:" -ForegroundColor Cyan - Write-Host " $installedBinary" -ForegroundColor Cyan - Write-Host "" -ForegroundColor Cyan - Write-Host " Or re-run this installer with -AutoStart for the same result." -ForegroundColor Cyan - Write-Host "" -ForegroundColor Cyan - Write-Host " Without auto-start, you'll need to run 'cua-driver serve' manually." -ForegroundColor Cyan - Write-Host " Auto-start spawns the daemon at logon at RunLevel=Highest, which is" -ForegroundColor Cyan - Write-Host " needed for some elevated operations (registry, services, ACLs)." -ForegroundColor Cyan -} +# Unified post-install hints come from a single shared text file so the +# 4 Rust installers (this script + _install-rust.sh + install-local.ps1 + +# install-local.sh) never drift. The .txt holds the OS-agnostic bulk +# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}} +# placeholders; OS-specific bits (autostart) stay inline below. +$HintsUrl = "https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/post-install-hints.txt" +try { + $hintsRaw = (Invoke-WebRequest -Uri $HintsUrl -UseBasicParsing -TimeoutSec 10).Content + Write-Host ($hintsRaw -replace '\{\{BINARY\}\}', $installedBinary) +} +catch { + # Network fetch failed — print one-line essentials so users always + # get enough to recover. + Write-Host "Next steps: $installedBinary --version | $installedBinary mcp-config | $installedBinary skills install" + Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +} -Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs" +# Windows-specific autostart hint (kept inline; OS-natural location). +Write-Host "" +Write-Host "Auto-start at logon (Windows-native equivalent of macOS LaunchAgent):" -ForegroundColor Cyan +Write-Host " cua-driver autostart enable (Scheduled Task at RunLevel=Highest)" -ForegroundColor Cyan +Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan +Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan +Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan +Write-Host " Or re-run this installer with -AutoStart for the same result." -ForegroundColor Cyan Write-Host "" Write-Host "WARNING -- BETA: cua-driver-rs is a cross-platform Rust port of the Swift" -ForegroundColor Yellow Write-Host " cua-driver. Windows and Linux support is feature-complete; macOS" -ForegroundColor Yellow diff --git a/libs/cua-driver/scripts/post-install-hints.txt b/libs/cua-driver/scripts/post-install-hints.txt new file mode 100644 index 0000000000..ee9ce1ac99 --- /dev/null +++ b/libs/cua-driver/scripts/post-install-hints.txt @@ -0,0 +1,51 @@ + +Next steps: + + 1. Try it: + {{BINARY}} --version + {{BINARY}} list-tools + + 2. Agent skill pack (optional): + {{BINARY}} skills install # fetch + link the cua-driver-rs skill pack + # into Claude Code / Codex / OpenClaw / OpenCode. + # The install never touches your agent dirs. + + 3. As an MCP server — run the one matching your client. Each is also + available via '{{BINARY}} mcp-config --client ': + + • Claude Code: + claude mcp add --transport stdio cua-driver -- {{BINARY}} mcp + + Claude Code computer-use compatibility mode: + claude mcp add --transport stdio cua-computer-use -- {{BINARY}} mcp --claude-code-computer-use-compat + Use this when you want Claude Code's vision/computer-use-style flow + to ground on CuaDriver window screenshots. It keeps the normal + CuaDriver tools and changes only the screenshot tool. + + • Codex (OpenAI): + codex mcp add cua-driver -- {{BINARY}} mcp + + • OpenClaw: + {{BINARY}} mcp-config --client openclaw + + • GitHub Copilot CLI (paste into ~/.copilot/mcp-config.json): + { + "mcpServers": { + "cua-driver": { + "type": "local", + "command": "{{BINARY}}", + "args": ["mcp"], + "tools": ["*"] + } + } + } + + • Cursor / OpenCode / Hermes (no add CLI — paste config): + {{BINARY}} mcp-config --client cursor # JSON for ~/.cursor/mcp.json + {{BINARY}} mcp-config --client opencode # JSON for opencode.json + {{BINARY}} mcp-config --client hermes # YAML for ~/.hermes/config.yaml + + For other clients accepting the generic mcpServers shape: + {{BINARY}} mcp-config + +Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs