docs(cua-driver): dedicated Linux install + run guide#1595
Conversation
Adds a Linux-specific getting-started page that covers what diverges
from the canonical macOS / Windows install — display server (X11 vs
Wayland vs XWayland), the AT-SPI prerequisite, autostart-via-systemd
(since `cua-driver autostart` is Windows-only today), and the headless
Xvfb workflow for CI.
Concrete behaviors documented (verified against the source):
* Display-server probe in `libs/cua-driver-rs/crates/cua-driver/src/
doctor.rs::append_platform_probes` (Linux branch) — Wayland-with-
XWayland is the supported case; pure Wayland w/o XWayland is not
today.
* AT-SPI bus probe via `probe_at_spi_bus_via_gdbus` — required for
accessibility-tree tools (`get_window_state`, indexed-element
clicks). Per-distro install table (`at-spi2-core` on every distro,
`gsettings` toggle for GNOME).
* `cua-driver autostart` returns the documented `NOT_YET` error on
Linux from `crates/cua-driver/src/autostart.rs` — the page points
users at the two working alternatives: `install-local.sh
--autostart` (which registers a systemd user unit) or a hand-rolled
`~/.config/systemd/user/cua-driver.service` (full file content
provided). Also mentions `loginctl enable-linger` for headless
runners.
* Headless workflow: `xvfb-run` recipe + standalone Xvfb + dbus-launch
one-liner.
* Distro notes for Ubuntu/Debian/Fedora/Arch/Alpine.
* Cross-links to the existing PARITY.md per-tool Linux matrix, the
new process-attribution explainer (#1594), the autostart concept
page, and installation.mdx for the install one-liner.
Registers `linux` in `getting-started/meta.json` between `windows-ssh`
and `autostart` so the sidebar ordering is: install → quickstart →
windows-ssh → linux → autostart → … .
Closes CUA-538
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR adds a new Linux getting-started guide for ChangesLinux Getting-Started Guide
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/docs/cua-driver/guide/getting-started/linux.mdx`:
- Line 157: The markdown list item referencing the non-existent page
'/cua-driver/explanation/process-attribution' (the line starting with "[Process
attribution] — Linux has none of the macOS-TCC or Windows-Session-0 weirdness;
this page explains what those problems are and why Linux sidesteps them") must
be fixed: either remove that entire list item, replace it with an inline
explanation about process attribution for Linux, or change the link to a valid
existing page; update the text accordingly so it no longer points to the missing
'/cua-driver/explanation/process-attribution' URL.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bab5e0aa-d008-48c9-ba91-b31dacb369b4
📒 Files selected for processing (2)
docs/content/docs/cua-driver/guide/getting-started/linux.mdxdocs/content/docs/cua-driver/guide/getting-started/meta.json
|
|
||
| - [Installation](/cua-driver/guide/getting-started/installation) — canonical one-liner that handles Linux automatically | ||
| - [Autostart](/cua-driver/guide/getting-started/autostart) — concept page (Windows-only verb family; Linux uses systemd) | ||
| - [Process attribution](/cua-driver/explanation/process-attribution) — Linux has none of the macOS-TCC or Windows-Session-0 weirdness; this page explains what those problems are and why Linux sidesteps them |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for process-attribution documentation page
fd -e mdx -e md 'process.*attribution' docs/Repository: trycua/cua
Length of output: 36
🏁 Script executed:
# Read the specific file to confirm the exact link
cat -n docs/content/docs/cua-driver/guide/getting-started/linux.mdx | sed -n '150,165p'Repository: trycua/cua
Length of output: 1110
🏁 Script executed:
# Search for references to process-attribution or `#1594`
rg 'process-attribution|`#1594`|process.*attribution' --type md --type mdxRepository: trycua/cua
Length of output: 82
🏁 Script executed:
# Check docs structure and link validation configuration
find docs -name 'next.config.*' -o -name 'docusaurus.config.*' -o -name 'netlify.toml' | head -5Repository: trycua/cua
Length of output: 75
🏁 Script executed:
# Search without specifying mdx type - use glob instead
rg 'process-attribution|`#1594`' docs/ --glob '*.{md,mdx}'Repository: trycua/cua
Length of output: 322
🏁 Script executed:
# Check what pages exist in the explanation directory
fd . docs/content/docs/cua-driver/explanation/ -type fRepository: trycua/cua
Length of output: 225
🏁 Script executed:
# Check the docs config to understand link validation
head -50 docs/next.config.mjsRepository: trycua/cua
Length of output: 1371
🏁 Script executed:
# List files in the explanation directory
ls -la docs/content/docs/cua-driver/explanation/ 2>/dev/null || echo "Directory may not exist"Repository: trycua/cua
Length of output: 78
🏁 Script executed:
# Search for any references to `#1594` in the entire repo
rg '`#1594`' --type-list | head -20Repository: trycua/cua
Length of output: 444
🏁 Script executed:
# Check git log or PR branches that mention process-attribution
git branch -a | grep -i 'process\|attribution'Repository: trycua/cua
Length of output: 36
🏁 Script executed:
# Check all pages in the cua-driver docs to understand the structure
find docs/content/docs/cua-driver -name '*.mdx' | sortRepository: trycua/cua
Length of output: 944
🏁 Script executed:
# Search for 'process-attribution' or 'process attribution' in all docs files
rg 'process.attribution|process-attribution' docs/Repository: trycua/cua
Length of output: 460
🏁 Script executed:
# Check if there are any pending/unreleased files or branches
git log --oneline --all | grep -i 'process\|attribution' | head -10Repository: trycua/cua
Length of output: 799
🏁 Script executed:
# List all directories in cua-driver docs
ls -d docs/content/docs/cua-driver/*/ 2>/dev/nullRepository: trycua/cua
Length of output: 130
🏁 Script executed:
# Check if there's any reference to this link validation in PR descriptions or issues
rg 'process-attribution' . --glob '*.md' --glob '*.mdx' -B2 -A2Repository: trycua/cua
Length of output: 880
🏁 Script executed:
# Verify link validation is actually checking these links
cat docs/next.config.mjs | grep -A 20 -B 5 'redirects\|rewrites\|link\|validation'Repository: trycua/cua
Length of output: 977
Remove or fix the broken link to non-existent page.
The link to /cua-driver/explanation/process-attribution at line 157 references a page that does not exist. The docs/content/docs/cua-driver/explanation/ directory does not exist in the codebase.
Options to resolve:
- Remove this list item entirely
- Replace with a direct explanation inline rather than a link
- Defer this PR if the page is planned in a dependent PR
🧰 Tools
🪛 GitHub Actions: CI: Check Docs Links / 0_Check Internal Links (next-validate-link).txt
[error] 157-157: docs:check-links failed: invalid URL '/cua-driver/explanation/process-attribution' (not found) reported at content/docs/cua-driver/guide/getting-started/linux.mdx:157:3.
🪛 GitHub Actions: CI: Check Docs Links / Check Internal Links (next-validate-link)
[error] 157-157: Invalid URL detected: /cua-driver/explanation/process-attribution is not found in content/docs/cua-driver/guide/getting-started/linux.mdx:157:3
🪛 LanguageTool
[style] ~157-~157: The words ‘explanation’ and ‘explains’ are quite similar. Consider replacing ‘explains’ with a different word.
Context: ... Windows-Session-0 weirdness; this page explains what those problems are and why Linux s...
(VERB_NOUN_SENT_LEVEL_REP)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/docs/cua-driver/guide/getting-started/linux.mdx` at line 157,
The markdown list item referencing the non-existent page
'/cua-driver/explanation/process-attribution' (the line starting with "[Process
attribution] — Linux has none of the macOS-TCC or Windows-Session-0 weirdness;
this page explains what those problems are and why Linux sidesteps them") must
be fixed: either remove that entire list item, replace it with an inline
explanation about process attribution for Linux, or change the link to a valid
existing page; update the text accordingly so it no longer points to the missing
'/cua-driver/explanation/process-attribution' URL.
1 participant
Summary
Adds a Linux-specific getting-started page covering what diverges from the canonical macOS / Windows install: display server, AT-SPI prerequisite, autostart-via-systemd (since
cua-driver autostartis Windows-only today), and the headless Xvfb workflow for CI.What's in it
Content
Grounded in code
Test plan
Notes
The branch name `docs/cua-driver-linux-getting-started` is slightly unusual because the natural name `docs/cua-driver-linux-guide` is already taken by an unrelated branch from earlier today (a local git-hook rename collision that landed PR #1585).
Closes CUA-538
🤖 Generated with Claude Code
Summary by CodeRabbit