feat(install): converge to one canonical .sh + .ps1 entry point per platform

[f-trycua]

Summary

Implements Phase 1 of Option A from issue #1555: every user-facing install URL collapses to libs/cua-driver/scripts/install.{sh,ps1}. Old URLs keep working via auto-delegation (.sh) + redirect shim (.ps1).

This unblocks the convergence story without doing the risky 600-LOC inline merge of Rust install logic into the Swift script — that's the Phase 2 cleanup which can land separately when macOS testing is convenient.

What this PR does

	Before	After
macOS	…/libs/cua-driver/scripts/install.sh → Swift driver	Unchanged. Swift default; --experimental-rust opts into Rust.
Linux	…/libs/cua-driver/scripts/install.sh → errors with "macOS-only"	Auto-detects uname -s != Darwin, flips USE_RUST_BACKEND=1 automatically, delegates to cua-driver-rs install. Prints note: detected non-macOS host (Linux); auto-selecting the cua-driver-rs Rust backend.
Linux backward-compat	…/libs/cua-driver-rs/scripts/install.sh → standalone Rust installer	Unchanged in this PR (Phase 2 inlines the logic + shims the rs URL).
Windows	…/libs/cua-driver-rs/scripts/install.ps1 → Rust installer	…/libs/cua-driver/scripts/install.ps1 is now the canonical URL. The Rust port is what installs — only the URL moved.
Windows backward-compat	(the only URL)	…/libs/cua-driver-rs/scripts/install.ps1 becomes a 30-line redirect shim that Invoke-WebRequest's the new URL and iex-pipes it. Params + env vars flow through unchanged.

Files

• libs/cua-driver/scripts/install.sh — new auto-delegation block ahead of the existing --experimental-rust codepath. macOS behavior bit-identical to main; non-macOS auto-flips to Rust.
• libs/cua-driver/scripts/install.ps1 — new (moved from libs/cua-driver-rs/scripts/install.ps1). Same code; canonical Windows entry point.
• libs/cua-driver-rs/scripts/install.ps1 — replaced with a 30-line shim that fetches + executes the canonical script. Deprecation note prints. Old URL still works.
• .github/workflows/cd-rust-cua-driver.yml — updated to bake versions into the new install.ps1 path; release-notes template's Windows install snippet now points at the canonical URL.

What this PR does NOT do (Phase 2, deferred)

• Inline merge of Rust install logic into the Swift script. Today libs/cua-driver/scripts/install.sh --experimental-rust still execs libs/cua-driver-rs/scripts/install.sh. User-facing URL is converged; internal code path is still two files. Phase 2 collapses them.
• Shim at libs/cua-driver-rs/scripts/install.sh. Deferred until Phase 2 so the shim has a single canonical script to delegate to.

These are pure internal cleanups — Phase 2 has no URL changes and is safe to land separately once a macOS box is handy for end-to-end testing the merged script.

Hermes compatibility

Hermes hardcodes https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh in tools/computer_use/cua_backend.py. This URL keeps working unchanged in every phase. Today: Swift install on macOS (no behavior change). Phase 2-flip-day: Rust install on macOS via the same URL (one-line CD edit). Hermes never needs to update.

Test plan

• macOS: curl …/libs/cua-driver/scripts/install.sh | bash (no flags) → Swift install, no Rust-related output.
• macOS: curl …/libs/cua-driver/scripts/install.sh | bash -s -- --experimental-rust → "installing experimental Rust backend" note + cua-driver-rs installed.
• Linux: curl …/libs/cua-driver/scripts/install.sh | bash → "detected non-macOS host (Linux); auto-selecting the cua-driver-rs Rust backend" note + cua-driver-rs installed automatically.
• Windows: irm …/libs/cua-driver/scripts/install.ps1 | iex → cua-driver-rs installed at the same locations as before.
• Windows backward-compat: irm …/libs/cua-driver-rs/scripts/install.ps1 | iex → deprecation note + same end state.

Closes part 1 of #1555.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Automatic Rust backend selection on non-macOS systems for streamlined installation.

• Chores

  • Reorganized installer distribution pipeline with canonical locations for Windows installers.
  • Legacy installer paths now serve as deprecation redirects to new canonical locations.
  • Updated release workflow to stage and reference canonical installer paths.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	May 18, 2026 0:48am

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 392e8e4c-4ee8-4a57-993c-1e0df5d778fa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR relocates the Windows installer to a canonical location under libs/cua-driver/scripts/install.ps1, replaces the old Rust-path location with a deprecation shim, updates the CD workflow and release process to reflect the change, and enables automatic Rust backend selection on non-macOS hosts.

Changes

Windows Installer Relocation and Non-macOS Auto-Selection

Layer / File(s)	Summary
Canonical Windows Installer Implementation libs/cua-driver/scripts/install.ps1	944-line comprehensive PowerShell installer that downloads cua-driver.exe from GitHub Releases, installs into versioned directories under the user's home, manages concurrent installs via lockfile serialization, wires NTFS directory junctions for atomic upgrades, prunes stale releases, supports optional auto-start registration, validates user PATH, and sends telemetry pings.
Deprecation Shim and CI/CD Integration libs/cua-driver-rs/scripts/install.ps1, .github/workflows/cd-rust-cua-driver.yml	Replaces the old Rust-path installer with a lightweight shim that downloads and executes the canonical script; updates the CD workflow to bake the version into the canonical path, stage it in releases, update release notes with a deprecation warning, and commit the new location.
Shell Script Non-macOS Auto-Selection libs/cua-driver/scripts/install.sh	Detects non-macOS hosts and automatically sets USE_RUST_BACKEND=1 without requiring explicit flags; updates delegation messaging to distinguish auto-selection from manual opt-in.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• trycua/cua#1555: The PR directly implements the Windows installer path convergence and backward-compatibility shim strategy described in the issue.

Possibly related PRs

• trycua/cua#1540: Introduced the original comprehensive Windows installer and initial workflow wiring; this PR relocates that installer and adds the deprecation shim.
• trycua/cua#1538: Modified install.sh to route to the Rust backend via explicit flags; this PR extends that by adding automatic non-macOS detection.
• trycua/cua#1550: Introduced the cua-driver autostart {enable|disable|status|kick} CLI verbs that the canonical installer now delegates to for auto-start registration.

Poem

🐰 The Windows path finds its home,
While old roads shimmer into foam,
On Linux toes, the Rust takes flight,
No flags required—just get it right!
One script to rule them, dark and light. 🌙

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: converging to canonical install entry points (.sh and .ps1) per platform, which aligns with the substantial refactoring across multiple installer scripts and workflow configurations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cua-driver-install-convergence

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}